Sextante

Introduction

Introduction

This text is targeted at those using geospatial algorithms from the SEXTANTE library through the available GUI on this new version of gvSIG, the SEXTANTE toolbar. It is located at the right of the three main icons of the gvSIG toolbar.

Particular information about SEXTANTE algorithms is not found in this text. The user should refer to the context help system instead.


Basic elements of the SEXTANTE toolbar

There are five basic elements in the SEXTANTE toolbar, which are used to run SEXTANTE algorithms for diferent purposes. Choosing one tool or another will depend on the kind of analysis that is to be performed and the particular characteristics of each user an project.

The SEXTANTE elements are available in a toolbar like the one show next.

images/en/stnt_toolbar.png

SEXTANTE toolbar

images/en/stnt_toolbox.png

SEXTANTE toolbox

images/en/stnt_modeler.png

SEXTANTE graphical modeler

images/en/stnt_command.png

SEXTANTE command-line

images/en/stnt_history.png

SEXTANTE history manager

images/en/stnt_results.png

SEXTANTE results

Along the following chapters we will review each one of this elements in detail.


The Sextante toolbox

Introduction

The Toolbox is the main element of the SEXTANTE GUI, and the one that you are more likely to use in your daily work. It shows the list of all available algorithms grouped in different blocks, and is the access point to run them whether as a single process or as a batch process involving several executions of a same algorithm on different sets of inputs.

images/en/stnt_toolbox.png

SEXTANTE toolbox

Depending on the data available in the gvSIG View, you will be able to execute an algorithm or not. When there is enough data for the algorithm to be executed (i.e. the algorithm requires raster layers and you have raster layer already loaded into the View), its name is shown in black, otherwise, it is show in grey.

In the lower part of the toolbox you can find a text box and a search button. To reduce the number of algorithms shown in the toolbox and make it easier to find the one you need, you can enter any word or phrase on the text box and click on the search button. SEXTANTE will search the help files associated to each algorithm and show only those algorithms that include the word or phrase in their corresponding help files. To show all the algorithms again, make a search with an empty string.

To execute an algorithm, just double-click on its name in the toolbox.


The algorithm dialog

Introduction

Once you double-click on the name of the algorithm that you want to execute, a dialog similar to the next one is shown (in this case, the dialog corresponds to the Anisotropic cost algorithm).

images/en/stnt_anisotropic.png

SEXTANTE dialog

This dialog is used to set the input values that the algorithm needs to be executed. There is a main tab named Parameters where input values and configuration parameters are set. This tab has a different content depending on the requirements of the algorithm to be executed, and is created automatically based on those requirements. On the left side, the name of the parameter is shown. On the right side the value of the parameter can be set.

Those algorithms that generate raster layers as output have an additional tab named Raster output. This tab is used to set the characteristics of those output raster layers, specifying its extent and its cell size. On the lower part of the window there is a help button. Click on it to see the context help related to the current algorithm, where you will find detailed description of each parameter and each output generated by the algorithm.


The parameters tab

Although the number and type of parameters depends on the characteristics of the algorithm, the structure is similar for all of them. The parameters found on the parameters tab can be of one of the following types.

images/en/stnt_raster.png

SEXTANTE raster dialog

images/en/stnt_multiple_selec.png

SEXTANTE multiple selection

Click on the button on the right side to see the table and edit its values.

images/en/stnt_filter_table.png

SEXTANTE filter table

Depending on the algorithm, the number of rows can be modified or not, using the buttons on the right side of the window.


The raster output tab

The Raster output tab is found in those algorithms that generate raster layers. Unlike in most GIS, when combining several raster layers as input for an algorithm, they do not have to have the same extent an cellsize in order to process them together. That is, layers don't have necessarily to match" between them. Instead, the characteristics of the output raster layer are defined and SEXTANTE performs the corresponding resampling and cropping needed to generate layer with those characteristics.

It is responsibility of the user to enter adequate values and be aware of the limitations of this mechanism, so as to generate cartographically correct results. (i.e. you can select a small cell size for the resulting raster layers, but if the input layers you are using have a bad resolution the results will not be geographically sound).

The following options are available in the raster output tab:

images/en/stnt_raster_output.png

SEXTANTE raster output tab

If an option other than the automatic fitting is selected, SEXTANTE will check that the values are correct and the resulting layers will not be too large (due to, for instance, a wrong cell size). If the output layers seems to large, SEXTANTE will show the next message dialog to ensure that the user really want those layer to be created.

images/en/stnt_size_warning.png

SEXTANTE size warning

Not all algorithms have the first option available, since not all algorithms that generate raster layers take some other raster layer as input. The interpolation algorithms, for instance, take a vector layer and create a raster one. The extent and cellsize of the latter has to be manually defined, since it cannot be set based solely on the input vector layer.


Data objects generated by Sextante algorithms

Data objects generated by SEXTANTE can be of any of the following types:

Layers and tables can be saved to a file, and the parameters window will contain a text box corresponding to each one of these outputs, where you can type the desired file path. If you do not enter any file path, a temporal file name and folder will be used.

The supported formats for the SEXTANTE cartographic output files are as follows.

To select a format, just select the corresponding file extension. If the extension of the file path you entered does not match any of the supported ones, the default extension (the first one in the list of supported ones) will be appended to the file path and the file format corresponding to that extension will be used to save the layer or table.

Graphics and texts are kept in memory and shown at the end of the algorithm execution in a new dialog. This dialog will keep the results produced by SEXTANTE during the current session, and can be shown at any time using the Results button. You can save graphical results as images in png format, and texts as HTML files. Rightclick on the name of the result in the tree on the left hand of the window and select Save as....

images/en/stnt_result_stat.png

SEXTANTE statistics results

images/en/stnt_result_graph.png

SEXTANTE graphic result


Context help

Each SEXTANTE algorithm has its own context help file, which provides detailed information about the meaning of each input parameter and each output object, and gives hints about its usage. To access the context help system, click on the button that you will find in the algorithm dialog, or rightclick on its name on the toolbox and then select See help.

images/en/stnt_info_icon.png

SEXTANTE help icon

The context help system contains not only information about each algorithm, but also description of each one of the elements of the SEXTANTE GUI like the text you are reading now. You will find it at the top of the tree on the left hand side of the help window. Just select an item to see its associated help file on the right canvas.

images/en/stnt_help.png

SEXTANTE help window (NOT AVAILABLE AT THE MOMENT)

Help files associated to each algorithm are stored as XML files, and can be edited using the help authoring tools included with SEXTANTE. Right click on the name of the algorithm in the context help window and select Edit help to get to the following window:

images/en/stnt_edit_help.png

SEXTANTE edit help window (NOT AVAILABLE AT THE MOMENT)

On the left hand side you can select any of the elements to be documented (input parameter and outputs, along with other fixed field such as a general description of the algorithm). Then use the right hand side boxes to enter to text associated to that element or add images.


The Sextante graphical modeler

Introduction

The graphical modeler allows to create complex models using a simple and easytouse interface. When working with a GIS, most analysis operations are not isolated, but part of a chain of operations instead. Using the graphical modeler, that chain of processes can be wrapped into a single process, so it is easier and more convenient to execute than single process later on a different set on inputs. No matter how many steps and different algorithms it involves, a model is executed as a single algorithm, thus saving time and effort, specially for larger models.

The modeler has a working canvas where the structure of the model and the workflow it represents are shown. On the left part of the window, a panel with two tabs can be used to add new elements to the model.

images/en/stnt_modeler.png

SEXTANTE modeler window

Creating a model is a two-step process.


Definition of inputs

The first step to create a model is to define the inputs it needs. The following elements are found in the Inputs tabs on the left side of the modeler window:

Double-clicking on any of them, a dialog is shown to define its characteristics. Depending on the parameter itself, the dialog will contain just one basic element (the description, which is what the user will see when executing the model) or more of them. For instance, when adding a numerical value, as can be seen in the next figure, apart from the description of the parameter is needed to set a default value, the type of numerical value and a range of valid values.

images/en/stnt_numerical_value.png

SEXTANTE modeler window for adding values

For each added input, a new element is added to the modeler canvas.

images/en/stnt_numerical_value2.png

SEXTANTE modeler elements


Definition of the workflow

Once the inputs have been defined, it is time to define the algorithms to apply on them. Algorithms can be found in the Processes tab, grouped much in the same way as they are in the toolbox.

images/en/stnt_modeler2.png

SEXTANTE modeler

To add a process, double-click on its name. An execution dialog will appear, with a content similar to the one found execution panel that SEXTANTE shows when executing the algorithm from the toolbox.

images/en/stnt_modeler_process.png

SEXTANTE modeler process

Some differences exist, however, the main one being the absence of a raster ouput tab, even if the selected algorithm generates raster layers as output.

Instead of the textbox that was used to set the filepath for output layers and tables, a checkbox and a text box are found. If the layer generated by the algorithm is just a temporary result that will be used as the input of another algorithm and should not be kept as a final result, the check box should be left unchecked. Checking it means that the result is a final one, and you have to supply also a valid description for the output, which will be the one the user will see when executing the model.

Selecting the value of each parameter is also a bit different, since there are important differences between the context of the modeler and the toolbox one. Let's see how to introduce the values for each type of parameter.

Once all the parameter have been assigned valid values, click on OK and the algorithm will be added to the canvas. It will be linked to all the other elements in the canvas, whether algorithms or inputs, which provide objects that are used as inputs for that algorithm.

images/en/stnt_modeler_process.png

SEXTANTE model


Editing the model

Once the model has been designed, it can be executed clicking on the Run button. The execution window will have a parameters tab automatically created based on the requirements of the model (the inputs added to it), just like it happens when a simple algorithm is executed. If any of the algorithms of the model generates raster layers, the Raster output tab will be added to the window.

Elements can be dragged to a different position within the canvas, to change the way the module structure is displayed and make it more clear and intuitive. Links between elements are update automatically.

To change the parameters of any of the algorithms of a model, doubleclick on it to access its parameters window.

To delete an element, right-click on it and select Delete. Only those elements that do not have any other one depending on them can be deleted. If you try to delete an element that cannot be deleted, SEXTANTE will show a warning message.


Saving and loading models

Models can be saved to be executed or edited at a later time. Use the Save button to save the current model and the Open model to open any model previously saved. Model are saved in an XML file with the .model extension.

Models saved on the models folder will appear in the toolbox algorithm tree in a group named Models.

images/en/stnt_model_root.png

SEXTANTE models on the tree

When the toolbox is invoked, SEXTANTE searches the models folder for files with .model extension and loads the models they contain. Since a model is itself a SEXTANTE algorithm, it can be added to the toolbox just like any other algorithm.

The models folder can be set from the SEXTANTE toolbox, clicking the configuration button at the right lower corner of the window, and then introducing the path to the folder in the corresponding field.

images/en/stnt_modeler_configuration.png

SEXTANTE modeler configuration

Models loaded from the models folder appear not only in the toolbox, but also in the algorithms tree in the Processes tab of the modeler window. That means that you can incorporate a model as a part of a bigger model, just as you add any other algorithm.


The Sextante batch processing interface

Introduction

SEXTANTE algorithms (including models) can be executed as a batch process. That is, they can be executed using not a single set of inputs, but several of them, executing the algorithm as many times as needed. This is useful when processing large amounts of data, since it is not necessary to launch the algorithm many times from the toolbox.

images/en/stnt_batch_exe.png

SEXTANTE executing batch


The parameters table

Executing a batch process is similar to performing a single execution of an algorithm. Parameter values have to be defined, but in this case we need not just a single value for each parameter, but a set of them instead, one for each time the algorithm has to be executed.

Values are introduced using a table like the one shown next.

images/en/stnt_batch_process.png

SEXTANTE batch processing

Each line of this table represents a single execution of the algorithm, and each cell contains the value of one of the parameters. It is similar to the parameters tab that you see when executing an algorithm from the toolbox, but with a different arrangement.

By default, the table contains just two rows. You can add or remove rows using the buttons on the right hand side of the window.

Once the size of the table has been set, it has to be filled with the desired values.


Filling the parameters table

Whatever the type of parameter it represents, every cell has a text string as its associated value. Doubleclicking on a cell, this string can be edited, directly typing the desired value. For most of the parameters, however, it is more convenient to use the button on the right hand side of the cell. Clicking on it, a dialog is shown to select the value of the parameter. The content of this dialog depends on the kind of parameter, and it features elements that make it easier to introduce the desired value. For example, for a selection parameter the list of all possible values is shown and the value can be chosen from them.

images/en/stnt_batch_method.png

SEXTANTE batch method

For all parameter cells, if the introduced value is correct, it will be shown in black. If the value is wrong (for instance, a numerical value out of the valid range or an option that does not exists for a selection parameter), the text will be shown in red.

images/en/stnt_batch_wrong.png

SEXTANTE batch wrong value

The most important different between executing an algorithm from the toolbox and executing it as part of a batch process is that input data objects are taken directly from files, and not from the set of layers already opened in the GIS. For this reason, any algorithm can be executed as a batch process even if no data objects at all are opened and the algorithm cannot be called from the toolbox.

Filenames for input data objects are introduced directly typing or, more conveniently, clicking on the button on the right hand of the cell, which shows a typical file chooser dialog. Multiple files can be selected at once. If the input parameter represents a single data object and several files are selected, each one of them will be put in a separate row, adding new ones if needed. If it represents a multiple input, all the selected files will be added to a single cell, separated by commas.

If multiple bands are required, a more complex dialog is shown, which incorporates a table for selecting both layer files and bands. Click on the cells on the left side to select the file which contains the raster layer. Then click on the left side to select the bands you want to use from that layer. To know the number of bands in a layer it would be necessary to open it. However, SEXTANTE does not open the layer, and shows instead a list of bands from 1 to 250 to select from. If you select a band that does not exist in the selected layer, an error message will be shown at execution time.

images/en/stnt_batch_band.png

SEXTANTE batch band dialog

Output data objects are always saved to a file and, unlike when executing an algorithm from the toolbox, saving to a temporary one is not permitted. You can type the name directly or use the file chooser dialog that appears when clicking on the accompanying button. This dialog differs slightly from the standard one, incorporating some additional fields for autocompletion.

images/en/stnt_batch_save.png

SEXTANTE batch save dialog

If the default value (Do not autofill) is selected, SEXTANTE will just put the selected filename in the selected cell from the parameters table. If any of the other options is selected, all the cells below the selected one will be automatically lled based on a defined criteria. This way, it is much easier to ll the table, and the batch process can be defined with less effort.

Automatic filling can be done simply adding correlative numbers to the selected filepath, or appending the value of another field at the same row. This is particularly useful for naming output data object according to input ones. Cells can be selected just clicking and dragging. Selected cells can be copied and pasted in a different place of the parameters table, making it easy to ll it with repeated values.


Setting raster output characteristics

Just like when executing a single algorithm, when running a batch process that generates raster layers you must define the extent and cellsize of the raster layers to be created. The corresponding Raster Output tab is similar to the one found when running a single algorithm, but only contains two options: t to input layers and user-defined.

The selection will be applied to all the single executions contained in the current batch process. If you want to use different raster output configurations, then you must define different batch processes.

images/en/stnt_batch_output.png

SEXTANTE batch raster output dialog


Executing the batch process

To execute the batch process once you have introduced all the necessary values, just click on OK. SEXTANTE will show the progress of each executed algorithm, and at the end will show a dialog with information about the values used and the problems encountered during the execution of the whole process.


Batch processing with layers in the current project

It is possible to execute the batch processing from a set of layers from the current view, clicking on the correct option in the toolbox tree, similar as it was the usual batch processing.


The Sextante command-line interface

Introduction

The command-line interface allows advanced users to increase their productivity and perform complex operations that cannot be performed using any of the other elements of the SEXTANTE GUI. Models involving several algorithms can be defined using the command-line interface, and additional operations such as loops and conditional sentences can be added to create more flexible and powerful workflows.


The interface

Introduction

Invoking the command-line interface will make the following dialog appear.

images/en/stnt_command.png

SEXTANTE command-line

The SEXTANTE 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.

A detailed description of BeanShell and its usage can be found at the BeanShell website. Refer to it if you want to learn more about generic BeanShell features. This chapter covers only those particular elements which are related to SEXTANTE geoalgorithms.

By using the extension mechanisms of BeanShell, SEXTANTE adds several new commands to it, so you can run geoalgorithms or get information about the geospatial data you are using, among other things.

Java users can create small scripts and programs combining standard elements of Java with SEXTANTE commands. However, those who are not familiar with Java can also use the command-line interface to execute single processes or small sets of them, simply calling the corresponding methods.

A detailed description of all SEXTANTE commands is given next.


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 the GIS (and which usually can be modied using GIS tool). To call a geoalgorithm you have to pass it an identifier which represents the data to use for an input.

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
-----------------
Curvas de nivel

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

Be aware that gvSIG allows you to have several layers with the same name. SEXTANTE will just take the first one which matches the specified identifier, so you should make sure you rename your data object so each one of them has a unique name.

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 
Type: Vector layer - Point
Number of entities: 300
Table fields: | ID | X | Y | SAND | SILT | CLAY | SOILTYPE | EXTRAPOLAT |

>describe dem25
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 
Type: TableNumber of records: 156 
Table fields: | Distance | I_Moran | c_Geary | Semivariance |

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

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 ow 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])

Running an algorithm

Now you know how to describe data and algorithms, so you have everything you need to run any algorithm. There is only one single command to execute algorithms: runalg. Its syntax is as follows:

> runalgname_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 aquick review of how to introduce values for each type of input parameter

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 usage example:

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

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

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]) ***************

The next line shows a valid usage example:

> 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).

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

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 "#".


Adjusting output raster characterisitics

Just like when you execute a geoalgorithm from the toolbox, when it generates new raster layers you have to define the extent and cellsize 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)

If you want to define the output raster characteristics manually or using a supporting layer, you have to use the extent command, which has three different variants.

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 this command is used, the autoextent functionality is automatically deactivated.


The Sextante history manager

Introduction

Every time you execute a SEXTANTE algorithm, information about the process is stored in the SEXTANTE history manager. Along with the parameters used, the date and time of the execution are also saved.

This way, it is easy to track the and control all the work that has been developed using SEXTANTE, and easily reproduce it.

The SEXTANTE history manager is a set of registries grouped according to their date of execution, making it easier to find information about an algorithm executed at any particular moment.

images/en/stnt_history.png

SEXTANTE history manager

Process information is kept as a command-line expression, even if the algorithm was launched from the toolbox. This makes it also useful for those learning how to use the command-line interface, since they can call an algorithm using the toolbox and then check the history manager to see how that same algorithm could be called from the command-line.

Apart from browsing the entries in the registry, processes can be reexecuted, simply double-clicking on the corresponding entry.



-----------------------------------
  1. Se ha producido un error en el documento Context help , accediendo a la imagen stnt_help.png, que probablemente no existe. No se han encontrado alternativas
  2. Se ha producido un error en el documento Context help , accediendo a la imagen stnt_edit_help.png, que probablemente no existe. No se han encontrado alternativas

Cached time 11/22/13 04:21:56 Clear cache and reload