render.py

Go to the documentation of this file.

"""!
@package core.render

@brief Rendering map layers and overlays into map composition image.

Classes:
 - render::Layer
 - render::MapLayer
 - render::Overlay
 - render::Map

(C) 2006-2013 by the GRASS Development Team

This program is free software under the GNU General Public License
(>=v2). Read the file COPYING that comes with GRASS for details.

@author Michael Barton
@author Jachym Cepicky
@author Martin Landa <landa.martin gmail.com>
"""

import os
import sys
import glob
import math
import copy
import tempfile
import types

import wx
from wx.lib.newevent import NewEvent

from grass.script import core as grass

from core          import utils
from core.gcmd     import GException, GError, RunCommand
from core.debug    import Debug
from core.settings import UserSettings

wxUpdateProgressBar, EVT_UPDATE_PRGBAR = NewEvent()

#
# use g.pnmcomp for creating image composition or
# wxPython functionality
#
USE_GPNMCOMP = True

class Layer(object):
    """!Virtual class which stores information about layers (map layers and
    overlays) of the map composition.
    
    For map layer use MapLayer class.
    For overlays use Overlay class.
    """
    def __init__(self, type, cmd, name = None,
                 active = True, hidden = False, opacity = 1.0):
        """!
        @todo pass cmd as tuple instead of list
        
        @param type layer type ('raster', 'vector', 'overlay', 'command', etc.)
        @param cmd GRASS command to render layer,
        given as list, e.g. ['d.rast', 'map=elevation@PERMANENT']
        @param name layer name, e.g. 'elevation@PERMANENT' (for layer tree)
        @param active layer is active, will be rendered only if True
        @param hidden layer is hidden, won't be listed in Layer Manager if True
        @param opacity layer opacity <0;1>
        """
        self.type  = type
        self.name  = name
        
        if self.type == 'command':
            self.cmd = list()
            for c in cmd:
                self.cmd.append(utils.CmdToTuple(c))
        else:
            self.cmd = utils.CmdToTuple(cmd)
        
        self.active  = active
        self.hidden  = hidden
        self.opacity = opacity
        
        self.force_render = True
        
        Debug.msg (3, "Layer.__init__(): type=%s, cmd='%s', name=%s, " \
                       "active=%d, opacity=%d, hidden=%d" % \
                       (self.type, self.GetCmd(string = True), self.name, self.active,
                        self.opacity, self.hidden))
        
        # generated file for each layer
        if self.type == 'overlay':
            tempfile_sfx = ".png"
        else:
            tempfile_sfx = ".ppm"
        mapfile = tempfile.NamedTemporaryFile(suffix=tempfile_sfx, delete=False)
        # we don't want it open, we just need the name
        self.mapfile = mapfile.name
        mapfile.close()
        # do we need to `touch` the maskfile so it exists?
        self.maskfile = self.mapfile.rsplit(".",1)[0] + ".pgm"

    def __del__(self):
        Debug.msg (3, "Layer.__del__(): layer=%s, cmd='%s'" %
                   (self.name, self.GetCmd(string = True)))

    def Render(self):
        """!Render layer to image
        
        @return rendered image filename
        @return None on error
        """
        if not self.cmd:
            return None
        
        # ignore in 2D
        if self.type == '3d-raster':
            return None
        
        Debug.msg (3, "Layer.Render(): type=%s, name=%s" % \
                       (self.type, self.name))
        
        # prepare command for each layer
        layertypes = ('raster', 'rgb', 'his', 'shaded', 'rastarrow', 'rastnum',
                      'vector','thememap','themechart',
                      'grid', 'geodesic', 'rhumb', 'labels',
                      'command', 'rastleg',
                      'overlay')
        
        if self.type not in layertypes:
            raise GException(_("<%(name)s>: layer type <%(type)s> is not supported") % \
                                 {'type' : self.type, 'name' : self.name})

        # start monitor
        if not self.mapfile:
            if self.type == 'overlay':
                tempfile_sfx =".png"
            else:
                tempfile_sfx =".ppm"
            mapfile = tempfile.NamedTemporaryFile(suffix=tempfile_sfx, delete=False)
            # we don't want it open, we just need the name
            self.mapfile = mapfile.name
            mapfile.close()
            self.maskfile = self.mapfile.rsplit(".",1)[0] + ".pgm"

        if UserSettings.Get(group='display', key='driver', subkey='type') == 'cairo':
            if self.mapfile:
                os.environ["GRASS_CAIROFILE"] = self.mapfile

# FIXME: the second RunCommand() here locks up the GUI, need to use 'xkill' to recover.
#        the first one works as expected.
#            if 'cairo' not in RunCommand('d.mon', flags='p', read = True):
#                RunCommand('d.mon', start = 'cairo', select = 'cairo')
        else:
            if self.mapfile:
                os.environ["GRASS_PNGFILE"] = self.mapfile
        
        # execute command
        try:
            if self.type == 'command':
                read = False
                for c in self.cmd:
                    ret, msg = RunCommand(c[0],
                                          getErrorMsg = True,
                                          quiet = True,
                                          **c[1])
                    if ret != 0:
                        break
                    if not read:
                        os.environ["GRASS_PNG_READ"] = "TRUE"
                
                os.environ["GRASS_PNG_READ"] = "FALSE"
            else:
                ret, msg = RunCommand(self.cmd[0],
                                      getErrorMsg = True,
                                      quiet = True,
                                      **self.cmd[1])
            
            if ret != 0:
                sys.stderr.write(_("Command '%s' failed\n") % self.GetCmd(string = True))
                if msg:
                    sys.stderr.write(_("Details: %s\n") % msg)
                raise GException()
        
        except GException:
            # clean up after problems
            try:
                os.remove(self.mapfile)
                os.remove(self.maskfile)
                os.remove(self.gtemp)
            except (OSError, TypeError):
                pass
            self.mapfile = None
            self.maskfile = None
        
        # stop monitor
        if UserSettings.Get(group='display', key='driver', subkey='type') == 'cairo':
# FIXME:
#            ret, msg = RunCommand('d.mon', stop = 'cairo', getErrorMsg = True)
#            if ret != 0:
#                sys.stderr.write(_("Closing Cairo driver failed\n"))
#                if msg:
#                    sys.stderr.write(_("Details: %s\n") % msg)
            del os.environ["GRASS_CAIROFILE"]

        elif "GRASS_PNGFILE" in os.environ:
            del os.environ["GRASS_PNGFILE"]
        
        self.force_render = False
        
        return self.mapfile
    
    def GetCmd(self, string = False):
        """!Get GRASS command as list of string.
        
        @param string get command as string if True otherwise as list
        
        @return command list/string
        """
        if string:
            if self.type == 'command':
                scmd = []
                for c in self.cmd:
                    scmd.append(utils.GetCmdString(c))
                
                return ';'.join(scmd)
            else:
                return utils.GetCmdString(self.cmd)
        else:
            return self.cmd

    def GetType(self):
        """!Get map layer type"""
        return self.type
    
    def GetElement(self):
        """!Get map element type"""
        if self.type == 'raster':
            return 'cell'
        return self.type
    
    def GetOpacity(self, float = False):
        """
        Get layer opacity level
        
        @param float get opacity level in <0,1> otherwise <0,100>
        
        @return opacity level
        """
        if float:
            return self.opacity
        
        return int (self.opacity * 100)

    def GetName(self, fullyQualified = True):
        """!Get map layer name

        @param fullyQualified True to return fully qualified name as a
        string 'name@mapset' otherwise directory { 'name', 'mapset' }
        is returned

        @return string / directory
        """
        if fullyQualified:
            return self.name
        else:
            if '@' in self.name:
                return { 'name' : self.name.split('@')[0],
                         'mapset' : self.name.split('@')[1] }
            else:
                return { 'name' : self.name,
                         'mapset' : '' }
        
    def IsActive(self):
        """!Check if layer is activated for rendering"""
        return self.active
    
    def SetType(self, type):
        """!Set layer type"""
        if type not in ('raster', '3d-raster', 'vector',
                        'overlay', 'command',
                        'shaded', 'rgb', 'his', 'rastarrow', 'rastnum',
                        'thememap', 'themechart', 'grid', 'labels',
                        'geodesic','rhumb'):
            raise GException(_("Unsupported map layer type '%s'") % type)
        
        self.type = type

    def SetName(self, name):
        """!Set layer name"""
        self.name = name
        
    def SetActive(self, enable = True):
        """!Active or deactive layer"""
        self.active = bool(enable)

    def SetHidden(self, enable = False):
        """!Hide or show map layer in Layer Manager"""
        self.hidden = bool(enable)

    def SetOpacity(self, value):
        """!Set opacity value"""
        if value < 0:
            value = 0.
        elif value > 1:
            value = 1.
        
        self.opacity = float(value)
        
    def SetCmd(self, cmd):
        """!Set new command for layer"""
        if self.type == 'command':
            self.cmd = []
            for c in cmd:
                self.cmd.append(utils.CmdToTuple(c))
        else:
            self.cmd = utils.CmdToTuple(cmd)
        Debug.msg(3, "Layer.SetCmd(): cmd='%s'" % self.GetCmd(string = True))
        
        # for re-rendering
        self.force_render = True
        
class MapLayer(Layer):
    def __init__(self, type, cmd, name = None,
                 active = True, hidden = False, opacity = 1.0): 
        """!Represents map layer in the map canvas
        
        @param type layer type ('raster', 'vector', 'command', etc.)
        @param cmd GRASS command to render layer,
        given as list, e.g. ['d.rast', 'map=elevation@PERMANENT']
        @param name layer name, e.g. 'elevation@PERMANENT' (for layer tree) or None
        @param active layer is active, will be rendered only if True
        @param hidden layer is hidden, won't be listed in Layer Manager if True
        @param opacity layer opacity <0;1>
        """
        Layer.__init__(self, type, cmd, name,
                       active, hidden, opacity)
        
    def GetMapset(self):
        """!Get mapset of map layer
        
        @return mapset name
        @return '' on error (no name given)
        """
        if not self.name:
            return ''
        
        try:
            return self.name.split('@')[1]
        except IndexError:
            return self.name
        
class Overlay(Layer):
    def __init__(self, id, type, cmd,
                 active = True, hidden = True, opacity = 1.0):
        """!Represents overlay displayed in map canvas
        
        @param id overlay id (for PseudoDC)
        @param type overlay type ('barscale', 'legend', etc.)
        @param cmd GRASS command to render overlay,
        given as list, e.g. ['d.legend', 'map=elevation@PERMANENT']
        @param active layer is active, will be rendered only if True
        @param hidden layer is hidden, won't be listed in Layer Manager if True
        @param opacity layer opacity <0;1>
        """
        Layer.__init__(self, 'overlay', cmd, type,
                       active, hidden, opacity)
        
        self.id = id
        
class Map(object):
    """!Map composition (stack of map layers and overlays)
    """
    def __init__(self, gisrc = None):
        # region/extent settigns
        self.wind      = dict() # WIND settings (wind file)
        self.region    = dict() # region settings (g.region)
        self.width     = 640    # map width
        self.height    = 480    # map height
        
        # list of layers
        self.layers    = list()  # stack of available GRASS layer
        
        self.overlays  = list()  # stack of available overlays
        self.ovlookup  = dict()  # lookup dictionary for overlay items and overlays
        
        # environment settings
        # environment variables, like MAPSET, LOCATION_NAME, etc.
        self.env   = dict()
        # path to external gisrc
        self.gisrc = gisrc
        
        # generated file for g.pnmcomp output for rendering the map
        mapfile = tempfile.NamedTemporaryFile(suffix='.ppm', delete=False)
        # we don't want it open, we just need the name
        self.mapfile = mapfile.name
        mapfile.close()
        
        # setting some initial env. variables
        self._initGisEnv() # g.gisenv
        self.GetWindow()
        # GRASS environment variable (for rendering)
        os.environ["GRASS_TRANSPARENT"] = "TRUE"
        os.environ["GRASS_BACKGROUNDCOLOR"] = "ffffff"
        
        # projection info
        self.projinfo = self._projInfo()
        
    def _runCommand(self, cmd, **kwargs):
        """!Run command in environment defined by self.gisrc if
        defined"""
        # use external gisrc if defined
        gisrc_orig = os.getenv("GISRC")
        if self.gisrc:
            os.environ["GISRC"] = self.gisrc
        
        ret = cmd(**kwargs)
        
        # back to original gisrc
        if self.gisrc:
            os.environ["GISRC"] = gisrc_orig
        
        return ret
    
    def _initGisEnv(self):
        """!Stores GRASS variables (g.gisenv) to self.env variable
        """
        if not os.getenv("GISBASE"):
            sys.exit(_("GISBASE not set. You must be in GRASS GIS to run this program."))
        
        self.env = self._runCommand(grass.gisenv)
            
    def GetProjInfo(self):
        """!Get projection info"""
        return self.projinfo
    
    def _projInfo(self):
        """!Return region projection and map units information
        """
        projinfo = dict()
        if not grass.find_program('g.proj', ['--help']):
            sys.exit(_("GRASS module '%s' not found. Unable to start map "
                       "display window.") % 'g.proj')
        
        ret = self._runCommand(RunCommand, prog = 'g.proj',
                               read = True, flags = 'p')
        
        if not ret:
            return projinfo
        
        for line in ret.splitlines():
            if ':' in line:
                key, val = map(lambda x: x.strip(), line.split(':'))
                if key in ['units']:
                    val = val.lower()
                projinfo[key] = val
            elif "XY location (unprojected)" in line:
                projinfo['proj'] = 'xy'
                projinfo['units'] = ''
                break
        
        return projinfo
    
    def GetWindow(self):
        """!Read WIND file and set up self.wind dictionary"""
        # FIXME: duplicated region WIND == g.region (at least some values)
        filename = os.path.join (self.env['GISDBASE'],
                                 self.env['LOCATION_NAME'],
                                 self.env['MAPSET'],
                                 "WIND")
        try:
            windfile = open (filename, "r")
        except IOError, e:
            sys.exit(_("Error: Unable to open '%(file)s'. Reason: %(ret)s. wxGUI exited.\n") % \
                         { 'file' : filename, 'ret' : e})
        
        for line in windfile.readlines():
            line = line.strip()
            key, value = line.split(":", 1)
            self.wind[key.strip()] = value.strip()
        
        windfile.close()
        
        return self.wind
        
    def AdjustRegion(self):
        """!Adjusts display resolution to match monitor size in
        pixels. Maintains constant display resolution, not related to
        computational region. Do NOT use the display resolution to set
        computational resolution. Set computational resolution through
        g.region.
        """
        mapwidth    = abs(self.region["e"] - self.region["w"])
        mapheight   = abs(self.region['n'] - self.region['s'])
        
        self.region["nsres"] =  mapheight / self.height
        self.region["ewres"] =  mapwidth  / self.width
        self.region['rows']  = round(mapheight / self.region["nsres"])
        self.region['cols']  = round(mapwidth / self.region["ewres"])
        self.region['cells'] = self.region['rows'] * self.region['cols']
        
        Debug.msg (3, "Map.AdjustRegion(): %s" % self.region)
        
        return self.region

    def AlignResolution(self):
        """!Sets display extents to even multiple of current
        resolution defined in WIND file from SW corner. This must be
        done manually as using the -a flag can produce incorrect
        extents.
        """
        # new values to use for saving to region file
        new = {}
        n = s = e = w = 0.0
        nwres = ewres = 0.0
        
        # Get current values for region and display
        reg = self.GetRegion()
        nsres = reg['nsres']
        ewres = reg['ewres']
        
        n = float(self.region['n'])
        s = float(self.region['s'])
        e = float(self.region['e'])
        w = float(self.region['w'])
        
        # Calculate rows, columns, and extents
        new['rows'] = math.fabs(round((n-s)/nsres))
        new['cols'] = math.fabs(round((e-w)/ewres))
        
        # Calculate new extents
        new['s'] = nsres * round(s / nsres)
        new['w'] = ewres * round(w / ewres)
        new['n'] = new['s'] + (new['rows'] * nsres)
        new['e'] = new['w'] + (new['cols'] * ewres)
        
        return new

    def AlignExtentFromDisplay(self):
        """!Align region extent based on display size from center
        point"""
        # calculate new bounding box based on center of display
        if self.region["ewres"] > self.region["nsres"]:
            res = self.region["ewres"]
        else:
            res = self.region["nsres"]
        
        Debug.msg(3, "Map.AlignExtentFromDisplay(): width=%d, height=%d, res=%f, center=%f,%f" % \
                      (self.width, self.height, res, self.region['center_easting'],
                       self.region['center_northing']))
            
        ew = (self.width / 2) * res
        ns = (self.height / 2) * res
        
        self.region['n'] = self.region['center_northing'] + ns
        self.region['s'] = self.region['center_northing'] - ns
        self.region['e'] = self.region['center_easting'] + ew
        self.region['w'] = self.region['center_easting'] - ew
        
        # LL locations
        if self.projinfo['proj'] == 'll':
            self.region['n'] = min(self.region['n'], 90.0)
            self.region['s'] = max(self.region['s'], -90.0)
        
    def ChangeMapSize(self, (width, height)):
        """!Change size of rendered map.
        
        @param width,height map size given as tuple

        @return True on success
        @return False on failure
        """
        try:
            self.width  = int(width)
            self.height = int(height)
            
            if self.width < 1 or self.height < 1:
                sys.stderr.write(_("Invalid map size %d,%d\n") % (self.width, self.height))
                raise ValueError
        except ValueError:
            self.width  = 640
            self.height = 480
        
        Debug.msg(2, "Map.ChangeMapSize(): width=%d, height=%d" % \
                      (self.width, self.height))
        
    def GetRegion(self, rast = [], zoom = False, vect = [], regionName = None,
                  n = None, s = None, e = None, w = None, default = False,
                  update = False):
        """!Get region settings (g.region -upgc)
        
        Optionally extent, raster or vector map layer can be given.
        
        @param rast list of raster maps
        @param zoom zoom to raster map (ignore NULLs)
        @param vect list of vector maps
        @param regionName  named region or None
        @param n,s,e,w force extent
        @param default force default region settings
        @param update if True update current display region settings
        
        @return region settings as directory, e.g. {
        'n':'4928010', 's':'4913700', 'w':'589980',...}
        
        @see GetCurrentRegion()
        """
        region = {}
        
        tmpreg = os.getenv("GRASS_REGION")
        if tmpreg:
            del os.environ["GRASS_REGION"]
        
        # use external gisrc if defined
        gisrc_orig = os.getenv("GISRC")
        if self.gisrc:
            os.environ["GISRC"] = self.gisrc
        
        # do not update & shell style output
        cmd = {}
        cmd['flags'] = 'ugpc'
        
        if default:
            cmd['flags'] += 'd'
        
        if regionName:
            cmd['region'] = regionName
        
        if n:
            cmd['n'] = n
        if s:
            cmd['s'] = s
        if e:
            cmd['e'] = e
        if w:
            cmd['w'] = w
        
        if rast:
            if zoom:
                cmd['zoom'] = rast[0]
            else:
                cmd['rast'] = ','.join(rast)
        
        if vect:
            cmd['vect'] = ','.join(vect)
        
        ret, reg, msg = RunCommand('g.region',
                                   read = True,
                                   getErrorMsg = True,
                                   **cmd)
        
        if ret != 0:
            if rast:
                message = _("Unable to zoom to raster map <%s>.") % rast[0] + \
                    "\n\n" + _("Details:") + " %s" % msg
            elif vect:
                message = _("Unable to zoom to vector map <%s>.") % vect[0] + \
                    "\n\n" + _("Details:") + " %s" % msg
            else:
                message = _("Unable to get current geographic extent. "
                            "Force quiting wxGUI. Please manually run g.region to "
                            "fix the problem.")
            GError(message)
            return self.region
        
        for r in reg.splitlines():
            key, val = r.split("=", 1)
            try:
                region[key] = float(val)
            except ValueError:
                region[key] = val
        
        # back to original gisrc
        if self.gisrc:
            os.environ["GISRC"] = gisrc_orig
        
        # restore region
        if tmpreg:
            os.environ["GRASS_REGION"] = tmpreg
        
        Debug.msg (3, "Map.GetRegion(): %s" % region)
        
        if update:
            self.region = region
        
        return region

    def GetCurrentRegion(self):
        """!Get current display region settings
        
        @see GetRegion()
        """
        return self.region

    def SetRegion(self, windres = False):
        """!Render string for GRASS_REGION env. variable, so that the
        images will be rendered from desired zoom level.
        
        @param windres uses resolution from WIND file rather than
        display (for modules that require set resolution like
        d.rast.num)

        @return String usable for GRASS_REGION variable or None
        """
        grass_region = ""
        
        if windres:
            compRegion = self.GetRegion()
            region = copy.copy(self.region)
            for key in ('nsres', 'ewres', 'cells'):
                region[key] = compRegion[key]
        else:
            # adjust region settings to match monitor
            region = self.AdjustRegion()
        
        # read values from wind file
        try:
            for key in self.wind.keys():
                if key == 'north':
                    grass_region += "north: %s; " % \
                        (region['n'])
                    continue
                elif key == "south":
                    grass_region += "south: %s; " % \
                        (region['s'])
                    continue
                elif key == "east":
                    grass_region += "east: %s; " % \
                        (region['e'])
                    continue
                elif key == "west":
                    grass_region += "west: %s; " % \
                        (region['w'])
                    continue
                elif key == "e-w resol":
                    grass_region += "e-w resol: %f; " % \
                        (region['ewres'])
                    continue
                elif key == "n-s resol":
                    grass_region += "n-s resol: %f; " % \
                        (region['nsres'])
                    continue
                elif key == "cols":
                    if windres:
                        continue
                    grass_region += 'cols: %d; ' % \
                        region['cols']
                    continue
                elif key == "rows":
                    if windres:
                        continue
                    grass_region += 'rows: %d; ' % \
                        region['rows']
                    continue
                else:
                    grass_region += key + ": "  + self.wind[key] + "; "
            
            Debug.msg (3, "Map.SetRegion(): %s" % grass_region)
            
            return grass_region
        
        except:
            return None
        
    def GetListOfLayers(self, l_type = None, l_mapset = None, l_name = None,
                        l_active = None, l_hidden = None):
        """!Returns list of layers of selected properties or list of
        all layers.

        @param l_type layer type, e.g. raster/vector/wms/overlay (value or tuple of values)
        @param l_mapset all layers from given mapset (only for maplayers)
        @param l_name all layers with given name
        @param l_active only layers with 'active' attribute set to True or False
        @param l_hidden only layers with 'hidden' attribute set to True or False
        
        @return list of selected layers
        """
        selected = []
        
        if type(l_type) == types.StringType:
            one_type = True
        else:
            one_type = False
        
        if one_type and l_type == 'overlay':
            llist = self.overlays
        else:
            llist = self.layers
        
        # ["raster", "vector", "wms", ... ]
        for layer in llist:
            # specified type only
            if l_type != None:
                if one_type and layer.type != l_type:
                    continue
                elif not one_type and layer.type not in l_type:
                    continue
            
            # mapset
            if (l_mapset != None and l_type != 'overlay') and \
                    layer.GetMapset() != l_mapset:
                continue
            
            # name
            if l_name != None and layer.name != l_name:
                continue
            
            # hidden and active layers
            if l_active != None and \
                   l_hidden != None:
                if layer.active == l_active and \
                       layer.hidden == l_hidden:
                    selected.append(layer)
            
            # active layers
            elif l_active != None:
                if layer.active == l_active:
                    selected.append(layer)
            
            # hidden layers
            elif l_hidden != None:
                if layer.hidden == l_hidden:
                    selected.append(layer)
            
            # all layers
            else:
                selected.append(layer)
        
        Debug.msg (3, "Map.GetListOfLayers(): numberof=%d" % len(selected))
        
        return selected

    def _renderLayers(self, force, mapWindow, maps, masks, opacities):
        # render map layers
        ilayer = 1
        for layer in self.layers + self.overlays:
            # skip dead or disabled map layers
            if layer == None or layer.active == False:
                continue
            
            # render if there is no mapfile
            if force or \
               layer.force_render or \
               layer.mapfile == None or \
               (not os.path.isfile(layer.mapfile) or not os.path.getsize(layer.mapfile)):
                if not layer.Render():
                    continue
            
            if mapWindow:
                # update progress bar
                ### wx.SafeYield(mapWindow)
                event = wxUpdateProgressBar(value = ilayer)
                wx.PostEvent(mapWindow, event)
            
            # add image to compositing list
            if layer.type != "overlay":
                maps.append(layer.mapfile)
                masks.append(layer.maskfile)
                opacities.append(str(layer.opacity))
                
            Debug.msg (3, "Map.Render() type=%s, layer=%s " % (layer.type, layer.name))
            ilayer += 1
        
    def Render(self, force = False, mapWindow = None, windres = False):
        """!Creates final image composite
        
        This function can conditionaly use high-level tools, which
        should be avaliable in wxPython library
        
        @param force force rendering
        @param reference for MapFrame instance (for progress bar)
        @param windres use region resolution (True) otherwise display resolution
        
        @return name of file with rendered image or None
        """
        maps = []
        masks = []
        opacities = []

        wx.BeginBusyCursor()
        # use external gisrc if defined
        gisrc_orig = os.getenv("GISRC")
        if self.gisrc:
            os.environ["GISRC"] = self.gisrc
        
        tmp_region = os.getenv("GRASS_REGION")
        os.environ["GRASS_REGION"] = self.SetRegion(windres)
        os.environ["GRASS_WIDTH"]  = str(self.width)
        os.environ["GRASS_HEIGHT"] = str(self.height)
        if UserSettings.Get(group='display', key='driver', subkey='type') == 'cairo':
            os.environ["GRASS_AUTO_WRITE"] = "TRUE"
            # in GRASS 6, RENDER_IMMEDIATE always triggers the PNG driver
            if "GRASS_RENDER_IMMEDIATE" in os.environ:
                del os.environ["GRASS_RENDER_IMMEDIATE"]
        else:
            os.environ["GRASS_PNG_AUTO_WRITE"] = "TRUE"
            os.environ["GRASS_PNG_READ"] = "FALSE"
            os.environ["GRASS_PNG_COMPRESSION"] = "0"
            os.environ["GRASS_TRUECOLOR"] = "TRUE"
            os.environ["GRASS_RENDER_IMMEDIATE"] = "TRUE"
        
        self._renderLayers(force, mapWindow, maps, masks, opacities)
        
        # ugly hack for MSYS
        if sys.platform != 'win32':
            mapstr = ",".join(maps)
            maskstr = ",".join(masks)
            mapoutstr = self.mapfile
        else:
            mapstr = ""
            for item in maps:
                mapstr += item.replace('\\', '/')               
            mapstr = mapstr.rstrip(',')
            maskstr = ""
            for item in masks:
                maskstr += item.replace('\\', '/')
            maskstr = maskstr.rstrip(',')
            mapoutstr = self.mapfile.replace('\\', '/')
        
        # compose command
        bgcolor = ':'.join(map(str, UserSettings.Get(group = 'display', key = 'bgcolor',
                                                     subkey = 'color')))
        
        # render overlays
        if tmp_region:
            os.environ["GRASS_REGION"] = tmp_region
        else:
            del os.environ["GRASS_REGION"]
        
        if maps:
            # run g.pngcomp to get composite image
            ret, msg = RunCommand('g.pnmcomp',
                                  getErrorMsg = True,
                                  input = '%s' % ",".join(maps),
                                  mask = '%s' % ",".join(masks),
                                  opacity = '%s' % ",".join(opacities),
                                  background = bgcolor,
                                  width = self.width,
                                  height = self.height,
                                  output = self.mapfile)
            
            if ret != 0:
                print >> sys.stderr, _("ERROR: Rendering failed. Details: %s") % msg
                wx.EndBusyCursor()
                return None
            
            Debug.msg (3, "Map.Render() force=%s file=%s" % (force, self.mapfile))
        
        # back to original gisrc
        if self.gisrc:
            os.environ["GISRC"] = gisrc_orig
        
        wx.EndBusyCursor()
        if not maps:
            return None
        
        return self.mapfile

    def AddLayer(self, type, command, name = None,
                 l_active = True, l_hidden = False, l_opacity = 1.0, l_render = False,
                 pos = -1):
        """!Adds generic map layer to list of layers
        
        @param type layer type ('raster', 'vector', etc.)
        @param command  GRASS command given as list
        @param name layer name
        @param l_active layer render only if True
        @param l_hidden layer not displayed in layer tree if True
        @param l_opacity opacity level range from 0(transparent) - 1(not transparent)
        @param l_render render an image if True
        @param pos position in layer list (-1 for append)
        
        @return new layer on success
        @return None on failure
        """
        wx.BeginBusyCursor()
        # l_opacity must be <0;1>
        if l_opacity < 0: l_opacity = 0
        elif l_opacity > 1: l_opacity = 1
        layer = MapLayer(type = type, name = name, cmd = command,
                         active = l_active, hidden = l_hidden, opacity = l_opacity)
        
        # add maplayer to the list of layers
        if pos > -1:
            self.layers.insert(pos, layer)
        else:
            self.layers.append(layer)
        
        Debug.msg (3, "Map.AddLayer(): layer=%s" % layer.name)
        if l_render:
            if not layer.Render():
                raise GException(_("Unable to render map layer <%s>.") % name)
        
        wx.EndBusyCursor()

        return layer

    def DeleteLayer(self, layer, overlay = False):
        """!Removes layer from list of layers
        
        @param layer layer instance in layer tree
        @param overlay delete overlay (use self.DeleteOverlay() instead)

        @return removed layer on success or None
        """
        Debug.msg (3, "Map.DeleteLayer(): name=%s" % layer.name)
        
        if overlay:
            list = self.overlays
        else:
            list = self.layers
        
        if layer in list:
            if layer.mapfile:
                base = os.path.split(layer.mapfile)[0]
                mapfile = os.path.split(layer.mapfile)[1]
                tempbase = mapfile.split('.')[0]
                if base == '' or tempbase == '':
                    return None
                basefile = os.path.join(base, tempbase) + r'.*'
                for f in glob.glob(basefile):
                    os.remove(f)
            list.remove(layer)
            
            return layer
        
        return None

    def ReorderLayers(self, layerList):
        """!Reorder list to match layer tree
        
        @param layerList list of layers
        """
        self.layers = layerList
        
        layerNameList = ""
        for layer in self.layers:
            if layer.name:
                layerNameList += layer.name + ','
        Debug.msg (4, "Map.ReoderLayers(): layers=%s" % \
                   (layerNameList))
        
    def ChangeLayer(self, layer, render = False, **kargs):
        """!Change map layer properties

        @param layer map layer instance
        @param type layer type ('raster', 'vector', etc.)
        @param command  GRASS command given as list
        @param name layer name
        @param active layer render only if True
        @param hidden layer not displayed in layer tree if True
        @param opacity opacity level range from 0(transparent) - 1(not transparent)
        @param render render an image if True
        """
        Debug.msg (3, "Map.ChangeLayer(): layer=%s" % layer.name)
        
        if 'type' in kargs:
            layer.SetType(kargs['type']) # check type
        
        if 'command' in kargs:
            layer.SetCmd(kargs['command'])
        
        if 'name' in kargs:
            layer.SetName(kargs['name'])
        
        if 'active' in kargs:
            layer.SetActive(kargs['active'])
        
        if 'hidden' in kargs:
            layer.SetHidden(kargs['hidden'])
        
        if 'opacity' in kargs:
            layer.SetOpacity(kargs['opacity'])
        
        if render and not layer.Render():
            raise GException(_("Unable to render map layer <%s>.") % 
                             name)
        
        return layer

    def ChangeOpacity(self, layer, l_opacity):
        """!Changes opacity value of map layer

        @param layer layer instance in layer tree
        @param l_opacity opacity level <0;1>
        """
        # l_opacity must be <0;1>
        if l_opacity < 0: l_opacity = 0
        elif l_opacity > 1: l_opacity = 1
        
        layer.opacity = l_opacity
        Debug.msg (3, "Map.ChangeOpacity(): layer=%s, opacity=%f" % \
                   (layer.name, layer.opacity))

    def ChangeLayerActive(self, layer, active):
        """!Enable or disable map layer
        
        @param layer layer instance in layer tree
        @param active to be rendered (True)
        """
        layer.active = active
        
        Debug.msg (3, "Map.ChangeLayerActive(): name='%s' -> active=%d" % \
                   (layer.name, layer.active))

    def ChangeLayerName (self, layer, name):
        """!Change name of the layer
        
        @param layer layer instance in layer tree
        @param name  layer name to set up
        """
        Debug.msg (3, "Map.ChangeLayerName(): from=%s to=%s" % \
                   (layer.name, name))
        layer.name =  name

    def RemoveLayer(self, name = None, id = None):
        """!Removes layer from layer list
        
        Layer is defined by name@mapset or id.
        
        @param name layer name (must be unique)
        @param id layer index in layer list

        @return removed layer on success
        @return None on failure
        """
        # delete by name
        if name:
            retlayer = None
            for layer in self.layers:
                if layer.name == name:
                    retlayer = layer
                    os.remove(layer.mapfile)
                    os.remove(layer.maskfile)
                    self.layers.remove(layer)
                    return layer
        # del by id
        elif id != None:
            return self.layers.pop(id)
        
        return None

    def GetLayerIndex(self, layer, overlay = False):
        """!Get index of layer in layer list.
        
        @param layer layer instace in layer tree
        @param overlay use list of overlays instead
        
        @return layer index
        @return -1 if layer not found
        """
        if overlay:
            list = self.overlay
        else:
            list = self.layers
            
        if layer in list:
            return list.index(layer)
        
        return -1

    def AddOverlay(self, id, type, command,
                   l_active = True, l_hidden = True, l_opacity = 1.0, l_render = False):
        """!Adds overlay (grid, barscale, legend, etc.) to list of
        overlays
        
        @param id overlay id (PseudoDC)
        @param type overlay type (barscale, legend)
        @param command GRASS command to render overlay
        @param l_active overlay activated (True) or disabled (False)
        @param l_hidden overlay is not shown in layer tree (if True)
        @param l_render render an image (if True)
        
        @return new layer on success
        @retutn None on failure
        """
        Debug.msg (2, "Map.AddOverlay(): cmd=%s, render=%d" % (command, l_render))
        overlay = Overlay(id = id, type = type, cmd = command,
                          active = l_active, hidden = l_hidden, opacity = l_opacity)
        
        # add maplayer to the list of layers
        self.overlays.append(overlay)
        
        if l_render and command != '' and not overlay.Render():
            raise GException(_("Unable to render overlay <%s>.") % 
                             name)
        
        return self.overlays[-1]

    def ChangeOverlay(self, id, render = False, **kargs):
        """!Change overlay properities
        
        Add new overlay if overlay with 'id' doesn't exist.
        
        @param id overlay id (PseudoDC)
        @param type overlay type (barscale, legend)
        @param command GRASS command to render overlay
        @param l_active overlay activated (True) or disabled (False)
        @param l_hidden overlay is not shown in layer tree (if True)
        @param l_render render an image (if True)
        
        @return new layer on success
        """
        overlay = self.GetOverlay(id, list = False)
        if  overlay is None:
            overlay = Overlay(id, type = None, cmd = None)
        
        if 'type' in kargs:
            overlay.SetName(kargs['type']) # type -> overlay
        
        if 'command' in kargs:
            overlay.SetCmd(kargs['command'])
        
        if 'active' in kargs:
            overlay.SetActive(kargs['active'])
        
        if 'hidden' in kargs:
            overlay.SetHidden(kargs['hidden'])
        
        if 'opacity' in kargs:
            overlay.SetOpacity(kargs['opacity'])
        
        if render and overlay.GetCmd() != [] and not overlay.Render():
            raise GException(_("Unable to render overlay <%s>.") % 
                             name)
        
        return overlay

    def GetOverlay(self, id, list = False):
        """!Return overlay(s) with 'id'
        
        @param id overlay id
        @param list return list of overlays of True
        otherwise suppose 'id' to be unique
        
        @return list of overlays (list=True)
        @return overlay (list=False)
        @retur None (list=False) if no overlay or more overlays found
        """
        ovl = []
        for overlay in self.overlays:
            if overlay.id == id:
                ovl.append(overlay)
                
        if not list:
            if len(ovl) != 1:
                return None
            else:
                return ovl[0]
        
        return ovl

    def DeleteOverlay(self, overlay):
        """!Delete overlay
        
        @param overlay overlay layer
        
        @return removed overlay on success or None
        """
        return self.DeleteLayer(overlay, overlay = True)

    def Clean(self):
        """!Clean layer stack - go trough all layers and remove them
        from layer list.

        Removes also l_mapfile and l_maskfile
        
        @return False on failure
        @return True on success
        """
        try:
            dir = os.path.dirname(self.mapfile)
            base = os.path.basename(self.mapfile).split('.')[0]
            removepath = os.path.join(dir,base)+r'*'
            for f in glob.glob(removepath):
                os.remove(f)
            for layer in self.layers:
                if layer.mapfile:
                    dir = os.path.dirname(layer.mapfile)
                    base = os.path.basename(layer.mapfile).split('.')[0]
                    removepath = os.path.join(dir,base)+r'*'
                    for f in glob.glob(removepath):
                        os.remove(f)
                self.layers.remove(layer)
            
            for overlay in self.overlays:
                if overlay.mapfile:
                    dir = os.path.dirname(overlay.mapfile)
                    base = os.path.basename(overlay.mapfile).split('.')[0]
                    removepath = os.path.join(dir,base)+r'*'
                    for f in glob.glob(removepath):
                        os.remove(f)
                self.overlays.remove(overlay)
        except:
            return False
        
        return True
    
    def ReverseListOfLayers(self):
        """!Reverse list of layers"""
        return self.layers.reverse()

    def RenderOverlays(self, force):
        """!Render overlays only (for nviz)"""
        for layer in self.overlays:
            if force or layer.force_render:
                layer.Render()
                
if __name__ == "__main__":
    import gettext
    gettext.install('grasswxpy', os.path.join(os.getenv("GISBASE"), 'locale'), unicode = True)
    
    Map = Map()
    Map.GetRegion(update = True)
    
    Map.AddLayer(type = "raster",
                 name = "elevation",
                 command = ["d.rast", "map=elevation@PERMANENT"],
                 l_opacity = .7)
    
    Map.AddLayer(type = "vector",
                 name = "roadsmajor",
                 command = ["d.vect", "map=roadsmajor@PERMANENT", "color=red", "width=3", "type=line"])
    
    image = Map.Render(force = True)
    
    if image:
        grass.call(["display", image])