doc: new documentation of projects and mapsets #6392
Conversation
petrasovaa
commented
Sep 22, 2025
petrasovaa
commented
doc/grass_projects.md
Outdated
| A GRASS project is stored as a directory on disk. | ||
| Inside this directory are the mapsets that make up the working environments | ||
| for analyses. All geospatial analyses in GRASS take place within a mapset. | ||
| At minimum, every project includes the PERMANENT mapset, which stores core | ||
| baseline data. Additional mapsets can be created for individual tasks, | ||
| study areas, or collaborators. |
There was a problem hiding this comment.
I like the first and last sentence and also the "At minimum, every project includes the PERMANENT mapset" part, but the middle does not feel right. I agree that for introduction, it can be brief, with more stuff later, but this seems it is trying to say too many things at once. It also starts with the directory (low level), but then it continues with more general usage and description (high level).
| may be inappropriate for areas that span multiple UTM zones, as distortions | ||
| will increase at the edges. | ||
|
|
||
| You can select a CRS using an EPSG code, derive it from an existing georeferenced |
There was a problem hiding this comment.
Context of previous paragraph suggest that "selecting" is related to choice of the right CRS, not parameterization of the project creation.
| You can select a CRS using an EPSG code, derive it from an existing georeferenced | |
| When creating a project, you can select a CRS using an EPSG code, derive it from an existing georeferenced |
| When creating a new project, it is a good idea to set a default computational | ||
| region in the PERMANENT mapset, especially when you expect to work with | ||
| raster data and multiple mapsets. | ||
| The default region is stored in the PERMANENT mapset and then applied |
There was a problem hiding this comment.
The storage question is an implementation detail, but when you can change it/manage it would be generally relevant.
| The default region is stored in the PERMANENT mapset and then applied | |
| The default region is managed in the PERMANENT mapset and applied |
| - GRASS GUI Project Wizard: Guides you step-by-step to set the CRS and | ||
| optionally import a georeferenced file. | ||
|
|
||
|  |
There was a problem hiding this comment.
Move to the end of the list. This will be in sync with other places and start with a simple almost one liner as opposed to a multi-step wizard process (which makes it seem more complicated than it is).
| and [v.import](v.import.md). These tools automatically reproject data if needed | ||
| and use GDAL library, enabling import of data from a wide range of sources. | ||
| There are other import tools for specific file formats, such as | ||
| [r.in.pdal](r.in.pdal.md) for lidar data. |
There was a problem hiding this comment.
| [r.in.pdal](r.in.pdal.md) for lidar data. | |
| [r.in.pdal](r.in.pdal.md) for lidar data and [r.unpack](r.unpack.md) for GRASS native rasters. |
| A mapset is a subdirectory within a GRASS project where geospatial analyses | ||
| are performed. All mapsets use their project's CRS. | ||
| Organizing data into mapsets allows isolation of tasks and supports workflows | ||
| where multiple users work on the same project concurrently, |
There was a problem hiding this comment.
It is not clear that the first sentence about tasks would be "cores", "processes" or "machines" and the second "users", this makes the first sentence an intro, or more general statement. The second one then gives the practical feature.
| where multiple users work on the same project concurrently, | |
| where multiple processes or users work on the same project concurrently, |
| ### Referring to maps from other mapsets | ||
|
|
||
| When you use a map in GRASS, you can either refer to it by its bare name | ||
| (e.g., `elevation`) or by its qualified name with a mapset (e.g., `elevation@PERMANENT`). |
There was a problem hiding this comment.
"qualified name" sounds good, but we are also using "full name". Both make sense to me. We do have a combo of both "fully qualified name" as well. (See also the comment above.)
| listed in the *mapset search path*. | ||
| By default, the search path always includes the current mapset | ||
| (first, highest priority) and the PERMANENT mapset so the core | ||
| layers are always available. |
There was a problem hiding this comment.
"core layers" not introduced before plus I suggest replacing the word "core" above.
| layers are always available. | |
| (first, highest priority) and the PERMANENT mapset so the baseline data are always available. |
...or "base layers", but the text did not use layer until now. Maybe it should in the import section.
| ### Examples of using projects and mapsets | ||
|
|
||
| **Site suitability analysis for solar plants:** | ||
| A researcher selects an appropriate CRS for the study area and creates a GRASS |
There was a problem hiding this comment.
| A researcher selects an appropriate CRS for the study area and creates a GRASS | |
| A data scientist selects an appropriate CRS for the study area and creates a GRASS |
The use case seems like a consulting, industry use-case, so Data Scientist or Data Analyst seem more fitting.
| large-scale analyses in parallel. | ||
|
|
||
| **Temporary data processing:** | ||
| A data engineer needs to bring in several raw datasets, run analyses, |
There was a problem hiding this comment.
It's not about "import", but about alignment and consistency. Projects facilite combining, require importing/linking.
| A data engineer needs to bring in several raw datasets, run analyses, | |
| A data engineer needs to combine several raw datasets, run analyses, |
| computational regions. This setup keeps the national dataset safe while allowing | ||
| large-scale analyses in parallel. | ||
|
|
||
| **Temporary data processing:** |
There was a problem hiding this comment.
I don't like the "temporary" part here, but I don't have a good alternative. Transient analysis environment or Ephemeral analysis environment may be too much jargony. What about "Temporary analytical environment" or "Data processing"?
