49. Command line

49.1. Introduction

The command-line interface allows advanced users to increase their productivity and performe complex operations with simple scripts.

It is available from “Tools/Geoprocessing/Command line”

The interface is:

The command-line interface is based on BeanShell. BeanShell is a Java source interpreter with object scripting language features, that meaning that it dynamically executes standard Java syntax and extends it with common scripting conveniences such as loose types, commands, and method closures like those in Perl and JavaScript. Several new commands have been added to it, so you can run geoalgorithms or get information about the geospatial data you are using, among other things.

49.2. Getting information about data

Algorithms need data to run. Layers and tables are identified using the name they have in the table of contents of gvSIG.

The data() command prints a list of all data objects available to be used, along with the particular name of each one (i.e. the one you have to use to refer to it). Calling it you will get something like this: 

RASTER LAYERS
-----------------
mdt25.asc



VECTOR LAYERS
-----------------
Contour lines



TABLES
-----------------

To get more information about a particular data object, use the describe(name_of_data_object) command. Here are a few examples of the result you will get when using it to get more information about a vector layer, a raster layer and a table.



>describe points.shp

Type: Vector layer - Point

Number of entities: 300

Table fields: | ID | X | Y | SAND | SILT | CLAY | SOILTYPE | EXTRAPOLAT |

>describe dem25.asc

Type: Raster layer

X min: 262846.525725

X max: 277871.525725

Y min: 4454025.0

Y max: 4464275.0

Cellsize X: 25.0

Cellsize Y: 0.0

Rows: 410

Cols: 601

>describe spatialCorrelation.dbf

Type: TableNumber of records: 156

Table fields: | Distance | I_Moran | c_Geary | Semivariance |

49.3. Getting information about algorithms

Once you know which data you have, it is time to know which algorithms are available and how to use them.

When you execute an algorithm using the toolbox, you use a parameters window with several fields, each one of them corresponding to a single parameter. When you use the command line interface, you must know which parameters are needed, so as to pass the right values to use to the method that runs that algorithm. Of course you do not have to memorize the requirements of all the algorithms, since SEXTANTE has a method to describe an algorithm in detail. But before we see that method, let's have a look at another one, the algs() method. It has no parameters, and it just prints a list of all the available algorithms. Here is a little part of that list as you will see it in your command-line shell.


bsh % algs();

acccost-------------------------------: Accumulated cost(isotropic)

acccostanisotropic--------------------: Accumulated cost (anisotropic)

acccostcombined-----------------------: Accumulated cost (combined)

accflow-------------------------------: Flow accumulation

acv-----------------------------------: Anisotropic coefficient of variation

addeventtheme-------------------------: Points layer from table

aggregate-----------------------------: Aggregate

aggregationindex----------------------: Aggregation index

ahp-----------------------------------: Analytical Hierarchy Process (AHP)

aspect--------------------------------: Aspect

buffer--------------------------------: Buffer

On the left side of the list you will find the command-line name of each algorithm. This is the one you have to use to make a reference to the algorithm you want to use. On the right you find the name of the algorithm in the current language, which is the same name that identifies the algorithm in the toolbox. However, this name is not constant, since it depends on the current language, and thus cannot be used to call the algorithm. Instead, a command-line is needed.

Now, let's see how to get a list of the parameters that an algorithms require and the outputs that it will generate. To do it, you can use the describealg(name_of_the_algorithm) method. Use the command-line name of the algorithm, not the full descriptive name.

For example, if we want to calculate a flow accumulation layer from a DEM, we will need to execute the corresponding module, which, according to the list show using the ags() method, is identified as accflow. The following is a description of its inputs and outputs.

>describealg("accflow")

Usage: accflow(DEM[Raster Layer]

WEIGHTS[Optional Raster Layer]

METHOD[Selection]

CONVERGENCE[Numerical Value]

FLOWACC [output raster layer])

49.4. Running an algorithm

There is only one single command to execute algorithms: runalg. Its syntax is as follows:

> runalg{name_of_the_algorithm, param1, param2, ..., paramN)

The list of parameters to add depends on the algorithm you want to run, and is exactly the list that the describealg method gives you, in the same order as shown.

Depending on the type of parameter, values are introduced differently. The next one is a quick review of how to introduce values for each type of input parameter

If the input is optional and you do not want to use any data object, write ``#''

  • Raster Layer, Vector Layer or Table. Simply introduce the name that identifies the data object to use. I.

  • Numerical value. Directly type the value to use or the name of a variable containing that value.

  • Selection. Type the number that identifies the desired option, as shown by the options command

  • String. Directly type the string to use or the name of a variable containing it.

  • Boolean. Type whether ``true'' or ``false'' (including quotes)

  • Multiple selection-data_type. Type the list of objects to use, separated by commas and enclosed between quotes.

    For example, for the maxvaluegrid algorithm:

Usage: runalg("maxvaluegrid",

INPUT[Multiple Input - Raster Layer]

NODATA[Boolean],

RESULT[Output raster layer])

The next line shows a valid use example

> runalg("maxvaluegrid", "lyr1, lyr2, lyr3", "false", "#")

Of course, lyr1, lyr2 and lyr3 must be valid layers already loaded into your GIS.

    When the multiple input is comprised of raster bands, each element is represented by a pair of values (layer, band). For example, for the cluster algorithm

Usage: runalg( "cluster",

INPUT[Multiple Input - Band],

NUMCLASS[Numerical Value],

RESULTLAYER[output raster layer],

RESULTTABLE[output table],

);

A valid example is:

> runalg("cluster, "lyr1, 1, lyr1, 2, lyr2, 2", 5, "#", "#")

The algorithm will use three bands, two of them from lyr1 (the first and the second ones of that layer) and one from lyr2 (its second band).

  • Table Field from XXX. Write the name of the field to use. This parameter is case-sensitive.

  • Fixed Table. Type the list of all table values separated by commas and enclosed between quotes. Values start on the upper row and go from left to right. Here is an example:

runalg("kernelfilter", mdt25.asc, "-1, -1, -1, -1, 9, -1, -1, -1, -1", "#")

  • Point . The two coordinates must be separated with a comma and in quotes. Example: ''220345, 4453616''

Input parameters such as strings or numerical values have default values. To use them, type ``#'' in the corresponding parameter entry instead of a value expression.

For output data objects, type the filepath to be used to save it, just as it is done from the toolbox. If you want to save the result to a temporary file, type ``#''. If you want to save the output to a permanent file, type the output file.

49.5. Running a model

Models can be executed from the command-line using the model command, which has a sintax similar to the runalg command. In this case, you must use the file name where the model is stored instead of the name of the algorithm as the first parameters. The remaining parameters depend on the particular model you want to execute, much like in the case of running a simple algorithm with the runalg command.

49.6. Managing layers from the command-line interface

You can perform some operation with layers from the command-line interface, like the following ones:

  • Close a layer. Use the close(layer_name) command.

  • Change the no-data value of a raster layer. Use the setnodata(layer_name, new_value) command

  • Change the name of a layer. Use the rename(layer_name, new_layer_name) command

49.7. Adjusting output raster characteristics

Just like when you execute a geoalgorithm from the toolbox, when it generates new raster layers you have to define the extent and cell size of those layers.

By default, those characteristics are defined based on the input layers. You can toggle this behaviour using the autoextent command.

> autoextent("true"/"false)

By default, it has a true value. However, iif you want to set a concrete extent and cell size for all the output raster layers, you should use the extent command:

Usage: extent(raster layer[string])

extent(vector layer[string], cellsize[double])

extent(x min[double], y min[double],

x max[double], y max[double],

cell size[double])

Type "autoextent" to use automatic extent fitting when possible

When a fixed extension has been set, automatically the autoextent will be deactivated (similar to execute a false autoextent).