gvsig-geoprocess / org.gvsig.geoprocess / trunk / org.gvsig.geoprocess / org.gvsig.geoprocess.app / org.gvsig.geoprocess.app.mainplugin / src / main / resources / help / en / general / batch.html @ 338
History | View | Annotate | Download (14.3 KB)
| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|---|
| 2 |
|
| 3 |
<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
|
| 4 |
original version by: Nikos Drakos, CBLU, University of Leeds
|
| 5 |
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
|
| 6 |
* with significant contributions from:
|
| 7 |
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
|
| 8 |
<HTML>
|
| 9 |
<HEAD>
|
| 10 |
<TITLE>The SEXTANTE command-line interface</TITLE> |
| 11 |
<META NAME="description" CONTENT="The SEXTANTE command-line interface"> |
| 12 |
<META NAME="keywords" CONTENT="IntroductionToSEXTANTE"> |
| 13 |
<META NAME="resource-type" CONTENT="document"> |
| 14 |
<META NAME="distribution" CONTENT="global"> |
| 15 |
|
| 16 |
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> |
| 17 |
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1"> |
| 18 |
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| 19 |
|
| 20 |
<LINK REL="STYLESHEET" HREF="IntroductionToSEXTANTE.css"> |
| 21 |
|
| 22 |
</HEAD>
|
| 23 |
|
| 24 |
<BODY > |
| 25 |
<!--Table of Child-Links-->
|
| 26 |
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> |
| 27 |
|
| 28 |
<UL CLASS="ChildLinks"> |
| 29 |
<LI><A NAME="tex2html202" |
| 30 |
HREF="node7.html#SECTION00710000000000000000">Introduction</A> |
| 31 |
<LI><A NAME="tex2html203" |
| 32 |
HREF="node7.html#SECTION00720000000000000000">The interface</A> |
| 33 |
<UL>
|
| 34 |
<LI><A NAME="tex2html204" |
| 35 |
HREF="node7.html#SECTION00721000000000000000">Getting information about data</A> |
| 36 |
</UL>
|
| 37 |
<BR>
|
| 38 |
<LI><A NAME="tex2html205" |
| 39 |
HREF="node7.html#SECTION00730000000000000000">Getting information about algorithms</A> |
| 40 |
<LI><A NAME="tex2html206" |
| 41 |
HREF="node7.html#SECTION00740000000000000000">Running an algorithm</A> |
| 42 |
<LI><A NAME="tex2html207" |
| 43 |
HREF="node7.html#SECTION00750000000000000000">Adjusting output raster characteristics</A> |
| 44 |
<LI><A NAME="tex2html208" |
| 45 |
HREF="node7.html#SECTION00760000000000000000">Running a model</A> |
| 46 |
<LI><A NAME="tex2html209" |
| 47 |
HREF="node7.html#SECTION00770000000000000000">Managing layers from the command-line interface</A> |
| 48 |
</UL>
|
| 49 |
<!--End of Table of Child-Links-->
|
| 50 |
<HR>
|
| 51 |
|
| 52 |
<H1><A NAME="SECTION00700000000000000000"> |
| 53 |
The SEXTANTE command-line interface</A>
|
| 54 |
</H1>
|
| 55 |
|
| 56 |
<H1><A NAME="SECTION00710000000000000000"> |
| 57 |
Introduction</A>
|
| 58 |
</H1>
|
| 59 |
|
| 60 |
<P>
|
| 61 |
The command-line interface allows advanced users to increase their productivity and performe 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. |
| 62 |
|
| 63 |
<P>
|
| 64 |
|
| 65 |
<H1><A NAME="SECTION00720000000000000000"> |
| 66 |
The interface</A>
|
| 67 |
</H1>
|
| 68 |
|
| 69 |
<P>
|
| 70 |
Invoking the command-line interface will make the following dialog appear. |
| 71 |
|
| 72 |
<P>
|
| 73 |
<DIV ALIGN="CENTER"> |
| 74 |
<IMG
|
| 75 |
WIDTH="397" HEIGHT="297" ALIGN="BOTTOM" BORDER="0" |
| 76 |
SRC="./command_line.png" |
| 77 |
ALT="Image command_line"> |
| 78 |
|
| 79 |
</DIV>
|
| 80 |
|
| 81 |
<P>
|
| 82 |
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. |
| 83 |
|
| 84 |
<P>
|
| 85 |
A detailed description of BeanShell and its usage can be found at the BeanShell website<A NAME="tex2html2" |
| 86 |
HREF="footnode.html#foot617"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A>. 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. |
| 87 |
|
| 88 |
<P>
|
| 89 |
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. |
| 90 |
|
| 91 |
<P>
|
| 92 |
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. |
| 93 |
|
| 94 |
<P>
|
| 95 |
A detailed description of all SEXTANTE commands is given next. |
| 96 |
|
| 97 |
<P>
|
| 98 |
|
| 99 |
<H2><A NAME="SECTION00721000000000000000"> |
| 100 |
Getting information about data</A>
|
| 101 |
</H2>
|
| 102 |
|
| 103 |
<P>
|
| 104 |
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 modified using GIS tool). To call a geoalgorithm you have to pass it an identifier which represents the data to use for an input. |
| 105 |
|
| 106 |
<P>
|
| 107 |
The <TT>data()</TT> 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: |
| 108 |
|
| 109 |
<P>
|
| 110 |
<PRE>
|
| 111 |
RASTER LAYERS |
| 112 |
----------------- |
| 113 |
mdt25.asc |
| 114 |
|
| 115 |
VECTOR LAYERS |
| 116 |
----------------- |
| 117 |
Contour lines |
| 118 |
|
| 119 |
TABLES |
| 120 |
----------------- |
| 121 |
</PRE>
|
| 122 |
|
| 123 |
<P>
|
| 124 |
Be aware that some GIS allow you two 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. |
| 125 |
|
| 126 |
<P>
|
| 127 |
To get more information about a particular data object, use the <TT>describe(name_of_data_object)</TT> 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. |
| 128 |
|
| 129 |
<P>
|
| 130 |
<PRE>
|
| 131 |
>describe points
|
| 132 |
Type: Vector layer - Point |
| 133 |
Number of entities: 300 |
| 134 |
Table fields: | ID | X | Y | SAND | SILT | CLAY | SOILTYPE | EXTRAPOLAT | |
| 135 |
|
| 136 |
>describe dem25
|
| 137 |
Type: Raster layer |
| 138 |
X min: 262846.525725 |
| 139 |
X max: 277871.525725 |
| 140 |
Y min: 4454025.0 |
| 141 |
Y max: 4464275.0 |
| 142 |
Cellsize X: 25.0 |
| 143 |
Cellsize Y: 0.0 |
| 144 |
Rows: 410 |
| 145 |
Cols: 601 |
| 146 |
|
| 147 |
>describe spatialCorrelation
|
| 148 |
Type: TableNumber of records: 156 |
| 149 |
Table fields: | Distance | I_Moran | c_Geary | Semivariance | |
| 150 |
</PRE>
|
| 151 |
|
| 152 |
<P>
|
| 153 |
|
| 154 |
<H1><A NAME="SECTION00730000000000000000"> |
| 155 |
Getting information about algorithms</A>
|
| 156 |
</H1>
|
| 157 |
|
| 158 |
<P>
|
| 159 |
Once you know which data you have, it is time to know which algorithms are available and how to use them. |
| 160 |
|
| 161 |
<P>
|
| 162 |
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 <TT>algs()</TT> 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. |
| 163 |
|
| 164 |
<P>
|
| 165 |
<PRE>
|
| 166 |
bsh % algs(); |
| 167 |
acccost-------------------------------: Accumulated cost(isotropic) |
| 168 |
acccostanisotropic--------------------: Accumulated cost (anisotropic) |
| 169 |
acccostcombined-----------------------: Accumulated cost (combined) |
| 170 |
accflow-------------------------------: Flow accumulation |
| 171 |
acv-----------------------------------: Anisotropic coefficient of variation |
| 172 |
addeventtheme-------------------------: Points layer from table |
| 173 |
aggregate-----------------------------: Aggregate |
| 174 |
aggregationindex----------------------: Aggregation index |
| 175 |
ahp-----------------------------------: Analytical Hierarchy Process (AHP) |
| 176 |
aspect--------------------------------: Aspect |
| 177 |
buffer--------------------------------: Buffer |
| 178 |
</PRE>
|
| 179 |
|
| 180 |
<P>
|
| 181 |
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. |
| 182 |
|
| 183 |
<P>
|
| 184 |
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 <TT>describealg(name_of_the_algorithm)</TT> method. Use the command-line name of the algorithm, not the full descriptive name. |
| 185 |
|
| 186 |
<P>
|
| 187 |
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 <TT>ags()</TT> method, is identified as <TT>accflow</TT>. The following is a description of its inputs and outputs. |
| 188 |
|
| 189 |
<P>
|
| 190 |
<PRE>
|
| 191 |
>describealg("accflow")
|
| 192 |
Usage: accflow(DEM[Raster Layer] |
| 193 |
WEIGHTS[Optional Raster Layer] |
| 194 |
METHOD[Selection] |
| 195 |
CONVERGENCE[Numerical Value] |
| 196 |
FLOWACC [output raster layer]) |
| 197 |
</PRE>
|
| 198 |
|
| 199 |
<P>
|
| 200 |
|
| 201 |
<H1><A NAME="SECTION00740000000000000000"> |
| 202 |
Running an algorithm</A>
|
| 203 |
</H1>
|
| 204 |
|
| 205 |
<P>
|
| 206 |
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: <TT>runalg</TT>. Its syntax is as follows: |
| 207 |
|
| 208 |
<P>
|
| 209 |
<PRE>
|
| 210 |
> runalg{name_of_the_algorithm, param1, param2, ..., paramN)
|
| 211 |
</PRE>
|
| 212 |
|
| 213 |
<P>
|
| 214 |
The list of parameters to add depends on the algorithm you want to run, and is exactly the list that the <TT>describealg</TT> method gives you, in the same order as shown. |
| 215 |
|
| 216 |
<P>
|
| 217 |
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 |
| 218 |
|
| 219 |
<UL>
|
| 220 |
<LI>Raster Layer, Vector Layer or Table. Simply introduce the name that identifies the data object to use. If the input is optional and you do not want to use any data object, write ``#''.
|
| 221 |
</LI>
|
| 222 |
<LI>Numerical value. Directly type the value to use or the name of a variable containing that value.
|
| 223 |
</LI>
|
| 224 |
<LI>Selection. Type the number that identifies the desired option, as shown by the <TT>options</TT> command |
| 225 |
</LI>
|
| 226 |
<LI>String. Directly type the string to use or the name of a variable containing it.
|
| 227 |
</LI>
|
| 228 |
<LI>Boolean. Type whether ``true'' or ``false'' (including quotes)
|
| 229 |
</LI>
|
| 230 |
<LI>Multiple selection - data_type. Type the list of objects to use, separated by commas and enclosed between quotes.
|
| 231 |
|
| 232 |
<P>
|
| 233 |
For example, for the <TT>maxvaluegrid</TT> algorithm: |
| 234 |
|
| 235 |
<P>
|
| 236 |
<PRE>
|
| 237 |
|
| 238 |
Usage: runalg("maxvaluegrid",
|
| 239 |
INPUT[Multiple Input - Raster Layer] |
| 240 |
NODATA[Boolean], |
| 241 |
RESULT[Output raster layer]) |
| 242 |
</PRE>
|
| 243 |
|
| 244 |
<P>
|
| 245 |
The next line shows a valid usage example: |
| 246 |
|
| 247 |
<P>
|
| 248 |
<PRE>
|
| 249 |
> runalg("maxvaluegrid", "lyr1, lyr2, lyr3", "false", "#")
|
| 250 |
</PRE>
|
| 251 |
|
| 252 |
<P>
|
| 253 |
Of course, lyr1, lyr2 and lyr3 must be valid layers already loaded into your GIS. |
| 254 |
|
| 255 |
<P>
|
| 256 |
When the multiple input is comprised of raster bands, each element is represented by a pair of values <SPAN CLASS="textit">(layer, band)</SPAN>. For example, for the <TT>cluster</TT> algorithm |
| 257 |
|
| 258 |
<P>
|
| 259 |
<PRE>
|
| 260 |
Usage: runalg( "cluster", |
| 261 |
INPUT[Multiple Input - Band], |
| 262 |
NUMCLASS[Numerical Value], |
| 263 |
RESULTLAYER[output raster layer], |
| 264 |
RESULTTABLE[output table], |
| 265 |
); |
| 266 |
</PRE>
|
| 267 |
|
| 268 |
<P>
|
| 269 |
The next line shows a valid usage example: |
| 270 |
|
| 271 |
<P>
|
| 272 |
<PRE>
|
| 273 |
> runalg("cluster, "lyr1, 1, lyr1, 2, lyr2, 2", 5, "#", "#")
|
| 274 |
</PRE>
|
| 275 |
|
| 276 |
<P>
|
| 277 |
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). |
| 278 |
</LI>
|
| 279 |
<LI>&lsqb#lbrack;Table Field from XXX &rsqb#rbrack;. Write the name of the field to use. This parameter is case-sensitive. |
| 280 |
</LI>
|
| 281 |
<LI>&lsqb#lbrack;Fixed Table &rsqb#rbrack;Tabla fija. 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: |
| 282 |
|
| 283 |
<P>
|
| 284 |
<PRE>
|
| 285 |
runalg("kernelfilter", mdt25.asc, "-1, -1, -1, -1, 9, -1, -1, -1, -1", "#")
|
| 286 |
</PRE>
|
| 287 |
|
| 288 |
<P>
|
| 289 |
</LI>
|
| 290 |
<LI>&lsqb#lbrack;Point &rsqb#rbrack;. Write the pair of coordinates separated by commas and enclosed between quotes. For instance "220345, 4453616" |
| 291 |
|
| 292 |
<P>
|
| 293 |
</LI>
|
| 294 |
</UL>
|
| 295 |
|
| 296 |
<P>
|
| 297 |
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. |
| 298 |
|
| 299 |
<P>
|
| 300 |
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 ``#''. |
| 301 |
|
| 302 |
<P>
|
| 303 |
|
| 304 |
<H1><A NAME="SECTION00750000000000000000"> |
| 305 |
Adjusting output raster characteristics</A>
|
| 306 |
</H1>
|
| 307 |
|
| 308 |
<P>
|
| 309 |
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. |
| 310 |
|
| 311 |
<P>
|
| 312 |
By default, those characteristics are defined based on the input layers. You can toggle this behaviour using the <TT>autoextent</TT> command. |
| 313 |
|
| 314 |
<P>
|
| 315 |
<PRE>
|
| 316 |
> autoextent("true"/"false)
|
| 317 |
</PRE>
|
| 318 |
|
| 319 |
<P>
|
| 320 |
If you want to define the output raster characteristics manually or using a supporting layer, you have to use the <TT>extent</TT> command, which has three different variants. |
| 321 |
|
| 322 |
<P>
|
| 323 |
<PRE>
|
| 324 |
Usage: extent(raster layer[string]) |
| 325 |
extent(vector layer[string], cellsize[double]) |
| 326 |
extent(x min[double], y min[double], |
| 327 |
x max[double], y max[double], |
| 328 |
cell size[double]) |
| 329 |
Type "autoextent" to use automatic extent fitting when possible |
| 330 |
</PRE>
|
| 331 |
|
| 332 |
<P>
|
| 333 |
When this command is used, the autoextent functionality is automatically deactivated. |
| 334 |
|
| 335 |
<P>
|
| 336 |
|
| 337 |
<H1><A NAME="SECTION00760000000000000000"> |
| 338 |
Running a model</A>
|
| 339 |
</H1>
|
| 340 |
|
| 341 |
<P>
|
| 342 |
Models can be executed from the command-line using the <TT>model</TT> command, which has a sintax similar to the <TT>runalg</TT> command. In this case, you must use the filename where the model is stored instead of the name of the algorithm as the first parameters. SEXTANTE will look for that file in the models folder, so make sure that you have saved the model in that folder, or set the corresponding folder using the SEXTANTE preferences window. The remaining parameters depend on the particular model you want to execute, much like in the case of running a simple algorithm with the <TT>runalg</TT> command. |
| 343 |
|
| 344 |
<P>
|
| 345 |
|
| 346 |
<H1><A NAME="SECTION00770000000000000000"> |
| 347 |
Managing layers from the command-line interface</A>
|
| 348 |
</H1>
|
| 349 |
|
| 350 |
<P>
|
| 351 |
You can perform some operation with layers from the command-line interface, like the following ones: |
| 352 |
|
| 353 |
<P>
|
| 354 |
|
| 355 |
<UL>
|
| 356 |
<LI>Close a layer. Use the <TT>close(layer_name)</TT> command. |
| 357 |
</LI>
|
| 358 |
<LI>Change the no-data value of a raster layer. Use the <TT>setnodata(layer_name, new_value)</TT> command |
| 359 |
</LI>
|
| 360 |
<LI>Change the name of a layer. Use the <TT>rename(layer_name, new_layer_name)</TT> command |
| 361 |
</LI>
|
| 362 |
</UL>
|
| 363 |
|
| 364 |
<P>
|
| 365 |
<BR><HR> |
| 366 |
<ADDRESS>
|
| 367 |
Victor Olaya |
| 368 |
2010-02-18 |
| 369 |
</ADDRESS>
|
| 370 |
</BODY>
|
| 371 |
</HTML>
|