femic.lidar.inventory Module
The femic.lidar.inventory module applies a pinned area-based inventory
model card to a FEMIC LiDAR product bundle and writes the long
inventory.als table. It is a consumer seam: it does not fit ABA models or
invent coefficients.
Key Entry Surfaces
InventoryAlsModelValidated model card with coefficients, RMSE, training scope, and ranges.load_inventory_als_model()Load and validate a JSON model card.build_inventory_als()Apply the model to the bundle’scanopytable or an explicit feature CSV and optionally validate against a plot table.build_chm_grid_features()Derive a CHM grid feature table (mean, CV, p95, percent cover) from a bundlechmproduct.build_pointcloud_grid_features()Derive first-return grid metrics (mean, CV, p95, cover) from LAS/LAZ tiles and a co-registered DEM. Optionalgrid_origin_x/grid_origin_ymake adjacent tiles share a global cell grid.write_inventory_als()Writeinventory_als.csvandinventory_als.json.InventoryAlsResultBundle/model provenance, long rows, warnings, and caveats.
Cross-References
Area-based inventory predictions from a pinned FEMIC LiDAR bundle.
The module is the INV-01 consumer seam, not a new ABA fitting algorithm. It
reads a versioned model card, applies that model to a table product in a FEMIC
LiDAR product bundle, and writes the long inventory.als table. A model card
must identify its coefficients, training scope, and error; FEMIC does not invent
them.
The first supported product is the tabular canopy artifact (one row per
LiDAR tile). The output is intentionally a fragment table: a real application
can substitute fragment polygons and zonal metrics without changing the output
contract, but that join is not done here.
- class femic.lidar.inventory.InventoryAlsModel(path, model_id, model_version, attribute, unit, intercept, coefficients, rmse, sample_count, training_scope, source, caveats, link='identity', output_scale=1.0, applicability=<factory>, predictor_ranges=<factory>, model_type='linear', terms=(), sha256='', schema_version='femic.inventory.als.model.v1')[source]
Bases:
objectA validated, pinned area-based model card.
- Parameters:
path (Path)
model_id (str)
model_version (str)
attribute (str)
unit (str)
intercept (float)
coefficients (Mapping[str, float])
rmse (float)
sample_count (int | None)
training_scope (str)
source (str)
caveats (tuple[str, ...])
link (str)
output_scale (float)
applicability (Mapping[str, object])
predictor_ranges (Mapping[str, tuple[float, float]])
model_type (str)
terms (tuple[InventoryAlsTerm, ...])
sha256 (str)
schema_version (str)
- applicability: Mapping[str, object]
- attribute: str
- caveats: tuple[str, ...]
- coefficients: Mapping[str, float]
- property features: tuple[str, ...]
Return the raw predictor names in stable model-card order.
- intercept: float
- link: str = 'identity'
- model_id: str
- model_type: str = 'linear'
- model_version: str
- output_scale: float = 1.0
- path: Path
- predictor_ranges: Mapping[str, tuple[float, float]]
- rmse: float
- sample_count: int | None
- schema_version: str = 'femic.inventory.als.model.v1'
- sha256: str = ''
- source: str
- terms: tuple[InventoryAlsTerm, ...] = ()
- to_dict()[source]
Return the model card summary as a JSON-serializable mapping.
- Return type:
dict[str, object]
- training_scope: str
- unit: str
- class femic.lidar.inventory.InventoryAlsResult(bundle_dir, manifest_path, bundle_id, bundle_version, model, rows, generated_utc, features_path=None, features_sha256='', validation=None, warnings=(), caveats=('Area-based inventory predictions are model outputs, not field measurements.', "Model transferability and extrapolation are the caller's responsibility.", 'The output table is long: one row per fragment and attribute.', 'No reprojection, resampling, or source-product rewrite is performed.'), schema_version='femic.inventory.als.v1')[source]
Bases:
objectThe complete
inventory.alsoutput contract.- Parameters:
bundle_dir (Path)
manifest_path (Path)
bundle_id (str)
bundle_version (str)
model (InventoryAlsModel)
rows (tuple[InventoryAlsRow, ...])
generated_utc (str)
features_path (Path | None)
features_sha256 (str)
validation (InventoryAlsValidation | None)
warnings (tuple[str, ...])
caveats (tuple[str, ...])
schema_version (str)
- bundle_dir: Path
- bundle_id: str
- bundle_version: str
- caveats: tuple[str, ...] = ('Area-based inventory predictions are model outputs, not field measurements.', "Model transferability and extrapolation are the caller's responsibility.", 'The output table is long: one row per fragment and attribute.', 'No reprojection, resampling, or source-product rewrite is performed.')
- features_path: Path | None = None
- features_sha256: str = ''
- generated_utc: str
- manifest_path: Path
- model: InventoryAlsModel
- rows: tuple[InventoryAlsRow, ...]
- schema_version: str = 'femic.inventory.als.v1'
- to_dict()[source]
Return the output manifest as a JSON-serializable mapping.
- Return type:
dict[str, object]
- validation: InventoryAlsValidation | None = None
- warnings: tuple[str, ...] = ()
- class femic.lidar.inventory.InventoryAlsRow(fragment_id, attribute, value, model_id, rmse, model_version, unit, source)[source]
Bases:
objectOne predicted inventory attribute for one fragment.
- Parameters:
fragment_id (str)
attribute (str)
value (float)
model_id (str)
rmse (float)
model_version (str)
unit (str)
source (str)
- attribute: str
- fragment_id: str
- model_id: str
- model_version: str
- rmse: float
- source: str
- unit: str
- value: float
- class femic.lidar.inventory.InventoryAlsTerm(kind, coefficient, feature=None, feature2=None)[source]
Bases:
objectOne term in a log-space model card.
- Parameters:
kind (str)
coefficient (float)
feature (str | None)
feature2 (str | None)
- coefficient: float
- feature: str | None = None
- feature2: str | None = None
- kind: str
- class femic.lidar.inventory.InventoryAlsValidation(plots_path, matched_rows, missing_observations, bias, mae, rmse, rows)[source]
Bases:
objectSummary of an optional plot/observation comparison.
- Parameters:
plots_path (Path)
matched_rows (int)
missing_observations (int)
bias (float | None)
mae (float | None)
rmse (float | None)
rows (tuple[InventoryAlsValidationRow, ...])
- bias: float | None
- mae: float | None
- matched_rows: int
- missing_observations: int
- plots_path: Path
- rmse: float | None
- rows: tuple[InventoryAlsValidationRow, ...]
- class femic.lidar.inventory.InventoryAlsValidationRow(fragment_id, attribute, predicted, observed, residual)[source]
Bases:
objectOne predicted-versus-observed comparison row.
- Parameters:
fragment_id (str)
attribute (str)
predicted (float)
observed (float)
residual (float)
- attribute: str
- fragment_id: str
- observed: float
- predicted: float
- residual: float
- exception femic.lidar.inventory.LidarInventoryError[source]
Bases:
RuntimeErrorRaised when a model card, bundle, or inventory prediction is invalid.
- femic.lidar.inventory.build_chm_grid_features(bundle_dir, output_path, *, grid_size_m=25.0, chm_product='chm', min_cover_pct=0.0)[source]
Derive a 25 m grid feature table from a bundle CHM.
Metrics are CHM proxies for the first-return metrics used by many published ABA models: mean height, coefficient of variation, p95, and percent cover above 2 m. Cells with fewer than three above-2 m pixels are omitted. This is a wall-to-wall feature seam, not a point-cloud metric replacement.
- Parameters:
bundle_dir (Path)
output_path (Path)
grid_size_m (float)
chm_product (str)
min_cover_pct (float)
- Return type:
dict[str, object]
- femic.lidar.inventory.build_inventory_als(bundle_dir, model_path, *, features_path=None, fragment_id_field=None, plots_path=None, generated_utc=None)[source]
Apply a fitted ABA model to one pinned FEMIC LiDAR bundle.
The default source is the bundle’s tabular
canopyproduct. A caller may instead passfeatures_path, a CSV withfragment_idand the model’s predictor columns; this is the seam for fragment or grid metrics computed from the bundle without pretending that the join happened here.- Parameters:
bundle_dir (Path)
model_path (Path)
features_path (Path | None)
fragment_id_field (str | None)
plots_path (Path | None)
generated_utc (str | None)
- Return type:
- femic.lidar.inventory.build_pointcloud_grid_features(pointcloud_paths, dem_path, output_path, *, grid_size_m=25.0, height_threshold_m=2.0, min_returns=10, min_cover_pct=0.0, grid_origin_x=None, grid_origin_y=None, source_tile=None, batch_size=5000000)[source]
Derive first-return point-cloud metrics on a regular grid.
The point clouds and the DEM must share a CRS. The function samples the DEM, normalizes first returns to height above ground, and aggregates by grid cell. It is the point-cloud counterpart to
build_chm_grid_features(); it does not fit an ABA model.The optional
laspy[lazrs]dependency is imported lazily because FEMIC does not make point-cloud processing mandatory for every installation.- Parameters:
pointcloud_paths (Sequence[Path])
dem_path (Path)
output_path (Path)
grid_size_m (float)
height_threshold_m (float)
min_returns (int)
min_cover_pct (float)
grid_origin_x (float | None)
grid_origin_y (float | None)
source_tile (str | None)
batch_size (int)
- Return type:
dict[str, object]
- femic.lidar.inventory.load_inventory_als_model(path)[source]
Load and validate a fitted ABA model card.
The model card is JSON. Coefficients are explicit; this function never estimates or imputes them. The card must identify its training scope and prediction error.
- Parameters:
path (Path)
- Return type:
- femic.lidar.inventory.resolve_inventory_model_path(config_path, model_key)[source]
Resolve a model path from an experimental inventory config.
Paths in the config are relative to the instance root when the config lives under
config/inventory/. Absolute paths are preserved.- Parameters:
config_path (Path)
model_key (str)
- Return type:
Path
- femic.lidar.inventory.write_inventory_als(result, out_dir)[source]
Write the long inventory table and its provenance manifest.
- Parameters:
result (InventoryAlsResult)
out_dir (Path)
- Return type:
dict[str, Path]