View source for QGIS GRASS Cookbook

== QGIS GRASS Cookbook ==

The GRASS Cookbook (GCB) is a collection of recipes for typical GIS tasks which can be accomplished with GRASS plugin in [http://www.qgis.org QGIS]. The recipes can be tried in any order but it is recommended to go through the ''Getting started'' section first. Each recipe can be reproduced with publicly available demo dataset. The cookbook presumes that the user has '''QGIS with the GRASS GIS plugin''' installed (and GRASS GIS plugin enabled in QGIS) and that s/he knows QGIS basics.

''Note: as alternative, there is the [[GRASS_and_Sextante#In_QGIS:_Sextante_plugin_with_GRASS_GIS_support|Sextante-GRASS GIS support in QGIS]] available since 2012 which offers a simplified integration with respect to the toolbox explained here.''

[[File:QGIS17_GRASS64.png||350px|thumb|center|GRASS Toolbox in QGIS]]

All the recipes (except some in Getting started section) requires open existing mapset (you can learn that in the OpenMapset section how to open a mapset). If a recipe has input maps in header it is expected that the maps are displayed in QGIS (you can learn that in the DisplayMap section how to display a map). The requested input maps are described in form 'map@mapset' which is the standard GRASS notation.

The information about effort (number of clicks and key strokes per each recipe) is only approximate.

Demo datasets:

* [http://grass.osgeo.org/download/data.php North Carolina + Spearfish]: get ZIP for Windows users, TAR for Linux/Mac users 

=== Getting started ===

* Display Map (18 clicks)
* Create new Mapset (13 clicks, 5 keystrokes)
* Open existing Mapset (12 clicks)
* Using GRASS Toolbox (11 clicks, 6 keystrokes)

==== Displaying GRASS Maps ====

* Objective: Display GRASS maps in QGIS
* Dataset: Spearfish
* Effort: 18 clicks
* By: Radim Blazek

* In GRASS Toolbox click on Add GRASS raster layer tool
* In Select GRASS raster layer dialog which opens: (screenshot)
* click on Browse button and in the standard file dialog select the director where you extracted Spearfish demo dataset. For example, if you extracted Spearfish package in directory C:\gdata\ (so that path to the dataset directory is C:\gdata\spearfish) select C:\gdata\ directory. The Location combobox will populate with existing locations.
* In the Location combobox select your spearfish location, in the Mapset combobox select PERMANENT and in the Map name combobox select elevation.10m: (screenshot)
* Push OK button. QGIS will load and display the selected layer as shown on the snapshot: (screenshot)
* In GRASS Toolbox click on Add GRASS vector layer tool: (screenshot)
* In the 'Select GRASS vector layer select in the Map name combobox map roads and in the Layer combobox select 1_line: (screenshot)
* Push OK button. QGIS will load and display the selected vectors layer over the previously loaded raster as shown on the snapshot: (screenshot)


Notes for polygons:
* polygon_0 are the holes
* polygon_1 are the areas with one centroid
* polygon_2 are the area with two centroids (overlapped areas)

==== Create new Mapset ====

(Adapted from [http://spatialintel.blogspot.com/2009/01/create-grass-mapset-in-qgis.html here])

# Go to the menu Plugins -> GRASS -> New Mapset
# In the resulting dialog, go to an existing directory for the GRASS database or specify a new one and select "Next"
# Select an existing GRASS location or check "Create new location" and name a new location and select "Next"
# In the next dialog you should see in the existing mapsets of which one mapset is called PERMANENT (this is the default GRASS mapset which you can use to store your base cartography inside). Now you can specify a new mapset name. When you select "Next" the new mapset will be created.
# Select Finish and you are almost done.

Now you need to set the region extents which can be done from an existing GRASS vector or raster layer. In a GRASS mapset, always the current [[computational region]] is to be defined since all raster operations use it (along with the current raster resolution).

# Go to the menu Plugins -> GRASS -> Open Mapset and open the mapset you have just created
# Now go to menu Plugins -> GRASS -> Open GRASS Tools
# Scroll down to the modules tree item File -> Import vector -> v.in.ogr (for this example, we are using a vector layer here)
# Select the OGR file type (shapefile, MapInfo etc.), define a name for the output GRASS vector layer and select Run (note: do not select the check box for "Limit import to current region")
# Close the import tool and go back to the modules tree to select Config -> Region -> Region Settings -> g.region.multiple.vector
# Use enter or select the name of the newly imported vector layer and select Run (note: you can select multiple vector layers and the region will be set to the extents of all)
# When you open this mapset you should see a red boundary around the region

You should now have a new GRASS vector mapset with the region set to one or more vector layers. You can now begin adding new data, creating maps and analysing the data with the other GRASS and QGIS tools.

==== Open an existing Mapset ====

Go to the menu Plugins -> GRASS -> Open Mapset and open an existing mapset. This enables you to use the GRASS Toolbox if you have write access to that mapset. If not, create a new mapset.

=== Using GRASS 7 Toolbox ===

To enable the GRASS 7 toolbox (required QGIS 2.12 or later)
* Menu Plugins >> Manage and Install Plugins >> Search for GRASS 7 >> enable
* Menu Plugins >> GRASS >> GRASS options
** Change the path to "/usr/lib64/grass-7.0.3" or whatever appropriate (the directory containing the GRASS GIS software)

Visualizing GRASS maps:
* Menu View >> Panels >> enable "Browser (2) panel"
* In that "Browser (2) panel" >> Home >> go-to-the-grassdata-location-mapset >> pick map with GRASS logo

==== Troubleshooting ====
** Error message like "This algorithm cannot be run :-( GRASS folder is not configured. Please configure it before running GRASS algorithms.":
*** QGIS searches in the path for grass73, then grass72, then grass70 (in this order). Are you sure that GRASS GIS is installed on your system?
** Error message like "GRASS init error: GRASS was not found in '/usr/lib64/grass-7.0.3' (GISBASE), provider and plugin will not work.":
*** Edit the settings (Menu Plugins >> GRASS >> GRASS options) and change the path to the correct path.

=== Using GRASS 6 Toolbox ===

'''''Note: The [[GRASS_and_Sextante#SEXTANTE_in_QGIS|new Processing interface with GRASS GIS support]] is much easier to use!'''''

* Objective: To learn how to set GRASS region and how to run GRASS modules in QGIS
* Dataset: Spearfish
* Input maps: soils@PERMANENT (vector)
* Effort: 11 clicks, 6 key strokes
* By: Radim Blazek

'''Hint:''' if the GRASS Toolbox is greyed out then you have likely no write access to the mapset. In this case change this or create a new mapset.

==== Example: Aspect map from DEM ====
As the first example we will use a module which generates aspect map from raster DEM (digital elevation model). Because all GRASS modules which read or write raster maps always work in '''[[computational region|current region]]''' we will learn first how to visualize and modify current GRASS region.

# The GRASS region is a rectangle defining certain area. To visualize the current region in QGIS switch on '''Display current region''' tool in GRASS toolbox (screenshot)
# If the current region is inside current QGIS extent the current GRASS region will be drawn as red (by default) rectangle (screenshot)
# Because raster analysis on large raster files can be time consuming it is often useful to set current region to a smaller area than that covered by the whole input raster. Click on '''Edit Current GRASS Region''' tool (screenshot)
# In the ''GRASS Region Settings'' which opens (screenshot)
you can enter new values for region extent and resolution. Alternatively you can define a new region in QGIS canvas with mouse while the ''GRASS Region Settings'' dialog is open. (screenshot)
# If you are content with new region settings click on '''OK''' button and the defined region will become current GRASS region for open mapset. From now on all the modules working with raster maps will read/write data in current region with current resolution. Note also that physical resolution of output raster maps does not depend on input map but on resolution of current region. The new region displayed in QGIS map canvas: (screenshot)
# Open GRASS tools clicking on '''Open GRASS Tools''' in GRASS Toolbox (screenshot)
# In the '''GRASS Tools''' window tab '''Modules''' click on tool '''Generate aspect map from DEM''' (screenshot)
# In the new tab which is opened for the selected tool select ''Elevation.10m'' as input and type ''aspect'' as name of output (screenshot)
# If you click on '''Run''' button the module will be started and module's interface will be switched to '''Output'''. In the output tab are printed messages from the running modules. You can follow the progress on the bar under the text output (screenshot)
# When the progress reaches 100% and message '''Successfully finished''' is printed in the text output you can add the output map to QGIS map canvas. As you see the map extent corresponds to the previously set GRASS region (screenshot)
# Optional tip. You can change transparency of the new aspect map to enhance visualization of the DEM (screenshot)

==== Example: Cleaning of topology of a SHAPE file using the GRASS Toolbox ====

# Load the SHAPE file into QGIS
# Use existing GRASS mapset (or create a new one) with matching projection settings
# Now you have to transfer the SHAPE file from QGIS to GRASS using Toolbox -> File management -> Import into GRASS -> Import vector into GRASS -> Import vector into GRASS from QGIS view (v.in.ogr.qgis). Some topological problems may be reported depending on the quality of your SHAPE file.
# These topological problems we can fix now in GRASS via toolbox using the topology tools: Vector -> Develop map -> Toolset for cleaning topology of vector map -> v.clean.break. Define a threshold in map units (for example 0.5 [m] or likewise). Analyse the printed report, probably the threshold needs to be adjusted or a different topology cleanup tool to be used. Click then on view output to show the result as map.
# Export the cleaned map to SHAPE format: File management -> Export from GRASS -> Export vector from GRASS -> v.out.ogr

=== Using GRASS via Sextante/Processing in QGIS ===

See here: [[GRASS_and_Sextante#SEXTANTE_in_QGIS|new Sextante plugin with GRASS GIS support]] for a much easier to use integration.

=== Setting the database backend connection to SQLite ===

In GRASS 6, the DBF driver is the default database driver. However, the SQLite driver is way more powerful. To set

In QGIS, in the GRASS Toolbox, you can change from the DBF driver to the SQLite driver:

  Database
  --> Database management
      --> db.connect

  Driver name: sqlite database=nome_del_database
  Database name: '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite.db'

Tip: take care to use ' and not " quoting.

Note: The database name "sqlite.db" is commonly used as indicated above.

If you prefer to use PostgreSQL or MySQL as backend, the procedure is similar (see the integrated manual for the parameters).

=== Running on Mac OSX ===

To start QGIS from the GRASS command line, do
 open -a QGIS.app

=== Further reading and video tutorials ===

* [http://wiki.awf.forst.uni-goettingen.de/wiki/index.php/QGIS_tutorial QGIS tutorial with GRASS exercises] (in 12 lectures, 2011)
* [http://qgis.spatialthoughts.com/2012/01/setting-up-working-grass-environment-in.html Tutorial: Setting Up A Working GRASS Environment in QGIS]
* [http://www.dur.ac.uk/resources/geography/conferences/3d_modeling/lidar_lab_notes_r_bennett.pdf Using QGIS and GRASS for Processing and Analysing Lidar Data] (Lab, 2010)
* [http://blog.qgis.org/node/90 Screencast - Loading Data into GRASS with QGIS] (2007)
* [http://www.youtube.com/results?search_query=using+grass+qgis+tutorial&aq=f QGIS GRASS video tutorials]
* [http://hub.qgis.org/projects/quantum-gis/wiki/Adding_New_Tools_to_the_GRASS_Toolbox Adding new tools to the GRASS toolbox]


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