root/PrimaGIS/trunk/interfaces.py

# -*- coding: ISO-8859-1 -*-
##############################################################################
#
# Copyright (c) 2005 Kai Hänninen <kai.hanninen@mbconcert.fi>
#
# This file is part of PrimaGIS.
#
# PrimaGIS is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# PrimaGIS is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with PrimaGIS; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
# $Id$
#
##############################################################################

from zope.interface import Interface
from Products.ZCO.interfaces import IDataStoreProxy, ILayerProxy, IStyleProxy

class IGeoAware(Interface):
    """
    Classes implementing IGeoAware contain spatial information which may
    be accessed through the interface methods to be used with PrimaGIS.

    For an object to be geo-aware, it must provide the following
    information:
     - spatial data
     - title
     - description
     - URL to the object

    In most cases it is probably most convenient to hook the
    getGeoTitle() and getGeoDescription() methods to their Dublin Core
    equivalents (Title() and Description() respectively).

    The reason we define separate methods is that if the object
    requires to have more sophisticated information shown with
    PrimaGIS, it is possible to do so without modifying the Title()
    and Description() methods.
    The same reasoning applies to getGeoURL() which can be hooked to
    absolute_url() in most cases. With complex AT hierarchies with
    multiple objects creating a sigle logical component, we might need
    more control over the URL.
    """


    def getGeometry():
        """
        Returns a Python Cartographic Library (PCL) geometry object representing
        the geometry of the implementing object. PCL geometry objects may be
        instantiated either by actual data or a WKT string representation of it.
        
        Implementors need to import either Point, LineString or Polygon from
        cartography.spatial and return an instance of it.
        
        Example:
        
        from cartography.spatial import Point
        return Point(x=self.getGeoX(), y=self.getGeoY())
        """

    def getGeoTitle():
        """
        Returns the title for the geo-aware object.
        
        The title will be shown as the title of the Javascript popups.
        """

    def getGeoDescription():
        """
        Returns a description of the geo-aware object.
        
        The description will be shown as the content of the Javascript popups
        and may contain HTML markup.
        """

    def getGeoURL():
        """
        Returns an URL to the object used in creating a link in
        PrimaGIS.
        If this method returns None, PrimaGIS will not create a link
        in the imagemap hotspot, but assumes that the object will
        provide necessary links within the data from
        getGeoDescription(). In addition the JavaScript pop-up will be
        sticky, so the user is able to use the in-content links.
        """

class IPrimaGISMap(Interface):
    """
    PrimaGIS main application interface.
    """
    
    def getZCOPath():
        """
        Returns the traversable (in acquisition sense) path to the ZCO
        hierarchy used by this map. The path is relative to this
        PrimaGISMap instance and points to the ZCO hierarchy container.
        """
    
    def setZCOPath(zcopath):
        """
        Sets the traversable (in acquisition sense) path to the ZCO hierarchy
        container. The path should be relative to this PrimaGISMap instance.
        
        Examples: "zco", "../path/to/somewhere/ZCO", ...
        
        Parameters
        ----------
        zcopath : string
            Relative path expression to the ZCO hierarchy container. 
        """
    
    def getZCOContainer():
        """
        Returns the ZCO hierarchy container object.
        """
    
    def getBackgroundColor():
        """
        Returns the background color used for this map in the RGB hexadecimal
        representation, e.g. "#ffffff". An empty string means transparent
        background.
        """
    
    def setBackgroundColor(color):
        """
        Sets the background color used for this map. The color should be
        given in the RGB hexadecimal format.
        
        Parameters
        ----------
        color : string
            Background color in hexadecimal form (e.g. "#ff00ff") or empty
            string for transparent background.
        """
    
    def getOutputFormat():
        """
        Returns the extended mimetype information of the image format used for
        this map.
        """
    
    def setOutputFormat(format):
        """
        Sets the image format used for this map.
        The format string is an extended mimetype declaration. See documentation
        for cartography.engine.mapserver.rendering.render() for more details and
        supported values.
        
        Parameters
        ----------
        format : string
            Extended mimetype information, e.g. "image/png; mode=RGBA"
        """
    
    def getSpatialReferenceCode():
        """
        Returns the spatial reference code defined for this map. This can
        either be an EPSG code, e.g. "EPSG:4326", or a white-space separated list
        of PROJ.4 parameters, e.g. "proj=latlong datum=WGS84".
        """
    
    def setSpatialReferenceCode(code):
        """
        Sets the spatial reference code for this map. This can
        either be an EPSG code, e.g. "EPSG:4326", or a white-space separated list
        of PROJ.4 parameters, e.g. "proj=latlong datum=WGS84".
        
        Parameters
        ----------
        code : string
            Either an EPSG code or PROJ.4 parameters.
        """
    
    def getMapView():
        """
        Returns a cartography.spatial.BoundingBox object defining the current
        map extent.
        """
    
    def getDefaultExtent():
        """ Returns a cartography.spatial.geometry.BoundingBox object defining
        the default extent for this map.
        """
    
    def setDefaultView(bbox=None):
        """
        Sets the default extent for this map. This extent is used for all
        new users before they modify their session through the map UI.
        
        Parameters
        ----------
        bbox : cartography.spatial.BoundingBox | string (optional)
            The new default extent. Can be either a BoundingBox object or a
            string representation in the form "minx,miny,maxx,maxy".
        """
    
    def getDefaultSize():
        """
        Returns the default map image size as (width, height) tuple in pixel
        units. 
        """
    
    def setDefaultSize(width, height):
        """
        Sets the default map image size for this map. It is possible for
        this value to not be included in the user selectable sizes, but that
        means that the user will not be able to view the map at this size
        without reseting the user session.
        
        See also IPrimaGISMap.setAvailableSizes()
        
        Parameters
        ----------
        width : int
            The default width for this map in pixels.
            
        heigth : int
            The default height for this map in pixels.
        """
    
    def getMapSize():
        """
        Returns the current map size as a (width, height) tuple.
        """
    
    def getAvailableSizes():
        """
        Returns a list of dictionaries (keys: width, height, description) of the
        available sizes for this map.
        """
    
    def setAvailableSizes(sizes):
        """
        Sets the user selectable sizes for this map.
        
        Parameters
        ----------
        sizes : [{}]
            List of dictionaries with keys 'width', 'height' and 'description'.
        """
    
    def getGeoAwareTypes():
        """
        Returns a list of content type names that are allowed to be used as data
        for the PrimaGISDataLayers under this map.
        """
    
    def setGeoAwareTypes(types):
        """
        Sets the content types that are allowed to be used as data for the 
        PrimaGISDataLayers under this map. All the types should implement the
        IGeoAware interface.
        This allows the possible content types to be controlled on a map basis.
        """
    
    def view():
        """
        Returns a rendered map image based on the current user session.
        """
    
    def getSession():
        """
        Returns the current user's session, a PrimaGISSession object.
        If the user is viewing multiple maps on a single Plone site, this method
        guarantees that the user will have a unique session for each map.
        """
    
    def reprojectPoint(point, srcSRS=None, tgtSRS=None):
        """
        Reprojects the given point from the spatial reference system defined by
        srcSRS to the spatial reference system defined by tgtSRS.
        
        Both srcSRS and tgtSRS can either be an EPSG code, e.g. "EPSG:4326" or
        white-space separated PROJ.4 parameters, e.g. "proj=latlong datum=WGS84".
        
        Parameters
        ----------
        point : cartography.spatial.Point
            The point that will be reprojected.
            
        srsSRS : string (optional)
            Source SRS identifier. Defaults to the map spatial reference system.
            
        tgtSRS : string (optional)
            Target SRS identifier. Defaults to the map spatial reference system.
        """
    
    def action():
        """
        Performs actions on the user session based on parameters from the
        REQUEST object.
        """
    
    def getDataLayers(check_rw=False):
        """
        Returns a list of PrimaGISDataLayers under this map.
        
        Parameters
        ----------
        check_rw : boolean (optional)
            Checks whether the current user has write access to the data layers'
            data containers and filters out those that the user has inadequate
            rights when set to True.
        """
    
    def getLayers():
        """
        Returns a list of PrimaGISDataLayer and PrimaGISLayer objects under this
        map.

        The returned list is subject to workflow and only those layers that the
        current user has View permission will be returned.

        The ordering of the layers defined in the folder_contents page for this
        map is honored.
        """
    
    def getDefaultLayers():
        """
        Returns a list of ids for ZCO Layer/ZCO Style pairs that should be
        rendered by default.

        The returned list is subject to workflow and only those layers that the
        current user has View permission will be returned.

        The ordering of the layers defined in the folder_contents page for this
        map is honored.
        """
    
    def getLegendLayers():
        """
        Returns a list of ids for ZCO Layer/ZCO Style pairs whose symbols should
        be shown in the legend.
        """
    
    def getHidableLayers():
        """
        Returns a list of PrimaGISDataLayer and PrimaGISLayer objects under this
        map that are hidable by the user.

        The returned list is subject to workflow and only those layers that the
        current user has View permission will be returned.

        The ordering of the layers defined in the folder_contents page for this
        map is honored.
        """
    
    def hasHidableLayers():
        """
        Checks whether this map has any layers that are hidable by the user.
        """
    
    def getMapRenderer():
        """
        Returns the ZCO Map Renderer object used for rendering this map.
        """
    
    def getLayerContainer():
        """
        Returns the container object containing all the ZCO Layers used with
        this map.
        """
    
    def getSerial():
        """
        Returns a running serial number that can be used to differentiate HTTP
        requests and avoid caching problems.
        """
    
    def getImageMapData(evaluate=False):
        """
        Returns a JSON string representation containing the information needed
        to create the client side image map with the overlib popups.
        Alternatively the method can return an evaluated list of python
        dictionaries containing the same information.
        
        Parameters
        ----------
        evaluate : boolean (optional)
            Set to True to get list of dictionaries instead of a JSON string.
        """
    
    def getLegendData(evaluate=False):
        """
        Returns a JSON string representation of the information needed to create
        the map legend.
        Alternatively the method can return an evaluated list of python
        dictionaries containing the same information.
        
        Parameters
        ----------
        evaluate : boolean (optional)
            Set to True to get list of dictionaries instead of a JSON string.        
        """
    
    def setSessionDefaultView():
        """
        Saves the current map extent as the default view for the user session.
        Returns an i18n aware message that can be displayed to the user in the
        map UI.
        """

    def getNamedViews():
        """
        Returns a list of PrimaGISView objects under this map. The objects will
        be sorted by their Title in ascending order.
        """

    def staticview(self, layers=None, width=None, height=None, bbox=None, REQUEST=None):
        """Returns a static, non-session aware image of the map.
        
        This method can be used to embed map imagery within other documents as
        static images by using a normal <img> tag such as
        
          <img src="primagis/staticview?layers=list,of,layers&width=600&height=600&bbox=-500,-500,500,500" />
          
        Calling this method does not modify the user's session. The map layers
        will be rendered in the order defined for the map regardless of the
        ordering of the 'layers' parameter.
        
        Parameters
        ==========
        
        layers : string
            A comma separated list of layer ids, e.g. "capitals,world_borders".
            The ids correspond to the available layers within this map. The
            default map layers will be always appended to the requested layers.
        
        width : int
            The width of the map in pixels. Defaults to map default if omitted.
        
        height : int
            The height of the map in pixels. Defaults to map default if omitted.
        
        bbox : string
            The map extent that will be rendered. The value must be a comma
            separated string containing the values for minx, miny, maxx and maxy
            in that order, e.g. "-500,-500,500,500". Defaults to map default if
            omitted.
        """


class IPrimaGISLayer(ILayerProxy, IStyleProxy):
    """
    PrimaGIS Layer interface.
    
    This interface defines a relationship with a ZCO Layer/ZCO Style pair and
    a PrimaGIS map.
    """

    def getStyledLayer():
        """
        Returns a ZCO Layer / ZCO Style id pair that this PrimaGISLayer
        represents. If there is no ZCO Style object available, then "nostyle"
        will be used as the id of the non-existing Style.
        """

    def setStyledLayer(layer):
        """
        Sets the ZCO Layer / ZCO Style id pair that this layer represent on
        the map. The id pair is also a traversable path relative to the ZCO
        layer container (see IPrimaGISMap.getLayerContainer()) and is of the
        form "[layerid]/[styleid]".
        
        Parameters
        ----------
        
        layer : string
            Traversable path to a ZCO Layer / ZCO Style combination relative to
            the layer container. If there is no corresponding Style object for
            the Layer, then the style can be omitted and a path to the ZCO Layer
            object used instead.
        """
    
    def getDefaultVisibility():
        """
        Returns a boolean flag showing whether this layer should be rendered
        by default on the map.
        """

    def setDefaultVisibility(status):
        """
        Sets whether this layer should be rendered on the map by default. If set
        to False, then the user must explicitly request that this layer be
        rendered.
        
        Parameters
        ----------
        status : boolean
            The boolean flag for showing the layer by default or not.
        """
    
    def getLegendVisibility():
        """
        Returns a boolean flag showing whether symbols from this layer should
        be visible in the map legend.
        """

    def setLegendVisibility(status):
        """
        Sets whether the symbols from this layer should be rendered on the map.
        
        Parameters
        ----------
        status : boolean
            The boolean flag for whether symbols should be shown in the legend
            or not.
        """
        
    def getHidability():
        """
        Returns a boolean flag showing whether this layer should be hidable by
        the user through the map UI.
        """
   
    def setHidability(status):
        """
        Sets whether this layer should be hidable by the user through the map UI.
        
        Parameters
        ----------
        status : boolean
            The boolean flag for whether the users should be able to hide this
            layer or not.
        """
    
    def view(width=300, height=300):
        """
        Returns a rendered image of this layer.
        
        Parameters
        ----------
        width : int (optional)
            Pixel width for the image. Defaults to 300.
            
        height : int (optional)
            Pixel height for the image. Default to 300.
        """
        
    def getAvailableStyledLayers():
        """
        Returns a list of ZCO Layer / ZCO Style id pairs that are not yet used
        by other PrimaGIS[Data]Layers within the same map as this layer.
        
        This provides a safe and validated vocabulary for the
        IPrimaGISLayer.setStyledLayer() method.
        """
    
class IPrimaGISDataLayer(IPrimaGISLayer, IDataStoreProxy):
    """
    This interface defines a relationship with a ZCO Layer/ZCO Style pair and
    a PrimaGISMap and in addition allows the implementing object to act as a
    ZCO data source providing data from within the Plone site.
    """

    def getDataSourcePath():
        """
        Returns a traversable (in acquisition sense) path relative to this layer
        to a folderish object containing the spatial data for this layer.
        """
    
    def setDataSourcePath(source):
        """
        Sets the traversable (in acquisition sense) path relative to this layer
        to a folderish object containing the spatial data for this layer.
        
        The folderish object can be of arbitrary type as long as it behaves like
        a folder and provides methods for accessing its contents.
        
        Use "." (dot) to indicate that the data is stored within this object.
        """

    def getDataSource():
        """
        Returns the folderish object containing the spatial data for this layer
        or None if the object could not be acquired.
        """
    
    def getGeometryType():
        """
        Returns the geometry type string defined for this layer.
        """
    
    def setGeometryType(geometry):
        """
        Sets the geometry type for this layer. All the spatial data objects
        used as data for this layer should have the same type.
        
        Parameters
        ----------
        geometry : string
            Either 'POINT', 'LINE' or 'POLYGON'.
            
        """
    
    def getDefaultContentType():
        """
        Returns the name of the default content type for this layer.
        """
    
    def setDefaultContentType(typename):
        """
        Sets the default content type for this layer.
        
        When a user adds a new feature to this layer through the map UI, an
        object of this type will be created.
        
        Parameters
        ----------
        typename : string
            Name of the default content type. This type must implement the
            IGeoAware interface.
        """
    
    def getSpatialReferenceCode():
        """
        Returns the spatial reference code defined for this layer. This can
        either be an EPSG code, e.g. "EPSG:4326", or a white-space separated list
        of PROJ.4 parameters, e.g. "proj=latlong datum=WGS84".
        """
    
    def setSpatialReferenceCode(code):
        """
        Sets the spatial reference code for this layer. This can
        either be an EPSG code, e.g. "EPSG:4326", or a white-space separated list
        of PROJ.4 parameters, e.g. "proj=latlong datum=WGS84".
        
        Parameters
        ----------
        code : string
            Either an EPSG code or PROJ.4 parameters.
        """

    def getSpatialReference():
        """
        Returns an instance of cartography.referencing.srs.SpatialReference
        initialized with the values set for this layer.
        """
    
    def getSpatialData():
        """
        Returns the spatial data for this layer as a list of objects that
        implement the IGeoAware interface.
        
        Note! The list of objects is subject to the workflow state of each
        individual object and the results may vary depending on the access
        rights of the user accessing this method.
        
        See also PrimaGIS.config.ACTIVE_WORKFLOW_STATE.
        """
    
class IPrimaGISSession(Interface):
    """
    User session interface.
    """

    def revertView():
        """
        Reverts the current map extent to its previous value, saving the current
        value in the user session.
        
        Calling this method in succession will oscillate between the two
        previous map extents.
        """
    
    def setDefaultView(bbox=None):
        """
        Sets the default map extent for the duration of this user session. This
        does not affect the map default extent shown when users access the map
        for the first time.
        
        Parameters
        ----------
        bbox : cartography.spatial.BoundingBox (optional)
            The bounding box used as the new default view, if omitted then the
            current map extent will be used.
        """

    def setPreviousView(bbox=None):
        """
        Stores a view in the session that can be reverted to by using the
        IPrimaGISSession.revertView() method.
        
        Parameters
        ----------
        bbox : cartography.spatial.BoundingBox (optional)
            The bounding box stored as the previous view, if omitted then the
            current map extent will be used.
        """
        
    def setView(bbox):
        """
        Sets the current map extent.
        
        Parameters
        ----------
        bbox : cartography.spatial.BoundingBox
            The bounding box defining the new map extent.
        """

    def resetView():
        """
        Resets the map extent to the default value. If the user has saved a
        session specific default value, then this will be used. Otherwise the
        default extent for the map will be used.
        """

    def getView():
        """
        Returns a cartography.spatial.BoundingBox object defining the current
        map extent.
        """
    
    def isIsomorphic(bbox=None):
        """
        Checks whether the given bounding box and map image size are
        isomorphic (same width to height ratio).
        
        Parameters
        ----------
        bbox : cartography.spatial.BoundingBox
            The bounding box to check. If omitted then the current map
            extent will be used.
        """
    
    def normalizeView(bbox=None):
        """
        Normalizes the given bounding box so that it is isomorphic (matching
        width / height ratio) with the current image size.
        
        Parameters
        ----------
        bbox : cartography.spatial.BoundingBox
            The bounding box to normalize. If omitted then the current map
            extent will be used.
        """

    def setSize(width, height):
        """
        Sets the map image size in pixels.
        Maintains the isomorphism by normalizing the current map extent.
        
        Parameters
        ----------
        width : int
            Map width in pixels.
            
        height : int
            Map height in pixels.
        """

    def getSize():
        """
        Returns the current image pixel size as a tuple (width, height).
        """
    
    def setActiveLayers(layers):
        """
        Sets the active layers for the session.
        
        Parameters
        ----------
        layers : []
            List of active layers.
        """
    
    def getActiveLayers():
        """
        Returns a list of ZCO Layer or ZCO Style objects that are active in the
        current session. Maintains the ordering defined in the Plone UI.
        """
    
    def getLegendLayers():
        """
        Returns a list of layers whose symbols should be drawn in the map
        legend.
        """
    
    def inView(point):
        """
        Checks whether the given point is contained within the current map
        extent. Returns True if the point is within the current extent, False
        otherwise.
        
        Parameters
        ----------
        point : cartography.spatial.Point
            The point that is to be checked.
        """
    
    def isActiveLayer(