5/8 Add polygon land-cover apportionment and ingestion

[Timothy-W-Hilton]

Add polygon land-cover apportionment and ingestion

Summary

Add a generic path for using polygon-native land-cover products with pyVPRM. The new utility calculates fractional source-class coverage for each cell of an existing regular satellite grid. A companion preprocessor method maps those already-grid-aligned source fractions to VPRM classes without regridding them again.

Existing fractional land-cover workflow

pyVPRM already supports fractional VPRM land cover from a categorical raster: add_land_cover_map() maps source pixels to VPRM classes, creates a binary layer for each resulting class, and conservatively regrids those layers to the satellite grid.

This PR does not replace that workflow. It adds the corresponding input path for products that begin as vector polygons, or for fractions computed by an external geometric workflow.

What this adds

• pyVPRM.apportion_polygons_to_grid.apportion().
  • Intersects classified source polygons with regular target-grid cell polygons and returns class × y × x fractional coverage.
  • Requires the caller to provide an equal-area CRS for area calculations; no region-specific CRS is assumed.
  • Processes target rows in chunks and uses a conservative rasterized footprint prefilter, avoiding expensive intersection work for cells that cannot overlap any source polygon.
  • Transforms target-cell bounds to the source polygon CRS before spatial index queries, which is necessary when the source and target use different CRSs.
  • Retains the original target-grid coordinates, CRS, and affine transform.
• vprm_preprocessor.add_fractional_land_cover_map().
  • Accepts source-class fractions already aligned with the active satellite grid.
  • Validates coordinates, CRS, fraction bounds, and complete source-class mappings.
  • Maps source classes to VPRM classes and sums contributions when several source classes share a VPRM class.
  • Does not perform another regridding operation.

Example

from pyVPRM.apportion_polygons_to_grid import apportion

fractions = apportion(
    land_cover_polygons,
    satellite_grid,
    area_crs="EPSG:6933",
    class_column="land_cover_class",
)

vprm_pre.add_fractional_land_cover_map(
    fractions,
    class_mapping={10: 1, 20: 1, 30: 8},
    source_name="example polygon land cover",
)

Validation

• Tests cover full and partial polygon coverage, preservation of fractional coverage and CRS metadata, mixed-CRS spatial-index queries, mapping and aggregation of source classes, and rejection of incomplete class mappings.
• Focused test suite on this branch: 4 passed.
• The approach was also applied outside this test suite to New Zealand LCDB polygons on five MODIS grids.