Provided by: grass-core_7.8.2-1build3_amd64 bug

GRASS startup program

SYNOPSIS

       grass78 [-h | -help | --help] [-v | --version] | [-c | -c geofile | -c EPSG:code[:datum_trans]] | -e | -f
       | [--text | --gtext | --gui] | --config | --exec EXECUTABLE | --tmp-location  [[[<GISDBASE>/]<LOCATION>/]
       <MAPSET>]

   Flags:
       -h | -help | --help
           Prints a brief usage message and exits

       -v | --version
           Prints the version of GRASS and exits

       -c
           Creates new GRASS unprojected location in specified GISDBASE

       -c geofile
           Creates new GRASS projected location in specified GISDBASE based on georeferenced file

       -c EPSG:code
           Creates new GRASS projected location in specified GISDBASE with given EPSG code

       -c EPSG:code:datum_trans
           Creates  new  GRASS projected location in specified GISDBASE with given EPSG code and datum transform
           parameters

       -e
           Exit after creation of location or mapset. Only with -c flag

       -f
           Forces removal of .gislock if exists (use with care!). Only with --text flag

       --text
           Indicates that Text-based User Interface should be used (skip welcome screen)

       --gtext
           Indicates that Text-based User Interface should be used (show welcome screen)

       --gui
           Indicates that Graphical User Interface (wxGUI) should be used

       --config
           Prints GRASS configuration parameters (options: arch, build, compiler, path, revision)

       --exec EXECUTABLE
           Execute  GRASS  module  or  script.  The  provided  executable  will  be  executed  in  a  GRASS  GIS
           non-interactive session.

       --tmp-location
           Run  using  a  temporary location which is created based on the given coordinate reference system and
           deleted at the end of the execution (use the --exec flag).  The active mapset will be PERMANENT.

   Parameters:
       GISDBASE
           Initial database directory which should be a fully qualified path (e.g., /usr/local/share/grassdata)

       LOCATION
           Initial location directory which is a subdirectory of GISDBASE

       MAPSET
           Initial mapset directory which is a subdirectory of LOCATION Note: These parameters must be specified
           in one of the following ways:
               MAPSET
               LOCATION/MAPSET
               GISDBASE/LOCATION/MAPSET

DESCRIPTION

       This  command  is  used to launch GRASS GIS. It will parse the command line arguments and then initialize
       GRASS for the user. Since GRASS modules require a specific  environment,  this  program  must  be  called
       before  any other GRASS module can run. The command line arguments are optional and provide the user with
       a method to indicate the desired user interface, as well as the desired mapset to work on.

       The startup program will remember both the desired user interface and mapset. Thus,  the  next  time  the
       user runs GRASS, typing grass78 (without any options) will start GRASS with the previous settings for the
       user interface and mapset selected.

       If you specify a graphical user interface (--gui) the grass78 program will try to verify that the  system
       you  specified  exists  and that you can access it successfully. If any of these checks fail then grass78
       will automatically switch back to the text user interface mode.

SAMPLE DATA

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

ENVIRONMENT VARIABLES

       A number of environment  variables  are  available  at  GRASS  startup  to  assist  with  automation  and
       customization. Most users will not need to bother with these.

       In addition to these shell environment variables GRASS maintains a number of GIS environment variables in
       the $HOME/.grass7/rc file. User changes to this file will be read during the next startup  of  GRASS.  If
       this  file  becomes corrupted the user may edit it by hand or remove it to start afresh.  See the list of
       implemented GRASS variables for more information.  The rest of this help page will  only  consider  shell
       environment variables.

       Note  that  you will need to set these variables using the appropriate method required for the UNIX shell
       that you use (e.g. in a Bash shell you must export the variables for them to propagate).

   User Interface Environment Variable
       The grass78 program will check for the existence  of  an  environment  variable  called  GRASS_GUI  which
       indicates  the  type of user interface for GRASS to use. If this variable is not set when grass78 is run,
       then it will be created and then saved in the $HOME/.grass7/rc file for the next time GRASS  is  run.  It
       can be set to text, gtext or gui.

       There is an order of precedence in the way grass78 determines the user interface to use. The following is
       the hierarchy from highest precedence to lowest.

       1      Command line argument

       2      Environment variable GRASS_GUI

       3      Value set in $HOME/.grass7/rc (GUI)

       4      Default value - gui

   Python Environment Variables
       If you choose to use wxGUI interface, then the GRASS_PYTHON environment variable can be used to  override
       your system default python command.

       Suppose for example your system has Python 3.6 installed and you install a personal version of the Python
       3.7 binaries under $HOME/bin. You can use the above variables to have GRASS use the Python  3.7  binaries
       instead.
          GRASS_PYTHON=python3.7

   Addon Path to Extra User Scripts
       This  environment  variable  allows  the user to extend the GRASS program search paths to include locally
       developed/installed GRASS modules or user scripts.
          GRASS_ADDON_PATH=/usr/mytools
          GRASS_ADDON_PATH=/usr/mytools:/usr/local/othertools

       In this example above path(s) would be added to the standard GRASS path environment.

   Addon Base for Extra Local GRASS Addon Modules
       This environment variable allows the user to extend the GRASS program search  paths  to  include  locally
       installed  (see  g.extension for details) GRASS Addon modules which are not distributed with the standard
       GRASS release.
          GRASS_ADDON_BASE=/usr/grass-addons

       In this example above path would be added to the standard GRASS path environment.

       If not defined by user, this variable  is  set  by  GRASS  startup  program  to  $HOME/.grass7/addons  on
       GNU/Linux and $APPDATA\GRASS7\addons on MS Windows.

   HTML Browser Variable
       The  GRASS_HTML_BROWSER  environment  variable  allows  the  user  to set the HTML web browser to use for
       displaying help pages.

   Running non-interactive batch jobs
       If the GRASS_BATCH_JOB environment variable is set to the full path and filename of a shell  script  then
       GRASS  will  be  launched  in  a non-interactive way and the script will be run. The script itself can be
       interactive if that is what the user requires. When it is finished GRASS will  automatically  exit  using
       the exit-success code given by the script. The script file must have its executable bit set.

EXAMPLES

       The following are some examples of how you could start GRASS

       grass78
           Start  GRASS  using  the  default user interface. The user will be prompted to choose the appropriate
           location and mapset.

       grass78 --gui
           Start GRASS using the graphical user interface. The user will be prompted to choose  the  appropriate
           location and mapset.

       grass78 --text
           Start  GRASS  using  the  text-based  user  interface. Appropriate location and mapset must be set by
           environmental variables (see examples below) otherwise taken from the last GRASS session.

       grass78 --gtext
           Start GRASS using the text-based user interface. The user will be prompted to choose the  appropriate
           location and mapset.

       grass78 $HOME/grassdata/spearfish70/user1
           Start  GRASS  using  the  default  user  interface  and  automatically  launch into the given mapset,
           bypassing the mapset selection menu.

       grass78 --gui -
           Start GRASS using the graphical user interface and  try  to  obtain  the  location  and  mapset  from
           environment variables.

       grass78 -c EPSG:4326 $HOME/grassdata/mylocation
           Creates  a  new  GRASS  location  with  EPSG  code  4326 (latitude-longitude, WGS84) in the specified
           GISDBASE

       grass78 -c EPSG:5514:3 $HOME/grassdata/mylocation
           Creates a new GRASS location with EPSG code 5514 (S-JTSK / Krovak East  North  -  SJTSK)  with  datum
           transformation parameters used in Czech Republic in the specified GISDBASE

       grass78 -c XY $HOME/grassdata/gnomonic --exec g.proj -c proj4=’+proj=gnom +lat_0=90 +lon_0=-50’
           Creates a new GRASS location from PROJ definition string (here: gnomonic) in the specified GISDBASE

       grass78 -c myvector.shp $HOME/grassdata/mylocation
           Creates a new GRASS location based on georeferenced Shapefile

       grass78 -c myraster.tif $HOME/grassdata/mylocation
           Creates a new GRASS location based on georeferenced GeoTIFF file

   Batch jobs with the exec interface
       Creating a new Location based on a geodata file’s projection (-c) and exit (-e) immediately:
       grass78 -c elevation.tiff -e /path/to/grassdata/test1/
       Linking external raster data to PERMANENT Mapset:
       grass78 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=basins.tiff output=basins
       grass78 /path/to/grassdata/test1/PERMANENT/ --exec r.external input=elevation.tiff output=elevation
       Get statistics for one raster map:
       grass78 /path/to/grassdata/test1/PERMANENT/ --exec r.univar map=elevation
       Compare the rasters visually:
       grass78 /path/to/grassdata/test1/PERMANENT/ --exec g.gui.mapswipe first=elevation second=basins

   Execution of shell and Python scripts instead of single commands
       A sequence of commands can be bundled in a script and executed using the exec interface.

       Shell script example: the command to execute a shell script might be:
       grass78 /path/to/grassdata/test1/PERMANENT/ --exec sh test.sh
       A very simple bash script ("test.sh") may look like this:
       #!/bin/bash
       g.region -p
       g.list type=raster
       r.info elevation

       Python script example: the command to execute a Python script might be:
       grass78 /path/to/grassdata/test1/PERMANENT/ --exec python test.py
       A very simple Python script ("test.py") may look like this:
       #!/usr/bin/env python3
       # import GRASS Python bindings (see also pygrass)
       import grass.script as gscript
       import grass.script.setup as gsetup
       gscript.message(’Current GRASS GIS 7 environment:’)
       print(gscript.gisenv())
       gscript.message(’Available raster maps:’)
       for raster in gscript.list_strings(type=’raster’):
           print(raster)
       gscript.message(’Available vector maps:’)
       for vector in gscript.list_strings(type=’vector’):
           print(vector)

   Using temporary location
       Creating  a new temporary location based on a georeferenced file’s projection coordinate reference system
       (CRS) and simultaneously starting computation in a shell script:
       grass78 --tmp-location elevation.tiff --exec test.sh
       The same, but using an EPSG code and a Python script:
       grass78 --tmp-location EPSG:3358 --exec test.py
       Finally, for special cases, we can create an XY location without any CRS:
       grass78 --tmp-location XY --exec test.py
       Temporary location is automatically deleted after computation, so the script is expected to export,  link
       or otherwise preserve the output data before ending.

       A single command can be also executed, e.g. to examine properties of the temporary location:
       grass78 --tmp-location EPSG:3358 --exec g.proj -p
       A temporary XY location with single command is useful, e.g. to show help text of a module:
       grass78 --tmp-location XY --exec r.neighbors --help

   Troubleshooting
       Importantly,  to  avoid  an  "[Errno 8] Exec format error" there must be a shebang line at the top of the
       script (like #!/bin/sh, #!/bin/bash, or #!/usr/bin/env python3) indicating which interpreter to  be  used
       for the script. The script file must have its executable bit set.

CAVEAT

       If  you start GRASS using the wxGUI interface you must have a python command in your $PATH variable. That
       is, the command must be named python and not something like python3.6. Rarely some  Python  installations
       do  not  create  a  python  command. In these cases you can override python by GRASS_PYTHON environmental
       variable.

       Furthermore, if you have more than one version of Python installed, make sure that the version  you  want
       to use with GRASS is set by GRASS_PYTHON environmental variable.

SEE ALSO

       List of GRASS environment variables

       GRASS GIS Web site
       GRASS GIS User Wiki
       GRASS GIS Bug Tracker
       GRASS GIS 7 Programmer’s Manual

AUTHORS (of this page)

       Justin Hickey
       Markus Neteler
       Hamish Bowman
       Martin Landa, Czech Technical University in Prague, Czech Republic

       Main index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual