[GRASS-git] [OSGeo/grass] 512bd6: raster: Read raster for mask from env variable (#2...

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 512bd6d3ba7892514fa95c183deea3bf8b718fa5
      https://github.com/OSGeo/grass/commit/512bd6d3ba7892514fa95c183deea3bf8b718fa5
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-02-26 (Wed, 26 Feb 2025)

  Changed paths:
    M doc/development/style_guide.md
    M doc/examples/notebooks/parallelization_tutorial.ipynb
    M lib/init/variables.html
    M lib/init/variables.md
    M lib/raster/auto_mask.c
    M lib/raster/get_row.c
    M lib/raster/mask_info.c
    M lib/raster/maskfd.c
    M lib/raster/open.c
    M lib/raster/rasterlib.dox
    M lib/raster/set_window.c
    M python/grass/script/__init__.py
    M python/grass/script/raster.py
    M python/grass/script/tests/conftest.py
    A python/grass/script/tests/grass_script_raster_mask_test.py
    M raster/r.mapcalc/testsuite/const_map_test.sh
    M raster/r.mask.status/tests/r_mask_status_test.py
    M raster/rasterintro.html
    M raster/rasterintro.md
    M scripts/r.fillnulls/r.fillnulls.py
    M scripts/r.in.wms/wms_base.py
    M scripts/r.mask/r.mask.html
    M scripts/r.mask/r.mask.md
    M scripts/r.mask/r.mask.py
    M testsuite/raster_md5test.sh

  Log Message:
  -----------
  raster: Read raster for mask from env variable (#2392)

Use environment variable GRASS_MASK to obtain the name of the raster map to use as raster map for auto-masking. The name defaults to MASK in the current mapset. Otherwise, the behavior follows the same rules.

Mask can be in another mapset. If it does not exist, mask is not applied. The direct masking rules for values (zero and null is masked out) apply (as when using `g.copy raster=xxx,MASK`).

It works with r.mask, i.e., r.mask gets the name from the environment variable. While setting and unsetting can be done only by manipulating the environment variable, r.mask will use whatever is the mask name set by the environment variable or the default name. This allows to fully use the r.mask capabilities without a need to reimplement them somewhere else. It will also keep the workflows with and without the variable same, so all the r.mask documentation applies to the advanced case of using the variable. If the mask set by the environment is in a different mapset, r.mask will fail.

An alternative would be to implement this without r.mask, i.e., r.mask does not get the name from the environment variable. Setting and unsetting this mask would be done only by manipulating the environment variable. This would be analogous to GRASS_REGION which cannot be manipulated by g.region and similar to g.copy used for MASK which is not easily mixed with r.mask. However, while GRASS_REGION says what the computational region should be, GRASS_MASK merely says what the mask name is regardless of its presence. We could fail if the raster is not present, but it seems more natural to behave the same as with the default name (MASK). This discussion then leads to the current implementation where r.mask respects whatever GRASS_MASK says.

r.fillnulls and r.in.wms are Python scripts which need to handle mask in a special way. The new functionality makes the implementation simpler and it makes the tools more robust as they don't touch the global mask state anymore. The new implementation is included here.

C library:

* Use separate function for name of the mask.
* Support arbitrary mask name in the library (updates r.mask.status behavior).
* Create a new internal function to separate testing of the presence and testing of the reclassification.

Python library:

* MaskManager: Add Python context manager for mask env variable and start tests.
* Add MaskManager to the package init file.

Tools:

* r.mask: Support user-provided mask name in r.mask.
* r.fillnulls: Use a custom mask (but don't set it) instead of moving around the current user mask.
* r.in.wms: Refactor into a function and use with-statement.

Tests:

* Use env var in r.mapcalc test to disable masking instead of managing MASK file.
* Use new mask handling for raster md5 sh test and sync the const test.
* Add tests for different for the various situations which can occur with mask.
* Use a global variable for the default mask name in tests.

Documentation:

* r.mask: Document the new behavior in a basic way and center documentation around the r.mask tool and raster mask rather than a raster called MASK.
* r.mask: Rewrite whole section about different masks.
* Extent parallelization notebook.
* Update best practices for managing mask and document best practices more specifically for Python.
* Add GRASS_MASK to env vars doc.
* Use raster mask, not MASK in r.mask documentation in code.
* Replace MASK by mask in source code comments.

As part of the Markdown transition, it updates the Markdown doc with new content, but also the originally modified HTML files.



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications