Skip to content

Add tree inventory modifications and treatments in convenience module… #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amarcozzi merged 1 commit into from
Dec 10, 2025
Merged

Add tree inventory modifications and treatments in convenience module… #146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 39 additions & 1 deletion docs/tutorials/export_to_quicfire.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,10 +397,48 @@ features_config = {

```python
tree_inventory_config = {
"featureMasks": ["road", "water"] # Features to mask from inventory
"version": "2022", # TreeMap version: "2014", "2016", "2020", "2022"
"seed": 42, # Random seed for reproducibility (optional)
"featureMasks": ["road", "water"], # Features to mask from inventory
"canopyHeightMapSource": "Meta2024", # High-resolution canopy height data

# Tree attribute modifications (optional)
"modifications": [
{
"conditions": [
{"attribute": "CR", "operator": "gt", "value": 0.1}
],
"actions": [
{"attribute": "CR", "modifier": "multiply", "value": 0.9}
]
}
],

# Silvicultural treatments (optional)
"treatments": [
{
"method": "proportionalThinning",
"targetMetric": "basalArea",
"targetValue": 25.0
}
]
}
```

**Available modification attributes:**
- `HT`: Height (meters)
- `DIA`: Diameter at breast height (centimeters)
- `CR`: Crown ratio (0-1) - crown length = height × crown ratio
- `SPCD`: Species code (integer)

**Available operators:** `eq`, `ne`, `gt`, `lt`, `ge`, `le`

**Available modifiers:** `multiply`, `divide`, `add`, `subtract`, `replace`, `remove`

**Treatment methods:**
- `proportionalThinning`: Thin to target basal area (m²/ha)
- `directionalThinning`: Remove trees above/below size threshold

#### Advanced Configuration Examples

**Completely custom surface grid:**
Expand Down
82 changes: 80 additions & 2 deletions fastfuels_sdk/convenience.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> None:
}

DEFAULT_TREE_INVENTORY_CONFIG = {
"version": "2022",
"featureMasks": ["road", "water"],
"canopyHeightMapSource": "Meta2024",
}
Expand Down Expand Up @@ -366,7 +367,23 @@ def export_roi(
Structure::

{
"featureMasks": ["road", "water"] # Features to mask out
"featureMasks": ["road", "water"], # Features to mask out
"canopyHeightMapSource": "Meta2024", # High-resolution canopy height map
"version": "2022", # TreeMap version
"seed": 42, # Random seed for reproducibility
"modifications": [ # Tree attribute modifications
{
"conditions": [{"attribute": "CR", "operator": "gt", "value": 0.1}],
"actions": [{"attribute": "CR", "modifier": "multiply", "value": 0.9}]
}
],
"treatments": [ # Silvicultural treatments
{
"method": "proportionalThinning",
"targetMetric": "basalArea",
"targetValue": 25.0
}
]
}

Returns
Expand Down Expand Up @@ -415,6 +432,43 @@ def export_roi(
... features_config=features_config
... )

Apply tree inventory modifications to reduce crown ratio:

>>> tree_inventory_config = {
... "modifications": [
... {
... "conditions": [{"attribute": "CR", "operator": "gt", "value": 0.1}],
... "actions": [{"attribute": "CR", "modifier": "multiply", "value": 0.9}]
... }
... ]
... }
>>> export = export_roi(
... roi, "modified_trees.zip",
... tree_inventory_config=tree_inventory_config
... )

Apply silvicultural treatments and remove small trees:

>>> tree_inventory_config = {
... "modifications": [
... {
... "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}],
... "actions": [{"attribute": "all", "modifier": "remove"}]
... }
... ],
... "treatments": [
... {
... "method": "proportionalThinning",
... "targetMetric": "basalArea",
... "targetValue": 25.0
... }
... ]
... }
>>> export = export_roi(
... roi, "thinned_forest.zip",
... tree_inventory_config=tree_inventory_config
... )

Notes
-----
This function performs the complete export workflow:
Expand All @@ -431,6 +485,26 @@ def export_roi(
All configuration parameters support partial overrides - only specify the
values you want to change from the defaults. The function will merge your
configuration with sensible defaults for all other parameters.

**Tree Inventory Modifications and Treatments:**

When both modifications and treatments are specified in tree_inventory_config,
they are applied in the following order:

1. **Modifications** are applied first to adjust or remove individual trees
based on their attributes (height, diameter, crown ratio, species)
2. **Treatments** are then applied to the modified inventory to achieve
target stand-level metrics (basal area, density)

Use modifications when you want to:
- Adjust specific tree attributes (e.g., multiply heights by 0.9)
- Remove trees matching certain criteria (e.g., diameter < 10 cm)
- Apply expression-based conditions (e.g., crown length < 1 m)

Use treatments when you want to:
- Apply silvicultural operations (proportional or directional thinning)
- Achieve target stand metrics (e.g., basal area of 25 m²/ha)
- Simulate forest management scenarios
"""
# Validate export format
supported_formats = ["QUIC-Fire", "zarr"]
Expand Down Expand Up @@ -500,10 +574,14 @@ def export_roi(
tree_inventory = Inventories.from_domain_id(
domain.id
).create_tree_inventory_from_treemap(
feature_masks=merged_tree_inventory_config.get("featureMasks", []),
version=merged_tree_inventory_config.get("version", "2022"),
seed=merged_tree_inventory_config.get("seed"),
canopy_height_map_source=merged_tree_inventory_config.get(
"canopyHeightMapSource"
),
modifications=merged_tree_inventory_config.get("modifications"),
treatments=merged_tree_inventory_config.get("treatments"),
feature_masks=merged_tree_inventory_config.get("featureMasks", []),
)

# Create surface grid using configuration
Expand Down
Loading
Loading