source: TI05-delivery/ows_framework/branches/ows_framework-refactor/ows_common/ows_common/service/wms_iface.py @ 3596

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI05-delivery/ows_framework/branches/ows_framework-refactor/ows_common/ows_common/service/wms_iface.py@3596
Revision 3596, 5.9 KB checked in by spascoe, 14 years ago (diff)

Improved WMS interface docstrings

Line 
1"""
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.
8
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.
14 - To hide how layers are actually retrieved and rendered from ows_server.
15
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.
22
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.
28
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.
35
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
39implementations.
40
41
42"""
43
44class ILayerMapper(object):
45    """
46    Maps keyword arguments to a collection of layers.
47
48    ILayerMapper supports the retrieval of sets of layers according to arbitary
49    keyword/value pairs.
50   
51    """
52    def map(self, **kwargs):
53        """
54        Given arbitary keywords/value pairs list the names of
55        all layers available.
56
57        @return: A mapping of layer names to ILayer implementations.
58        @raise ValueError: If no layers are available for these keywords.
59
60        """
61        raise NotImplementedError
62
63
64class ILayer(object):
65    """
66    An interface representing a WMS layer.
67
68    @ivar title: The layer title.  As seen in the Capabilities document.
69    @ivar abstract:  Abstract as seen in the Capabilities document.
70    @ivar dimensions: A mapping of dimension names to IDimension objects.
71    @ivar units: A string describing the units.
72    @ivar crss: A sequence of SRS/CRSs supported by this layer.
73    @ivar legendSize: (width, height) in pixels of legend.
74
75    @todo: Do we need minValue/maxValue?
76
77    """
78    title = abstract = dimensions = units = crss = NotImplemented
79
80    def getBBox(self, crs):
81        """
82        @return: the bounding box (llx, lly, urx, ury) in the given
83            coordinate reference system.
84
85        """
86        raise NotImplementedError
87
88    def getSlab(self, crs, dimValues=None, renderOpts={}):
89        """
90        Creates a slab of the layer in a particular CRS and set of
91        dimensions.
92
93        @param crs: The coordinate reference system.
94        @param dimValues: A mapping of dimension names to dimension values
95            as specified in the IDimension.extent
96        @param renderOpts: A generic mapping object for passing rendering
97            options
98        @return: An object implementing ILayerSlab
99
100        """
101        raise NotImplementedError
102
103    def getCacheKey(self, crs, dimValues=None, renderOpts={}):
104        """
105        Create a unique key for use in caching a slab.
106
107        Any unique combination of crs, dimValues and renderOpts should
108        produce a unique key.
109
110        The intention here is that most of the work should be done when
111        instantiating an ILayerSlab object.  These can be cached by the
112        server for future use.  The server will first call getCacheKey()
113        for the slab creation arguments and if the key is in it's cache
114        it will use a pre-generated ILayerSlab object.
115
116        """
117        raise NotImplementedError
118
119    def getLegendImage(self, orientation='vertical', renderOpts={}):
120        """
121        Create an image of the colourbar for this layer.
122       
123        @param orientation: Either 'vertical' or 'horizontal'
124        @return: A PIL image
125
126        """
127        raise NotImplementedError
128
129class IDimension(object):
130    """
131    An interface representing a WMS dimension
132   
133    @ivar units: The units string.
134    @ivar extent: Sequence of extent values.
135
136    """
137    units = extent = NotImplemented
138
139class ILayerSlab(object):
140    """
141    An interface representing a particular horizontal slice of a WMS layer.
142
143    ILayerSlab objects are designed to be convenient to cache.
144    Ideally they should be pickleable to enable memcached support in
145    the future.
146
147    @ivar layer: The source ILayer instance.
148    @ivar crs: The coordinate reference system.
149    @ivar dimValues: A mapping of dimension values of this view.
150    @ivar renderOpts: The renderOpts used to create this view.
151    @ivar bbox: The bounding box as a 4-tuple.
152
153    """
154    layer = crs = dimValues = renderOpts = bbox = NotImplemented
155
156    def getImage(self, bbox, width, height):
157        """
158        Create an image of a sub-bbox of a given size.
159
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.
164        @return: A PIL Image object.
165
166        """
167        raise NotImplementedError
168
Note: See TracBrowser for help on using the repository browser.