| | 1 | = New Easy-to-use CLI and API Idea = |
| | 2 | |
| | 3 | * Make running of GRASS GIS modules as easy as it is to run GDAL commands. |
| | 4 | * GRASS GIS requires GRASS GIS Database, Location and Mapset to be set up to maintain data consistency, efficiency and security. Unfortunately, this is cumbersome when GRASS GIS is not the primary tool user is using. |
| | 5 | * There are different ways for calling GRASS modules without starting iterative GRASS session: |
| | 6 | * Modules executed with the `--exec` interface (see [https://grass.osgeo.org/grass74/manuals/grass7.html#batch-jobs-with-the-exec-interface the grass7 manual page] >=7.2) |
| | 7 | * `GRASS_BATCH_JOB`: same as newer `--exec` but through environmental variable and more limited |
| | 8 | * Use `grass.script.setup` package from GRASS GIS (requires boilerplate to add the packages on path first) |
| | 9 | * Use the standalone `grass_session` package (new, see [https://grasswiki.osgeo.org/wiki/Working_with_GRASS_without_starting_it_explicitly#Python:_GRASS_GIS_7_with_an_external_library:_grass-session here]) |
| | 10 | * Set up environmental variables and "RC file" yourself (the classic method). |
| | 11 | * None of these allows the user to skip the database setup phase. This leads to the need for constant reimplementing of setup, import and export steps in various software and environments including ''user scripts'' (in Bash, Python, R), QGIS Processing, gvSIG/SEXTANTE, uDig/JGrassTools, and all the web/server/cloud tools and applications which use GRASS GIS as a processing backend (e.g. PyWPS server). |
| | 12 | * GRASS GIS itself can make it easier for the callers (at least in most cases) by implementing an interface which would allow to use GRASS GIS modules without explicit dealing with GRASS GIS database. |
| | 13 | * The command line call using the proposed interface would look like these: |
| | 14 | |
| | 15 | {{{ |
| | 16 | grass run r.lake elevation=some/file.tiff water_level=10 lake=some/new/file.tiff coordinates=100,520 |
| | 17 | grass run r.slope.aspect elevation=file://.../elevation.tiff aspect=file://...aspect.tiff |
| | 18 | grass run r.slope.aspect elevation=https://.../elevation.tiff.zip aspect=file://...aspect.tiff |
| | 19 | }}} |
| | 20 | |
| | 21 | * Basic execution phases: |
| | 22 | * The `grass` command would have to parse the command line, compare it with the module XML interface description, find the files which should be maps (either using `file://` and ideally anything else), potentially download and uncompress, and import (or link) them, and then call the actual command (GRASS module). |
| | 23 | * The input maps could be linked (external) rather than imported (except for the cases when projection differs) which should be faster than import. |
| | 24 | * Doing the work in GRASS rather than in the other software would allow GRASS to make the decision about the details, for example the data exchange (r.external vs r.import vs r.in.gdal - see [https://github.com/qgis/QGIS/pull/5426#issuecomment-345067457 comment from MarkusN for QGIS Processing issue] or [https://lists.osgeo.org/pipermail/grass-dev/2017-November/086598.html mailing list]). |
| | 25 | * GRASS Database would be created with an appropriate Location (projection based on input files or additional CLI input). |
| | 26 | * The GRASS GIS Database, Location and Mapset should be created on the fly and deleted afterwards (the `.grassrc` wouldn't be used). |
| | 27 | * Computational region would be set based on input file(s) or additional CLI input. |
| | 28 | * Module execution. |
| | 29 | * The output maps could be be also linked (e.g. r.external.out) with projection same as input which is should be faster then export. |
| | 30 | * Ideally export (as well as import) should work also with PostGIS and databases provided through GDAL/OGR. |
| | 31 | * Proposal should discuss and address how advanced things such raster algebra, multi-map inputs and outputs, temporal framework, cartography and visualization tools will work (or what are the limits). |
| | 32 | * Use should be able to always specify the details manually: |
| | 33 | |
| | 34 | {{{ |
| | 35 | grass run --mapset=/some/directory/grassdata/ncspm/practice1 r.lake elevation=some/file.tiff ... |
| | 36 | grass run --region="s=55600 n=60500..." --mask=some/mask.tiff r.lake elevation=some/file.tiff ... |
| | 37 | grass run --crs=EPSG:3358 --mask=some/mask.tiff r.lake elevation=some/file.tiff ... |
| | 38 | grass run --use=some/file_a.tiff --get=some/file_b.tiff r.slope.aspect elevation=file_a aspect=file_b |
| | 39 | }}} |
| | 40 | |
| | 41 | * The system behind the interface will be inherently fragile, so it is necessary to write large amount of tests which would check different combinations of data types and projections. |
| | 42 | * All the underlying code is expected to be in Python, so the project should involve also creation of Python API on the way. |
| | 43 | * Bonus tasks: |
| | 44 | * Making this work for the GUI in the same way. It is expected that this would work for any `g.gui.*` modules too but implementing similar mechanism also for module dialogs is more work (but some basic implementation might be quite straightforward). |
| | 45 | * Making this connected to the standalone `grass_session` package. |
| | 46 | * Generalization of the API, so that it incorporates also the concept of remote sessions (see e.g. [https://github.com/wenzeslaus/g.remote g.remote on GitHub]) |
| | 47 | * Current GRASS code involved: |
| | 48 | * source:grass/trunk/lib/python/script/setup.py (library function(s) for Location setup in Python) |
| | 49 | * source:grass/trunk/lib/init/grass.py (full GRASS GIS standard startup "script") |
| | 50 | |
| | 51 | == See also == |
| | 52 | * Tickets, PRs, commits: |
| | 53 | * #2424 PyGRASS does not work when GRASS is invoked from outside because it is not possible to change path to dynamic libraries in running process |
| | 54 | * #2511 Starting GRASS in mapset which is not owned by the user |
| | 55 | * #2579 Specify command to be executed as parameter of grass command (patch) and other suggestion for CLI, especially see the comment:15:ticket:2579 which summarizes the remaining issues after closing the ticket |
| | 56 | * #2639 grass command should read commands from stdin as an interpreter would do |
| | 57 | * #2678 GRASS starts even when Mapset is locked |
| | 58 | * #2679 Drop or fix setting of Location and Mapset using environmental variables |
| | 59 | * #2681 Remove legacy meaning of LOCATION variable |
| | 60 | * #2685 Add ignore lock flag to grass command |
| | 61 | * #3537 Add functionalities `--tmp-location` and `--no-clean` |
| | 62 | * r72790 Add `--tmp-location` |
| | 63 | * [https://github.com/OSGeo/grass/pull/313 PR #313] Add `--tmp-mapset` option |
| | 64 | * Documentation: |
| | 65 | * [https://grass.osgeo.org/grass74/manuals/grass_database.html GRASS GIS Database] |
| | 66 | * [https://grass.osgeo.org/grass70/manuals/libpython/script.html#module-script.setup grass.script.setup] |
| | 67 | * Mailing list and wikis: |
| | 68 | * [https://lists.osgeo.org/pipermail/grass-dev/2018-March/087764.html grass-dev New CLI GSoC Idea: Comments, Mentors, Students Needed] (whole thread) |
| | 69 | * [https://lists.osgeo.org/pipermail/grass-dev/2015-January/072979.html grass-dev QGIS Processing & GRASS (January 2015)] |
| | 70 | * [https://grasswiki.osgeo.org/wiki/Working_with_GRASS_without_starting_it_explicitly Working with GRASS without starting it explicitly] |
| | 71 | * wiki:Grass7/VectorLib/OGRInterface |
| | 72 | * wiki:Grass7/VectorLib/PostGISInterface |
| | 73 | * [https://lists.osgeo.org/pipermail/grass-dev/2015-February/073867.html On GSoC Proposal New easy-to-use...] |
| | 74 | * [https://lists.osgeo.org/pipermail/grass-dev/2015-March/074433.html GSOC project proposal] |
| | 75 | * Other projects (see also the ones linked in the text): |
| | 76 | * [https://github.com/qgis/QGIS/blob/0a1382a0be36d408aebd227fb0066f68c513e41e/python/plugins/processing/algs/grass7/Grass7Algorithm.py QGIS Processing Grass7Algorithm.py] source code |
| | 77 | * [https://github.com/moovida/jgrasstools/blob/530c87f26d220f3eeff9d2fb9d21abd8821c00c3/grass/src/main/java/org/jgrasstools/grass/utils/ModuleSupporter.java uDig's JGrasstools] source code |
| | 78 | * [https://sextante.googlecode.com/svn/trunk/soft/sextante_lib/sextante_gui/src/es/unex/sextante/gui/grass/ SEXTANTE grass] source code (broken link) |
| | 79 | * [https://github.com/geopython/PyWPS/blob/425f0eb160f60714a6705a24ba926e03690ab371/pywps/Grass.py PyWPS source code] and [https://pywps.wald.intevation.org/documentation/process.html PyWPS documentation] (broken link) |
| | 80 | * [https://code.google.com/p/wps-grass-bridge/source/browse/trunk/?r=97 wps-grass-bridge] source code (broken link) |
| | 81 | * Similar complex command line interfaces to learn from: |
| | 82 | * Git (a classic example of subcommand interface) |
| | 83 | * Docker (subcommand interface combined with running other commands inside a container) |
| | 84 | * !GeoGig (needs to get geospatial data in and out) |
| | 85 | * !ImageMagic |
| | 86 | * radical changes in CLI interface between versions [https://legacy.imagemagick.org/script/index.php 6] and [https://www.imagemagick.org/script/command-line-tools.php 7] |
| | 87 | * new CLI has a single `magick` command with many parameters |
| | 88 | * GMT |
| | 89 | * [http://gmt.soest.hawaii.edu/doc/5.3.2/GMT_Docs.html#new-features-in-gmt-5 radical changes in CLI interface between versions 4 and 5] |
| | 90 | * new CLI has a single `gmt` command and subcommands |
