1grass7(1)                     Grass User's Manual                    grass7(1)
2
3
4

GRASS startup program

SYNOPSIS

7       grass78  [-h | -help | --help] [-v | --version] | [-c | -c geofile | -c
8       EPSG:code[:datum_trans]] | -e | -f |  [--text  |  --gtext  |  --gui]  |
9       --config  |  --exec  EXECUTABLE  | --tmp-location [[[<GISDBASE>/]<LOCA‐
10       TION>/] <MAPSET>]
11
12   Flags:
13       -h | -help | --help
14           Prints a brief usage message and exits
15
16       -v | --version
17           Prints the version of GRASS and exits
18
19       -c
20           Creates new GRASS unprojected location in specified GISDBASE
21
22       -c geofile
23           Creates new GRASS projected location in specified GISDBASE based on
24           georeferenced file
25
26       -c EPSG:code
27           Creates  new  GRASS  projected  location in specified GISDBASE with
28           given EPSG code
29
30       -c EPSG:code:datum_trans
31           Creates new GRASS projected location  in  specified  GISDBASE  with
32           given EPSG code and datum transform parameters
33
34       -e
35           Exit after creation of location or mapset. Only with -c flag
36
37       -f
38           Forces  removal  of  .gislock if exists (use with care!). Only with
39           --text flag
40
41       --text
42           Indicates that Text-based User Interface should be used (skip  wel‐
43           come screen)
44
45       --gtext
46           Indicates  that Text-based User Interface should be used (show wel‐
47           come screen)
48
49       --gui
50           Indicates that Graphical User Interface (wxGUI) should be used
51
52       --config
53           Prints GRASS configuration parameters (options: arch,  build,  com‐
54           piler, path, revision)
55
56       --exec EXECUTABLE
57           Execute  GRASS  module  or  script. The provided executable will be
58           executed in a GRASS GIS non-interactive session.
59
60       --tmp-location
61           Run using a temporary location which is created based on the  given
62           coordinate reference system and deleted at the end of the execution
63           (use the --exec flag).  The active mapset will be PERMANENT.
64
65   Parameters:
66       GISDBASE
67           Initial database directory which should be a fully  qualified  path
68           (e.g., /usr/local/share/grassdata)
69
70       LOCATION
71           Initial location directory which is a subdirectory of GISDBASE
72
73       MAPSET
74           Initial  mapset directory which is a subdirectory of LOCATION Note:
75           These parameters must be specified in one of the following ways:
76               MAPSET
77               LOCATION/MAPSET
78               GISDBASE/LOCATION/MAPSET
79

DESCRIPTION

81       This command is used to launch GRASS GIS. It  will  parse  the  command
82       line arguments and then initialize GRASS for the user. Since GRASS mod‐
83       ules require a specific environment, this program must be called before
84       any other GRASS module can run. The command line arguments are optional
85       and provide the user with a method to indicate the desired user  inter‐
86       face, as well as the desired mapset to work on.
87
88       The  startup  program will remember both the desired user interface and
89       mapset. Thus, the next time the user runs GRASS, typing grass78  (with‐
90       out  any  options)  will start GRASS with the previous settings for the
91       user interface and mapset selected.
92
93       If you specify a graphical user interface (--gui) the  grass78  program
94       will  try  to  verify that the system you specified exists and that you
95       can access it successfully. If any of these checks  fail  then  grass78
96       will automatically switch back to the text user interface mode.
97

SAMPLE DATA

99       The  GRASS GIS project provides several free sample geospatial datasets
100       as  ready-to-use  locations.  They  are  available   to   download   at
101       https://grass.osgeo.org/download/sample-data/.    The  "North  Carolina
102       data set" is a modern package of geospatial data  from  North  Carolina
103       (USA),  and  it includes raster, vector, LiDAR and satellite data. This
104       is the most extensively used data set  in  the  documentation  and  the
105       examples throughout the user manual pages are based upon it.
106

ENVIRONMENT VARIABLES

108       A  number  of  environment  variables are available at GRASS startup to
109       assist with automation and customization. Most users will not  need  to
110       bother with these.
111
112       In addition to these shell environment variables GRASS maintains a num‐
113       ber of GIS environment variables in  the  $HOME/.grass7/rc  file.  User
114       changes  to this file will be read during the next startup of GRASS. If
115       this file becomes corrupted the user may edit it by hand or  remove  it
116       to  start afresh.  See the list of implemented GRASS variables for more
117       information.  The rest of this help page will only consider shell envi‐
118       ronment variables.
119
120       Note  that  you  will need to set these variables using the appropriate
121       method required for the UNIX shell that you use (e.g. in a  Bash  shell
122       you must export the variables for them to propagate).
123
124   User Interface Environment Variable
125       The  grass78  program  will  check  for the existence of an environment
126       variable called GRASS_GUI which indicates the type  of  user  interface
127       for GRASS to use. If this variable is not set when grass78 is run, then
128       it will be created and then saved in the $HOME/.grass7/rc file for  the
129       next time GRASS is run. It can be set to text, gtext or gui.
130
131       There  is an order of precedence in the way grass78 determines the user
132       interface to use. The following is the hierarchy  from  highest  prece‐
133       dence to lowest.
134
135       1      Command line argument
136
137       2      Environment variable GRASS_GUI
138
139       3      Value set in $HOME/.grass7/rc (GUI)
140
141       4      Default value - gui
142
143   Python Environment Variables
144       If you choose to use wxGUI interface, then the GRASS_PYTHON environment
145       variable can be used to override your system default python command.
146
147       Suppose for example your  system  has  Python  3.6  installed  and  you
148       install  a personal version of the Python 3.7 binaries under $HOME/bin.
149       You can use the above variables to have GRASS use the Python 3.7  bina‐
150       ries instead.
151          GRASS_PYTHON=python3.7
152
153   Addon Path to Extra User Scripts
154       This  environment  variable allows the user to extend the GRASS program
155       search paths to include locally developed/installed  GRASS  modules  or
156       user scripts.
157          GRASS_ADDON_PATH=/usr/mytools
158          GRASS_ADDON_PATH=/usr/mytools:/usr/local/othertools
159
160       In this example above path(s) would be added to the standard GRASS path
161       environment.
162
163   Addon Base for Extra Local GRASS Addon Modules
164       This environment variable allows the user to extend the  GRASS  program
165       search paths to include locally installed (see g.extension for details)
166       GRASS Addon modules which are not distributed with the  standard  GRASS
167       release.
168          GRASS_ADDON_BASE=/usr/grass-addons
169
170       In  this  example  above path would be added to the standard GRASS path
171       environment.
172
173       If not defined by user, this variable is set by GRASS  startup  program
174       to  $HOME/.grass7/addons  on GNU/Linux and $APPDATA\GRASS7\addons on MS
175       Windows.
176
177   HTML Browser Variable
178       The GRASS_HTML_BROWSER environment variable allows the user to set  the
179       HTML web browser to use for displaying help pages.
180
181   Running non-interactive batch jobs
182       If the GRASS_BATCH_JOB environment variable is set to the full path and
183       filename of a shell script then GRASS will be launched in a  non-inter‐
184       active  way and the script will be run. The script itself can be inter‐
185       active if that is what the user requires. When  it  is  finished  GRASS
186       will  automatically  exit  using  the  exit-success  code  given by the
187       script. The script file must have its executable bit set.
188

EXAMPLES

190       The following are some examples of how you could start GRASS
191
192       grass78
193           Start GRASS using the default user  interface.  The  user  will  be
194           prompted to choose the appropriate location and mapset.
195
196       grass78 --gui
197           Start  GRASS  using  the graphical user interface. The user will be
198           prompted to choose the appropriate location and mapset.
199
200       grass78 --text
201           Start GRASS using the text-based user interface. Appropriate  loca‐
202           tion  and  mapset must be set by environmental variables (see exam‐
203           ples below) otherwise taken from the last GRASS session.
204
205       grass78 --gtext
206           Start GRASS using the text-based user interface. The user  will  be
207           prompted to choose the appropriate location and mapset.
208
209       grass78 $HOME/grassdata/spearfish70/user1
210           Start  GRASS  using  the  default  user interface and automatically
211           launch into the given mapset, bypassing the mapset selection menu.
212
213       grass78 --gui -
214           Start GRASS using the graphical user interface and  try  to  obtain
215           the location and mapset from environment variables.
216
217       grass78 -c EPSG:4326 $HOME/grassdata/mylocation
218           Creates  a  new GRASS location with EPSG code 4326 (latitude-longi‐
219           tude, WGS84) in the specified GISDBASE
220
221       grass78 -c EPSG:5514:3 $HOME/grassdata/mylocation
222           Creates a new GRASS location with EPSG code 5514 (S-JTSK  /  Krovak
223           East  North  -  SJTSK) with datum transformation parameters used in
224           Czech Republic in the specified GISDBASE
225
226       grass78   -c   XY    $HOME/grassdata/gnomonic    --exec    g.proj    -c
227       proj4=’+proj=gnom +lat_0=90 +lon_0=-50’
228           Creates  a  new  GRASS  location from PROJ definition string (here:
229           gnomonic) in the specified GISDBASE
230
231       grass78 -c myvector.shp $HOME/grassdata/mylocation
232           Creates a new GRASS location based on georeferenced Shapefile
233
234       grass78 -c myraster.tif $HOME/grassdata/mylocation
235           Creates a new GRASS location based on georeferenced GeoTIFF file
236
237   Batch jobs with the exec interface
238       Creating a new Location based on a geodata file’s projection  (-c)  and
239       exit (-e) immediately:
240       grass78 -c elevation.tiff -e /path/to/grassdata/test1/
241       Linking external raster data to PERMANENT Mapset:
242       grass78 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins
243       grass78 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation
244       Get statistics for one raster map:
245       grass78 /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation
246       Compare the rasters visually:
247       grass78 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins
248
249   Execution of shell and Python scripts instead of single commands
250       A  sequence  of  commands can be bundled in a script and executed using
251       the exec interface.
252
253       Shell script example: the command to execute a shell script might be:
254       grass78 /path/to/grassdata/test1/PERMANENT/ --exec sh test.sh
255       A very simple bash script ("test.sh") may look like this:
256       #!/bin/bash
257       g.region -p
258       g.list type=raster
259       r.info elevation
260
261       Python script example: the command to execute a Python script might be:
262       grass78 /path/to/grassdata/test1/PERMANENT/ --exec python test.py
263       A very simple Python script ("test.py") may look like this:
264       #!/usr/bin/env python3
265       # import GRASS Python bindings (see also pygrass)
266       import grass.script as gscript
267       import grass.script.setup as gsetup
268       gscript.message(’Current GRASS GIS 7 environment:’)
269       print(gscript.gisenv())
270       gscript.message(’Available raster maps:’)
271       for raster in gscript.list_strings(type=’raster’):
272           print(raster)
273       gscript.message(’Available vector maps:’)
274       for vector in gscript.list_strings(type=’vector’):
275           print(vector)
276
277   Using temporary location
278       Creating a new temporary location based on a georeferenced file’s  pro‐
279       jection  coordinate  reference system (CRS) and simultaneously starting
280       computation in a shell script:
281       grass78 --tmp-location elevation.tiff --exec test.sh
282       The same, but using an EPSG code and a Python script:
283       grass78 --tmp-location EPSG:3358 --exec test.py
284       Finally, for special cases, we can create an XY  location  without  any
285       CRS:
286       grass78 --tmp-location XY --exec test.py
287       Temporary  location  is automatically deleted after computation, so the
288       script is expected to export, link or  otherwise  preserve  the  output
289       data before ending.
290
291       A  single  command  can be also executed, e.g. to examine properties of
292       the temporary location:
293       grass78 --tmp-location EPSG:3358 --exec g.proj -p
294       A temporary XY location with single command is  useful,  e.g.  to  show
295       help text of a module:
296       grass78 --tmp-location XY --exec r.neighbors --help
297
298   Troubleshooting
299       Importantly,  to avoid an "[Errno 8] Exec format error" there must be a
300       shebang line at the top of the script (like #!/bin/sh, #!/bin/bash,  or
301       #!/usr/bin/env python3) indicating which interpreter to be used for the
302       script. The script file must have its executable bit set.
303

CAVEAT

305       If you start GRASS using the wxGUI interface you  must  have  a  python
306       command  in  your  $PATH  variable.  That is, the command must be named
307       python and not something like python3.6. Rarely some  Python  installa‐
308       tions  do  not create a python command. In these cases you can override
309       python by GRASS_PYTHON environmental variable.
310
311       Furthermore, if you have more than one  version  of  Python  installed,
312       make  sure  that  the  version  you  want  to  use with GRASS is set by
313       GRASS_PYTHON environmental variable.
314

SEE ALSO

316       List of GRASS environment variables
317
318       GRASS GIS Web site
319       GRASS GIS User Wiki
320       GRASS GIS Bug Tracker
321       GRASS GIS 7 Programmer’s Manual
322

AUTHORS (of this page)

324       Justin Hickey
325       Markus Neteler
326       Hamish Bowman
327       Martin Landa, Czech Technical University in Prague, Czech Republic
328
329       Main index | Topics index | Keywords index |  Graphical  index  |  Full
330       index
331
332       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
333
334
335
336GRASS 7.8.2                                                          grass7(1)
Impressum