root/PCL/trunk/PCL-Core/cartography/context/rendering.py

# $Id: rendering.py 498 2006-10-08 05:48:49Z seang $

# =============================================================================
# Python Cartographic Library. Copyright (C) 2004 Sean C. Gillies
#
# This program 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.
#
# This program 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
# this program; if not, write to the Free Software Foundation, Inc., 59 Temple
# Place, Suite 330, Boston, MA 02111-1307 USA
#
# Contact email: sgillies@frii.com
# =============================================================================

from cStringIO import StringIO

from cartography.styles import Style
from cartography.proj import SpatialReference
from cartography.geometry import Point

METERS_PER_DD = 111319.490793

class View:
    
    """Defines the reference system and bounding values of a map view.

    Attributes 
    ----------
    srs : SpatialReference
        spatial reference system
    
    ul : Point
        upper left point of bounding box
    
    lr : Point
        lower right point of bounding box

    units : string
        'DD', 'METERS', or 'FEET'

    """

    def __init__(self, srs, bbox, units='METERS'):
        """Initialize a View.
        
        Expects a SpatialReference, an upper left Point, a lower right Point,
        and a units string.

        Example
        -------
        >>> srs = SpatialReference(epsg=4326)
        >>> view = View(srs, [-110.0, 38.0, -105.0, 42.0], 'DD')

        """
        self.srs = srs
        self.ul = Point(bbox[0], bbox[3])
        self.lr = Point(bbox[2], bbox[1])
        self.units = units.upper()

    def getaspectratio(self):
        """Return spatial width to height ratio"""
        return (self.lr.x - self.ul.x) / (self.ul.y - self.lr.y)

    def getviewforscale(self, scale, size):
        """Returns a new View object initialized at the given scale.
        
        Parameters
        ----------
        scale : float
            Scale denominator.
        
        size : tuple
            Two tuple containing the (width, height) screen size of the view.
        """
        assert scale > 0, "Scale must have value > 0."
        
        # map "screen" width in meters based on a standard 0.28 mm pixel
        half_screen_width = size[0] * 0.00028 * 0.5
        half_screen_height = size[1] * 0.00028 * 0.5
        
        # width on the ground in map units
        ground_width = self.lr.x - self.ul.x
        ground_height = self.ul.y - self.lr.y
        
        # Maintain the same center point with the current view
        center_x = self.ul.x + (ground_width / 2.0)
        center_y = self.lr.y + (ground_height / 2.0)
        
        if self.units == 'METERS':
            dx = half_screen_width * scale
            dy = half_screen_height * scale
        elif self.units == 'DD':
            dx = (half_screen_width * scale) / METERS_PER_DD
            dy = (half_screen_height * scale) / METERS_PER_DD
        elif self.units == 'FEET':
            dx = half_screen_width * scale * 3.28
            dy = half_screen_height * scale * 3.28
        else:
            raise Exception, "Cannot compute new view for %s units" % (self.units)

        bounds = (center_x - dx, center_y - dy, center_x + dx, center_y + dy)
        return View(self.srs, bounds, self.units)
    
    def getscaledenominator(self, size):
        """Return denominator of the view scale

        We assume a standard "screen" pixel size of 0.28 mm x 0.28 mm
        and do not correct for latitude in the case of lat/long projections.
        
        Parameters
        ----------
        size : []
            output image dimensions like [pixels, lines]
        """
        # map "screen" width in meters based on a standard 0.28 mm pixel
        screen_width = size[0] * 0.00028
        
        # width on the ground in map units
        ground_width = self.lr.x - self.ul.x
        
        if self.units == 'METERS':
            return ground_width / screen_width
        elif self.units == 'DD':
            return METERS_PER_DD * ground_width / screen_width
        elif self.units == 'FEET':
            return ground_width / (3.28 * screen_width)
        else:
            raise Exception, "Cannot compute scale for %s units" % (self.units)

    def contains(self, point):
        """Return true if the point is within or on boundary, else false"""
        if point.x <= self.lr.x and point.x >= self.ul.x \
        and point.y <= self.ul.y and point.y >= self.lr.y:
            return True
        else: return False


class Image:
    
    """Map imagery.
    
    Attributes
    ----------
    mimetype : string
        'image/png', 'image/jpeg', 'image/gif'
    data : StringIO
        the image data.
    size : []
        image dimensions in pixels, [width, height]
    """

    def __init__(self, mimetype=''):
        """Initialize an Image.  The mimetype should be like 'image/png'."""
        self.mimetype = mimetype
        self.data = StringIO()
        self.size = []

    def getdata(self):
        """Return image data"""
        return self.data.getvalue()


class ContextLayer(object):
    """A layer of a map context.
    """

    def __init__(self, name, layer, style=None, title=None, visible=True):
        self.name = name
        self.title = title or name
        self.layer = layer
        self.style = style or Style()
        self._visible = bool(visible)

    def _set_visibility(self, v):
        self._visible = bool(v)
        try:
            self.layer.updateVisibility(v)
        except AttributeError:
            pass

    def _get_visibility(self):
        return self._visible

    # Managed attribute
    visible = property(_get_visibility, _set_visibility)
    
        
class MapContext(object):
    """A map context.
    """

    def __init__(self, layers=None):
        """Initialize.

        Parameters
        ----------
        layers : list
            List of ContextLayers.
        """
        if layers is None:
            self._layers = []
        else:
            self._layers = layers
        self._names = [l.name for l in self._layers]
        
        #for layer, style in layering:
        #    # Munge PCL styled layer into a MapServer-like tree
        #    self.ltree.append(_munge_layers(layer, style))
        
    def __getitem__(self, n):
        return self._layers[n]

    def __setitem__(self, n, o):
        if o.name in self._names and o.name != self._layers[n].name:
            raise KeyError, "A context layer with name %s already exists" \
                % o.name
        self._layers[n] = o
        self._names[n] = o.name

    def __delitem__(self, n):
        del self._layers[n]
        del self._names[n]
       
    def __iter__(self):
        return iter(self._layers)

    def __len__(self):
        return len(self._layers)

    def index(self, name):
        return self._names.index(name)

    def insert(self, n, o):
        if o.name in self._names:
            raise KeyError, "A context layer with name %s already exists" \
                % o.name
        self._layers.insert(n, o)
        self._names.insert(n, o.name)

    def append(self, o):
        if o.name in self._names:
            raise KeyError, "A context layer with name %s already exists" \
                % o.name
        self._layers.append(o)
        self._names.append(o.name)


def MapRenderer(engine='mapserver', format='image', **kw):
    """Factory for map renderers.

    Calls the MapRender class of the specified engine module.
    
    Arguments
    ---------
    engine : string
        Mapping engine module name, such as 'mapserver'.  Either case is
        acceptable.
    format : string
        Output format such as 'image'.  Acceptable values depend on the
        particular rendering engine.
    **kw : mapping
        keyword arguments passed to the specific engine's renderer.
    """
    
    try:
        #from cartography.engine.mapserver.rendering import ImageRenderer
        #try:
        #    import pkg_resources
        #    pkg_resources.require("PCL-%s" % engine)
        #except:
        #    pass
        name = 'cartography.engine.%s' % (engine.lower())
        engine_module = __import__(name, globals(), locals(), ['rendering'])
        # presently all we've implemented is an image renderer
        return engine_module.rendering.ImageRenderer(**kw)
    except ImportError:
        raise
        #raise Exception, "No such rendering engine: %s" % (engine.lower())
    except AttributeError, e:
        # a possible cause of this error is lack of mapscript/_mapscript
        if 'mapscript' not in dir(engine_module.rendering):
            raise Exception, \
            "Python mapscript module could not be imported during load of mapping engine. Check that it has been properly installed on your system."
        else:
            raise AttributeError, (str(e), engine.lower(), engine_module.__file__, engine_module.rendering.__file__, engine_module.rendering.__dict__)