[GRASS-SVN] r51061 - grass/branches/develbranch_6/lib/python

[svn_grass at osgeo.org]

Author: martinl
Date: 2012-03-14 15:15:54 -0700 (Wed, 14 Mar 2012)
New Revision: 51061

Modified:
   grass/branches/develbranch_6/lib/python/core.py
   grass/branches/develbranch_6/lib/python/pythonlib.dox
Log:
pythonlib: introduce region_env()
          add 3D support for region()
	  (merge r51058, r51059, r51060 from trunk)


Modified: grass/branches/develbranch_6/lib/python/core.py
===================================================================
--- grass/branches/develbranch_6/lib/python/core.py	2012-03-14 22:13:32 UTC (rev 51060)
+++ grass/branches/develbranch_6/lib/python/core.py	2012-03-14 22:15:54 UTC (rev 51061)
@@ -560,10 +560,12 @@
 
 # interface to g.region
 
-def region():
+def region(region3d = False):
     """!Returns the output from running "g.region -g", as a
     dictionary. Example:
 
+    \param region3d True to get 3D region
+    
     \code
     >>> region = grass.region()
     >>> [region[key] for key in "nsew"]
@@ -574,12 +576,95 @@
 
     @return dictionary of region values
     """
-    s = read_command("g.region", flags='g')
+    flgs = 'g'
+    if region3d:
+        flgs += '3'
+    
+    s = read_command("g.region", flags = flgs)
     reg = parse_key_val(s, val_type = float)
-    for k in ['rows', 'cols']:
+    for k in ['rows',  'cols',  'cells',
+              'rows3', 'cols3', 'cells3', 'depths']:
+        if k not in reg:
+            continue
 	reg[k] = int(reg[k])
+    
     return reg
 
+def region_env(region3d = False,
+               **kwargs):
+    """!Returns region settings as a string which can used as
+    GRASS_REGION environmental variable.
+
+    If no 'kwargs' are given then the current region is used. Note
+    that this function doesn't modify the current region!
+
+    See also use_temp_region() for alternative method how to define
+    temporary region used for raster-based computation.
+
+    \param region3d True to get 3D region
+    \param kwargs g.region's parameters like 'rast', 'vect' or 'region'
+    \code
+    os.environ['GRASS_REGION'] = grass.region_env(region = 'detail')
+    grass.mapcalc('map = 1', overwrite = True)
+    os.environ.pop('GRASS_REGION')
+    \endcode
+
+    @return string with region values
+    @return empty string on error
+    """
+    # read proj/zone from WIND file
+    env = gisenv()
+    windfile = os.path.join (env['GISDBASE'], env['LOCATION_NAME'],
+                              env['MAPSET'], "WIND")
+    fd = open(windfile, "r")
+    grass_region = ''
+    for line in fd.readlines():
+        key, value = map(lambda x: x.strip(), line.split(":", 1))
+        if kwargs and key not in ('proj', 'zone'):
+            continue
+        if not kwargs and not region3d and \
+                key in ('top', 'bottom', 'cols3', 'rows3',
+                        'depths', 'e-w resol3', 'n-s resol3', 't-b resol'):
+            continue
+        
+        grass_region += '%s: %s;' % (key, value)
+    
+    if not kwargs: # return current region
+        return grass_region
+    
+    # read other values from `g.region -g`
+    flgs = 'ug'
+    if region3d:
+        flgs += '3'
+        
+    s = read_command('g.region', flags = flgs, **kwargs)
+    if not s:
+        return ''
+    reg = parse_key_val(s)
+    
+    kwdata = [('north',     'n'),
+              ('south',     's'),
+              ('east',      'e'),
+              ('west',      'w'),
+              ('cols',      'cols'),
+              ('rows',      'rows'),
+              ('e-w resol', 'ewres'),
+              ('n-s resol', 'nsres')]
+    if region3d:
+        kwdata += [('top',        't'),
+                   ('bottom',     'b'),
+                   ('cols3',      'cols3'),
+                   ('rows3',      'rows3'),
+                   ('depths',     'depths'),
+                   ('e-w resol3', 'ewres3'),
+                   ('n-s resol3', 'nsres3'),
+                   ('t-b resol',  'tbres')]
+    
+    for wkey, rkey in kwdata:
+        grass_region += '%s: %s;' % (wkey, reg[rkey])
+    
+    return grass_region
+    
 def use_temp_region():
     """!Copies the current region to a temporary region with "g.region save=",
     then sets WIND_OVERRIDE to refer to that region. Installs an atexit

Modified: grass/branches/develbranch_6/lib/python/pythonlib.dox
===================================================================
--- grass/branches/develbranch_6/lib/python/pythonlib.dox	2012-03-14 22:13:32 UTC (rev 51060)
+++ grass/branches/develbranch_6/lib/python/pythonlib.dox	2012-03-14 22:15:54 UTC (rev 51061)
@@ -158,6 +158,8 @@
 
  - python::core::region()
 
+ - python::core::region_env()
+
  - python::core::use_temp_region()
 
 <b>Interface to g.findfile</b>