1Interface to GRASS GIS modules 2============================== 3 4In :mod:`~pygrass.modules` module, GRASS GIS modules are represented 5by :class:`~pygrass.modules.interface.module.Module` class 6objects. These objects are generated based on the XML module 7description that is used also for the generation of the graphical user 8interface (GUI). :: 9 10 >>> from grass.pygrass.modules import Module 11 >>> slope_aspect = Module("r.slope.aspect", elevation='elevation', 12 ... slope='slp', aspect='asp', 13 ... format='percent', overwrite=True) 14 15 16It is possible to create a run-able module object and run it later (this 17is also needed for registering GRASS GIS commands with more than one dot 18in their name, e.g. r.slope.aspect): 19 20 >>> slope_aspect = Module("r.slope.aspect", elevation='elevation', 21 ... slope='slp', aspect='asp', 22 ... format='percent', overwrite=True, run_=False) 23 24Then we can run the module with: :: 25 26 >>> slope_aspect() 27 28or using the run method: :: 29 30 >>> slope_aspect.run() 31 32 33It is possible to initialize a module, and give the parameters later: :: 34 35 >>> slope_aspect = Module("r.slope.aspect") 36 >>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', 37 ... format='percent', overwrite=True) 38 39 40Create the module object input step by step and run later: :: 41 42 >>> slope_aspect = Module("r.slope.aspect") 43 >>> slope_aspect.inputs['elevation'] 44 Parameter <elevation> (required:yes, type:raster, multiple:no) 45 >>> slope_aspect.inputs["elevation"].value = "elevation" 46 >>> slope_aspect.inputs["format"] 47 Parameter <format> (required:no, type:string, multiple:no) 48 >>> print slope_aspect.inputs["format"].__doc__ 49 format: 'degrees', optional, string 50 Format for reporting the slope 51 Values: 'degrees', 'percent' 52 >>> slope_aspect.inputs["format"].value = 'percents' 53 Traceback (most recent call last): 54 ... 55 ValueError: The Parameter <format>, must be one of: ['degrees', 'percent'] 56 >>> slope_aspect.inputs["format"].value = 'percent' 57 >>> slope_aspect.flags = "g" 58 Traceback (most recent call last): 59 ... 60 ValueError: Flag not valid, valid flag are: ['a'] 61 >>> slope_aspect.flags = "a" 62 >>> slope_aspect.flags_dict['overwrite'] 63 Flag <overwrite> (Allow output files to overwrite existing files) 64 >>> slope_aspect.flags_dict['overwrite'].value = True 65 >>> slope_aspect() 66 67 68 69It is possible to access the module descriptions (name, one line description, 70keywords, label) with: 71 72 >>> slope_aspect.name 73 'r.slope.aspect' 74 >>> slope_aspect.description 75 'Aspect is calculated counterclockwise from east.' 76 >>> slope_aspect.keywords 77 'raster, terrain' 78 >>> slope_aspect.label 79 'Generates raster maps of slope, aspect, curvatures and partial derivatives from a elevation raster map.' 80 81and get the module documentation with: :: 82 83 >>> print slope_aspect.__doc__ 84 r.slope.aspect(elevation=elevation, slope=None, aspect=None 85 format=percent, prec=None, pcurv=None 86 tcurv=None, dx=None, dy=None 87 dxx=None, dyy=None, dxy=None 88 zfactor=None, min_slp_allowed=None) 89 <BLANKLINE> 90 Parameters 91 ---------- 92 <BLANKLINE> 93 <BLANKLINE> 94 elevation: required, string 95 Name of input elevation raster map 96 slope: optional, string 97 Name for output slope raster map 98 aspect: optional, string 99 Name for output aspect raster map 100 format: 'degrees', optional, string 101 Format for reporting the slope 102 Values: 'degrees', 'percent' 103 prec: 'float', optional, string 104 Type of output aspect and slope maps 105 Values: 'default', 'double', 'float', 'int' 106 pcurv: optional, string 107 Name for output profile curvature raster map 108 tcurv: optional, string 109 Name for output tangential curvature raster map 110 dx: optional, string 111 Name for output first order partial derivative dx (E-W slope) raster map 112 dy: optional, string 113 Name for output first order partial derivative dy (N-S slope) raster map 114 dxx: optional, string 115 Name for output second order partial derivative dxx raster map 116 dyy: optional, string 117 Name for output second order partial derivative dyy raster map 118 dxy: optional, string 119 Name for output second order partial derivative dxy raster map 120 zfactor: 1.0, optional, float 121 Multiplicative factor to convert elevation units to meters 122 min_slp_allowed: optional, float 123 Minimum slope val. (in percent) for which aspect is computed 124 <BLANKLINE> 125 Flags 126 ------ 127 <BLANKLINE> 128 a: None 129 Do not align the current region to the elevation layer 130 overwrite: None 131 Allow output files to overwrite existing files 132 verbose: None 133 Verbose module output 134 quiet: None 135 Quiet module output 136 137 138 139For each input and output parameter it is possible to obtain specific 140information. To see all module inputs, just type: :: 141 142 >>> slope_aspect.inputs #doctest: +NORMALIZE_WHITESPACE 143 TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> ...)]) 144 145To get information for each parameter: :: 146 147 >>> slope_aspect.inputs["elevation"].description 148 'Name of input elevation raster map' 149 >>> slope_aspect.inputs["elevation"].type 150 'raster' 151 >>> slope_aspect.inputs["elevation"].typedesc 152 'string' 153 >>> slope_aspect.inputs["elevation"].multiple 154 False 155 >>> slope_aspect.inputs["elevation"].required 156 True 157 158Or get a small documentation for each parameter with: 159 160 >>> print slope_aspect.inputs["elevation"].__doc__ 161 elevation: required, string 162 Name of input elevation raster map 163 164 165User or developer can check which parameters have been set, with: :: 166 167 if slope_aspect.outputs['aspect'].value == None: 168 print "Aspect is not computed" 169 170 171After we set the parameters, we can run the module in the background with 172`finish_=False`. Then call `wait()` and retrieve the returncode. :: 173 174 >>> slope_aspect = Module('r.slope.aspect') 175 >>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False) 176 >>> slope_aspect.wait() 177 Module('r.slope.aspect') 178 >>> slope_aspect.returncode 179 0 180 181 182Another example of use: :: 183 184 >>> from subprocess import PIPE 185 >>> info = Module("r.info", map="elevation", flags="r", stdout_=PIPE) 186 >>> from grass.script.utils import parse_key_val 187 >>> parse_key_val(info.outputs.stdout) 188 {'max': '156.3299', 'min': '55.57879'} 189 190 191Launching GRASS GIS modules in parallel 192--------------------------------------- 193 194PyGRASS implements simple mechanism for launching GRASS modules in 195parallel. See 196:class:`~pygrass.modules.interface.module.ParallelModuleQueue` class 197for details. 198 199Multiple GRASS modules can be joined into one object by 200:class:`~pygrass.modules.interface.module.MultiModule`. 201 202 203.. _Popen: http://docs.python.org/library/subprocess.html#Popen 204