Source code for femic.lidar.trees

"""Optional individual-tree product ingestion and block summaries.

P79.7 consumes existing LidarBC or external individual-tree products. It does
not implement a new tree-segmentation algorithm. Tree products are optional and
are summarized with explicit completeness and uncertainty fields.
"""

from __future__ import annotations

import csv
import json
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path

import geopandas as gpd  # type: ignore[import-untyped]
import numpy as np

TREE_PRODUCT_SCHEMA_VERSION = "femic.lidar.individual_tree.v1"
DEFAULT_TREE_ID_FIELD = "tree_id"
DEFAULT_TREE_HEIGHT_FIELD = "height_m"
DEFAULT_TREE_CROWN_FIELD = "crown_radius_m"
DEFAULT_TREE_SPECIES_FIELD = "species"
DEFAULT_BLOCK_ID_FIELD = "block_id"
TREE_PRODUCT_CAVEATS: tuple[str, ...] = (
    "Individual-tree products are optional and source-dependent.",
    (
        "FEMIC does not implement a new tree-segmentation algorithm; ingest a "
        "suitable existing public product."
    ),
    "Tree heights and crowns are not a field-accuracy claim without validation.",
)


[docs] class TreeProductError(RuntimeError): """Raised when an individual-tree product or block summary is invalid."""
[docs] @dataclass(frozen=True) class IndividualTreeSummary: """Completeness and distribution summary for one tree product.""" path: Path crs: str feature_count: int unique_tree_count: int duplicate_tree_count: int missing_height_count: int height_metrics: dict[str, object] crown_metrics: dict[str, object] species_counts: dict[str, int] geometry_types: tuple[str, ...] generated_utc: str warnings: tuple[str, ...] = () schema_version: str = TREE_PRODUCT_SCHEMA_VERSION
[docs] def to_dict(self) -> dict[str, object]: """Return the summary as a JSON-serializable mapping.""" return { "schema_version": self.schema_version, "path": str(self.path), "crs": self.crs, "feature_count": self.feature_count, "unique_tree_count": self.unique_tree_count, "duplicate_tree_count": self.duplicate_tree_count, "missing_height_count": self.missing_height_count, "height_metrics": self.height_metrics, "crown_metrics": self.crown_metrics, "species_counts": self.species_counts, "geometry_types": list(self.geometry_types), "generated_utc": self.generated_utc, "warnings": list(self.warnings), }
[docs] @dataclass(frozen=True) class TreeBlockRow: """Tree summary for one block or polygon.""" block_id: str tree_count: int mean_height_m: float | None p95_height_m: float | None max_height_m: float | None species_counts: dict[str, int]
[docs] def to_dict(self) -> dict[str, object]: """Return the block row as a JSON-serializable mapping.""" return { "block_id": self.block_id, "tree_count": self.tree_count, "mean_height_m": self.mean_height_m, "p95_height_m": self.p95_height_m, "max_height_m": self.max_height_m, "species_counts": self.species_counts, }
[docs] @dataclass(frozen=True) class TreeBlockSummary: """Block-level summary for an individual-tree product.""" trees_path: Path blocks_path: Path block_id_field: str rows: tuple[TreeBlockRow, ...] generated_utc: str warnings: tuple[str, ...] = () schema_version: str = TREE_PRODUCT_SCHEMA_VERSION
[docs] def to_dict(self) -> dict[str, object]: """Return the block summary as a JSON-serializable mapping.""" return { "schema_version": self.schema_version, "trees_path": str(self.trees_path), "blocks_path": str(self.blocks_path), "block_id_field": self.block_id_field, "rows": [row.to_dict() for row in self.rows], "generated_utc": self.generated_utc, "warnings": list(self.warnings), }
[docs] def inspect_individual_tree_product( path: Path, *, id_field: str = DEFAULT_TREE_ID_FIELD, height_field: str = DEFAULT_TREE_HEIGHT_FIELD, crown_field: str | None = DEFAULT_TREE_CROWN_FIELD, species_field: str | None = DEFAULT_TREE_SPECIES_FIELD, generated_utc: str | None = None, ) -> IndividualTreeSummary: """Inspect an existing point-based individual-tree product.""" resolved = path.expanduser().resolve() try: frame = gpd.read_file(resolved) except (OSError, RuntimeError, TypeError, ValueError) as exc: raise TreeProductError( f"Unable to read individual-tree product: {resolved}: {exc}" ) from exc if frame.empty: raise TreeProductError("Individual-tree product contains no features.") if frame.crs is None: raise TreeProductError("Individual-tree product has no CRS.") for field in (id_field, height_field): if field not in frame.columns: raise TreeProductError( f"Individual-tree product is missing required field {field!r}." ) geometry_types = tuple( sorted({str(value) for value in frame.geometry.geom_type.dropna().unique()}) ) unsupported = [ value for value in geometry_types if value not in {"Point", "MultiPoint"} ] if unsupported: raise TreeProductError( "Individual-tree geometry must be point-based; found: " + ", ".join(unsupported) ) warnings: list[str] = [ "No reprojection or resampling was performed.", "Tree products are optional and source-dependent.", ] if not frame.crs.is_projected: warnings.append( "Tree product CRS is not projected; block summaries may be unreliable." ) if crown_field is not None and crown_field not in frame.columns: warnings.append(f"Optional crown field {crown_field!r} is missing.") if species_field is not None and species_field not in frame.columns: warnings.append(f"Optional species field {species_field!r} is missing.") ids = frame[id_field].dropna().astype(str) duplicate_tree_count = int(ids.duplicated(keep=False).sum()) heights = _numeric_values(frame[height_field]) missing_height_count = int(frame[height_field].isna().sum()) crowns = ( _numeric_values(frame[crown_field]) if crown_field is not None and crown_field in frame.columns else np.asarray([], dtype=float) ) species_counts: dict[str, int] = {} if species_field is not None and species_field in frame.columns: species_counts = { str(key): int(value) for key, value in frame[species_field] .fillna("unknown") .value_counts() .items() } return IndividualTreeSummary( path=resolved, crs=frame.crs.to_string(), feature_count=len(frame), unique_tree_count=int(ids.nunique()), duplicate_tree_count=duplicate_tree_count, missing_height_count=missing_height_count, height_metrics=_distribution(heights), crown_metrics=_distribution(crowns), species_counts=species_counts, geometry_types=geometry_types, generated_utc=generated_utc or _now(), warnings=tuple(warnings), )
[docs] def summarize_individual_trees_by_block( trees_path: Path, blocks_path: Path, *, block_id_field: str = DEFAULT_BLOCK_ID_FIELD, id_field: str = DEFAULT_TREE_ID_FIELD, height_field: str = DEFAULT_TREE_HEIGHT_FIELD, species_field: str | None = DEFAULT_TREE_SPECIES_FIELD, generated_utc: str | None = None, ) -> TreeBlockSummary: """Join tree points to blocks and summarize tree counts and heights.""" resolved_trees = trees_path.expanduser().resolve() resolved_blocks = blocks_path.expanduser().resolve() try: trees = gpd.read_file(resolved_trees) blocks = gpd.read_file(resolved_blocks) except (OSError, RuntimeError, TypeError, ValueError) as exc: raise TreeProductError(f"Unable to read tree/block inputs: {exc}") from exc if trees.empty or blocks.empty: raise TreeProductError("Tree and block inputs must both contain features.") if trees.crs is None or blocks.crs is None: raise TreeProductError("Tree and block inputs must both have a CRS.") if trees.crs.to_string() != blocks.crs.to_string(): raise TreeProductError( "Tree and block CRS do not match; reprojection is not allowed." ) for field in (id_field, height_field): if field not in trees.columns: raise TreeProductError(f"Tree product is missing required field {field!r}.") if block_id_field not in blocks.columns: raise TreeProductError( f"Block product is missing required field {block_id_field!r}." ) joined = gpd.sjoin( trees, blocks[[block_id_field, "geometry"]], how="inner", predicate="within", ) warnings: list[str] = [ "No reprojection or resampling was performed.", ] if len(joined) < len(trees): warnings.append( f"{len(trees) - len(joined)} trees were outside all blocks and " "were excluded from block summaries." ) rows: list[TreeBlockRow] = [] for block_id, group in joined.groupby(block_id_field): heights = _numeric_values(group[height_field]) species_counts: dict[str, int] = {} if species_field is not None and species_field in group.columns: species_counts = { str(key): int(value) for key, value in group[species_field] .fillna("unknown") .value_counts() .items() } rows.append( TreeBlockRow( block_id=str(block_id), tree_count=len(group), mean_height_m=(float(np.mean(heights)) if heights.size else None), p95_height_m=( float(np.percentile(heights, 95)) if heights.size else None ), max_height_m=(float(np.max(heights)) if heights.size else None), species_counts=species_counts, ) ) rows.sort(key=lambda row: row.block_id) return TreeBlockSummary( trees_path=resolved_trees, blocks_path=resolved_blocks, block_id_field=block_id_field, rows=tuple(rows), generated_utc=generated_utc or _now(), warnings=tuple(warnings), )
[docs] def write_individual_tree_summary( summary: IndividualTreeSummary, path: Path, ) -> Path: """Write a tree-product summary as JSON.""" resolved = path.expanduser().resolve() resolved.parent.mkdir(parents=True, exist_ok=True) resolved.write_text( json.dumps(summary.to_dict(), indent=2, sort_keys=True) + "\n", encoding="utf-8", ) return resolved
[docs] def write_tree_block_summary_csv(summary: TreeBlockSummary, path: Path) -> Path: """Write block-level tree summaries as CSV.""" resolved = path.expanduser().resolve() resolved.parent.mkdir(parents=True, exist_ok=True) with resolved.open("w", newline="", encoding="utf-8") as handle: writer = csv.writer(handle) writer.writerow( [ "block_id", "tree_count", "mean_height_m", "p95_height_m", "max_height_m", "species_counts", ] ) for row in summary.rows: writer.writerow( [ row.block_id, row.tree_count, row.mean_height_m, row.p95_height_m, row.max_height_m, json.dumps(row.species_counts, sort_keys=True), ] ) return resolved
def _numeric_values(series: object) -> np.ndarray: try: values = np.asarray(series, dtype=float) except (TypeError, ValueError): return np.asarray([], dtype=float) return values[np.isfinite(values)] def _distribution(values: np.ndarray) -> dict[str, object]: if values.size == 0: return { "count": 0, "min": None, "mean": None, "median": None, "p95": None, "max": None, } return { "count": int(values.size), "min": float(np.min(values)), "mean": float(np.mean(values)), "median": float(np.median(values)), "p95": float(np.percentile(values, 95)), "max": float(np.max(values)), } def _now() -> str: return datetime.now(UTC).isoformat()