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:
objectCompleteness 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:
objectTree 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:
objectBlock-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:
RuntimeErrorRaised 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:
- 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:
- femic.lidar.trees.write_individual_tree_summary(summary, path)[source]
Write a tree-product summary as JSON.
- Parameters:
summary (IndividualTreeSummary)
path (Path)
- Return type:
Path
- femic.lidar.trees.write_tree_block_summary_csv(summary, path)[source]
Write block-level tree summaries as CSV.
- Parameters:
summary (TreeBlockSummary)
path (Path)
- Return type:
Path