Check the grid cell size against the clone when the reference system is projected

[soaressgabriel]

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Added tests for changed code.
• Updated documentation for changed code.

Description

• New rubem/validation/grid_cell_size.py with check_grid_cell_size(grid, pixel_width, pixel_height, crs_wkt, file): when the reference coordinate reference system is projected, the pixel size of the clone is converted to metres through the linear unit of the system (SpatialReference.GetLinearUnits()) and compared with GRID.grid (raster_info.grid_size in format 1.0); a relative difference above 1e-6 on either axis is a blocking problem naming the declared value, the pixel size in the unit of the system and in metres (implication: the cell area converts the accumulated runoff from mm to m3/s, so a wrong cell size scales it quadratically). A geographic system, an engineering system or the absence of a system (PCRaster maps without a georeference) yields no problem: one informational log line states the declared cell size and the resolution the raster offers.
• Wired in ModelConfiguration for both configuration formats, right after the clone geometry and the reference CRS are known, and only under validate_input (the raster validation tier skipped by -s).
• Tests (tests/unit/validation/test_grid_cell_size.py): projected metres matching and mismatching, both sides of the tolerance (500.0000001 and 500.0002 pass, 500.001 and 500.002 block), a single differing axis, a US survey foot system converted to metres with both units in the reason, geographic and CRS-less rasters not compared (log asserted), and the loader wiring on the synthetic dataset for both formats, including validate_input=False.
• User guide: grid is the metric cell size the user asserts, when it is compared and with which reference system (clone, then georeference raster, then DEM), what happens in geographic coordinates (the published basins), and rubem preprocess info as the way to obtain the value. Changelog entry under Added.

Related Issue

• Resolve Check GRID.grid against the raster cell size when the coordinate reference system is projected #329;

Motivation and context

• GRID.grid was typed by the user and never compared with the rasters, although the cell area scales arn quadratically without any other symptom (finding 6 of the scientific review, accepted with the evaluation of when and how). The published basins are in degrees with a nominal metric resolution, so there the value must stay user-provided; in a projected system it can be checked.

How has this been tested

• python -m pytest -q -p no:cacheprovider --ignore=tests/integration/doc -n 4: 1021 passed, 1 skipped, on main at 176f204 (Linux, Python 3.13, PCRaster 4.4.2).
• The unit conversion was re-derived against the installed GDAL/OSR (GetLinearUnits() 1.0 for the metre system, 0.3048006096 for the US survey foot one).
• uvx ruff@0.16.4 format --check . and uvx ruff@0.16.4 check .: clean.
• sphinx-build -W -b html doc/source: no warnings, with the documentation's Python 3.13 environment (the first CI run failed there: the mocked osgeo does not support the union operator in an eagerly evaluated annotation; the module now defers its annotations like the rest of the package).

Left as written, for the maintainer: on a rotated or sheared affine the pixel size would be the norm of the affine columns, not abs(pixel_width); the issue asks for the absolute values and a rotated clone is already refused at run time when PCRaster maps are written, so only the message would differ there.

Screenshots

• N/A

[codecov]

Codecov Report

❌ Patch coverage is 95.34884% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.75%. Comparing base (fb3db34) to head (3667df8).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
rubem/validation/grid_cell_size.py	93.93%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #339      +/-   ##
==========================================
+ Coverage   92.72%   92.75%   +0.02%     
==========================================
  Files          60       61       +1     
  Lines        3985     4028      +43     
  Branches      502      510       +8     
==========================================
+ Hits         3695     3736      +41     
- Misses        234      235       +1     
- Partials       56       57       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.