GRASS-Wiki - User contributions [en]

GRASS SoC Ideas 2013

2013-02-15T01:51:12Z

⚠️PierreRoudier: Added "interface to OTB" as a suggestion

== About ==

This is the GRASS page for [http://wiki.osgeo.org/index.php/Google_Summer_of_Code Google Summer of Code 2013]. Here we will list project ideas and and other information related to the GRASS GSoC projects.

== Ideas ==

* Also review ideas from [[GRASS SoC Ideas 2009#Ideas|2009]], [[GRASS SoC Ideas 2010#Ideas|2010]], [[GRASS SoC Ideas 2011#Ideas|2011]] and [[GRASS SoC Ideas 2012#Ideas|2012]] which are still open.

* Project ideas of '''your own''' are also most welcome and often the best.

=== Symbology / Cartography ===

* Allow display of a vector legend in the map display (equivalent to current {{cmd|d.legend}} implementation for rasters)

* Expand [[IconSymbols|symbology]]
: ''HB: note that SoC only accepts coding projects, not graphics design or documentation projects. Adding svg/eps support to a d.* module and ps.map would be quite helpful. See the {{Cmd|d.graph}} help page and {{Cmd|ps.map}}'s "eps" and "vpoints" instructions.''

* Rework the complete set of thematic cartography tools such as {{Cmd|d.vect.thematic}} and {{Cmd|d.thematic.area}} and the related classification routines

=== Imagery ===

* Based on the work on [[GRASS_GSoC_2012_Image_Segmentation|segmentation]] in GSoC 2012 develop routines for object-based (ore region-based) image classification. This probably entails:
** Characterizing segments. Thsi includes producing statistics such as mean, median, variance of the segmented data within each delineated segment.
** Classifying segments based on the characteristics and (possibly) training areas
** Interface with other modules in a consistent workflow (i.cluster, r.fuzzy, etc)

* Implement hierarchical classification tools (e.g. being able to create a large class "forest", with subclasses of different types of forests)

* Interface with the [http://www.orfeo-toolbox.org/otb/ Orfeo toolbox (OTB)], which is an open source, [http://www.itk.org ITK]-based, C++ library of (spatial) image processing library. OTB implements a very wide set of interesting features for anybody working with raster data - in particular satellite imagery: radiometric corrections, orthorectification, filtering, feature extraction, image segmentation , classification, change detection, etc.

{{GSoC}}

GRASS GSoC 2012 Image Segmentation

2012-07-12T00:03:36Z

⚠️PierreRoudier: Added a Results section to showcase i.segment results and keep track of performance

{{GSoC}}
''(See also other [[GRASS_SoC_Ideas_2012#Accepted_Ideas|GRASS GSoC 2012 projects]])''

{| {{table}}
|Student Name: || Eric Momsen
|-
|Organization: || [http://www.osgeo.org OSGeo - Open Source Geospatial Foundation]
|-
| Mentor Name: || Mentor: Markus Metz (backup mentors: M Lennert, P Roudier)
|-
| Title: || '''Image Segmentation'''
|-
|-
| Repository: || AddOns, browse at: [https://trac.osgeo.org/grass/browser/grass-addons/grass7/imagery/i.segment i.segment]
|-
|}
=Abstract=

GRASS GIS has many imagery related processing capabilities, but the field is rapidly developing and many techniques are not yet implemented. The goal of this GSoC project is to implement the region growing image segmentation algorithm.

Input: Raster map(s) to be segmented (plus optional vector map for a constraint)

Output: To include segmented regions with statistics. This information can be directly used or taken as input to existing image classification modules.

Update: This process will be split into two modules, the first will output a raster map with segments, the second will compute statistics for the segments.

=Background=

Image classification techniques already implemented in GRASS GIS include supervised and unsupervised classification. Classification of images based on pixels can often be very noisy. By first segmenting the image, later classification of 'objects' can be more effective. Noise is reduced, classification speed is increased, and most importantly the classification is performed on objects instead of pixels. The {{cmd|i.smap}} module does include a segmentation step (based on Gaussian mixture distribution), but there does not exist a module intended to segment the image and provide segment data for general use. A summary of the existing methods implemented in GRASS are at [[Image classification]]. Furthermore, the module {{AddonCmd|r.seg}} in GRASS-addons uses internally the Mumford-Shah variational model for image segmentation.

== Segmentation Methods ==

* Boundary Based
** optimal edge detector +
** watershed +
* Region Based
** multilevel thresholding technique +
** region growing +
* Combined boundary/region (is this a correct category for these two?)
** mean-shift
** watershed

Carleer et.al. [1] reviewed 4 methods (marked with + above). Boundary based methods are sensitive to noise and texture, and usually depend on good pre-processing. (Does GRASS already have this pre-processing/filtering?) Good results with urban zones, high contrast. Both region based methods had difficulty with transition zones. Region growing was less sensitive to texture (good for high resolution (1m) images). Multi-level techniques are the only way to get all objects without over-segmentation.

I don't recall the source, but I read in one place that mean-shift could be difficult to apply to very large images, and elsewhere it was mentioned watershed sees more use in greyscale images.

As additional algorithms are added to the module, attention should be given to diversify so algorithms with different strengths are implemented first.

=== Region Growing Variations ===

Even within the region growing label, there are a number of approaches. Here are two described in [5].

1. Growing

Seeds (as a subset of the pixels) are selected (using image histogram, previous knowledge, or other methods). Region growing is done by adding adjacent pixels. No merging of segments is done, only unassigned pixels can be assigned to adjacent regions.

2. Growing and Merging

Use all pixels as seeds, no need to have user figure out a reasonable starting seed selection. Now adjacent segments can be merged.

Is there ever a case where someone may want to start with seeds, but still allow segment merging? Or does that fall into the realm of classification to be done in the next step?

At this point, it seems both variations should be implemented.

== Segmentation Considerations ==

All(?) methods have some input parameter(s) that can be set. These parameters influence if the algorithm will over-segment (one expected region is divided into 2 or more segments) or under-segment (putting two expected regions into one segment). If the segments are used for later classification, over-segmentation should usually get preference to under-segmentation. With extensive over-segmentation, some of the advantages provided by segmentation can be lost, but at least the classification can combine the segments into the expected region. Under-segmentation is more critical, as the classification step will not divide the segment to recover the different regions. (Based on a summary of a number of papers from [1])

In order to respond to the issue of over/under-segmentation, a multiscalar approach would be interesting. This would mean either a top-down approach with a first coarse segmentation (under-segmentation) and the finer segmentation in selected segments, or a bottom-up approach with first a very fine-grained segmentation (over-segmentation) and the regrouping of segments to form higher levels. The first approach can be solved by doing a first segmentation, using certain segments as masks and then relaunching a second segmentation. {Or by using a vector map of the first segmentation as a boundary constraint in the second segmentation.} The second approach requires an algorithm to decide which segments should be combined in a larger higher-level segments. A simple nearest neighbor or kmeans approach based on spectral mean can be used here. In terms of implementation in GRASS, this would probably call for several modules, one for the segmentation, and another for grouping of segments. The latter could be an all-purpose clustering module (and can also be emulated by simple data analysis in the attribute table + {{cmd|v.dissolve}}).

It can sometimes be interesting to do a first segmentation on one band (e.g. panchromatic with higher resolution) and then regroup segments based on multispectral data (possibly weighting bands).

=Main Goal=

Implement an image segmentation method to extend the available options for image processing in GRASS. The region growing method has been selected as a robust general purpose method. An important contribution of the new method will be to include vector maps (for example road networks) as a constraint in growing the segments. Output from the module will include Spectral (mean/variance/range/ect) and Spatial (area/shape/location/etc) data for each region.

=Specifications=

* General considerations
** The general principle in GRASS is KISS, with each module doing one thing. It is to be seen if the result of this project is one single module or rather more than one module each specialised in one task in a segmentation workflow.
** As soon as code is to be (potentially) used in several modules, the use of a library should be envisaged.
** Be able to process large images while being considerate of system memory
* Input
** in the GRASS logic, input should be an image group, <del>or even image subgroup</del>, which can contain any number of raster maps, but generally satellite or areal images that are pre-processed and ready for analysis (i.e. no pre-processing in the module) (Update: subgroups are not often used, there use will not be implemented unless someone asks.)
*** This input group will define the feature space which can include spectral and other continuous (elevation, PCA layers, slope aspect...) and possibly (probably not initially) even discrete data (soil type, land cover...)
*** Default action will be to normalize/scale all input rasters to a 0-1 range. The allows bands (0-255), NDVI, and other numbers to be compared on an equal basis in the distance formula without any preprocessing steps. Since it gives equal weights to all rasters in the input group, a flag will give the user the option to skip this normalization step in case they want to use the actual values.
** optionally vector maps of existing features
*** lines (be it linear features or boundary lines of polygons) should be used as constraints meaning that no segment boundary should cross such a line
*** centroids/points to be used as initial seeds
** What segmentation algorithm to use
** Parameters for that algorithm
* Algorithm of segmentation
** in GSoC implementation of only one algorithm
** code should be structured to allow easy implementation of additional algorithms
** multi-scalar segmentation can significantly improve results and should thus be implemented if possible (see i.smap code for example)
* Similarity measurement
** The squared euclidean distance will be the default similarity measurement. If time allows, Manhattan distance will be added as an option. (Using the square will give same results, we will also square the similarity threshold so the user doesn't need to worry about this detail.
** For the default scaling of the input, the similarity threshold will be 0 to 1. This should be a good intuitive range for the user, 0 being the entire image is one segment and 1 being no segments can be formed. (Internally, this number must be multiplied by the number of rasters in the image group, but again the user doesn't need to worry about the details.) If the user selects the option to skip the normalization function, they will need to be careful how to select this parameter.
* Output
** first (segmentation) module: raster map of segments (i.e. each pixel value represents id of segment the pixel belongs to)
** second (stats) module: one vector map of segments per hierarchy level with a series of attributes (not all of these attributes should probably be calculated directly be the segmentation module)
*** spectral attributes:
**** per spectral band: mean, min, max, skewness
**** combination of bands: brightness, indices (i.e. results of multi-band calculations)
*** textural attributes: stdev (per-band and/or multi-band), mean difference to neighbor, Haralick texture features cf {{cmd|r.texture}}
*** geometric/morphological attributes: area, perimeter, length/width measures, see also {{cmd|r.li}}
*** context attributes: mean difference to all other regions in the same upper hierarchical level, relative localisation within upper hierarchical level, absolute localisation, number of objects in lower level
** depending on segmentation algorithm: raster map indicating for each pixel the probability of belonging to the segment it was put into, i.e. some measure of reliability of results

=== Questions ===

Number of modules: Should the user run one module to create the segments (raster output), then if they are interested, run r.to.vect and run a second module (vector input/output) if they want to get the statistics. (GUI glue to put them in one screen would be a low priority task for time remaining at the end of the summer.) (I wonder if the stats module should take vector or raster as the input, it will also need the original raster.)

"Probability of belonging to the segment": For region growing - should this be the similarity measure when it was merged? Or similarity measure of the pixel compared to the average?
/*ML: Not sure, but I would think that similarity between pixel and average of region it belongs to might be a good choice. Am not a specialist in statistics, but maybe it is possible to translate this into some form of probability of really "belonging" to that region (cf i.maxlik)*/
So this would be a comparison of the pixel to the final segment. Does anyone have a standard measurement that should be used?

4 vs. 8 neighbors: Should this be a user input option? It seems 4 neighbors (no diagonals) is the normal definition for segmentation, but not for other GRASS modules. Update: Using 4 neighbors as default, with optional flag to select 8 neighbors.

Null cells: Is it possible for some pixels inside the image to have null values? If yes, should they just be excluded from the calculation, or merged into the nearest segment? Update: current plan is to ignore all NULL values in the calculations.

Are there any examples of using linear features to constraint segment growth, or will it usually be polygons?

=== Lower priority ===

Add shape characteristics (smoothness, compactness) to the similarity measurement. Similar to eCognition "Multiresolution Segmentation"

It may be useful to do some calculations for the color space (RGB, HSI, L*u*v*, L*a*b*)? (I saw one paper [3] discussing pro/con of different systems, "best" answer is application dependent.)

ML: I would say leave decisions on color space (which is just one portion of feature space) to the user: one can group any kind raster maps with i.group and submit that to segmentation, and so the user can decide whether to use an image represented by different bands in a specific color space, plus any kind of other bands, indices, etc.

= Test Images =

The results of the implemented algorithm should be compared against the results of a similar algorithm implement in other software. The North Carolina GRASS sample location will be used for documentation and manuals.

Carleer [1] used images with 1m resolution from Ikonos, panchromatic band from 08 June 2000, Brussels area.

Should check segmentation results on images from a few different resolutions and different numbers of bands against what is obtained in other software.

Is there a benchmark for processing speed that should be considered? [4]

=Project Plan=

Preparation: Gather ideas from the community! Feature requests, image segmentation literature, and any other ideas and suggestions.

* May 21: Start coding, 8 weeks until Midterm Evaluation
* Week 1: Develop pseudocode to outline the work [http://lists.osgeo.org/pipermail/soc/2012-May/001747.html Report 1]
* Week 2-4: Implement the main algorithm [http://lists.osgeo.org/pipermail/soc/2012-June/001779.html Report 2] [http://lists.osgeo.org/pipermail/soc/2012-June/001804.html Report 3] [http://lists.osgeo.org/pipermail/soc/2012-June/001826.html Report 4]
* Week 5: Add vector maps as a constraint to the segmentation
* Week 6: Validation
* Week 7: Debugging
* Week 8: Contingency time for finishing the above, ensure a solid main program.
* July 9: Midterm Evaluation: Evaluate the existing program, determine the plan for the remaining 3-4 weeks. Options include:
* Improving the main algorithm
* Adding control for what scale the segmentation is performed at
* Providing updates to {{cmd|i.maxlik}} to ensure the segmentation output can be used as input for the existing classification functionality
* GUI
* Adding a second image segmentation algorithm

= Region Growing Algorithm =

Here is (a start!) for the processing steps, based on SPRING [2]

Region Growing, bottom up processing. Main improvement compared to simple algorithm is to slowly lower the similarity function, so only best matches are made first. This prevents the "first" segment from taking over any unclear areas between it and the next clear segment.

1. Input:
** Seeds: all pixels (Later addition can be alternate seeding methods)
** Similarity Threshold T(t)... as t increases, threshold for similarity is lower. SPRING used: <math>T(t) = T(0) alpha^t </math>, where T(0) > 0, t =0,1,2... and alpha <1
** Size of smallest allowed area (Is this wanted or needed ???)
2. Loop for t
** initialize candidate regions, save mean value vector and neighboring regions (Not sure why this needs to be calculated/saved ahead of time ??)
3. For each region i in candidate region set (first pass this equals the seeds):
** Compare Ri with neighbors (Question: should neighbors include or exclude those regions that were already matched?
** If it exists, Rk is best neighbor if smallest D of all neighbors and and D < T.
** Check Rk's neighbors.
** Merge IF Ri is Rk's best neighbor
** remove from candidate region set. (give all "small" regions a chance to merge with best neighbor before growing larger regions)
** update segment values
** next i
3. next t, with all segments returned to candidate region set, until no regions can be merged

4. Force a merge of regions that are too small

= ToDo List =

The following list was developed at the "mid" point review, with about 1 month left. Rating system is 1: must do, 2: would be nice, 3: probably only will be finished if it is a quick task.

== Functionality ==

1: Implement the 8 neighbor option (currenly only the 4 pixel neighbors are considered).

1: Starting seed pixels for the segments

1: handle null cells in the optional boundary constraints raster.

2: Current input limit is 2 billion starting segments, constrained by "int" data type for segment ID. Consider long int, and/or dynamic allocation of different storage depending on what is needed. (MM: Unfortunately you are stuck with the largest integer type that a GRASS raster supports with is 32 bit integer. Internally you could use larger integer types, but then you can not save the results... EM: Hmm, if the segments are renumbered sequenctial at the end, it would be possible to then save them if the resulting number of segments is less then 2 billion... Does anyone want to segment a raster with more than 2 billion pixels? As a work around, larger maps could be processed, if a random selection of pixels are used as seeds... At a minimum, put this limitation in as error checking and the documents.)

2: Check input parameters for mean-shift and other segmentation algorithms, try to make input parameters "generic" so they could be used for any/other algorithms.

2: Add shape characteristics (smoothness, compactness) to the similarity measurement. Similar to eCognition "Multiresolution Segmentation". Check Baatz and Shape paper. Adds two input parameters (weight of radiometric to shape, and weight of compactness to smoothness.) (Maybe use the ratio of the number of edge cells to the total number of cells as a proxy for compactness, which could be easily obtained as a side-product when finding neighbors.)

2: Alternate similarity measurements (Manhattan, Malahanobis)

3: Adding a parameter to make it easier to merge smaller segments and harder to merge large segments. (Preliminary testing is not promising, low priority)

3: Estimating the threshold value. (at least add to docs) (1 to 5% of the max difference gave me (MM) subjectively good results.)

?: Adding control for what scale the segmentation is performed at. (EM: I'm not certain what is meant/needed for this, but I think it is a different concept from just using g.region.)

== Statistics/metrics ==

1: i.segment.stats
(It should do more then just statistics... .evaluation .metrics .data Maybe i.segment.metrics?)
(Will need to evaulate what is already available from other GRASS modules, what is easy, what is hard. Start from the specifications for what is desired.)

1: Providing updates to i.maxlik to ensure the segmentation output can be used as input for the existing classification functionality.

1: Integration/workflow for r.fuzzy.

== Speed ==

2: Neighbor finding, keep a tree structure of found neighbor segments to reduce the number of neighbor pixels that the similarity function will be run on.

2: Search continuation. If Ri isn't Rk's best neighbor, then use Rk as the next Ri. (Skips one neighbor finding routine.)

2: Consider peano or other ordering for pixel processing (instead of row major order), should help processing time if an entire "row" of segments are not in RAM.

3: neighbor finding: When checking for Rk's neighbors, account for already knowing Ri and skip those pixels.

?: change candidate flag to int (compare with pass number) to avoid resetting each time. (32x RAM requirement for the flag, is it worth it?)

?: RAM storage of the segment membership and the neighboring segments (calculate first the requirements, if this is even possible for reasonable (what size?) maps). (check what % of the processing time is spent finding neighbors.)

== Memory ==

1: Put segment ID in SEG instead of RAM. (Possibly make this dependent on available RAM?)

1: User input for how much RAM can be used.

2: Consider putting the optional boundary constraints raster into RAM (dependent on available RAM).

2: Use "zero" for segment ID's of Null cells, discard the NULL flag. (Need to check speed impact with Seg ID in SEG storage.)

3: Check input map type(s), currently storing in DCELL sized SEG file, could reduce this dynamically depending on input map time. (Could only reduce to FCELL, since will be storing mean we can't use CELL. Might not be worth the added code complexity.)

== Polish ==

1: Add error traps. (Certainly for memory allocation, Minimum number of non-NULL cells in the input bands?anything else?)

2: Make the output segment ID's sequential (currently they have what ID the "first" pixel in the segment had).

2: There are many small TODO scattered in the code. Resolve some easy questions to clean up the code.

2: Change G_percentage: estimate total number of passes expected from histogram and threshold. (If this isn't reliabe, maybe change to show 1% for each pass, i.e. % complete out of first 100 passes, then % complete out of next 100 passes, etc.)

3: GUI (to combine i.segment with the stats module)

== Documentation ==

How to choose parameters, what their impact is.

Typical workflow:

* i.group
* i.segment
* r.to.vect
* i.segment.metrics and/or i.maxlik and/or r.fuzzy

= Workflow =

Todo: Some typical workflow examples, type of data, GRASS modules used before and after the image segmentation.

= Results =

== Ortho-photo ==

The data has 3 bands, and the computational region is 1,120,080 cells, at 1-m resolution.

Here's the code used to generate this segmentation result:

i.segment group=ortho output=ortho_segs_ha threshold=0.02 endt=10000 final_mean=ortho_segs_mean_ha min=20 --o

The segmentation performed in 22m53.255s on a Intel i5 laptop with 4Go RAM. The memory consumption was around 38 Mo.

[[File:Raglan_ortho_seg.png]]

== SPOT5 scene ==

The data has 4 bands, and the computational region is 4,444,517 cells, at 10-m resolution.

Here's the code used to generate this segmentation result:

i.segment group=spot output=spot_seg threshold=0.01 endt=10000 min=30 --o

The segmentation performed in 87m3.870s on a Intel Core 2 workstation with 8Go RAM. The memory consumption was around 170 Mo.

[[File:Taranaki spot seg.png]]

= References =

TODO: complete references with links.

[http://www.armurs.ulb.ac.be/images/8/86/PERS_Carleer_05.pdf] Carleer, et al: Assessment of Very High Spatial Resolution Satellite Image Segmentations, 2005 (Evaluates 2 boundary and 2 region based algorithms.)

[http://marte.dpi.inpe.br/col/sid.inpe.br/deise/1999/02.05.09.30/doc/T205.pdf] Bins, et al: Satellite Imagery Segmentation: A Region Growing Approach, 1996 (Describes approach taken in SPRING software.)

[http://www.sciencedirect.com/science/article/pii/S0031320300001497] Cheng et. al.: Color image segmentation: advances and prospect, 2000 (survey of segmentation methods and color spaces)

[http://www.isprs.org/proceedings/XXXV/congress/comm4/papers/506.pdf] G. Meinel, M. Neubert: A Comparison of Segmentation Programs for High Resolution Remote Sensing Data, 20?? (Includes timing to complete segmentation)

[http://www.wiley.com/WileyCDA/WileyTitle/productCd-0471377392.html?0471377392=] Pitas, I: Digital Image Processing Algorithms and Applications, 2000 (Textbook, including 1 chapter on segmentation methods.)

eCognition Reference Manual

Kurtz et. al: Hierarchical Segmentation of Multiresolution Remote Sensing Images, 2011

Comaniciu, Dorin: Mean Shift: A Robust Approach Toward Feature Space Analysis, 2002

File:Taranaki spot seg.png

2012-07-11T23:55:24Z

⚠️PierreRoudier: Test of i.segment (as at 12/07/2012) on an cropped SPOT 5 scene.

Test of i.segment (as at 12/07/2012) on an cropped SPOT 5 scene.

File:Raglan ortho seg.png

2012-07-11T23:52:06Z

⚠️PierreRoudier: Test of i.segment (as at 12/07/2012) on an orthophoto.

Test of i.segment (as at 12/07/2012) on an orthophoto.

Computational region

2012-04-29T23:56:28Z

⚠️PierreRoudier: Added FAQ entry on the -a flag

The current region or computational region is the actual setting of the region boundaries and the actual raster resolution.

As a general rule in GRASS:

#Raster maps are always '''imported completely''' at their own resolution (exception: WMS imported layers).
#Vector maps are always '''imported completely'''.
#In computations,
##raster '''input''' maps are automatically cropped/padded and rescaled (using nearest neighbour resampling) to match the current region in order to produce the output raster map or to query values.
##Raster '''output''' maps have their bounds and resolution equal to those of the current computational region.
##Vector maps are always '''considered completely'''.

=== FAQs ===

'''Q:''' I don't see anything!

'''A:''' Typically the computational region is set to an area not covering the raster map of interest. Use {{cmd|g.region}} to adjust the computational region settings, e.g. by setting it to the raster map:

g.region rast=myrastermap -p

'''Using the graphical user interface:'''

Set display to selected map:

[[Image:Wxgui zoom to raster.png|350px|center|thumb|wxGUI: set map display to selected map (right mouse button context menu on map name)]]

Set computational region to selected map:

[[Image:Wxgui computat region to raster.png|350px|center|thumb|wxGUI: set computational region to selected map (right mouse button context menu on map name)]]

 '''Q:''' The resolution of my region is not the one I asked for!

'''A:''' Sometimes, the resolution of the computational region is not matching exactly the resolution entered to {{cmd|g.region}}. Here's an example:
g.region rast=myrastermap res=1 -p
(...)
nsres: 0.9993515
ewres: 1.00025576
(...)

To force the computational region to match the resolution entered, you need to use the -a flag:
g.region rast=myrastermap res=1 -ap
(...)
nsres: 1
ewres: 1
(...)

 '''Q:''' The raster map looks ugly.

'''A:''' The resolution of the computational region does not match the resolution of the raster map. Use {{cmd|g.region}} to adjust the resolution settings of the computational region or set it to the raster map (see above).

 '''Q:''' I get "xyz module: G_malloc error"

'''A:''' You likely try to use more memory than your computer offers which is commonly caused by a too high raster resolution (or too large computational region). E.g., it is pointless to calculate common DEM data at nanometer raster resolution. Set the region extent and raster resolution properly with {{cmd|g.region}} (in the wxGUI: menu Settings -> Region -> Display Region | Set Region).

[[Category: Documentation]]
[[Category: FAQ]]
[[Category: Tutorial]]

GRASS SoC Ideas 2012

2012-04-25T22:49:31Z

⚠️PierreRoudier:

<center>

[[Image:grasslogo_vector_small.png|link=http://grass.osgeo.org]] @ [[Image:Gsoc-2012-logo-color.png|250px|link=http://wiki.osgeo.org/wiki/Google_Summer_of_Code_2012]] @ [[Image:OSGeo 220pix.png|link=http://www.osgeo.org]]
</center>

* See also previous Google Summer of Code [[GRASS SoC Ideas 2011|ideas from 2011]].

* Visit the [http://wiki.osgeo.org/wiki/Google_Summer_of_Code_2012 main OSGeo Google Summer of Code 2012 @ OSGeo wiki page].

__TOC__
== About ==

This is the GRASS page for [http://wiki.osgeo.org/index.php/Google_Summer_of_Code Google Summer of Code 2012]. Here we will list project ideas and and other information related to the GRASS GSoC projects.

* [http://code.google.com/soc/ Official Google Summer of Code 2012 homepage]
* [http://wiki.osgeo.org/wiki/Google_Summer_of_Code_2012 OSGeo SoC 2012 homepage]

Promotion:

* Videos at http://code.google.com/p/google-summer-of-code/wiki/Videos
* More Flyers at http://code.google.com/p/google-summer-of-code/wiki/GsocFlyers

== Timeline ==

* '''[http://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2012/faqs#timeline The official timeline]'''

== Required Steps ==

* '''List ideas'''

* Assign Mentors to Ideas

* Notify OSGeo

* Mentors evaluate student applications

* Accepted students announced

* Students subscribe to the [http://lists.osgeo.org/mailman/listinfo/grass-dev grass-dev mailing list] and introduce themselves

* Mentor will create directory structure in the [http://trac.osgeo.org/grass/browser/grass-addons GRASS add-ons SVN] for projects and setup access for students
** Students must read and post agreement to [http://grass.osgeo.org/programming7/rfc2_psc.html RFC2] to the [http://lists.osgeo.org/mailman/listinfo/grass-psc grass-psc mailing list] to gain SVN access
** Create a Wiki page for each accepted project, to be used as a progress reporting tool

* Coding begins...

* Students and mentors: Complete the Mid-term survey

* Final commit and packaging for Google

== Ideas ==

* Also review ideas from [[GRASS SoC Ideas 2007#Ideas|2007]], [[GRASS SoC Ideas 2008#Ideas|2008]], [[GRASS SoC Ideas 2009#Ideas|2009]], [[GRASS SoC Ideas 2010#Ideas|2010]], and [[GRASS SoC Ideas 2011#Ideas|2011]] which are still open.

* Project ideas of '''your own''' are also most welcome and often the best.

=== [[wxGUI]] ===

# Develop GUI support in wxPython for visualy analyzing series of raster map layers. The module should provide users with capabilities to browse and animate raster (and potentially also vector) data series in a 2D display and save outputs to animated GIF, MOV, or MPEG files. A related module that displays the series as small images and support re-ordering, deleting and adding raster maps (frames) to the series would also be helpful. To compare visually two images a slider functionality could be added to the 2D display, for example, to compare before and after images, or two consequent images in series. The series of data layers can be handled as multiple standard raster or vector layers or using the new time series support. See existing modules {{cmd|xganim}}, {{cmd|r.out.mpeg}}, [[NVIZ]]'s animation tools, and the [[Movies]] creation wiki page. There is also a related capability in the TclTk GUI. (co-mentor Helena Mitasova).
# Develop an interactive vector geometry selection and export tool for [[wxGUI]] as described in the trac ticket [http://trac.osgeo.org/grass/ticket/1471 #1471]
# Offer also (optional) "conventional" '''GUI layout''': For some users, the current approach of separate windows (SDI) leads to a '''windows flooding'''. This is a common complaint especially from newbies. Especially on large monitors or dual screen systems catching the [[wxGUI]] windows can be tedious when they appear on separate monitors (depends on windows manager, the much used KDE scatters typically the wxGUI windows all over the screen real estate). Almost each task generates a new wxGUI window which is freely floating around on the screen: [http://grass.osgeo.org/grass63/screenshots/images/wxgrass_digit-03.png example 1] and [http://grass.osgeo.org/grass63/screenshots/images/wxgrass_digit-01.png example 2]. On a dual-screen this may sum up to 50cm of distance! The idea is to capture all those windows in one frame. For details, see [[wxGUI#Layout| wxGUI layout]].
<center>
<gallery widths=400 heights=250>
Image:Wxgui_current.png|Current wxGUI layout with detached window components
Image:Wxgui_proposal.png|Proposal for wxGUI layout modification (Recomposition of existing toolbars, mapview and menus)
</gallery>
</center>
# ''Your idea here''

'''Willing to Mentor:''' [[User:Landa|Martin Landa]], [[User:MarisN|Maris Nartiss]], [[User:Mmetz|Markus Metz]], (''your name here'')

=== Raster ===

#Add '''[[OpenMP]] parallelization''' where appropriate, for example {{cmd|r.cost}}, {{cmd|r.surf.contour}}, {{cmd|r.watershed}}. It is important to understand which modules are processor bound, and concentrate on them. i.e. do not needlessly complicate the code of non-long running processor bound modules. A good working knowledge of ANSI C and {{wikipedia|OpenMP}} is required. ({{wikipedia|OpenCL}} and {{wikipedia|pthreads}} are fine too!)
#Create a new GRASS module to find the {{wikipedia|topographic_prominence}} of peaks from a raster elevation map within the region. (probably this would only make up 1/4 to 1/2 of a multi-part GSoC project)
# ''Your suggestion here!''

'''Willing to Mentor:''' Hamish (co-mentor parallelization and prominence projects), Wolf Bergenheim(''your name here'')

=== Vector ===

# Add '''[[OpenMP]] parallelization''' where appropriate, for example, {{cmd|v.surf.rst}} and {{cmd|v.vol.rst}} ''(co-mentor Helena Mitasova)''. (OpenCL and pthreads are fine too!) See above idea in the [[GRASS SoC Ideas 2012#Raster|Raster section]].
# Better '''support for wrap-around at 180 longitude''': Currently the raster engine is pretty good at wrapping data over 180 longitude. The vector data isn't, but it should be. This is a great task if by the end of the summer you'd like to be familiar with the implementation method of an entire vector stack of a fully featured modern GIS.
# Add '''break lines support to interpolation modules''' ({{cmd|v.surf.rst}}, {{cmd|v.surf.idw}}, {{cmd|v.surf.bspline}}). Current implementations provide no support to specify locations of cliffs or faults* thus leading to improper results within non-continous datasets. See [http://www.spatialanalysisonline.com/output/html/Breaklinesandnaturalboundaries.html Geospatial Analysis - a comprehensive guide. 3rd edition] for description. [*] well, some support exists, see {{AddonCmd|v.surf.icw}}.
# Speed up [[wxGUI]] handling and 2D display of large point clouds (several million points). This is likely to include additional "Level-1 Vector" support in the backend modules (for which a working knowledge of ANSI C is req'd).
# ''Your idea here'' ...

'''Willing to Mentor:''' [[User:Landa|Martin Landa]], [[User:Mmetz|Markus Metz]], Hamish (co-mentor for parallelization), Wolf Bergenheim, (''your name here'')

=== Imagery ===

# GRASS's imagery modules (for satellite, scanned maps, and orthophotos) act as enhanced raster modules. In GRASS 5 and 6 they were mostly implemented using interactive X-monitors which are not available in MS Windows and so are removed in the new cross-platform code of GRASS 7.
#* We need someone willing to '''port the old modules to work with GRASS 7''', including writing new '''wxPython GUI frontends''' to a number of existing tools and updating the imagery libraries to current raster library standards.
#* In addition, there are a number of '''improved/automated georectification tools''' which have not been merged into GRASS 5/6 which it would be nice to have updated and merged into the main code.
# Implement '''[[OpenMP]] (multithreading)''' as much as possible (where appropriate; OpenCL and pthreads are fine too)
# In addition to the porting of the georectification tools mentioned above, it would be interesting to implement an orthorectification tool for satellite imagery. Currently, GRASS only has {{cmd|i.ortho.photo}} for aerial photographs.
# Implement image segmentation algorithms and tools
# Implement region-based classification
# Implement hierarchical classification tools (e.g. being able to create a large class "forest", with subclasses of different types of forests)
# ''Your idea here''

See the [[Image_processing#Ideas_collection_for_improving_GRASS.27_Image_processing_capabilities|ideas for imagery improvement]] and [http://trac.osgeo.org/grass/wiki/Grass7/ImageryLib GRASS 7 ideas] wiki pages for more details.

'''Willing to Mentor:''' Hamish (co-mentor for parallelization), Markus Metz (orthorectification), (''your name here'')

=== Cartography and display ===

# Add SVG (and perhaps EPS) support to the display library, for use via {{cmd|d.graph}} and/or {{cmd|d.vect}}, and add SVG support to {{cmd|ps.map}} via a SVG to EPS converter tool (probably by adapting an existing GPL-compatible library). Code to be written in ANSI C. Step 1 is adding a Bézier curve rendering library function.
# Integrate Quantum/GRASS SVG output plugin with Inkscape. Python can serve as a common glue between these tools. The project would facilitate easy cartographic workflow while utilizing the advanced design functionality of Inkscape. This would be a two way bridge:
## QGIS/GRASS plugins to invoke an Inkscape process and send a data set.
## Inkscape plugin to query various OSGeo projects and display various data sets as layers.
# ''Your idea here ...''

'''Willing to Mentor:''' Hamish (as a co-mentor)

=== 3D visualization ===

# Optimize OGSF (and NVIZ/wxNVIZ) to '''display large 3D point clouds with uninterupted tought speed'''. OGSF + (wx)NVIZ should be able to rotate point cloud (i.e. LiDAR dataset) with 4 millions of points on medium hardware (i.e. 2GHz CPU with 2Gb RAM and GPU with hardware transform and lighting support and dedicated video RAM) with response time not greater than 1.0 second.
# Design and implement '''text displaying and styling in OGSF library''' and it's front-ends (NVIZ, [[wxNVIZ]]). Solution should be user configurable (fonts, colors, effects etc.) and multilanguage friendly.
# Design and implement user-provided '''symbol support in OGSF library''' and it's front-ends (NVIZ, [[wxNVIZ]]). Solution should support GRASS symbols, SVG, and/or simple EPS symbols.

# Drape multiple color maps over topography (equivalent to running r.patch or r.composite and draping the result; second raster is currently supported as transparency).
# Improve handling of z-exageration so that z-exag=1 is a realistic representation of landscape in terms of vertical scaling. Other default settings could also be improved to support wider range of data and improve robustness.

'''Willing to Mentor:''' [[User:Landa|Martin Landa]] (for 2), co-mentor for 1 and 5: Helena Mitasova, (''your name here'')

=== Volume modeling ===

# Develop '''r3.flow''' for computing 3D flow lines and 3D flow accumulation from 3D rasters
# Enhance volume interpolation module '''{{cmd|v.vol.rst}}''' for handling of data in space-time cube, including computation of gradients and hypercurvatures

'''Willing to Mentor:''' co-mentor Helena Mitasova, [[User:Huhabla|Sören Gebbert]]

=== Improved Python interface ===

Design '''sophisticated Python scripting interface''' for GRASS based on [http://grass.osgeo.org/programming7/pythonlib.html GRASS Python Scripting Library]. This API should become more intuitive and more integrative

GRASS GIS would gain even more attractiveness!

'''Willing to Mentor:''' [[User:Huhabla|Sören Gebbert]]

=== Other ===

* See also the [https://trac.osgeo.org/grass/query?status=assigned&status=new&status=reopened&order=priority&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&type=enhancement GRASS wish list]

# Implement selected modules (in C/C++) for geospatial analysis (kriging, etc.) based on [http://hpgl.aoizora.org/ HPGL] library (see also [http://hub.qgis.org/projects/quantum-gis/wiki/Python_Plugin_Ideas#Add-and-R-Free-geostatistic-toolbox-using-HPGL QGIS plugin wish]).
# Design and implement modern '''metadata management system''' for GRASS to support [http://www.opengeospatial.org/standards/cat OGC CSW] and INSPIRE discovery a view services

# ''Your idea here''

'''Willing to Mentor:''' Wolf Bergenheim (Python API, metadata management), [[User:Landa|Martin Landa]] (for HPGL) (''your name here'')

== Guidelines for Students ==

How do you maximize your chances of getting picked? First read the [http://code.google.com/p/google-summer-of-code/wiki/AdviceforStudents Google SoC FAQ]. Then talk to us about your idea. Try emailing our [http://lists.osgeo.org/mailman/listinfo/grass-dev dev-mailing list], or come and talk to us in [[IRC]] (#grass). You can also reach the mentors directly by emailing:
* [http://lists.osgeo.org/mailman/listinfo/soc The OSGeo SoC mailing list]



* If you are thinking about applying, do make a point of reading the "[http://google-opensource.blogspot.co.nz/2011/02/flip-bits-not-burgers-student-guide.html Flip bits not Burgers: The Student's Guide to the Summer of Code]" eBook

=== Getting started with GRASS coding ===

* The source code is maintained in a [http://trac.osgeo.org/grass/browser/grass/trunk SVN server] which is easy to browse

* Please review the submitting files for our coding standards
** {{src|SUBMITTING|branch=trunk}} for C coding rules
** {{src|SUBMITTING_PYTHON|branch=trunk}} for Python coding rules
** {{src|SUBMITTING_DOCS|branch=trunk}} for Documentantion coding rules

* There is lots of good info at the [http://trac.osgeo.org/grass/wiki GRASS Developer's wiki]
: See also the [[Development|development section]] of the GRASS user's wiki

== Guidelines for Mentors ==

* Un(?)official book: http://www.booki.cc/gsoc-mentoring/
* Some more hints on the [http://wiki.osgeo.org/wiki/Google_Summer_of_Code_2012_Administrative#Links OSGeo wiki]

== Accepted Ideas ==

# ''Python high level map interaction for GRASS GIS'' ([http://www.google-melange.com/gsoc/project/google/gsoc2012/zarch/11001 abstract])
#: Student: Pietro Zambelli
#: Mentor: Sören Gebbert
#: Backup mentors: Luca Delucchi, Martin Landa
#: Wiki page: [[GRASS SoC Ideas 2012/High level map interaction]]
# ''GRASS GIS WxGui front end for vector analysis modules'' ([http://www.google-melange.com/gsoc/project/google/gsoc2012/turek/38001 abstract])
#: Student: Stepan Turek
#: Mentor: Martin Landa
#: Backup mentor: Markus Metz
#: Wiki page: wiki/blog page maintained by the student (typically in this GRASS wiki, or the trac development wiki, with weekly progress reports)
# ''Image Segmentation in GRASS GIS'' ([http://www.google-melange.com/gsoc/project/google/gsoc2012/emomsen/20001 abstract])
#: Student: Eric Momsen
#: Mentor: Markus Metz
#: Backup mentors: Moritz Lennert, Pierre Roudier
#: Wiki page: wiki/blog page maintained by the student (typically in this GRASS wiki, or the trac development wiki, with weekly progress reports)



[[Category:Development]]
[[Category:Community]]
[[Category:GSoC]]

GRASS and Python

2011-06-01T04:29:07Z

⚠️PierreRoudier: /* Python extensions for GRASS GIS */

''(for discussions on the new GRASS GUI, see [[GRASS GUI|here]])''

==Python SIGs==
Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface (note 7/2010: swig stuff to be superseded with 'ctypes' soon).

* GRASS Python interface to library functions: http://grass.osgeo.org/programming6/swig/
* GRASS Python scripting library: http://grass.osgeo.org/programming6/pythonlib.html

Code style: Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Creating Python scripts that call GRASS functionality from outside ===

In order to use GRASS from outside, some environment variables have to be set.

==== MS-Windows ====

GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-64\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-64\msys\bin\sh.exe

Some hints:

# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
# PYTHONPATH needs to be set to %WINGISBASE%\etc\python

1-3 should be taken care of by the Python installer. 4 needs to be done by the startup (currently, this doesn't appear to be the case on MS-Windows).

Note:

Currently (as of 22 Feb 2011) if you want to use Python for scripting GRASS on Windows, the best solution is to delete the bundled version of Python 2.5 from the GRASS installation, install Python and the required add-ons (wxPython, NumPy, PyWin32) from their official installers,
then edit the GRASS start-up script to remove any references to the bundled version.

==== Linux ====

The variables are set like this:

export GISBASE="/usr/local/grass-6.4.svn/"
export PATH="$PATH:$GISBASE/bin:$GISBASE/scripts"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$GISBASE/lib"
# for parallel session management, we use process ID (PID) as lock file number:
export GIS_LOCK=$$
# path to GRASS settings file
export GISRC="$HOME/.grassrc6"

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Examples ===

==== Display example ====
Example of Python script, which is processed by g.parser:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 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.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()

</source>

==== Parsing the options and flags ====

grass.parser() is an interface to g.parser, and allows to parse the options and flags passed to your script on the command line. It is to be called at the top-level:

<source lang="python">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

Global variables "options" and "flags" are Python dictionaries containing the options/flags values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans. All those variables have to be previously declared in the header of your script.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</source>

==== Example for embedding r.mapcalc (map algebra) ====

grass.mapcalc() accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

==== Example for parsing category numbers ====

Q: How to obtain the number of cells of a certain category?

A: It is recommended to use pipe_command() and parse the output, e.g.:

<source lang="python">
p = grass.pipe_command('r.stats',flags='c',input='map')
result = {}
for line in p.stdout:
val,count = line.strip().split()
result[int(val)] = int(count)
p.wait()
</source>

==== Example for getting the region's number of rows and columns ====

Q: How to obtain the number of rows and columns of the current region?

A: It is recommended to use the "grass.region()" function which will create a dictionary with values for extents and resolution, e.g.:

<source lang="python">
#!/usr/bin/env python
#-*- coding:utf-8 -*-
#
############################################################################
#
# MODULE: g.region.resolution
# AUTHOR(S): based on a post at GRASS-USER mailing list [1]
# PURPOSE: Parses "g.region -g", prints out number of rows, cols
# COPYLEFT: ;-)
# COMMENT: ...a lot of comments to be easy-to-read for/by beginners
#
#############################################################################
#
#%Module
#% description: Print number of rows, cols of current geographic region
#% keywords: region
#%end

# importing required modules
import sys # the sys module [2]
from grass.script import core as grass # the core module [3]

# information about imported modules can be obtained using the dir() function
# e.g.: dir(sys)

# define the "main" function: get number of rows, cols of region
def main():

# #######################################################################
# the following commented code works but is kept only for learning purposes

## assigning the output of the command "g.region -g" in a string called "return_rows_x_cols"
# return_rows_x_cols = grass.read_command('g.region', flags = 'g')

## parsing arguments of interest (rows, cols) in a dictionary named "rows_x_cols"
# rows_x_cols = grass.parse_key_val(return_rows_x_cols)

## selectively print rows, cols from the dictionary "rows_x_cols"
# print 'rows=%d \ncols=%d' % (int(rows_x_cols['rows']), int(rows_x_cols['cols']))

# #######################################################################

# faster/ easier way: use of the "grass.region()" function
gregion = grass.region()
rows = gregion['rows']
cols = gregion['cols']

# print rows, cols properly formated
print 'rows=%d \ncols=%d' % (rows, cols)

# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly
if __name__ == "__main__": # this allows the script to be used as a module in other scripts or as a standalone script
options, flags = grass.parser() #
sys.exit(main()) #

# Links
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] http://download.osgeo.org/grass/grass6_progman/pythonlib.html#pythonCore
</source>

==== Managing mapsets ====

To check if a certain mapset exists in the active location, use:

<source lang="python">
grass.script.mapsets(False)
</source>

... returns a list of mapsets in the current location.

==== r.mapcalc example ====

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

grass.mapcalc("MASK=if(($cloudResampName < 0.01000),1,null())",
cloudResampName = cloudResampName)
</source>

The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than quiet, verbose or overwrite) specify substitutions.

==== Using output from GRASS modules in the script ====

Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.

Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use <code>grass.script.raster_info()</code>, e.g.:

<source lang="python">
import grass.script as grass

max = grass.raster_info(inmap)['max']
grass.mapcalc("$outmap = $inmap / $max",
inmap = inmap, outmap = outmap, max = max)
</source>

==== Calling a GRASS module in Python ====

Imagine, you wanted to execute this command in Python:
<source lang="bash">
r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>

All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:

<source lang="python">
grass.run_command(
'r.profile',
input = input_map,
output = output_file,
profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.

'''Differences between ''run_command()'' and ''read_command()'':'''

* run_command() executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* read_command() executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.

'''How to retrieve error messages from ''read_command()'':'''

None of the existing *_command functions redirect stderr. You can do so with e.g.:

<source lang="python">
def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</source>

This behaves like read_command() except that it returns a tuple of (stdout,stderr) rather than just stdout.

==== Path to GISDBASE ====

In order to a avoid hardcoded paths to GRASS mapset files like the SQLite DB file, you can get the GISDBASE variable from the environment:
<source lang="python">
import grass.script as grass
import os.path

env = grass.gisenv()

gisdbase = env['GISDBASE']
location = env['LOCATION_NAME']
mapset = env['MAPSET']

path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
</source>

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[wxGUI]] wiki page

=== GRASS Python Scripting Library ===

See [http://grass.osgeo.org/programming7/pythonlib.html GRASS Python Scripting Library] (Programmer's manual). See also [[Converting Bash scripts to Python]], and [http://trac.osgeo.org/grass/browser/grass/trunk/scripts sample Python scripts in GRASS 7]

==== Uses for read, feed and pipe, start and exec commands ====

All of the *_command functions use make_command to construct a command
line for a program which uses the GRASS parser. Most of them then pass
that command line to ''subprocess.Popen()'' via ''start_command()'', except
for ''exec_command()'' which uses ''os.execvpe()''.

[To be precise, they use grass.Popen(), which just calls
subprocess.Popen() with shell=True on Windows and shell=False
otherwise. On Windows, you need to use shell=True to be able to
execute scripts (including batch files); shell=False only works with
binary executables.]

start_command() separates the arguments into those which
subprocess.Popen() understands and the rest. The rest are passed to
make_command() to construct a command line which is passed as the
"args" parameter to subprocess.Popen().

In other words, start_command() is a GRASS-oriented interface to
subprocess.Popen(). It should be suitable for any situation where you
would use subprocess.Popen() to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is r.mapcalc in 6.x).

Most of the others are convenience wrappers around start_command(), for common use cases.

* run_command() calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to system().

* pipe_command() calls start_command() with stdout=PIPE and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").

* feed_command() calls start_command() with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")

* read_command() calls pipe_command(), reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.

* write_command() calls feed_command(), sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".

* parse_command() calls read_command() and parses its output as key-value pairs. Useful for obtaining information from g.region, g.proj, r.info, etc.

* exec_command() doesn't use start_command() but os.execvpe(). This causes the specified command to replace the current program (i.e. the Python script), so exec_command() never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step.

If you have any other questions, you might want to look at the code ($GISBASE/etc/python/grass/script/core.py). Most of these functions are only a few lines long.

==== Interfacing with NumPy ====

''Glynn writes:''

The {{api|pythonlib.html#pythonArray|grass.script.array}} module defines a {{api|classpython_1_1array_1_1array.html|class array}} which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] with <code>.read()</code> and <code>.write()</code> methods to read/write the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}.

Example:

<source lang="python">
import grass.script.array as garray
a = garray.array()
a.read("elevation.dem")
b = garray.array()
b[...] = (a / 50).astype(int) * 50 # or whatever
b.write("elev.50m")
</source>

The size of the array is taken from the current region.

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of <code>numpy.memmap</code> lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

One may also use the scipy matlab interface:

### SH: in GRASS ###
r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

=== Testing and installing Python extensions ===

==== Debugging ====

Make sure the script is executable:

chmod +x /path/to/my.extension.py

During development, a Python script can be debugged using the Python Debugger (pdb):

python -m pdb /path/to/my.extension.py input=my_input_layer output=my_output_layer option=value -f

==== Installation ====

Once you're happy with your script, you can put it in the scripts/ folder of your GRASS install. To do so, first create a directory named after your extension, then create a Makefile for it, and a HTML man page:

cd /path/to/grass_src/
cd scripts
ls # It is useful to check out the existing scripts and their structure
mkdir my.extension
cd my.extension
cp path/to/my.extension.py .
touch my.extension.html
touch Makefile

Next step is to edit the Makefile. It is a very simple text file, the only thing to check is to put the right extension name (WITHOUT the .py file extension) after PGM:

MODULE_TOPDIR = ../..

PGM = my.extension

include $(MODULE_TOPDIR)/include/Make/Script.make

default: script

The HTML file would be generated automatically. If you want to add more precisions in it, you can do it (just make sure you start at DESCRIPTION. See existing scripts.)

You can then run "make" within the my.extension folder. Running "make" in the extension directory places the resulting files in the staging directory (path/to/grass_src/dist.<YOUR_ARCH>/). If you're running GRASS from the staging directory (/path/to/grass_src/bin.<YOUR_ARCH>/grass7), subsequent commands will used the updated files.

# in your extension directory (/path/to/grass_src/scripts/my.extension/)
make
# Starting GRASS from the staging directory
/path/to/grass_src/bin.<YOUR_ARCH>/grass7
my.extension help

You can also run "make install" from the top level directory of your GRASS install (say /usr/local/src/grass_trunk/). Running "make install" from the top level just copies the whole of the dist.<YOUR_ARCH>/ directory to the installation directory (e.g. /usr/local/grass70) and the bin.<YOUR_ARCH>/grass70 bin file to the bin directory (e.g. /usr/local/bin), and fixes any embedded paths in scripts and configuration files.

cd /path/to/grass_src
make install
# Starting GRASS as usual would work and show your extension available
grass7
my.extension help

=== Python Ctypes Interface ===

This interface allows calling GRASS library functions from Python scripts. See [[Python Ctypes Examples]] for details.

Examples:

* GRASS 7: [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/raster_example_ctypes.py raster], [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/vector_example_ctypes.py vector] example

=== Python SWIG interface ===

Warning: The GRASS-SWIG interface isn't particularly stable and well understood. Please consider to use the Python ctypes GRASS above.

There is a prototype GRASS-SWIG interface available (thanks to Sajith VK), find it in GRASS 6-CVS: '''swig/python/'''. Draft documentation is [http://download.osgeo.org/grass/grass6_progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org SWIG] (Simplified Wrapper and Interface Generator) is:

* A compiler that turns ANSI C/C++ declarations into scripting language interfaces.
* Completely automated (produces a fully working Python extension module).
* Language neutral. SWIG can also target Tcl, Perl, Guile, MATLAB (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* Latest and greatest: [[http://trac.osgeo.org/grass/browser/grass/trunk/scripts GRASS 7 Python scripts]]

* [[PythonSwigExamples|More complicated examples]]

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

Sample script for vector access (use within GRASS, Spearfish session):

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

# define open level (level 2: topology)
grassvect.Vect_set_open_level (2)

# open existing map
grassvect.Vect_open_old(map, input, mapset)

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

==== TODO ====

* Implement modules support in a Python class using --interface-description and a Python-XML parser. This should be a generic class with module's name as parameter, returning back an object which describes the module (description, flags, parameters, status of not/required). See [http://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/ GRASS 6 wxPython interface] for inspiration. Important is to auto-generate the GRASS-Python class at compile time with a Python script.

=== Python-GRASS add-ons ===

Stand-alone addons:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

=== Using GRASS gui.tcl in Python ===

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

<source lang="python">
import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui = fd.read()
# Run it
tk.eval(gui)
dlg = tk.eval('set dlg') # This is used later to get and set

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")
</source>

== FAQ ==

* '''Q:''' Error message "execl() failed: Permission denied" - what to do?
: '''A:''' Be sure that the execute bit of the script is set.

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
*: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]
* [http://wiki.python.org/moin/PythonEditors Python Editors]

=== Programming ===

* Python and GRASS:
** GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/
** GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html
** PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

{{Python}}

GRASS and Python

2011-06-01T03:59:12Z

⚠️PierreRoudier: /* Parsing the options and flags */

''(for discussions on the new GRASS GUI, see [[GRASS GUI|here]])''

==Python SIGs==
Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface (note 7/2010: swig stuff to be superseded with 'ctypes' soon).

* GRASS Python interface to library functions: http://grass.osgeo.org/programming6/swig/
* GRASS Python scripting library: http://grass.osgeo.org/programming6/pythonlib.html

Code style: Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Creating Python scripts that call GRASS functionality from outside ===

In order to use GRASS from outside, some environment variables have to be set.

==== MS-Windows ====

GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-64\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-64\msys\bin\sh.exe

Some hints:

# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
# PYTHONPATH needs to be set to %WINGISBASE%\etc\python

1-3 should be taken care of by the Python installer. 4 needs to be done by the startup (currently, this doesn't appear to be the case on MS-Windows).

Note:

Currently (as of 22 Feb 2011) if you want to use Python for scripting GRASS on Windows, the best solution is to delete the bundled version of Python 2.5 from the GRASS installation, install Python and the required add-ons (wxPython, NumPy, PyWin32) from their official installers,
then edit the GRASS start-up script to remove any references to the bundled version.

==== Linux ====

The variables are set like this:

export GISBASE="/usr/local/grass-6.4.svn/"
export PATH="$PATH:$GISBASE/bin:$GISBASE/scripts"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$GISBASE/lib"
# for parallel session management, we use process ID (PID) as lock file number:
export GIS_LOCK=$$
# path to GRASS settings file
export GISRC="$HOME/.grassrc6"

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Examples ===

==== Display example ====
Example of Python script, which is processed by g.parser:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 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.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()

</source>

==== Parsing the options and flags ====

grass.parser() is an interface to g.parser, and allows to parse the options and flags passed to your script on the command line. It is to be called at the top-level:

<source lang="python">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

Global variables "options" and "flags" are Python dictionaries containing the options/flags values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans. All those variables have to be previously declared in the header of your script.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'output': 'map_out', 'option1': '21.472', 'option2': ''}
>>> flags
{'c': True, 'm': False}
</source>

==== Example for embedding r.mapcalc (map algebra) ====

grass.mapcalc() accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

==== Example for parsing category numbers ====

Q: How to obtain the number of cells of a certain category?

A: It is recommended to use pipe_command() and parse the output, e.g.:

<source lang="python">
p = grass.pipe_command('r.stats',flags='c',input='map')
result = {}
for line in p.stdout:
val,count = line.strip().split()
result[int(val)] = int(count)
p.wait()
</source>

==== Example for getting the region's number of rows and columns ====

Q: How to obtain the number of rows and columns of the current region?

A: It is recommended to use the "grass.region()" function which will create a dictionary with values for extents and resolution, e.g.:

<source lang="python">
#!/usr/bin/env python
#-*- coding:utf-8 -*-
#
############################################################################
#
# MODULE: g.region.resolution
# AUTHOR(S): based on a post at GRASS-USER mailing list [1]
# PURPOSE: Parses "g.region -g", prints out number of rows, cols
# COPYLEFT: ;-)
# COMMENT: ...a lot of comments to be easy-to-read for/by beginners
#
#############################################################################
#
#%Module
#% description: Print number of rows, cols of current geographic region
#% keywords: region
#%end

# importing required modules
import sys # the sys module [2]
from grass.script import core as grass # the core module [3]

# information about imported modules can be obtained using the dir() function
# e.g.: dir(sys)

# define the "main" function: get number of rows, cols of region
def main():

# #######################################################################
# the following commented code works but is kept only for learning purposes

## assigning the output of the command "g.region -g" in a string called "return_rows_x_cols"
# return_rows_x_cols = grass.read_command('g.region', flags = 'g')

## parsing arguments of interest (rows, cols) in a dictionary named "rows_x_cols"
# rows_x_cols = grass.parse_key_val(return_rows_x_cols)

## selectively print rows, cols from the dictionary "rows_x_cols"
# print 'rows=%d \ncols=%d' % (int(rows_x_cols['rows']), int(rows_x_cols['cols']))

# #######################################################################

# faster/ easier way: use of the "grass.region()" function
gregion = grass.region()
rows = gregion['rows']
cols = gregion['cols']

# print rows, cols properly formated
print 'rows=%d \ncols=%d' % (rows, cols)

# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly
if __name__ == "__main__": # this allows the script to be used as a module in other scripts or as a standalone script
options, flags = grass.parser() #
sys.exit(main()) #

# Links
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] http://download.osgeo.org/grass/grass6_progman/pythonlib.html#pythonCore
</source>

==== Managing mapsets ====

To check if a certain mapset exists in the active location, use:

<source lang="python">
grass.script.mapsets(False)
</source>

... returns a list of mapsets in the current location.

==== r.mapcalc example ====

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

grass.mapcalc("MASK=if(($cloudResampName < 0.01000),1,null())",
cloudResampName = cloudResampName)
</source>

The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than quiet, verbose or overwrite) specify substitutions.

==== Using output from GRASS modules in the script ====

Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.

Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use <code>grass.script.raster_info()</code>, e.g.:

<source lang="python">
import grass.script as grass

max = grass.raster_info(inmap)['max']
grass.mapcalc("$outmap = $inmap / $max",
inmap = inmap, outmap = outmap, max = max)
</source>

==== Calling a GRASS module in Python ====

Imagine, you wanted to execute this command in Python:
<source lang="bash">
r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>

All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:

<source lang="python">
grass.run_command(
'r.profile',
input = input_map,
output = output_file,
profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.

'''Differences between ''run_command()'' and ''read_command()'':'''

* run_command() executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* read_command() executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.

'''How to retrieve error messages from ''read_command()'':'''

None of the existing *_command functions redirect stderr. You can do so with e.g.:

<source lang="python">
def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</source>

This behaves like read_command() except that it returns a tuple of (stdout,stderr) rather than just stdout.

==== Path to GISDBASE ====

In order to a avoid hardcoded paths to GRASS mapset files like the SQLite DB file, you can get the GISDBASE variable from the environment:
<source lang="python">
import grass.script as grass
import os.path

env = grass.gisenv()

gisdbase = env['GISDBASE']
location = env['LOCATION_NAME']
mapset = env['MAPSET']

path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
</source>

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[wxGUI]] wiki page

=== GRASS Python Scripting Library ===

See [http://grass.osgeo.org/programming7/pythonlib.html GRASS Python Scripting Library] (Programmer's manual). See also [[Converting Bash scripts to Python]], and [http://trac.osgeo.org/grass/browser/grass/trunk/scripts sample Python scripts in GRASS 7]

==== Uses for read, feed and pipe, start and exec commands ====

All of the *_command functions use make_command to construct a command
line for a program which uses the GRASS parser. Most of them then pass
that command line to ''subprocess.Popen()'' via ''start_command()'', except
for ''exec_command()'' which uses ''os.execvpe()''.

[To be precise, they use grass.Popen(), which just calls
subprocess.Popen() with shell=True on Windows and shell=False
otherwise. On Windows, you need to use shell=True to be able to
execute scripts (including batch files); shell=False only works with
binary executables.]

start_command() separates the arguments into those which
subprocess.Popen() understands and the rest. The rest are passed to
make_command() to construct a command line which is passed as the
"args" parameter to subprocess.Popen().

In other words, start_command() is a GRASS-oriented interface to
subprocess.Popen(). It should be suitable for any situation where you
would use subprocess.Popen() to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is r.mapcalc in 6.x).

Most of the others are convenience wrappers around start_command(), for common use cases.

* run_command() calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to system().

* pipe_command() calls start_command() with stdout=PIPE and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").

* feed_command() calls start_command() with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")

* read_command() calls pipe_command(), reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.

* write_command() calls feed_command(), sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".

* parse_command() calls read_command() and parses its output as key-value pairs. Useful for obtaining information from g.region, g.proj, r.info, etc.

* exec_command() doesn't use start_command() but os.execvpe(). This causes the specified command to replace the current program (i.e. the Python script), so exec_command() never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step.

If you have any other questions, you might want to look at the code ($GISBASE/etc/python/grass/script/core.py). Most of these functions are only a few lines long.

==== Interfacing with NumPy ====

''Glynn writes:''

The {{api|pythonlib.html#pythonArray|grass.script.array}} module defines a {{api|classpython_1_1array_1_1array.html|class array}} which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] with <code>.read()</code> and <code>.write()</code> methods to read/write the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}.

Example:

<source lang="python">
import grass.script.array as garray
a = garray.array()
a.read("elevation.dem")
b = garray.array()
b[...] = (a / 50).astype(int) * 50 # or whatever
b.write("elev.50m")
</source>

The size of the array is taken from the current region.

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of <code>numpy.memmap</code> lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

One may also use the scipy matlab interface:

### SH: in GRASS ###
r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

=== Python Ctypes Interface ===

This interface allows calling GRASS library functions from Python scripts. See [[Python Ctypes Examples]] for details.

Examples:

* GRASS 7: [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/raster_example_ctypes.py raster], [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/vector_example_ctypes.py vector] example

=== Python SWIG interface ===

Warning: The GRASS-SWIG interface isn't particularly stable and well understood. Please consider to use the Python ctypes GRASS above.

There is a prototype GRASS-SWIG interface available (thanks to Sajith VK), find it in GRASS 6-CVS: '''swig/python/'''. Draft documentation is [http://download.osgeo.org/grass/grass6_progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org SWIG] (Simplified Wrapper and Interface Generator) is:

* A compiler that turns ANSI C/C++ declarations into scripting language interfaces.
* Completely automated (produces a fully working Python extension module).
* Language neutral. SWIG can also target Tcl, Perl, Guile, MATLAB (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* Latest and greatest: [[http://trac.osgeo.org/grass/browser/grass/trunk/scripts GRASS 7 Python scripts]]

* [[PythonSwigExamples|More complicated examples]]

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

Sample script for vector access (use within GRASS, Spearfish session):

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

# define open level (level 2: topology)
grassvect.Vect_set_open_level (2)

# open existing map
grassvect.Vect_open_old(map, input, mapset)

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

==== TODO ====

* Implement modules support in a Python class using --interface-description and a Python-XML parser. This should be a generic class with module's name as parameter, returning back an object which describes the module (description, flags, parameters, status of not/required). See [http://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/ GRASS 6 wxPython interface] for inspiration. Important is to auto-generate the GRASS-Python class at compile time with a Python script.

=== Python-GRASS add-ons ===

Stand-alone addons:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

=== Using GRASS gui.tcl in Python ===

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

<source lang="python">
import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui = fd.read()
# Run it
tk.eval(gui)
dlg = tk.eval('set dlg') # This is used later to get and set

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")
</source>

== FAQ ==

* '''Q:''' Error message "execl() failed: Permission denied" - what to do?
: '''A:''' Be sure that the execute bit of the script is set.

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
*: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]
* [http://wiki.python.org/moin/PythonEditors Python Editors]

=== Programming ===

* Python and GRASS:
** GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/
** GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html
** PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

{{Python}}

GRASS and Python

2011-06-01T02:12:12Z

⚠️PierreRoudier: Added more explainations about grass.parser() and its output

''(for discussions on the new GRASS GUI, see [[GRASS GUI|here]])''

==Python SIGs==
Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface (note 7/2010: swig stuff to be superseded with 'ctypes' soon).

* GRASS Python interface to library functions: http://grass.osgeo.org/programming6/swig/
* GRASS Python scripting library: http://grass.osgeo.org/programming6/pythonlib.html

Code style: Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Creating Python scripts that call GRASS functionality from outside ===

In order to use GRASS from outside, some environment variables have to be set.

==== MS-Windows ====

GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-64\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-64\msys\bin\sh.exe

Some hints:

# The Python interpreter (python.exe) needs to be in the PATH
# Python needs to be associated with the .py extension
# PATHEXT needs to include .py if you want to be able to omit the extension
# PYTHONPATH needs to be set to %WINGISBASE%\etc\python

1-3 should be taken care of by the Python installer. 4 needs to be done by the startup (currently, this doesn't appear to be the case on MS-Windows).

Note:

Currently (as of 22 Feb 2011) if you want to use Python for scripting GRASS on Windows, the best solution is to delete the bundled version of Python 2.5 from the GRASS installation, install Python and the required add-ons (wxPython, NumPy, PyWin32) from their official installers,
then edit the GRASS start-up script to remove any references to the bundled version.

==== Linux ====

The variables are set like this:

export GISBASE="/usr/local/grass-6.4.svn/"
export PATH="$PATH:$GISBASE/bin:$GISBASE/scripts"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$GISBASE/lib"
# for parallel session management, we use process ID (PID) as lock file number:
export GIS_LOCK=$$
# path to GRASS settings file
export GISRC="$HOME/.grassrc6"

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Examples ===

==== Display example ====
Example of Python script, which is processed by g.parser:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 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.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()

</source>

==== Parsing the options and flags ====

grass.parser() is an interface to g.parser, and allows to parse the options and flags passed to your script on the command line. It is to be called at the top-level:

<source lang="python">
if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

Global variables "options" and "flags" are Python dictionaries containing the options/flags values, keyed by lower-case option/flag names. The values in "options" are strings, those in "flags" are Python booleans. All those variables have to be previously declared in the header of your script.

<source lang="python">
>>> options, flags = grass.parser()
>>> options
{'input': 'my_map', 'size': '21.472', 'output': 'map_out'}
>>> flags
{'c': True, 'm': False}
</source>

==== Example for embedding r.mapcalc (map algebra) ====

grass.mapcalc() accepts a template string followed by keyword
arguments for the substitutions, e.g. (code snippets):

<source lang="python">
grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = options['output'],
rast1 = options['raster1'],
rast2 = options['raster2'])
</source>

''Best practice'': first copy all of the options[] into separate variables at the beginning of main(), i.e.:

<source lang="python">
def main():
output = options['output']
raster1 = options['raster1']
raster2 = options['raster2']

...

grass.mapcalc("${out} = ${rast1} + ${rast2}",
out = output,
rast1 = raster1,
rast2 = raster2)
</source>

==== Example for parsing category numbers ====

Q: How to obtain the number of cells of a certain category?

A: It is recommended to use pipe_command() and parse the output, e.g.:

<source lang="python">
p = grass.pipe_command('r.stats',flags='c',input='map')
result = {}
for line in p.stdout:
val,count = line.strip().split()
result[int(val)] = int(count)
p.wait()
</source>

==== Example for getting the region's number of rows and columns ====

Q: How to obtain the number of rows and columns of the current region?

A: It is recommended to use the "grass.region()" function which will create a dictionary with values for extents and resolution, e.g.:

<source lang="python">
#!/usr/bin/env python
#-*- coding:utf-8 -*-
#
############################################################################
#
# MODULE: g.region.resolution
# AUTHOR(S): based on a post at GRASS-USER mailing list [1]
# PURPOSE: Parses "g.region -g", prints out number of rows, cols
# COPYLEFT: ;-)
# COMMENT: ...a lot of comments to be easy-to-read for/by beginners
#
#############################################################################
#
#%Module
#% description: Print number of rows, cols of current geographic region
#% keywords: region
#%end

# importing required modules
import sys # the sys module [2]
from grass.script import core as grass # the core module [3]

# information about imported modules can be obtained using the dir() function
# e.g.: dir(sys)

# define the "main" function: get number of rows, cols of region
def main():

# #######################################################################
# the following commented code works but is kept only for learning purposes

## assigning the output of the command "g.region -g" in a string called "return_rows_x_cols"
# return_rows_x_cols = grass.read_command('g.region', flags = 'g')

## parsing arguments of interest (rows, cols) in a dictionary named "rows_x_cols"
# rows_x_cols = grass.parse_key_val(return_rows_x_cols)

## selectively print rows, cols from the dictionary "rows_x_cols"
# print 'rows=%d \ncols=%d' % (int(rows_x_cols['rows']), int(rows_x_cols['cols']))

# #######################################################################

# faster/ easier way: use of the "grass.region()" function
gregion = grass.region()
rows = gregion['rows']
cols = gregion['cols']

# print rows, cols properly formated
print 'rows=%d \ncols=%d' % (rows, cols)

# this "if" condition instructs execution of code contained in this script, *only* if the script is being executed directly
if __name__ == "__main__": # this allows the script to be used as a module in other scripts or as a standalone script
options, flags = grass.parser() #
sys.exit(main()) #

# Links
# [1] http://n2.nabble.com/Getting-rows-cols-of-a-region-in-a-script-tp2787474p2787509.html
# [2] http://www.python.org/doc/2.5.2/lib/module-sys.html
# [3] http://download.osgeo.org/grass/grass6_progman/pythonlib.html#pythonCore
</source>

==== Managing mapsets ====

To check if a certain mapset exists in the active location, use:

<source lang="python">
grass.script.mapsets(False)
</source>

... returns a list of mapsets in the current location.

==== r.mapcalc example ====

Example of Python script, which is processed by {{cmd|g.parser}}:

The shell script line:

<source lang="bash">
r.mapcalc "MASK = if(($cloudResampName < 0.01000),1,null())"
</source>

would be written like this:

<source lang="python">
import grass.script as grass

...

grass.mapcalc("MASK=if(($cloudResampName < 0.01000),1,null())",
cloudResampName = cloudResampName)
</source>

The first argument to the mapcalc function is a template (see the Python library documentation for [http://docs.python.org/library/string.html string.Template]). Any keyword arguments (other than quiet, verbose or overwrite) specify substitutions.

==== Using output from GRASS modules in the script ====

Sometimes you need to use the output of a module for the next step. There are dedicated functions to obtain the result of, for example, a statistical analysis.

Example: get the range of a raster map and use it in {{cmd|r.mapcalc}}. Here you can use <code>grass.script.raster_info()</code>, e.g.:

<source lang="python">
import grass.script as grass

max = grass.raster_info(inmap)['max']
grass.mapcalc("$outmap = $inmap / $max",
inmap = inmap, outmap = outmap, max = max)
</source>

==== Calling a GRASS module in Python ====

Imagine, you wanted to execute this command in Python:
<source lang="bash">
r.profile -g input=mymap output=newfile profile=12244.256,-295112.597,12128.012,-295293.77
</source>

All arguments except the first (which is a flag) are keyword arguments, i.e. <tt>arg = val</tt>. For the flag, use <tt>flags = 'g'</tt> (note that "-g" would be the negative of a Python variable named "g"!). So:

<source lang="python">
grass.run_command(
'r.profile',
input = input_map,
output = output_file,
profile = [12244.256,-295112.597,12128.012,-295293.77]
</source>
or:
<source lang="python">
profile = [(12244.256,-295112.597),(12128.012,-295293.77)]
</source>

i.e. you need to provide the keyword, and the argument must be a valid Python expression. Function <code>run_command()</code> etc accept lists and tuples.

'''Differences between ''run_command()'' and ''read_command()'':'''

* run_command() executes the command and waits for it to terminate; it doesn't redirect any of the standard streams.
* read_command() executes the command with stdout redirected to a pipe, and reads everything written to it. Once the command terminates, it returns the data written to stdout as a string.

'''How to retrieve error messages from ''read_command()'':'''

None of the existing *_command functions redirect stderr. You can do so with e.g.:

<source lang="python">
def read2_command(*args, **kwargs):
kwargs['stdout'] = grass.PIPE
kwargs['stderr'] = grass.PIPE
ps = grass.start_command(*args, **kwargs)
return ps.communicate()
</source>

This behaves like read_command() except that it returns a tuple of (stdout,stderr) rather than just stdout.

==== Path to GISDBASE ====

In order to a avoid hardcoded paths to GRASS mapset files like the SQLite DB file, you can get the GISDBASE variable from the environment:
<source lang="python">
import grass.script as grass
import os.path

env = grass.gisenv()

gisdbase = env['GISDBASE']
location = env['LOCATION_NAME']
mapset = env['MAPSET']

path = os.path.join(gisdbase, location, mapset, 'sqlite.db')
</source>

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[wxGUI]] wiki page

=== GRASS Python Scripting Library ===

See [http://grass.osgeo.org/programming7/pythonlib.html GRASS Python Scripting Library] (Programmer's manual). See also [[Converting Bash scripts to Python]], and [http://trac.osgeo.org/grass/browser/grass/trunk/scripts sample Python scripts in GRASS 7]

==== Uses for read, feed and pipe, start and exec commands ====

All of the *_command functions use make_command to construct a command
line for a program which uses the GRASS parser. Most of them then pass
that command line to ''subprocess.Popen()'' via ''start_command()'', except
for ''exec_command()'' which uses ''os.execvpe()''.

[To be precise, they use grass.Popen(), which just calls
subprocess.Popen() with shell=True on Windows and shell=False
otherwise. On Windows, you need to use shell=True to be able to
execute scripts (including batch files); shell=False only works with
binary executables.]

start_command() separates the arguments into those which
subprocess.Popen() understands and the rest. The rest are passed to
make_command() to construct a command line which is passed as the
"args" parameter to subprocess.Popen().

In other words, start_command() is a GRASS-oriented interface to
subprocess.Popen(). It should be suitable for any situation where you
would use subprocess.Popen() to execute a normal GRASS command (one
which uses the GRASS parser, which is almost all of them; the main
exception is r.mapcalc in 6.x).

Most of the others are convenience wrappers around start_command(), for common use cases.

* run_command() calls the wait() method on the process, so it doesn't return until the command has finished, and returns the command's exit code. Similar to system().

* pipe_command() calls start_command() with stdout=PIPE and returns the process object. You can use the process' .stdout member to read the command's stdout. Similar to popen(..., "r").

* feed_command() calls start_command() with stdin=PIPE and returns the process object. You can use the process' .stdin member to write to the command's stdout. Similar to popen(..., "w")

* read_command() calls pipe_command(), reads the data from the command's stdout, and returns it as a string. Similar to `backticks` in the shell.

* write_command() calls feed_command(), sends the string specified by the "stdin" argument to the command's stdin, waits for the command to finish and returns its exit code. Similar to "echo ... | command".

* parse_command() calls read_command() and parses its output as key-value pairs. Useful for obtaining information from g.region, g.proj, r.info, etc.

* exec_command() doesn't use start_command() but os.execvpe(). This causes the specified command to replace the current program (i.e. the Python script), so exec_command() never returns. Similar to bash's "exec" command. This can be useful if the script is a "wrapper" around a single command, where you construct the command line and execute the command as the final step.

If you have any other questions, you might want to look at the code ($GISBASE/etc/python/grass/script/core.py). Most of these functions are only a few lines long.

==== Interfacing with NumPy ====

''Glynn writes:''

The {{api|pythonlib.html#pythonArray|grass.script.array}} module defines a {{api|classpython_1_1array_1_1array.html|class array}} which is a subclass of [http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html numpy.memmap] with <code>.read()</code> and <code>.write()</code> methods to read/write the underlying file via {{cmd|r.out.bin}}/{{cmd|r.in.bin}}.

Example:

<source lang="python">
import grass.script.array as garray
a = garray.array()
a.read("elevation.dem")
b = garray.array()
b[...] = (a / 50).astype(int) * 50 # or whatever
b.write("elev.50m")
</source>

The size of the array is taken from the current region.

The main drawback of using numpy is that you're limited by available
memory. Using a subclass of <code>numpy.memmap</code> lets you use files which may
be much larger, but processing the entire array in one go is likely to
produce in-memory results of a similar size.

One may also use the scipy matlab interface:

### SH: in GRASS ###
r.out.mat input=elevation output=elev.mat

<source lang="python">
### PY ###
import scipy.io as sio
# load data
elev = sio.loadmat('elev.mat')
# retrive the actual array. the data set contains also the spatial reference
elev.get('map_data')
data = elev.get('map_data')
# a first simple plot
import pylab
pylab.plot(data)
pylab.show()
# the contour plot
pylab.contour(data)
# obviously data needs to ne reversed
import numpy as np
data_rev = data[::-1]
pylab.contour(data_rev)
# => this is a quick plot. basemap mapping may provide a nicer map!
#######
</source>

=== Python Ctypes Interface ===

This interface allows calling GRASS library functions from Python scripts. See [[Python Ctypes Examples]] for details.

Examples:

* GRASS 7: [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/raster_example_ctypes.py raster], [http://trac.osgeo.org/grass/browser/grass/trunk/doc/python/vector_example_ctypes.py vector] example

=== Python SWIG interface ===

Warning: The GRASS-SWIG interface isn't particularly stable and well understood. Please consider to use the Python ctypes GRASS above.

There is a prototype GRASS-SWIG interface available (thanks to Sajith VK), find it in GRASS 6-CVS: '''swig/python/'''. Draft documentation is [http://download.osgeo.org/grass/grass6_progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org SWIG] (Simplified Wrapper and Interface Generator) is:

* A compiler that turns ANSI C/C++ declarations into scripting language interfaces.
* Completely automated (produces a fully working Python extension module).
* Language neutral. SWIG can also target Tcl, Perl, Guile, MATLAB (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* Latest and greatest: [[http://trac.osgeo.org/grass/browser/grass/trunk/scripts GRASS 7 Python scripts]]

* [[PythonSwigExamples|More complicated examples]]

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

Sample script for vector access (use within GRASS, Spearfish session):

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

# define open level (level 2: topology)
grassvect.Vect_set_open_level (2)

# open existing map
grassvect.Vect_open_old(map, input, mapset)

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

==== TODO ====

* Implement modules support in a Python class using --interface-description and a Python-XML parser. This should be a generic class with module's name as parameter, returning back an object which describes the module (description, flags, parameters, status of not/required). See [http://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/ GRASS 6 wxPython interface] for inspiration. Important is to auto-generate the GRASS-Python class at compile time with a Python script.

=== Python-GRASS add-ons ===

Stand-alone addons:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

=== Using GRASS gui.tcl in Python ===

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

<source lang="python">
import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui = fd.read()
# Run it
tk.eval(gui)
dlg = tk.eval('set dlg') # This is used later to get and set

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")
</source>

== FAQ ==

* '''Q:''' Error message "execl() failed: Permission denied" - what to do?
: '''A:''' Be sure that the execute bit of the script is set.

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
*: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]
* [http://wiki.python.org/moin/PythonEditors Python Editors]

=== Programming ===

* Python and GRASS:
** GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/
** GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html
** PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

{{Python}}