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

"""
Refactored model of object to support WMS requests through
ows_server.

Primary goals of this model is to:
 - support multiple dimensions.
 - Allow caching of layer views by dimensions and CRS to mitigate
   the overhead of data retreival and rendering.
 - To hide how layers are actually retrieved and rendered from ows_server.

"""

class ILayerMapper(object):
    """
    Map keyword arguments to a collection of layers.

    ILayerMapper supports the retrieval of sets of layers according to arbitary
    keyword/value pairs.
    
    """
    def map(self, **kwargs):
        """
        Given arbitary keywords/value pairs list the names of
        all layers available.

        @return: A mapping of layer names to ILayer implementations.
        @raise ValueError: If no layers are available for these keywords.

        """
        raise NotImplementedError


class ILayer(object):
    """
    An interface representing a WMS layer.

    @ivar title: The layer title.  As seen in the Capabilities document.
    @ivar abstract:  Abstract as seen in the Capabilities document.
    @ivar dimensions: A dictionary of IDimension objects.
    @ivar units: A string describing the units.
    @ivar crss: A sequence of SRS/CRSs supported by this layer.
    @ivar legendSize: (width, height) in pixels of legend.

    @todo: Do we need minValue/maxValue?

    """
    title = abstract = dimensions = units = crss = NotImplemented

    def getBBox(self, crs):
        """
        @return: A 4-typle of the bounding box in the given coordinate
            reference system.

        """
        raise NotImplementedError

    def getSlab(self, crs, dimValues=None, renderOpts={}):
        """
        Creates a slab of the layer in a particular CRS and set of
        dimensions.

        @param crs: The coordinate reference system.
        @param dimValues: A mapping of dimension names to dimension values
            as specified in the IDimension.extent
        @param renderOpts: A generic mapping object for passing rendering
            options
        @return: An object implementing ILayerSlab

        """
        raise NotImplementedError

    def getCacheKey(self, crs, dimValues=None, renderOpts={}):
        """
        Create a unique key for use in caching a slab.

        The intention here is that most of the work should be done when
        instantiating an ILayerSlab object.  These can be cached by the
        server for future use.  The server will first call getCacheKey()
        for the slab creation arguments and if the key is in it's cache
        it will use a pre-generated ILayerSlab object.

        """
        raise NotImplementedError

    def getLegendImage(self, orientation='vertical', renderOpts={}):
        """
        Create an image of the colourbar for this layer.
        
        @param orientation: Either 'vertical' or 'horizontal'
        @return: A PIL image

        """
        raise NotImplementedError

class IDimension(object):
    """
    @ivar units: The units string.
    @ivar extent: Sequence of extent values.

    """
    units = extent = NotImplemented

class ILayerSlab(object):
    """
    An interface representing a particular horizontal slice of a WMS layer.

    ILayerSlab objects are designed to be convenient to cache.
    They should be pickleable to enable memcached support in the future.

    @ivar layer: The source ILayer instance.
    @ivar crs: The coordinate reference system.
    @ivar dimValues: A mapping of dimension values of this view.
    @ivar renderOpts: The renderOpts used to create this view.
    @ivar bbox: The bounding box as a 4-tuple.

    """
    layer = crs = dimValues = renderOpts = bbox = NotImplemented

    def getImage(self, bbox, width, height):
        """
        Create an image of a sub-bbox of a given size.

        @ivar bbox: A bbox 4-tuple.
        @ivar width: width in pixels.
        @ivar height: height in pixels.
        @return: A PIL Image object.

        """
        raise NotImplementedError