source: cows/trunk/cows/service/wms_iface.py @ 4912

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/cows/trunk/cows/service/wms_iface.py@5399
Revision 4912, 5.1 KB checked in by spascoe, 13 years ago (diff)

Added LICENSE file and a short banner at the top of each python file.
Use add_license.py to add a license to new files.

NOTE: also contains a couple of files missed at last commit.

Line 
1# BSD Licence
2# Copyright (c) 2009, Science & Technology Facilities Council (STFC)
3# All rights reserved.
4#
5# See the LICENSE file in the source distribution of this software for
6# the full license text.
7
8"""
9The classes in this module define an interface between the OWS Pylons
10server and components that provide Web Map Server layers. They extend the interfaces
11defined in wxs_iface.py.
12
13The interface was designed with several requirements in mind:
14 - support multiple dimensions (in the WMS sense, i.e. non-geospatial dimensions).
15 - support multiple CRSs/SRSs
16 - Allow caching of horizontal slices (called layer slabs) by
17   dimensions and CRS to mitigate the overhead of data retreival and rendering.
18 - To hide how layers are actually retrieved and rendered from ows_server.
19
20IwmsLayer instances provide dimension and CRS information to the server
21and can render a legend.  A layer image is requested by a two stage
22process.  First the CRS and non-geospatial dimensions are selected
23through IwmsLayer to return a IwmsLayerSlab instance.  WMS images are then
24retrieved through IwmsLayerSlab for a given bounding box.
25
26This allows implementations to cache the result if it makes sense to
27do so.  implementing IwmsLayer.getCacheKey() will cause the server to
28cache IwmsLayerSlab objects for future use, therefore not requiring
29repeated calls to IwmsLayer.getSlab().  This strategy works well with
30tiling WMS clients that will make multiple GetMap requests with the
31same CRS and dimension parameters.
32
33
34
35"""
36
37from wxs_iface import ILayer
38
39       
40#!TODO: missing definitions: self.dimensions
41class IwmsLayer(ILayer):
42    """
43    An interface representing a WMS layer, based on ILayer.
44   
45    @ivar legendSize: (width, height) in pixels of legend.
46
47    @ivar featureInfoFormats: A sequence of formats supported for the
48        self.getFeatureInfo method.  If this is None or empty GetFeatureInfo
49        is not supported.
50
51    @todo: Do we need minValue/maxValue?
52
53    """
54
55
56    def getSlab(self, crs, dimValues=None, renderOpts={}):
57        """
58        Creates a slab of the layer in a particular CRS and set of
59        dimensions.
60
61        @param crs: The coordinate reference system.
62        @param dimValues: A mapping of dimension names to dimension values
63            as specified in the IDimension.extent
64        @param renderOpts: A generic mapping object for passing rendering
65            options
66        @return: An object implementing ILayerSlab
67
68        """
69        raise NotImplementedError
70
71    def getCacheKey(self, crs, dimValues=None, renderOpts={}):
72        """
73        Create a unique key for use in caching a slab.
74
75        Any unique combination of crs, dimValues and renderOpts should
76        produce a unique key.
77
78        The intention here is that most of the work should be done when
79        instantiating an ILayerSlab object.  These can be cached by the
80        server for future use.  The server will first call getCacheKey()
81        for the slab creation arguments and if the key is in it's cache
82        it will use a pre-generated ILayerSlab object.
83
84        """
85        raise NotImplementedError
86
87    def getLegendImage(self, orientation='vertical', renderOpts={}):
88        """
89        Create an image of the colourbar for this layer.
90       
91        @param orientation: Either 'vertical' or 'horizontal'
92        @return: A PIL image
93
94        """
95        raise NotImplementedError
96
97    def getFeatureInfo(self, format, crs, point, dimValues):
98        """
99        Return a response string descibing the feature at a given
100        point in a given CRS.
101
102        @param format: One of self.featureInfoFormats.  Defines which
103            format the response will be in.
104        @param crs: One of self.crss
105        @param point: a tuple (x, y) in the supplied crs of the point
106            being selected.
107        @param dimValues: A mapping of dimension names to dimansion values.
108        @return: A string containing the response.
109
110        """
111        raise NotImplementedError
112       
113
114class IwmsDimension(object):
115    """
116    An interface representing a WMS dimension
117   
118    @ivar units: The units string.
119    @ivar extent: Sequence of extent values.
120
121    """
122    units = extent = NotImplemented
123
124class IwmsLayerSlab(object):
125    """
126    An interface representing a particular horizontal slice of a WMS layer.
127
128    IwmsLayerSlab objects are designed to be convenient to cache.
129    Ideally they should be pickleable to enable memcached support in
130    the future.
131
132    @ivar layer: The source IwmsLayer instance.
133    @ivar crs: The coordinate reference system.
134    @ivar dimValues: A mapping of dimension values of this view.
135    @ivar renderOpts: The renderOpts used to create this view.
136    @ivar bbox: The bounding box as a 4-tuple.
137
138    """
139    layer = crs = dimValues = renderOpts = bbox = NotImplemented
140
141    def getImage(self, bbox, width, height):
142        """
143        Create an image of a sub-bbox of a given size.
144
145        @param bbox: A bbox tuple (llx, lly, urx, ury).  bbox will
146            always lie within the self.layer.getBBox(self.crs)
147        @param width: width in pixels.
148        @param height: height in pixels.
149        @return: A PIL Image object.
150
151        """
152        raise NotImplementedError
153
Note: See TracBrowser for help on using the repository browser.