My first JGrass modules

Finally I decided to start to work in the new JGrass developing some hydrological modules (like I did in the JGrass2.0).
Just for exercise and fun I did this two interesting modules, available from the next JGrass release:

• r.cutout
• h.hypsographic

This two modules are developed, as all the others in JGrass, following the OpenMI guidelines.

r.cutout

r.cutout allows the user to cut a map on the region defined by an other map that is considered as the MASK. There is also the option to invert the extraction and extract the output map as the complementary of the MASK map in the active region.
The usage is the following:

• standard mode: jgrass r.cutout --igrass-mask adigebz_nabla --igrass-tocut ad_pit4 --ograss-cut adigebzmask_pit
  
• invert mode: jgrass r.cutout --igrass-mask adigebz_nabla --igrass-tocut ad_pit4 --ograss-cut adigebzmask_pit --invert true

where:

--igrass-mask: is the name of the input raster map containing the MASK -> the map that defines the region to cut out
--igrass-tocut: is the input map to cut out
--ograss-cut: is the output cut map over the defined region
--invert is the boolean that indicates the mode of calculation, default is FALSE -> standard mode, for the complementary map use TRUE

In term of pictures.
Starting from the two maps:

• the map of NABLA calculated on the extracted basin

• the whole map of depitted elevations

• obtain the map of depitted elevations on the extracted basin

• obtain the map of depitted elevation on the extracted basin's complementary area in the active region
  

r.hypsographic

r.hypsographic allows the user to create the hypsographic curve of a map limited to the active region. The hypsographic curve is usually calculated starting from an elavation map and it is described by the cumulative height frequency curve for the Earth’s surface or some part thereof. A hypsometric curve is essentially a graph that shows the proportion of land area that exists at various elevations by plotting relative area against relative height (http://www.britannica.com/EBchecked/topic/280163/hypsometric-curve).
The usage is the following:
jgrass h.hypsographic --igrass-elevation bz_bacino.pit --bins 50 --ochart-hypsographic "LINE#hypsografic curve#heigth[m smm]#area[km2]#hypso"

where:

--igrass-elevation: is the name of the input raster map of elevation
--bins: is the number of bins in which divide the entire range of heigth of the raster map (default is 100)
--oscalar-hypsographic: is the output scalar set
--ochart-hypsographic: is a way to visualize the output scalar set in a chart

In the example below:

• the input elevation map on the basin
  

• the output hypsographic chart

Some JGrass commands

Before using JGrass commands you have to set the active region that is the portion of the world in which JGrass makes raster elaborations. Note that visualization is more or less independent from active region, calculations are stricktly related to it.

To kown ho to set the active region in JGrass have a lood at the moovidas blog.

Here some JGrass commands to write in the console environment. Thanks to Erica and Andreas that gave them to me. I didn't test all of them but pretty sure they runs well.

h.netnumbering

This command allows you to enumerate the stream network channels and to extract the related basins. The network will be divided in subpieces which start and end at the confluences. To dived the network also in some other interesting points you have to add a shapefile of node point.

1. first option is the command in the basic mode: Usage mode 0: h.netnumbering --mode 0 --igrass-flow flow --igrass-net net --ograss-netnumber netnumber --ograss-basin basin
2. second option is dividing the network in subpieces which have an area less than the threshold fixed on the tca: Usage mode 1: h.netnumbering --mode 1 --thtca value --igrass-flow flow --igrass-net net --igrass-tca tca --ograss-netnumber netnumber--ograss-basin basin
3. third option is dividing the network in some interesting points taken from a shapefile: Usage mode 2: h.netnumbering --mode 2 --igrass-flow flow --igrass-net net --ishapefile-pointshape "filepath" -ograss-netnumber netnumber--ograss-basin basin
4. fourth method: mixed method between second and third (tca threshold and point shapefile): Usage mode 3: h.netnumbering --mode 3 --thtca value --igrass-flow flow --igrass-net net --igrass-tca tca ishapefile-pointshape "filepath" --ograss-netnumber netnumber--ograss-basin basin

How to set Console Environment in JGrass

To satisfy Moovidas requirements... :-)
here are some screenshots, and much more, about the JGrass commands in the JGrass Console environment.

Console preferences for JGrass are in the Window - Preferences menu. The tag to select is Console, the first pannel to set is about the general preferences the one below:

The second step is to set the compiler settings that should be already pre-compiled in the installation activity.

The rt folder is the folder in which JGrass looks for the commands, if the user wants to use other commands in other folders, just specify the name of the new folder or add the new commands to the files in the rt folder.

The third panel is about the preferences for the GRASS natives commands. For unix like systems (linux and mac) the preferences are setted in this way:
1. GRASS location, mapset and database specification
2. GRASS environment and library folder (to have the GISBASE name just enter GRASS and type which r.sun
3. user information

Last panel is to set the syntax colouring, not so useful for now.

To accept the changes just press Apply and then OK to close the Preferences window.

After setting the Console preferences you have to open the console editor by clicking the correspondet icon in the tools bar.

The new JGrass editor looks like in the picture below.

Here first click with the right mouse button and set the runtime preferences with the name of the location and mapset you want to use for elaborations.

Select the options and then close the window to accept the changes.

In the JGrass console editor the commands are mainly divided in two groups:
1. JGrass commands (written in Java and directly in JGrass)
2. GRASS natives commands (written in C for GRASS and executed from JGrass)

To execute a JGrass command use the word jgrass before the command, for GRASS use the grass word before the linestring of the GRASS command.

Every JGrass command has an help string to show the main targets. This string can be visualized by writing the --help string after the command, just like in GRASS environment. For GRASS commands the syntax and the options are the same as in GRASS.

To run a script or a part of it, select from the right mouse button the option "run name_of_the_console_editor_file". If you want to execute all the script just select the run option, if you want to run only a part of the script, before running, select the string you need to execute and the run with the right mouse button.

For example to know how you can use the h.pitfiller command:

jgrass h.pitfiller --help

The result is written in the console window below the console editor window as shown in picture.

There is not at present a good command line execution and so you can not see the complete list of the JGrass and GRASS commands. To see them you can have a look at the files in the rt folder of the console plugin in the JGrass installation folder.

The usage sentence contains:

1. the name of the command
2. the inputs of the commands that can be
   
• igrass: input in the GRASS - JGrass standard format
• igrassascii: input in the grassascii format in the related folder of the JGrass location
• iesrigrid: input in the esri grid format in the related folder of the JGrass location
• ifluidturtle: input in the fluidturtle format in the related folder of the JGrass location
• ishapefile: vector input shapefile
3. the outputs of the commands that can be
• ograss: output in the GRASS - JGrass standard format
• ograssascii: output in the grassascii format in the related folder of the JGrass location
• oesrigrid: output in the esri grid format in the related folder of the JGrass location
• ofluidturtle: output in the fluidturtle format in the related folder of the JGrass location
• oshapefile: vector output shapefile
• otable: writes an output file containing a table, used in commands like r.cb
• ocolor: writes the color table file of the related raster map
• ocats: writes the category file of the related raster map
  

For every input and output of the JGrass command it is possible to set the proper format. Standard format (JGrass-GRASS location) is the i/ograss format for raster maps and i/oshapefile for vector ones.

When a command has more than one input (or output) the syntax requires to define what type of input (r output) it is. So in command like r.netnumbering you can obtain:

jgrass h.netnumbering --help

**********************************************************************************************

untitled.jgrass - 1 model/s compiled, total compilation time: 26 ms

-------------------------------------------------------------------------------
Beanshell, Version 2.0b4, Copyright (C) Pat Niemeyer
------------------------------ Running model... -------------------------------
Usage:
h.netnumbering --igrass-flow flow --igrass-net net --ograss-netnumber netnumber --ograss-basin basin

Total run time: 51 ms


**********************************************************************************************

Where the --igrass-flow means that the input is a flow map in the grass format, and so on...