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

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@3688
Revision 3688, 5.9 KB checked in by spascoe, 11 years ago (diff)

A required element was being missed. This has required a change to the WMS API.

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