12/03/08 14:57:20 (14 years ago)

Improved WMS interface docstrings

1 edited


  • TI05-delivery/ows_framework/branches/ows_framework-refactor/ows_common/ows_common/service/wms_iface.py

    r3573 r3596  
    2 Refactored model of object to support WMS requests through 
    3 ows_server. 
     2The classes in this module define an interface between the OWS Pylons 
     3server and components that provide Web Map Server layers.  The 
     4intention is that a WMS can be created for a given datatype and 
     5renderring engine by creating classes that implement these interfaces 
     6-- there is no need to mess around with Pylons controllers or the 
     7ows_common metadata model. 
    5 Primary goals of this model is to: 
    6  - support multiple dimensions. 
    7  - Allow caching of layer views by dimensions and CRS to mitigate 
    8    the overhead of data retreival and rendering. 
     9The interface was designed with several requirements in mind: 
     10 - support multiple dimensions (in the WMS sense, i.e. non-geospatial dimensions). 
     11 - support multiple CRSs/SRSs 
     12 - Allow caching of horizontal slices (called layer slabs) by 
     13   dimensions and CRS to mitigate the overhead of data retreival and rendering. 
    914 - To hide how layers are actually retrieved and rendered from ows_server. 
     16The main entry point for the OWS Pylons server is the ILayerMapper 
     17interface.  This provides a mechanism for serving multiple WMS 
     18endpoints through a single server.  Keywords deduced from the pylons 
     19routes mapper are passed to the ILayerMapper instance to return a 
     20dictionary of ILayer instances.  These are the layers available to the 
     21WMS on this route. 
     23ILayer instances provide dimension and CRS information to the server 
     24and can render a legend.  A layer image is requested by a two stage 
     25process.  First the CRS and non-geospatial dimensions are selected 
     26through ILayer to return a ILayerSlab instance.  WMS images are then 
     27retrieved through ILayerSlab for a given bounding box. 
     29This allows implementations to cache the result if it makes sense to 
     30do so.  implementing ILayer.getCacheKey() will cause the server to 
     31cache ILayerSlab objects for future use, therefore not requiring 
     32repeated calls to ILayer.getSlab().  This strategy works well with 
     33tiling WMS clients that will make multiple GetMap requests with the 
     34same CRS and dimension parameters. 
     36It is expected that implementing classes will inherit from these 
     37interface classes, using them as abstract base classes.  However, in 
     38the future zope.Interface might be used to associate interfaces with 
    1344class ILayerMapper(object): 
    1445    """ 
    15     Map keyword arguments to a collection of layers. 
     46    Maps keyword arguments to a collection of layers. 
    1748    ILayerMapper supports the retrieval of sets of layers according to arbitary 
    3768    @ivar title: The layer title.  As seen in the Capabilities document. 
    3869    @ivar abstract:  Abstract as seen in the Capabilities document. 
    39     @ivar dimensions: A dictionary of IDimension objects. 
     70    @ivar dimensions: A mapping of dimension names to IDimension objects. 
    4071    @ivar units: A string describing the units. 
    4172    @ivar crss: A sequence of SRS/CRSs supported by this layer. 
    4980    def getBBox(self, crs): 
    5081        """ 
    51         @return: A 4-typle of the bounding box in the given coordinate 
    52             reference system. 
     82        @return: the bounding box (llx, lly, urx, ury) in the given 
     83            coordinate reference system. 
    5485        """ 
    74105        Create a unique key for use in caching a slab. 
     107        Any unique combination of crs, dimValues and renderOpts should 
     108        produce a unique key. 
    76110        The intention here is that most of the work should be done when 
    77111        instantiating an ILayerSlab object.  These can be cached by the 
    95129class IDimension(object): 
    96130    """ 
     131    An interface representing a WMS dimension 
    97133    @ivar units: The units string. 
    98134    @ivar extent: Sequence of extent values. 
    107143    ILayerSlab objects are designed to be convenient to cache. 
    108     They should be pickleable to enable memcached support in the future. 
     144    Ideally they should be pickleable to enable memcached support in 
     145    the future. 
    110147    @ivar layer: The source ILayer instance. 
    121158        Create an image of a sub-bbox of a given size. 
    123         @ivar bbox: A bbox 4-tuple. 
    124         @ivar width: width in pixels. 
    125         @ivar height: height in pixels. 
     160        @param bbox: A bbox tuple (llx, lly, urx, ury).  bbox will 
     161            always lie within the self.layer.getBBox(self.crs) 
     162        @param width: width in pixels. 
     163        @param height: height in pixels. 
    126164        @return: A PIL Image object. 
Note: See TracChangeset for help on using the changeset viewer.