From 36506462860a445a3a74d8d846eb8eae95a269bf Mon Sep 17 00:00:00 2001 From: Vaclav Petras Date: Wed, 29 Jan 2025 01:50:03 -0500 Subject: [PATCH] r.mapcalc: Use mask and not MASK in the doc (#4999) Uses mask or raster mask instead of MASK in the documentation. Where the raster called MASK needs to be accessed directly in an example, MASK is used as the assumed name mentioning that explicitly. Updates r3.mapcalc in the same way which should be harmless since the wording does not explicitly mention the possibility of a different name. The text looks like a direct copy-paste from r.mapcalc, so that is preserved. The only improvement is that r3.mask is now linked instead of r.mask (in the 3D doc). --- raster/r.mapcalc/r.mapcalc.html | 24 +++++++++++++----------- raster/r.mapcalc/r3.mapcalc.html | 26 ++++++++++++++------------ 2 files changed, 27 insertions(+), 23 deletions(-) diff --git a/raster/r.mapcalc/r.mapcalc.html b/raster/r.mapcalc/r.mapcalc.html index 5f943f2abae..0f41f42b5db 100644 --- a/raster/r.mapcalc/r.mapcalc.html +++ b/raster/r.mapcalc/r.mapcalc.html @@ -619,15 +619,15 @@

Interactive input in command line

the map title will contain only some of it, but most (if not all) of the formula will be placed into the history file for the result map. -

Raster MASK handling

+

Raster mask handling

-r.mapcalc follows the common GRASS behavior of raster MASK handling, -so the MASK is only applied when reading an existing GRASS raster map. +r.mapcalc follows the common GRASS behavior of raster mask handling, +so the mask is only applied when reading an existing GRASS raster map. This implies that, for example, the command: 

 r.mapcalc "elevation_exaggerated = elevation * 3"
-create a map respecting the masked pixels if MASK is active. +create a map with NULL cells for the masked-out cells if raster mask is active.

However, when creating a map which is not based on any map, @@ -636,17 +636,19 @@

Raster MASK handling

r.mapcalc "base_height = 200.0" the created raster map is limited only by a computation region -but it is not affected by an active MASK. -This is expected because, as mentioned above, MASK is only applied when reading, -not when writing a raster map. -

-If also in this case the MASK should be applied, an if() statement including the -MASK should be used, e.g.: +but it is not affected by an active raster mask. +This is expected because, as mentioned above, the mask is only applied +when reading, not when writing a raster map. +If the raster mask should be applied in this case, an if() +function including the mask raster should be used, e.g. +(assuming the mask is called MASK): 

 r.mapcalc "base_height = if(MASK, 200.0, null())"
-When testing MASK related expressions keep in mind that when MASK is active +

+When testing expressions related to mask handling keep in mind that +when the raster mask is active, you don't see data in masked areas even if they are not NULL. See r.mask for details. diff --git a/raster/r.mapcalc/r3.mapcalc.html b/raster/r.mapcalc/r3.mapcalc.html index 742f5974384..46bcbcff3ae 100644 --- a/raster/r.mapcalc/r3.mapcalc.html +++ b/raster/r.mapcalc/r3.mapcalc.html @@ -449,15 +449,15 @@

Interactive input in command line

existing map layers. Users should therefore take care to assign program outputs raster map names that do not yet exist in their current mapsets. -

3D GRID MASK handling

+

3D GRID mask handling

-r3.mapcalc follows the common GRASS behavior of raster MASK handling, -so the MASK is only applied when reading an existing GRASS raster map. +r3.mapcalc follows the common GRASS behavior of raster mask handling, +so the mask is only applied when reading an existing GRASS raster map. This implies that, for example, the command: 

 r3.mapcalc "volume_amplified = volume * 3"
-create a map respecting the masked pixels if MASK is active. +create a map with NULL cells for the masked-out cells if raster mask is active.

However, when creating a map which is not based on any map, @@ -466,19 +466,21 @@

3D GRID MASK handling

r3.mapcalc "volume_const = 200.0" the created raster map is limited only by a computation region -but it is not affected by an active MASK. -This is expected because, as mentioned above, MASK is only applied when reading, -not when writing a raster map. -

-If also in this case the MASK should be applied, an if() statement including the -MASK should be used, e.g.: +but it is not affected by an active raster mask. +This is expected because, as mentioned above, the mask is only applied +when reading, not when writing a raster map. +If the raster mask should be applied in this case, an if() +function including the mask raster should be used, e.g. +(assuming the mask is called MASK): 

 r3.mapcalc "volume_const = if(MASK, 200.0, null())"
-When testing MASK related expressions keep in mind that when MASK is active +

+When testing expressions related to mask handling keep in mind that +when the raster mask is active, you don't see data in masked areas even if they are not NULL. -See r.mask for details. +See r3.mask for details.

Random number generator initialization

The pseudo-random number generator used by the rand() function can