Repository navigation
Roadmap ideas for rgrass #110
stevenpawley
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Development roadmap ideas rgrass
Purpose and scope
This document provides a roadmap for
rgrassdevelopment, intended to be used for general discussion. Changes should continue to support existingrgrasscode.The long-term aim is to continue to make GRASS itself easy to use from R. This aim is broader than using GRASS as a disposable backend for R geoprocessing functions. For this use case, packages such as fasterRaster provide a terra-like geoprocessing vocabulary using GRASS as an interchangeable backend, while keeping many GRASS-specific mechanics behind the scenes, such as computational-region effects, raster alignment and resampling, NULL/NA handling, category behavior, and vector topology.
Design direction
rgrass instead aims to make GRASS projects, mapsets, regions, maps, and modules directly accessible through a more discoverable, GRASS-native R interface. The opportunity for rgrass is enhanced features inspired by the different levels of
the GRASS Python interface:
grass.toolsprovides named, discoverable tool methods, consistent execution, error handling, and structured result outputs;grass.scriptremains available when direct command-oriented control is appropriate.rgrass does not need to copy the Python APIs exactly. These are useful design references for reducing the need to memorize module syntax while retaining GRASS terminology and behavior.
GRASS maps should remain GRASS maps while work stays inside GRASS. When a workflow explicitly needs a terra object, ideally the preferred bridge should be the GDAL-GRASS raster or vector driver, where available, rather than routinely exporting an intermediate file.
Development roadmap
Housekeeping items
A series of small, housekeeping items are proposed initially, which focus on maintainability and testing improvements. These should invoke limited user-facing changes.
1. Refactor the
initGRASSstartup procedureGoal: Refactor and simplify the startup procedure used by
initGRASS()to broadly match the process used withingrass.script.setup.init().The original procedure performed all operations inline, within a single function. Refactoring will extract the platform-specific setup and session initialization code into separate internal helper functions. This should make initGRASS() easier to follow, test, and maintain, without any other user-facing changes.
The existing startup procedure is incremental. It first writes a partial GISRC containing GISDBASE and blank LOCATION_NAME and MAPSET values. This gives g.gisenv enough configuration to run. It then uses GRASS itself to set GISDBASE, LOCATION_NAME, MAPSET, and GRASS_GUI=text in the GISRC, after creating the location and mapset directories. On Windows, it also used g.dirseps.exe to normalize paths.
The refactor follows the broad ordering used by
grass.script.setup.init(): resolve the complete session identity beforewriting a final GISRC containing the database, location, and mapset. Unlike
grass.script.setup.init(),initGRASS()can also create the required location and mapset structure and initialize its region files.Completion criterion: startup procedure behavior is maintained for linux/unix system-installed GRASS, conda-forge, OSGEO4W, and Windows standalone.
2. Support
GRASS_ADDON_PATHGoal: bring rgrass add-on discovery in line with
grass.script.setup.init()while retainingGRASS_ADDON_BASEcompatibility.GRASS_ADDON_PATHshould accept the platform path separator and more than one add-on directory. rgrass should construct the effective executable search path without duplicating entries or unexpectedly replacing user configuration.Proposed work:
addon_baseargument,GRASS_ADDON_BASE, andGRASS_ADDON_PATH.binandscriptsdirectories toPATHwhile preserving pre-existing values.Completion criterion: modules found through
GRASS_ADDON_PATHcan be run byexecGRASS()without manualPATHchanges, and existingaddon_basebehavior is unchanged.3. Encapsulate
.GRASS_CACHEstateGoal: make package state explicit and consistently accessed before adding new public abstractions.
.GRASS_CACHEcurrently mixes session state, platform details, command caches, user options, and values saved for cleanup.get()andassign()calls throughout the package make the lifecycle of values difficult track.Proposed work:
get()andassign()calls.Completion criterion: package code no longer performs ad hoc cache access. This milestone should improve internals without exposing
.GRASS_CACHEor changing public behavior. It also creates an object that a future session concept could build onMajor updates
These updates build upon the internal package maintenance changes and begin to add new functionality to rgrass. These are additions; they do not break existing behavior.
1. Develop a modern, GRASS-native R API
Goal: provide a discoverable interface that follows current R naming and argument conventions, then grow it beyond synonyms into useful wrappers around GRASS modules and concepts while preserving the established API.
This milestone should proceed in layers rather than attempting a complete new API at once.
Entry points
An initial, deliberately small set of synonyms could include:
grass_init()initGRASS()grass_exec()execGRASS()grass_read_rast()read_RAST()grass_write_rast()write_RAST()grass_read_vect()read_VECT()grass_write_vect()write_VECT()grass_metadata()gmeta()Proposed work:
grass_prefix, snake case, and consistentrast/vectterminology.The existing functions are not deprecated by this milestone.
2. Discoverable module wrappers
The next stage should reduce the need to remember every GRASS module's exact parameter names, flags, and parsing rules. It should be close to
grass.toolsand the module interface in PyGRASS.Rather than exporting an R function for every GRASS module, rgrass could follow a dynamic pattern where a constructor such as
grass_tools()would inspect the modules available to a particular GRASS installation and session, generate methods from their interface descriptions, and return a nested tools object:The first level could correspond to GRASS module families such as
g,r,r3,v,i,db, andt. Method names would replace the dots (such asslope.aspect) with underscores (slope_aspect).Proposed work:
r.slope.aspecttotools$r$slope_aspect().execGRASS()for full command-level control and as a fallback when dynamic discovery cannot describe a module.Completion criterion: a coherent core workflow can be written using the tools object; several representative GRASS modules have discoverable, validated arguments and structured results.
3. GRASS concepts in R
After module execution is consistent, consider focused wrappers for concepts that users currently manage through several commands:
3a. R objects for GRASS maps
One idea is a typed R object representing a map that continues to live in GRASS. At present, rgrass users identify maps with character strings, so R cannot distinguish a raster from a vector, retain the originating mapset or session, or validate how a map is used by subsequent commands.
A lightweight map reference object in R could record:
The object would not contain cell values or vector geometries, but it would be designed to interact with rgrass module wrappers and GRASS-native concepts. Module results that create maps could return these references, and subsequent commands could accept them directly:
Character map names should remain supported for compatibility and concise interactive use.
3b. Computational region
The identity of a GRASS map is separate from the computational region used by GRASS modules. The current computational region is normally stored in the mapset’s WIND file, and its settings can be returned to R by gmeta(). Changing this shared region modifies the execution context for subsequent execGRASS() calls, so results can depend on implicit state established earlier in a workflow.
A complementary
grass_regionobject could represent an immutable region specification in R. The object is conceptually inspired by the PyGRASS Region class, which represents computational-region settings independently of raster map identity. Unlike the mutable, process-wide region used by PyGRASS raster-library operations, an rgrass grass_region would preferably be an immutable value supplied explicitly to individual module calls.It could be created from:
The object should record its project/location because a region is meaningful only within a particular coordinate reference system and project/location. Creating a R grass_region object would not update the mapset's
WINDfile. Then, module wrappers could accept a.regionargument in addition to their ordinary GRASS module parameters:The .region argument would apply the supplied region only to that command, preferably through a command-specific GRASS_REGION environment value rather than by changing and subsequently restoring WIND. It would not become part of the map reference or permanently alter the mapset’s active computational region. For modules that create raster maps, the returned map references could record the region used to create them as provenance or cached metadata without making it part of their identity.
4. Prototype a stateful GRASS session object
Goal: explore an explicit R representation of a GRASS session without pretending that GRASS's process-global environment can be eliminated.
Although GRASS does not run as a persistent server process, a session has state: its GISRC, runtime environment, database, project/location, current mapset, lock, temporary resources, and cleanup status. Representing this state as an object would give rgrass a clear owner for resources which are currently distributed between process environment variables and
.GRASS_CACHE.A stateful session object would provide several advantages:
A session may need to record:
A session would normally be supplied when constructing the tools object and typed map references. Generated methods would then obtain their GRASS environment from the tools object and validate it against the session retained by any map arguments:
All reactions