Running analyses and developing workflows

Running analyses and developing workflows

There are currently 2 ways to specify Python workflows.

1. In Analyses tab, provide a Python file with workflows
2. In Activites tab provide JSON configuration file and Python files.

This page is about how the Python workflows work (for either case).

GRASS GIS Python API

Check the following links for learning how to use the API:

• Quick intro to Python in GRASS GIS
• Official documentation of Python in GRASS GIS
• Examples of Tangible Landscape workflows from FOSS4G NA 2016

Python workflows

In Analyses tab, click on Create new file and create a new Python file somewhere. When you open it in a text editor, you should see already some import statements and commented Python code. These can be uncommented and adjusted. For example, if we uncomment:

def run_contours(scanned_elev, env, **kwargs):
    analyses.contours(scanned_elev=scanned_elev, new='contours_scanned', env=env, step=2)

This will activate contour computation with contour interval equal 2 (the right interval depends on your reference DEM). Once Tangible Landscape runs, after each scanning cycle a vector map 'contours_scanned' (you can change this name) is created. You can add that vector map to the Map Display (look for Add vector map layer tool in Layer Manager toolbar.) During scanning you can change the code, for example to change the contour interval. Once the file is saved the change will be reflected.

Each function is independently run for each scan. The function name must start with run_.... The function has several parameters, but not all have to be listed, only the ones which are useful for that specific workflow:

def run_myanalysis(real_elev, scanned_elev, zexag, giface, update, eventHandler, env, **kwargs):
    # do some stuff

or for example

def run_myanalysis(real_elev, scanned_elev, env, **kwargs):
    # do some stuff

parameter	meaning	note
real_elev	name of the reference DEM
scanned_elev	name of the scanned DEM
scanned_calib_elev	name of scan captured during calibration phase
scanned_color	basename for the RGB rasters, name of imagery group
blender_path	path to directory used for coupling with Blender
zexag	currently set vertical exaggeration
giface	GRASS GUI interface object to access GUI	advanced
update	update function	advanced
eventHandler	event handler object	advanced
env	environment for running modules	always needed, see explanation below

Certain predefined functionality is defined in analyses.py, see example above how to call contours. Custom functionality can be scripted using the Python API, for examples see Tangible Landscape workflows from FOSS4G NA 2016.

Advanced tips

Environment

The env parameter needs to be passed to all run_command/read_command/write_command/parse_command function calls. This is needed for several things:

1. The computational region definition is part of the env and is set based on the scanned raster, therefore the raster won't be resampled during computation.
2. It allows overwriting of the outputs (sets --overwrite flag).
3. Sets quiet mode to avoid excessive text outputs from modules.

If computation needs to be done with different resolution or extent, new environment can be created inside the functions:

def run_myanalysis(scanned_elev, env, **kwargs):
    env2 = get_environment(raster=scanned_elev, res=10) # use parameters from g.region --h
    gscript.run_command(..., env=env2)