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

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@3696
Revision 3696, 6.7 KB checked in by spascoe, 12 years ago (diff)

Implementation of GetFeatureInfo?. Not tested yet but the interface
described in wms_iface.py should remain constant.

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 wgs84BBox: The bounding box in CRS:84 (lat/lon)
74    @ivar legendSize: (width, height) in pixels of legend.
75
76    @ivar featureInfoFormats: A sequence of formats supported for the
77        self.getFeatureInfo method.  If this is None or empty GetFeatureInfo
78        is not supported.
79
80    @todo: Do we need minValue/maxValue?
81
82    """
83    title = abstract = dimensions = units = crss = wgs84BBox = NotImplemented
84    featureInfoFormats = NotImplemented
85
86    def getBBox(self, crs):
87        """
88        @return: the bounding box (llx, lly, urx, ury) in the given
89            coordinate reference system.
90
91        """
92        raise NotImplementedError
93
94    def getSlab(self, crs, dimValues=None, renderOpts={}):
95        """
96        Creates a slab of the layer in a particular CRS and set of
97        dimensions.
98
99        @param crs: The coordinate reference system.
100        @param dimValues: A mapping of dimension names to dimension values
101            as specified in the IDimension.extent
102        @param renderOpts: A generic mapping object for passing rendering
103            options
104        @return: An object implementing ILayerSlab
105
106        """
107        raise NotImplementedError
108
109    def getCacheKey(self, crs, dimValues=None, renderOpts={}):
110        """
111        Create a unique key for use in caching a slab.
112
113        Any unique combination of crs, dimValues and renderOpts should
114        produce a unique key.
115
116        The intention here is that most of the work should be done when
117        instantiating an ILayerSlab object.  These can be cached by the
118        server for future use.  The server will first call getCacheKey()
119        for the slab creation arguments and if the key is in it's cache
120        it will use a pre-generated ILayerSlab object.
121
122        """
123        raise NotImplementedError
124
125    def getLegendImage(self, orientation='vertical', renderOpts={}):
126        """
127        Create an image of the colourbar for this layer.
128       
129        @param orientation: Either 'vertical' or 'horizontal'
130        @return: A PIL image
131
132        """
133        raise NotImplementedError
134
135    def getFeatureInfo(self, format, crs, point, dimValues):
136        """
137        Return a response string descibing the feature at a given
138        point in a given CRS.
139
140        @param format: One of self.featureInfoFormats.  Defines which
141            format the response will be in.
142        @param crs: One of self.crss
143        @param point: a tuple (x, y) in the supplied crs of the point
144            being selected.
145        @param dimValues: A mapping of dimension names to dimansion values.
146        @return: A string containing the response.
147
148        """
149        raise NotImplementedError
150       
151
152class IDimension(object):
153    """
154    An interface representing a WMS dimension
155   
156    @ivar units: The units string.
157    @ivar extent: Sequence of extent values.
158
159    """
160    units = extent = NotImplemented
161
162class ILayerSlab(object):
163    """
164    An interface representing a particular horizontal slice of a WMS layer.
165
166    ILayerSlab objects are designed to be convenient to cache.
167    Ideally they should be pickleable to enable memcached support in
168    the future.
169
170    @ivar layer: The source ILayer instance.
171    @ivar crs: The coordinate reference system.
172    @ivar dimValues: A mapping of dimension values of this view.
173    @ivar renderOpts: The renderOpts used to create this view.
174    @ivar bbox: The bounding box as a 4-tuple.
175
176    """
177    layer = crs = dimValues = renderOpts = bbox = NotImplemented
178
179    def getImage(self, bbox, width, height):
180        """
181        Create an image of a sub-bbox of a given size.
182
183        @param bbox: A bbox tuple (llx, lly, urx, ury).  bbox will
184            always lie within the self.layer.getBBox(self.crs)
185        @param width: width in pixels.
186        @param height: height in pixels.
187        @return: A PIL Image object.
188
189        """
190        raise NotImplementedError
191
Note: See TracBrowser for help on using the repository browser.