src.eval.raster.raster_postproc

author:

Alberto M. Esmoris Pena

The raster_postproc module contains the thin Python orchestrators that validate the per-grid JSON post-processor specifications and dispatch to the typed C++ entry points exposed by pyvl3dpp for the five new raster post-processors (hillshade, LRM, resampling filter, VAT, MSRM) plus the legacy hillshading key (now routed through the same C++ Horn kernel as hillshade).

The C++ kernels are required at run time: the module hard-imports pyvl3dpp at load time, mirroring the convention of src.mining.smooth_feats_minerpp. If a kernel symbol is missing in the loaded pyvl3dpp build (e.g., the C++ build has not been rebuilt with the raster module), the affected post-processor raises a src.eval.evaluator.EvaluatorException carrying a clear rebuild hint. No Python fallback path is shipped in production; the Python reference implementations live only under src.tests.raster_grid_postproc_ref.

Functions

apply_hillshade(z2d, xres, yres, spec, bits)

Apply the new hillshade JSON key using the C++ Horn kernel.

apply_hillshading(z2d, xres, yres, spec, bits)

Apply the legacy hillshading JSON key using the C++ Horn kernel.

apply_lrm(z2d, spec, bits)

Apply the Local Relief Model (Hesse 2010 / RVT SLRM) post- processor by subtracting a NaN-aware box-mean lowpass from the input grid (see plan sec.

apply_msrm(z2d, xres, yres, spec, bits)

Apply the Multi-Scale Relief Model (Orengo & Petrie 2018) post- processor; verbatim port of the reference notebook MSRM-Multi-Scale-Relief-Model/MSRM.ipynb (plan sec.

apply_resampling_filter(z2d, spec, bits)

Apply the resampling-filter (SAGA / RVT) post-processor as a two-step pipeline: first the input is down-sampled by a factor of scale_factor using a NaN-aware area-weighted mean computed in C++ (kernel raster_resampling_filter_{f,d}); then the coarsened grid is up-sampled back to the original resolution via scipy.interpolate.RectBivariateSpline with kx=ky=3, s=0 (plan sec.

apply_vat(z2d, xres, yres, spec, bits)

Apply the Visualization for Archaeological Topography (Kokalj & Somrak 2019) composite post-processor: hillshade, slope, positive openness, and sky-view factor are blended into a single output grid using the RVT blend pipeline (plan sec.
src.eval.raster.raster_postproc.apply_hillshading(z2d, xres, yres, spec, bits)

Apply the legacy hillshading JSON key using the C++ Horn kernel.

The defaults match the legacy contract (azimuth=30, altitude=30, z_factor=1.0) so legacy JSON specifications keep parsing unchanged; the numerical OUTPUT differs from the legacy earthpy implementation because the engine is the Horn GDAL math-CCW kernel shared with the new hillshade key.

Parameters:

  • z2d (np.ndarray) – The input 2D grid (rows, cols).

  • xres (float) – Cell size along the x-axis.

  • yres (float) – Cell size along the y-axis.

  • spec (dict) – The per-grid hillshading specification dict.

  • bits (int) – The feature-space bits selector (32 or 64).

Returns:

The post-processed grid (same shape as input).

Return type:

np.ndarray

src.eval.raster.raster_postproc.apply_hillshade(z2d, xres, yres, spec, bits)

Apply the new hillshade JSON key using the C++ Horn kernel.

Defaults match the GDAL / ArcGIS convention (azimuth=315, altitude=45, z_factor=1.0). The C++ kernel is shared with apply_hillshading() and only the default parameters differ at the Python dispatcher layer.

Parameters:

  • z2d (np.ndarray) – The input 2D grid (rows, cols).

  • xres (float) – Cell size along the x-axis.

  • yres (float) – Cell size along the y-axis.

  • spec (dict) – The per-grid hillshade specification dict.

  • bits (int) – The feature-space bits selector (32 or 64).

Returns:

The post-processed grid (same shape as input).

Return type:

np.ndarray

src.eval.raster.raster_postproc.apply_lrm(z2d, spec, bits)

Apply the Local Relief Model (Hesse 2010 / RVT SLRM) post- processor by subtracting a NaN-aware box-mean lowpass from the input grid (see plan sec. 4.3).

Defaults: radius=5 (cells), filter='mean', and edge_mode='reflect'. The C++ kernel takes a cell radius and enum-indexed filter_kind / edge_mode arguments; xres and yres are NOT passed (CONTRACT_iter1.md sec. 1).

Parameters:

  • z2d (np.ndarray) – The input 2D grid (rows, cols).

  • spec (dict) – The per-grid lrm specification dict.

  • bits (int) – The feature-space bits selector (32 or 64).

Returns:

The post-processed grid (same shape as input).

Return type:

np.ndarray

src.eval.raster.raster_postproc.apply_resampling_filter(z2d, spec, bits)

Apply the resampling-filter (SAGA / RVT) post-processor as a two-step pipeline: first the input is down-sampled by a factor of scale_factor using a NaN-aware area-weighted mean computed in C++ (kernel raster_resampling_filter_{f,d}); then the coarsened grid is up-sampled back to the original resolution via scipy.interpolate.RectBivariateSpline with kx=ky=3, s=0 (plan sec. 4.4).

Default: scale_factor=10 (cells per down-sampled block). The C++ kernel takes only (z, scale_factor); xres/yres are NOT passed (CONTRACT_iter1.md sec. 1).

Parameters:

  • z2d (np.ndarray) – The input 2D grid (rows, cols).

  • spec (dict) – The per-grid resampling_filter specification.

  • bits (int) – The feature-space bits selector (32 or 64).

Returns:

The post-processed grid (same shape as input).

Return type:

np.ndarray

src.eval.raster.raster_postproc.apply_vat(z2d, xres, yres, spec, bits)

Apply the Visualization for Archaeological Topography (Kokalj & Somrak 2019) composite post-processor: hillshade, slope, positive openness, and sky-view factor are blended into a single output grid using the RVT blend pipeline (plan sec. 4.5).

Defaults: n_directions=16, search_radius=20 cells, svf_opacity=0.5, po_opacity=0.5; the inner hillshade spec defaults to azimuth=315, altitude=45, z_factor=1.0. The C++ argument order pins (search_radius_cells, n_directions) and DOES NOT take slopeMin/slopeMax (the slope mapping S = slope_rad / (pi/2) is hardcoded inside the kernel per CONTRACT_iter1.md sec. 1).

Parameters:

  • z2d (np.ndarray) – The input 2D grid (rows, cols).

  • xres (float) – Cell size along the x-axis.

  • yres (float) – Cell size along the y-axis.

  • spec (dict) – The per-grid vat specification dict.

  • bits (int) – The feature-space bits selector (32 or 64).

Returns:

The post-processed grid (same shape as input).

Return type:

np.ndarray

src.eval.raster.raster_postproc.apply_msrm(z2d, xres, yres, spec, bits)

Apply the Multi-Scale Relief Model (Orengo & Petrie 2018) post- processor; verbatim port of the reference notebook MSRM-Multi-Scale-Relief-Model/MSRM.ipynb (plan sec. 4.6).

The number of relief models is derived from fmin, fmax, the average cell size rr = (|xres| + |yres|) / 2, and the exponent x (default x=2.0). Both fmin and fmax are required user inputs; fmax > fmin is enforced. edge_mode is forwarded to the C++ kernel ("reflect" by default).

Parameters:

  • z2d (np.ndarray) – The input 2D grid (rows, cols).

  • xres (float) – Cell size along the x-axis.

  • yres (float) – Cell size along the y-axis.

  • spec (dict) – The per-grid msrm specification dict.

  • bits (int) – The feature-space bits selector (32 or 64).

Returns:

The post-processed grid (same shape as input).

Return type:

np.ndarray