[Feat] Unexpected behaviour / documentation of 3D parameters of g.region

[lrntct]

Describe the bug

2D and 3D raster maps do no share the same resolution in the computational region, although they share other parameters. I find this behaviour unexpected with the current state of the documentation.

To reproduce

import grass_session  # noqa: F401
import grass.script as gs
from grass.script import array as garray

gs.run_command("g.region", b=0, t=100, tbres=20, rows=150, cols=135)
gs.run_command("g.region", flags="3p")

raster3d_name = "raster_3d_test"
gs.raster3d.mapcalc3d(exp=f"{raster3d_name}=rand(10,100)", seed=1, overwrite=True)
array3d = garray.array3d(mapname=raster3d_name)
array2d = garray.array(mapname="elev_srtm_30m")
print(f"{array3d.shape=}")  # Expected (5, 150, 135)
print(f"{array2d.shape=}")  # Expected (150, 135)

projection: 99 (Lambert Conformal Conic)
zone:       0
datum:      nad83
ellipsoid:  a=6378137 es=0.006694380022900787
north:      220750
south:      220000
west:       638300
east:       639000
top:        100.00000000
bottom:     0.00000000
nsres:      5
nsres3:     1
ewres:      5.18518519
ewres3:     1
tbres:      20
rows:       150
rows3:      750
cols:       135
cols3:      700
depths:     5
cells:      20250
cells3:     2625000
 100%
array3d.shape=(5, 750, 700)
array2d.shape=(150, 135)

Expected behavior

I would expect rows==rows3, cols==cols3, etc. Especially considering that the extent is shared between 2D and 3D rasters, and that there is no 3D equivalents for the cols and rows arguments in g.region.

Neither the current g.region nor the 3d raster documentation are explicit about the fact that although 2d and 3d maps share the region extent, they do not share its resolution.

Work items

• [x] Make documentation clearer (#5817)
• [x] Add parameters nsres3 and ewres3 to g.region (#5883)
• [ ] Support of 3D parameters in pygrass.Region

[lrntct]

Adding to the potential for confusion, the Region class from pygrass does not include the 3D resolution attributes. Only tbres could be set and retrieved, but there is no nsres3 or cols3 attributes.

Also, it is possible to have nsres != ewres, but nsres3 == ewres3 is mandatory. However, tbres could somehow be set independently?

[lrntct]

The wiki page about computational region might need an update as well.

[petrasovaa]

Adding to the potential for confusion, the Region class from pygrass does not include the 3D resolution attributes. Only tbres could be set and retrieved, but there is no nsres3 or cols3 attributes.

This should be fairly easy to fix I suppose, mostly copy-pasting.

Also, it is possible to have nsres != ewres, but nsres3 == ewres3 is mandatory. However, tbres could somehow be set independently?

You mean g.region doesn't have option for that? That could be added for sure. Or did you mean something else? I don't think there is inherently a need that they are the same.

[petrasovaa]

The wiki page about computational region my need an update as well.

This is not the right place for it anyway, I would like to have it all in the official documentation.

[lrntct]

Adding to the potential for confusion, the Region class from pygrass does not include the 3D resolution attributes. Only tbres could be set and retrieved, but there is no nsres3 or cols3 attributes.

This should be fairly easy to fix I suppose, mostly copy-pasting.

Looking quickly at the source code, it seems that it could be done easily.

Also, it is possible to have nsres != ewres, but nsres3 == ewres3 is mandatory. However, tbres could somehow be set independently?

You mean g.region doesn't have option for that? That could be added for sure. Or did you mean something else? I don't think there is inherently a need that they are the same.

There is only a res3 option in g.region, but no nsres3 and swres3 options. I do not know if this is a limitation of the raster3d back-end, or if it just an oversight in g.region.

[lrntct]

I added a note in the wiki. I can open a PR to modify the g.region docs and the 3d raster introduction. As for the g.region parameters, it seems that ns_res3 and ew_res3 are indeed stored separately under the hood. g.region simply does not provides the options to change them separately.

https://github.com/OSGeo/grass/blob/9445cc486f554ebf8afcb6e8cb609d6c2bdcb43b/general/g.region/main.c#L778-L786

[lrntct]

I am working on an update of g.region to set nsres3 and ewres3 independently.