QGIS GRASS Cookbook

The GRASS Cookbook (GCB) is a collection of recipes for typical GIS tasks which can be accomplished with GRASS plugin in 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 Sextante-GRASS GIS support in QGIS available since 2012 which offers a simplified integration with respect to the toolbox explained here.

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:

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 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 Toolbox

Note: The new Sextante plugin with GRASS GIS support is much earier 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 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

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

QGIS GRASS Cookbook

Contents