femic.lidar.trees Module

The femic.lidar.trees module owns optional individual-tree product ingestion and block summaries. It consumes existing point products; it does not implement a new segmentation algorithm.

Start Here If…

Use this page first if you are trying to:

  • inspect an existing individual-tree point product;

  • check duplicate tree IDs or missing heights;

  • summarize tree counts and heights by block; or

  • decide whether a source tree product is complete enough to use.

Typical Usage

femic lidar trees \
  --product data/lidar/trees/lidarbc_trees.gpkg \
  --output-dir data/lidar/trees

femic lidar trees \
  --product data/lidar/trees/lidarbc_trees.gpkg \
  --blocks data/input/blocks.gpkg \
  --block-id-field block_id
from pathlib import Path
from femic.lidar.trees import (
    inspect_individual_tree_product,
    summarize_individual_trees_by_block,
)

summary = inspect_individual_tree_product(
    Path("data/lidar/trees/lidarbc_trees.gpkg")
)
blocks = summarize_individual_trees_by_block(
    Path("data/lidar/trees/lidarbc_trees.gpkg"),
    Path("data/input/blocks.gpkg"),
)

Key Entry Surfaces

  • inspect_individual_tree_product() Validate point geometry, required fields, duplicates, missing heights, and distributions.

  • summarize_individual_trees_by_block() Join points to blocks on matching CRS and summarize counts/heights.

  • write_individual_tree_summary() Persist the product summary as JSON.

  • write_tree_block_summary_csv() Persist block summaries as CSV.

Cross-References

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.

class femic.lidar.trees.IndividualTreeSummary(path, crs, feature_count, unique_tree_count, duplicate_tree_count, missing_height_count, height_metrics, crown_metrics, species_counts, geometry_types, generated_utc, warnings=(), schema_version='femic.lidar.individual_tree.v1')[source]

Bases: object

Completeness and distribution summary for one tree product.

Parameters:
  • 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)

crown_metrics: dict[str, object]
crs: str
duplicate_tree_count: int
feature_count: int
generated_utc: str
geometry_types: tuple[str, ...]
height_metrics: dict[str, object]
missing_height_count: int
path: Path
schema_version: str = 'femic.lidar.individual_tree.v1'
species_counts: dict[str, int]
to_dict()[source]

Return the summary as a JSON-serializable mapping.

Return type:

dict[str, object]

unique_tree_count: int
warnings: tuple[str, ...] = ()
class femic.lidar.trees.TreeBlockRow(block_id, tree_count, mean_height_m, p95_height_m, max_height_m, species_counts)[source]

Bases: object

Tree summary for one block or polygon.

Parameters:
  • 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])

block_id: str
max_height_m: float | None
mean_height_m: float | None
p95_height_m: float | None
species_counts: dict[str, int]
to_dict()[source]

Return the block row as a JSON-serializable mapping.

Return type:

dict[str, object]

tree_count: int
class femic.lidar.trees.TreeBlockSummary(trees_path, blocks_path, block_id_field, rows, generated_utc, warnings=(), schema_version='femic.lidar.individual_tree.v1')[source]

Bases: object

Block-level summary for an individual-tree product.

Parameters:
  • trees_path (Path)

  • blocks_path (Path)

  • block_id_field (str)

  • rows (tuple[TreeBlockRow, ...])

  • generated_utc (str)

  • warnings (tuple[str, ...])

  • schema_version (str)

block_id_field: str
blocks_path: Path
generated_utc: str
rows: tuple[TreeBlockRow, ...]
schema_version: str = 'femic.lidar.individual_tree.v1'
to_dict()[source]

Return the block summary as a JSON-serializable mapping.

Return type:

dict[str, object]

trees_path: Path
warnings: tuple[str, ...] = ()
exception femic.lidar.trees.TreeProductError[source]

Bases: RuntimeError

Raised when an individual-tree product or block summary is invalid.

femic.lidar.trees.inspect_individual_tree_product(path, *, id_field='tree_id', height_field='height_m', crown_field='crown_radius_m', species_field='species', generated_utc=None)[source]

Inspect an existing point-based individual-tree product.

Parameters:
  • path (Path)

  • id_field (str)

  • height_field (str)

  • crown_field (str | None)

  • species_field (str | None)

  • generated_utc (str | None)

Return type:

IndividualTreeSummary

femic.lidar.trees.summarize_individual_trees_by_block(trees_path, blocks_path, *, block_id_field='block_id', id_field='tree_id', height_field='height_m', species_field='species', generated_utc=None)[source]

Join tree points to blocks and summarize tree counts and heights.

Parameters:
  • trees_path (Path)

  • blocks_path (Path)

  • block_id_field (str)

  • id_field (str)

  • height_field (str)

  • species_field (str | None)

  • generated_utc (str | None)

Return type:

TreeBlockSummary

femic.lidar.trees.write_individual_tree_summary(summary, path)[source]

Write a tree-product summary as JSON.

Parameters:
Return type:

Path

femic.lidar.trees.write_tree_block_summary_csv(summary, path)[source]

Write block-level tree summaries as CSV.

Parameters:
Return type:

Path