grass7(1grass)

1grass7(1)                   GRASS GIS 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 | --tmp-location [[[<GISDBASE>/]<LOCATION>/] <MAPSET>] [--exec
10       EXECUTABLE]
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, date, path, revision, svn_revision, version)
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 with the --exec flag).  The active mapset will be  the  PERMA‐
64           NENT mapset.
65
66   Parameters:
67       GISDBASE
68           Initial  database  directory which should be a fully qualified path
69           (e.g., /usr/local/share/grassdata)
70
71       LOCATION
72           Initial location directory which is a subdirectory of GISDBASE
73
74       MAPSET
75           Initial mapset directory which is a subdirectory of LOCATION  Note:
76           These parameters must be specified in one of the following ways:
77               MAPSET
78               LOCATION/MAPSET
79               GISDBASE/LOCATION/MAPSET
80

DESCRIPTION

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

FLAGS

100       The flag --config option prints GRASS  GIS  configuration  and  version
101       parameters, with the options:
102
103           ·   arch: system architecture (e.g., x86_64-pc-linux-gnu)
104
105           ·   build:   (e.g.,   ./configure   --with-cxx   --enable-largefile
106               --with-proj [...])
107
108           ·   compiler: (e.g., gcc)
109
110           ·   date: (e.g., 2020-04-24T14:49:27+00:00)
111
112           ·   path: (e.g., /usr/lib64/grass78)
113
114           ·   revision: (e.g., 54aa6fb87)
115
116           ·   svn_revision: (e.g., 4aa6fb87)
117
118           ·   version: (e.g., 7.8.3)
119

SAMPLE DATA

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

ENVIRONMENT VARIABLES

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

EXAMPLES

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

CAVEAT

327       If  you  start  GRASS  using the wxGUI interface you must have a python
328       command in your $PATH variable. That is,  the  command  must  be  named
329       python  and  not something like python3.6. Rarely some Python installa‐
330       tions do not create a python command. In these cases you  can  override
331       python by GRASS_PYTHON environmental variable.
332
333       Furthermore,  if  you  have  more than one version of Python installed,
334       make sure that the version you  want  to  use  with  GRASS  is  set  by
335       GRASS_PYTHON environmental variable.
336

AUTHORS (of this page)

346       Justin Hickey
347       Markus Neteler
348       Hamish Bowman
349       Martin Landa, Czech Technical University in Prague, Czech Republic
350
351       Main  index  |  Topics  index | Keywords index | Graphical index | Full
352       index
353
354       Â© 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
355
356
357
358GRASS 7.8.5                                                          grass7(1)