Debian Codegraph @

lib/init/grass.html

raw
1 <!-- meta page description: GRASS startup program -->
2
3 <h2>SYNOPSIS</h2>
4
5 <b>grass</b> [<b>-h</b> | <b>-help</b> | <b>--help</b>] [<b>-v</b> | <b>--version</b>] |
6 [<b>-c</b> | <b>-c geofile</b> | <b>-c EPSG:code[:datum_trans]</b>] | <b>-e</b> | <b>-f</b> |
7 [<b>--text</b> | <b>--gtext</b> | <b>--gui</b>] | <b>--config</b> |
8 [<b>--tmp-project</b> | <b>--tmp-mapset</b>]
9 [[[<b>&lt;GISDBASE&gt;/</b>]<b>&lt;PROJECT&gt;/</b>]
10 <b>&lt;MAPSET&gt;</b>]
11 [<b>--exec EXECUTABLE</b>]
12
13 <h3>Flags:</h3>
14
15 <dl>
16
17 <dt><b>-h</b> | <b>-help</b> | <b>--help</b>
18 <dd> Prints a brief usage message and exits
19
20 <dt><b>-v</b> | <b>--version</b>
21 <dd> Prints the version of GRASS and exits
22
23 <dt><b>-c XY</b>
24 <dd> Creates new GRASS project (location) without coordinate reference system in specified GISDBASE
25
26 <dt><b>-c geofile</b>
27 <dd> Creates new GRASS project in specified GISDBASE with coordinate reference system based on georeferenced file
28
29 <dt><b>-c EPSG:code</b>
30 <dd> Creates new GRASS project in specified GISDBASE with coordinate reference system defined by EPSG code
31
32 <dt><b>-c EPSG:code:datum_trans</b>
33 <dd> Creates new GRASS project in specified GISDBASE with coordinate reference system defined by EPSG code and datum transform parameters
34
35 <dt><b>-e</b>
36 <dd> Exit after creation of project or mapset. Only with <b>-c</b> flag
37
38 <dt><b>-f</b>
39 <dd> Forces removal of .gislock if exists (use with care!). Only with --text flag
40
41 <dt><b>--text</b>
42 <dd> Indicates that Text-based User Interface should be used (skip welcome screen)
43
44 <dt><b>--gtext</b>
45 <dd> Indicates that Text-based User Interface should be used (show welcome screen)
46
47 <dt><b>--gui</b>
48 <dd> Indicates that Graphical User Interface
49 (<em><a href="wxGUI.html">wxGUI</a></em>) should be used
50
51 <dt><b>--config</b>
52 <dd> Prints GRASS configuration parameters (options: arch, build, compiler, date, path, python_path, revision, svn_revision, version)
53
54 <dt><b>--exec EXECUTABLE</b>
55 <dd> Execute GRASS module or script. The provided executable will be executed in a GRASS non-interactive session.
56
57 <dt><b>--tmp-project</b>
58 <dd> Run using a temporary project which is created based on the given
59 coordinate reference system and deleted at the end of the execution
60 (use with the --exec flag).
61 The active mapset will be the PERMANENT mapset.
62
63 <dt><b>--tmp-mapset</b>
64 <dd> Run using a temporary mapset which is created in the specified
65 project and deleted at the end of the execution
66 (use with the --exec flag).
67
68 </dl>
69
70 <h3>Parameters:</h3>
71
72 <dl>
73 <dt><b>GISDBASE</b>
74 <dd> Initial database directory which should be a fully qualified path
75 (e.g., <code>/usr/local/share/grassdata</code>)
76
77 <dt><b>PROJECT</b>
78 <dd> Initial project directory which is a subdirectory of GISDBASE
79 (project was previously called location)
80
81 <dt><b>MAPSET</b>
82 <dd> Initial mapset directory which is a subdirectory of PROJECT
83 </dl>
84
85 <i>Note</i>: These parameters must be specified in one of the
86 following ways:
87
88 <div class="code"><pre>
89 MAPSET
90 PROJECT/MAPSET
91 GISDBASE/PROJECT/MAPSET
92 </pre></div>
93
94 <h2>DESCRIPTION</h2>
95
96 <p>This command is used to launch GRASS. It will parse the command
97 line arguments and then initialize GRASS for the user. Since GRASS
98 modules require a specific environment, this program must be called
99 before any other GRASS module can run. The command line arguments are
100 optional and provide the user with a method to indicate the desired
101 user interface, as well as the desired mapset to work on.
102
103 <p>The startup program will remember both the desired user interface
104 and mapset. Thus, the next time the user runs GRASS, typing
105 <em>grass</em> (without any options) will start GRASS with the
106 previous settings for the user interface and mapset selected.
107
108 <p>If you specify a graphical user interface (<b>--gui</b>)
109 the <em>grass</em> program will try to verify that the system you
110 specified exists and that you can access it successfully. If any of
111 these checks fail then <em>grass</em> will automatically switch back
112 to the text user interface mode.
113
114 <h3>Running non-interactive jobs</h3>
115
116 The <b>--exec</b> flag can run an executable on path, GRASS module, or a script.
117 All are executed as a subprocess and any additional arguments are passed to it.
118 A script needs to be specified by full or relative path and on unix-likes systems,
119 the script file must have its executable bit set. Calling the interpreter
120 (e.g., <code>python</code>) and providing the script as a parameter is possible, too.
121 When it is finished GRASS will automatically exit using the return code given
122 by the subprocess. Although the execution itself is non-interactive (no GUI or shell),
123 the subprocess itself can be interactive if that is what the user requires.
124
125 <h3>Config flag</h3>
126
127 The flag <b>--config option</b> prints GRASS configuration and
128 version parameters, with the options:
129
130 <ul>
131 <li><b>arch</b>: system architecture (e.g., <code>x86_64-pc-linux-gnu</code>)</li>
132 <li><b>build</b>: (e.g., <code>./configure --with-cxx --enable-largefile --with-proj [...]</code>)</li>
133 <li><b>compiler</b>: (e.g., <code>gcc</code>)</li>
134 <li><b>date</b>: (e.g., <code>2024-04-10T11:44:54+00:00</code>)</li>
135 <li><b>path</b>: (e.g., <code>/usr/lib64/grass</code>)</li>
136 <li><b>python_path</b>: (e.g., <code>/usr/lib64/grass/etc/python</code>)</li>
137 <li><b>revision</b>: (e.g., <code>745ee7ec9</code>)</li>
138 <li><b>svn_revision</b>: (e.g., <code>062bffc8</code>)</li>
139 <li><b>version</b>: (e.g., <code>8.4.0</code>)</li>
140 </ul>
141
142 <h2>SAMPLE DATA</h2>
143
144 The GRASS project provides several free sample geospatial datasets
145 as ready-to-use projects. They are available to download at
146 <a href="https://grass.osgeo.org/download/sample-data/">https://grass.osgeo.org/download/sample-data/</a>.
147
148 The "North Carolina data set" is a modern package of geospatial data from
149 North Carolina (USA), and it includes raster, vector, LiDAR and satellite
150 data. This is the most extensively used data set in the documentation and
151 the examples throughout the user manual pages are based upon it.
152
153 <h2>ENVIRONMENT VARIABLES</h2>
154
155 A number of environment variables are available at GRASS startup to
156 assist with automation and customization. Most users will not need to
157 bother with these.
158
159 <p>In addition to these shell environment variables GRASS maintains a
160 number of GIS environment variables in the <code>$HOME/.grass8/rc</code>
161 file. User changes to this file will be read during the next startup
162 of GRASS. If this file becomes corrupted the user may edit it by hand
163 or remove it to start afresh. See the list
164 of <em><a href="variables.html">implemented GRASS variables</a></em>
165 for more information. The rest of this help page will only consider
166 shell environment variables.
167
168 <p>Note that you will need to set these variables using the
169 appropriate method required for the UNIX shell that you use (e.g. in a
170 Bash shell you must <code>export</code> the variables for them to
171 propagate).
172
173 <h3>User Interface Environment Variable</h3>
174
175 <p>The <em>grass</em> program will check for the existence of an
176 environment variable called GRASS_GUI which indicates the type of user
177 interface for GRASS to use. If this variable is not set
178 when <em>grass</em> is run, then it will be created and then saved
179 in the <code>$HOME/.grass8/rc</code> file for the next time GRASS is
180 run. It can be set to <code>text</code>, <code>gtext</code> or <code>gui</code>.
181
182 <p>There is an order of precedence in the way <em>grass</em>
183 determines the user interface to use. The following is the hierarchy
184 from highest precedence to lowest.
185 <ol>
186 <li>Command line argument</li>
187 <li>Environment variable GRASS_GUI</li>
188 <li>Value set in <code>$HOME/.grass8/rc</code> (GUI)</li>
189 <li>Default value - <code>gui</code></li>
190 </ol>
191
192 <h3>Python Environment Variables</h3>
193
194 <p>If you choose to use <em><a href="wxGUI.html">wxGUI</a></em>
195 interface, then the GRASS_PYTHON environment variable can be used to
196 override your system default <code>python</code> command.
197
198 <p>Suppose for example your system has Python 3.6 installed and you
199 install a personal version of the Python 3.8 binaries
200 under <code>$HOME/bin</code>. You can use the above variables to have
201 GRASS use the Python 3.8 binaries instead.
202
203 <div class="code"><pre>
204 GRASS_PYTHON=python3.8
205 </pre></div>
206
207 <h3>Addon Path to Extra User Scripts</h3>
208
209 This environment variable allows the user to extend the GRASS program
210 search paths to include locally developed/installed GRASS modules or
211 user scripts.
212
213 <div class="code"><pre>
214 GRASS_ADDON_PATH=/usr/mytools
215 GRASS_ADDON_PATH=/usr/mytools:/usr/local/othertools
216 </pre></div>
217
218 <p>In this example above path(s) would be added to the standard GRASS path
219 environment.
220
221 <h3>Addon Base for Extra Local GRASS Addon Modules</h3>
222
223 This environment variable allows the user to extend the GRASS program
224 search paths to include locally installed
225 (see <em><a href="g.extension.html">g.extension</a></em> for details)
226 <a href="https://grasswiki.osgeo.org/wiki/GRASS_AddOns">GRASS Addon</a>
227 modules which are not distributed with the standard GRASS release.
228 <div class="code"><pre>
229 GRASS_ADDON_BASE=/usr/grass-addons
230 </pre></div>
231
232 <p>In this example above path would be added to the standard GRASS
233 path environment.
234
235 <p>If not defined by user, this variable is set by GRASS startup program
236 to <code>$HOME/.grass8/addons</code> on GNU/Linux
237 and <code>%APPDATA%\Roaming\GRASS8\addons</code> on MS Windows.
238
239 <h3>HTML Browser Variable</h3>
240
241 The GRASS_HTML_BROWSER environment variable allows the user to set the
242 HTML web browser to use for displaying help pages.
243
244 <h2>EXAMPLES</h2>
245
246 <p>The following are some examples of how you could start GRASS
247
248 <dl>
249 <dt><b>grass</b>
250 <dd> Start GRASS using the default user interface. The user will be
251 prompted to choose the appropriate project and mapset.
252
253 <dt><b>grass --gui</b>
254 <dd> Start GRASS using the graphical user interface. The user will be
255 prompted to choose the appropriate project and mapset.
256
257 <dt><b>grass --text</b>
258 <dd> Start GRASS using the text-based user interface. Appropriate
259 project and mapset must be set by environmental variables (see
260 examples below) otherwise taken from the last GRASS session.</dd>
261
262 <dt><b>grass --gtext</b>
263 <dd> Start GRASS using the text-based user interface. The user will be
264 prompted to choose the appropriate project and mapset.
265
266 <dt><b>grass $HOME/grassdata/spearfish70/user1</b>
267 <dd> Start GRASS using the default user interface and automatically
268 launch into the given mapset, bypassing the mapset selection menu.
269
270 <dt><b>grass --gui -</b>
271 <dd> Start GRASS using the graphical user interface and try to
272 obtain the project and mapset from environment variables.
273
274 <dt><b>grass -c EPSG:4326 $HOME/grassdata/myproject</b>
275 <dd> Creates a new GRASS project with EPSG code 4326 (latitude-longitude, WGS84)
276 in the specified GISDBASE
277
278 <dt><b>grass -c EPSG:5514:3 $HOME/grassdata/myproject</b>
279 <dd> Creates a new GRASS project with EPSG code 5514 (S-JTSK / Krovak
280 East North - SJTSK) with datum transformation parameters used in
281 Czech Republic in the specified GISDBASE
282
283 <dt><b>grass -c XY $HOME/grassdata/gnomonic --exec g.proj -c proj4='+proj=gnom +lat_0=90 +lon_0=-50'</b>
284 <dd> Creates a new GRASS project from PROJ definition string
285 (here: <a href="https://proj4.org/operations/projections/gnom.html">gnomonic</a>)
286 in the specified GISDBASE
287
288 <dt><b>grass -c myvector.shp $HOME/grassdata/myproject</b>
289 <dd> Creates a new GRASS project based on georeferenced Shapefile
290
291 <dt><b>grass -c myraster.tif $HOME/grassdata/myproject</b>
292 <dd> Creates a new GRASS project based on georeferenced GeoTIFF file
293 </dl>
294
295 <h3>Batch jobs with the exec interface</h3>
296
297 <!--
298 Data created with:
299 r.out.gdal input=elevation output=elevation.tiff
300 r.out.gdal input=basin_50K output=basins.tiff
301 Region issues ignored.
302 -->
303
304 Creating a new project based on a geodata file's projection (<b>-c</b>)
305 and exit (<b>-e</b>) immediately:
306
307 <div class="code"><pre>
308 grass -c elevation.tiff -e /path/to/grassdata/test1/
309 </pre></div>
310
311 Linking external raster data to PERMANENT Mapset:
312
313 <div class="code"><pre>
314 grass /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins
315 grass /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation
316 </pre></div>
317
318 Get statistics for one raster map:
319
320 <div class="code"><pre>
321 grass /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation
322 </pre></div>
323
324 Compare the rasters visually:
325
326 <div class="code"><pre>
327 grass /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
328 </pre></div>
329
330 <h4>Execution of shell and Python scripts instead of single commands</h4>
331
332 A sequence of commands can be bundled in a script and executed using the
333 exec interface.
334 <p>
335 <b>Shell script example:</b> the command to execute a shell script might be:
336
337 <div class="code"><pre>
338 grass /path/to/grassdata/test1/PERMANENT/ --exec sh test.sh
339 </pre></div>
340
341 A very simple bash script ("test.sh") may look like this:
342
343 <div class="code"><pre>
344 #!/bin/bash
345
346 g.region -p
347 g.list type=raster
348 r.info elevation
349 </pre></div>
350
351 <p>
352 <b>Python script example:</b> the command to execute a Python script might be:
353
354 <div class="code"><pre>
355 grass /path/to/grassdata/test1/PERMANENT/ --exec python test.py
356 </pre></div>
357
358 A very simple Python script ("test.py") may look like this:
359
360 <div class="code"><pre>
361 #!/usr/bin/env python3
362
363 # import GRASS Python bindings (see also pygrass)
364 import grass.script as gs
365
366 gs.message('Current GRASS environment:')
367 print(gs.gisenv())
368
369 gs.message('Available raster maps:')
370 for raster in gs.list_strings(type='raster'):
371 print(raster)
372
373 gs.message('Available vector maps:')
374 for vector in gs.list_strings(type='vector'):
375 print(vector)
376 </pre></div>
377
378 <h4>Using temporary project</h4>
379
380 Creating a new temporary project based on a georeferenced file's
381 coordinate reference system (CRS) and simultaneously starting
382 computation in a shell script:
383
384 <div class="code"><pre>
385 grass --tmp-project elevation.tiff --exec test.sh
386 </pre></div>
387
388 The same, but using an EPSG code and a Python script:
389
390 <div class="code"><pre>
391 grass --tmp-project EPSG:3358 --exec test.py
392 </pre></div>
393
394 Finally, for special cases, we can create an XY project without any CRS:
395
396 <div class="code"><pre>
397 grass --tmp-project XY --exec test.py
398 </pre></div>
399
400 Temporary project is automatically deleted after computation,
401 so the script is expected to export, link or otherwise preserve the
402 output data before ending.
403
404 <p>
405 A single command can be also executed, e.g. to examine properties of the
406 temporary project:
407
408 <div class="code"><pre>
409 grass --tmp-project EPSG:3358 --exec g.proj -p
410 </pre></div>
411
412 A temporary XY project with single command is useful, e.g. to show
413 help text of a module:
414
415 <div class="code"><pre>
416 grass --tmp-project XY --exec r.neighbors --help
417 </pre></div>
418
419
420 <h4>Using temporary mapset</h4>
421
422 <p>
423 A single command can be executed, e.g., to examine properties of a
424 project (here using the NC SPM sample dataset):
425
426 <div class="code"><pre>
427 grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec g.proj -p
428 </pre></div>
429
430 Computation in a Python script can be executed in the same way:
431
432 <div class="code"><pre>
433 grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py
434 </pre></div>
435
436 Additional parameters are just passed to the script, so we can run the
437 script with different sets of parameters (here 5, 8 and 3, 9) in
438 different temporary mapsets which is good for parallel processing.
439
440 <div class="code"><pre>
441 grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py 5 8
442 grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.py 3 9
443 </pre></div>
444
445 The same applies to Bash scripts (and other scripts supported on you
446 platform):
447
448 <div class="code"><pre>
449 grass --tmp-mapset /path/to/grassdata/nc_spm_08/ --exec processing.sh 5 8
450 </pre></div>
451
452 The temporary mapset is automatically deleted after computation,
453 so the script is expected to export, link or otherwise preserve the
454 output data before ending.
455
456
457 <h4>Troubleshooting</h4>
458 Importantly, to avoid an <code>"[Errno 8] Exec format error"</code> there must be a
459 <a href="https://en.wikipedia.org/wiki/Shebang_%28Unix%29">shebang</a> line at the top of
460 the script (like <code>#!/bin/sh</code>, <code>#!/bin/bash</code>, or <code>#!/usr/bin/env python3</code>)
461 indicating which interpreter to be used for the script. The script file must
462 have its executable bit set.
463
464 <h2>CAVEAT</h2>
465
466 If you start GRASS using the <em><a href="wxGUI.html">wxGUI</a></em>
467 interface you must have a <code>python</code> command in your $PATH
468 variable. That is, the command must be named
469 <code>python</code> and not something like <code>python3.6</code>. Rarely some
470 Python installations do not create a <code>python</code> command. In these
471 cases you can override <code>python</code> by GRASS_PYTHON environmental
472 variable.
473
474 <p>Furthermore, if you have more than one version of Python installed,
475 make sure that the version you want to use with GRASS is set by
476 GRASS_PYTHON environmental variable.
477
478 <h2>SEE ALSO</h2>
479
480 List of <a href="variables.html">GRASS environment variables</a>
481
482 <p>
483 <a href="https://grass.osgeo.org">GRASS Web site</a><br>
484 <a href="https://grasswiki.osgeo.org/wiki/">GRASS User Wiki</a><br>
485 <a href="https://github.com/OSGeo/grass/issues">GRASS Bug Tracker</a><br>
486 <a href="https://grass.osgeo.org/programming8/">GRASS 8 Programmer's Manual</a>
487
488 <h2>AUTHORS (of this page)</h2>
489
490 Justin Hickey<br>
491 Markus Neteler<br>
492 Hamish Bowman<br>
493 Martin Landa, Czech Technical University in Prague, Czech Republic