Crown base height: regenerate client, add crown base height creator (#246)

docs/v2/guides/inventories.md

@@ -167,8 +167,9 @@ inventory.wait()
 ```
 
 The standard column roles are `tree_id`, `x`, `y`, `height` (m), `dbh`
-(cm), `crown_ratio`, `crown_radius` (m), `fia_species_code`,
-`fia_status_code`, and `fia_crown_class_code`. Columns whose
+(cm), `crown_ratio` (FIA compacted crown ratio, 0-1), `crown_base_height`
+(m), `crown_radius` (m), `fia_species_code`, `fia_status_code`, and
+`fia_crown_class_code`. Columns whose
 names already match need no mapping; otherwise map your file's column names
 onto the roles:
 
@@ -195,8 +196,9 @@ background job — `wait()` before reading data back:
 
 An uploaded inventory may carry only some columns — coordinates and heights,
 say, without diameters or species. `create_tree_inventory_from_gdam` fills in
-the missing morphology (`dbh`, `crown_ratio`, `fia_species_code`) for a
-completed inventory using GDAM allometry, producing a new inventory:
+the missing morphology (`dbh`, `crown_ratio`, `fia_species_code`,
+`crown_base_height`) for a completed inventory using GDAM allometry, producing
+a new inventory:
 
 ```python
 sparse = ff.inventories.create_tree_inventory_from_file(domain, "stems.csv")
@@ -207,7 +209,34 @@ full.wait()
 ```
 
 Existing values are preserved — only missing cells are imputed. Pass
-`impute_columns=["fia_species_code"]` to impute just a subset.
+`impute_columns=["fia_species_code"]` to impute just a subset, or
+`overwrite=True` to replace every tree's value in the imputed columns. GDAM
+predicts the crown base height too; to compute it with an equation from the
+imputed species, dbh, crown ratio and height instead, pass
+`crown_base_height_model=` a model name such as `"fia_national_logit_2026"`.
+
+## Compute crown base heights
+
+Voxelization and canopy grids need a `crown_base_height` (m) for every tree.
+To compute it for an inventory that already has species, dbh, crown ratio
+and height, use `create_tree_inventory_from_crown_base_height`:
+
+```python
+trees = ff.inventories.create_tree_inventory_from_file(domain, "plot_trees.csv")
+trees.wait()
+
+inventory = ff.inventories.create_tree_inventory_from_crown_base_height(
+    domain, trees
+)
+inventory.wait()
+```
+
+The default model is `"fia_national_logit_2026"`; pass `model=` another
+name (`"monleon_2004_eq1"`, `"monleon_2004_eq2"`, `"toney_reeves_2009"`,
+`"randolph_2010"`, `"westfall_2019"`) for a regional equation, or `"gdam"`
+to predict it from position and height alone. Existing crown base heights are
+kept and only empty cells are filled; pass `overwrite=True` to recompute
+every tree's.
 
 ## Wait for an inventory to finish
 

docs/v2/guides/migration.md

@@ -234,8 +234,9 @@ Available now — see the [Inventories guide](inventories.md) and the
   cover threshold v1 fixed internally.
 - **Upload columns changed.** v1 uploads required `TREE_ID`, `SPCD`,
   `STATUSCD`, `DIA`, `HT` columns. v2 uses the roles `x`, `y`, `height`,
-  `dbh`, `crown_ratio`, `fia_species_code`, `fia_status_code`, and a
-  `columns={role: your_name}` mapping replaces renaming your file.
+  `dbh`, `crown_ratio`, `crown_base_height`, `fia_species_code`,
+  `fia_status_code`, and a `columns={role: your_name}` mapping replaces
+  renaming your file.
 - **Modifications and treatments are typed models.** v1's dict syntax
   (`{"attribute": "HT", ...}`) becomes the generated
   `InventoryModification` / treatment models, passed to `modifications=` /

docs/v2/guides/modify-treat-inventories.md

@@ -39,16 +39,16 @@ import fastfuels_sdk.v2 as ff
 # Remove every tree under 10 cm DBH
 ff.remove_trees(ff.tree_attribute("dbh", "<", 10))
 
-# Shrink crowns on the largest trees inside a stand boundary
+# Raise crown bases by 2 m on the largest trees inside a stand boundary
 ff.modify_trees(
-    "crown_ratio", "multiply", 0.8,
+    "crown_base_height", "add", 2.0,
     ff.tree_attribute("dbh", ">", 40),
     ff.tree_within(stand),
 )
 ```
 
-`tree_attribute` takes an attribute (`"dbh"`, `"height"`, `"crown_ratio"`,
-`"fia_species_code"`) and a comparison (`"<"`, `"<="`, `">"`, `">="`, `"=="`,
+`tree_attribute` takes an attribute (`"dbh"`, `"height"`,
+`"crown_base_height"`, `"fia_species_code"`) and a comparison (`"<"`, `"<="`, `">"`, `">="`, `"=="`,
 `"!="`); pass several conditions to AND them. `modify_trees`'s modifier is
 `"replace"`, `"add"`, `"subtract"`, `"multiply"`, or `"divide"`.
 

fastfuels_sdk/v2/client_library/api/grids/create_inventory_canopy_grid.py

@@ -100,7 +100,7 @@ def sync_detailed(
 
     - **source_inventory_id**: (required) ID of a completed tree inventory in
       this domain. Required columns depend on the selected methods; the
-      defaults need `x`, `y`, `height`, `crown_ratio`, `dbh`, and
+      defaults need `x`, `y`, `height`, `crown_base_height`, `dbh`, and
       `fia_species_code`. Required columns must have no null values; a null
       `fia_status_code` counts as live.
     - **alignment**: (optional) Output lattice. Against the domain (the
@@ -206,7 +206,7 @@ def sync(
 
     - **source_inventory_id**: (required) ID of a completed tree inventory in
       this domain. Required columns depend on the selected methods; the
-      defaults need `x`, `y`, `height`, `crown_ratio`, `dbh`, and
+      defaults need `x`, `y`, `height`, `crown_base_height`, `dbh`, and
       `fia_species_code`. Required columns must have no null values; a null
       `fia_status_code` counts as live.
     - **alignment**: (optional) Output lattice. Against the domain (the
@@ -307,7 +307,7 @@ async def asyncio_detailed(
 
     - **source_inventory_id**: (required) ID of a completed tree inventory in
       this domain. Required columns depend on the selected methods; the
-      defaults need `x`, `y`, `height`, `crown_ratio`, `dbh`, and
+      defaults need `x`, `y`, `height`, `crown_base_height`, `dbh`, and
       `fia_species_code`. Required columns must have no null values; a null
       `fia_status_code` counts as live.
     - **alignment**: (optional) Output lattice. Against the domain (the
@@ -411,7 +411,7 @@ async def asyncio(
 
     - **source_inventory_id**: (required) ID of a completed tree inventory in
       this domain. Required columns depend on the selected methods; the
-      defaults need `x`, `y`, `height`, `crown_ratio`, `dbh`, and
+      defaults need `x`, `y`, `height`, `crown_base_height`, `dbh`, and
       `fia_species_code`. Required columns must have no null values; a null
       `fia_status_code` counts as live.
     - **alignment**: (optional) Output lattice. Against the domain (the

fastfuels_sdk/v2/client_library/api/grids/create_netcdf_upload.py

@@ -123,7 +123,7 @@ def sync_detailed(
     If a data variable has a `units` attribute it must be in canonical
     UDUNITS-2 ASCII form with `**` exponents (e.g. `kg/m**3`, `1/m`, `%`).
     Non-canonical forms (`kg/m³`, `kg/m^3`, `kg/m3`) fail with
-    `INVALID_UNITS`. See docs/units.md.
+    `INVALID_UNITS`.
 
     ## Z axis (3D only)
 
@@ -220,7 +220,7 @@ def sync(
     If a data variable has a `units` attribute it must be in canonical
     UDUNITS-2 ASCII form with `**` exponents (e.g. `kg/m**3`, `1/m`, `%`).
     Non-canonical forms (`kg/m³`, `kg/m^3`, `kg/m3`) fail with
-    `INVALID_UNITS`. See docs/units.md.
+    `INVALID_UNITS`.
 
     ## Z axis (3D only)
 
@@ -312,7 +312,7 @@ async def asyncio_detailed(
     If a data variable has a `units` attribute it must be in canonical
     UDUNITS-2 ASCII form with `**` exponents (e.g. `kg/m**3`, `1/m`, `%`).
     Non-canonical forms (`kg/m³`, `kg/m^3`, `kg/m3`) fail with
-    `INVALID_UNITS`. See docs/units.md.
+    `INVALID_UNITS`.
 
     ## Z axis (3D only)
 
@@ -407,7 +407,7 @@ async def asyncio(
     If a data variable has a `units` attribute it must be in canonical
     UDUNITS-2 ASCII form with `**` exponents (e.g. `kg/m**3`, `1/m`, `%`).
     Non-canonical forms (`kg/m³`, `kg/m^3`, `kg/m3`) fail with
-    `INVALID_UNITS`. See docs/units.md.
+    `INVALID_UNITS`.
 
     ## Z axis (3D only)
 

fastfuels_sdk/v2/client_library/api/grids/create_tree_inventory_grid.py

@@ -91,7 +91,7 @@ def sync_detailed(
     ## Request Body
 
     - **source_inventory_id**: (required) ID of a completed tree inventory.
-      Its `x`, `y`, `height`, `dbh`, `crown_ratio` and `fia_species_code`
+      Its `x`, `y`, `height`, `dbh`, `crown_base_height` and `fia_species_code`
       (and any biomass column read) must have no null values; a null
       `fia_status_code` counts as live.
     - **resolution**: (optional) Voxel resolution in meters. Defaults to
@@ -101,8 +101,8 @@ def sync_detailed(
       duplicates. Branchwood and fine bands are accepted by the API, but
       Treevox currently fails those jobs with a not-implemented processing
       error.
-    - **crown_profile_model**: (optional) Crown shape. Every crown runs from
-      the crown base, height × (1 − crown_ratio), to the tree height.
+    - **crown_profile_model**: (optional) Crown shape. Each tree's crown runs
+      from its `crown_base_height` to its height.
       - `purves` (default): Purves et al. (2007), species-specific; widest at
         the crown base.
       - `beta`: species-group beta distribution; widest within the crown, per
@@ -231,7 +231,7 @@ def sync(
     ## Request Body
 
     - **source_inventory_id**: (required) ID of a completed tree inventory.
-      Its `x`, `y`, `height`, `dbh`, `crown_ratio` and `fia_species_code`
+      Its `x`, `y`, `height`, `dbh`, `crown_base_height` and `fia_species_code`
       (and any biomass column read) must have no null values; a null
       `fia_status_code` counts as live.
     - **resolution**: (optional) Voxel resolution in meters. Defaults to
@@ -241,8 +241,8 @@ def sync(
       duplicates. Branchwood and fine bands are accepted by the API, but
       Treevox currently fails those jobs with a not-implemented processing
       error.
-    - **crown_profile_model**: (optional) Crown shape. Every crown runs from
-      the crown base, height × (1 − crown_ratio), to the tree height.
+    - **crown_profile_model**: (optional) Crown shape. Each tree's crown runs
+      from its `crown_base_height` to its height.
       - `purves` (default): Purves et al. (2007), species-specific; widest at
         the crown base.
       - `beta`: species-group beta distribution; widest within the crown, per
@@ -366,7 +366,7 @@ async def asyncio_detailed(
     ## Request Body
 
     - **source_inventory_id**: (required) ID of a completed tree inventory.
-      Its `x`, `y`, `height`, `dbh`, `crown_ratio` and `fia_species_code`
+      Its `x`, `y`, `height`, `dbh`, `crown_base_height` and `fia_species_code`
       (and any biomass column read) must have no null values; a null
       `fia_status_code` counts as live.
     - **resolution**: (optional) Voxel resolution in meters. Defaults to
@@ -376,8 +376,8 @@ async def asyncio_detailed(
       duplicates. Branchwood and fine bands are accepted by the API, but
       Treevox currently fails those jobs with a not-implemented processing
       error.
-    - **crown_profile_model**: (optional) Crown shape. Every crown runs from
-      the crown base, height × (1 − crown_ratio), to the tree height.
+    - **crown_profile_model**: (optional) Crown shape. Each tree's crown runs
+      from its `crown_base_height` to its height.
       - `purves` (default): Purves et al. (2007), species-specific; widest at
         the crown base.
       - `beta`: species-group beta distribution; widest within the crown, per
@@ -504,7 +504,7 @@ async def asyncio(
     ## Request Body
 
     - **source_inventory_id**: (required) ID of a completed tree inventory.
-      Its `x`, `y`, `height`, `dbh`, `crown_ratio` and `fia_species_code`
+      Its `x`, `y`, `height`, `dbh`, `crown_base_height` and `fia_species_code`
       (and any biomass column read) must have no null values; a null
       `fia_status_code` counts as live.
     - **resolution**: (optional) Voxel resolution in meters. Defaults to
@@ -514,8 +514,8 @@ async def asyncio(
       duplicates. Branchwood and fine bands are accepted by the API, but
       Treevox currently fails those jobs with a not-implemented processing
       error.
-    - **crown_profile_model**: (optional) Crown shape. Every crown runs from
-      the crown base, height × (1 − crown_ratio), to the tree height.
+    - **crown_profile_model**: (optional) Crown shape. Each tree's crown runs
+      from its `crown_base_height` to its height.
       - `purves` (default): Purves et al. (2007), species-specific; widest at
         the crown base.
       - `beta`: species-group beta distribution; widest within the crown, per

fastfuels_sdk/v2/client_library/api/inventories/apply_modifications.py

@@ -101,8 +101,8 @@ def sync_detailed(
     clears the inventory of all trees; use it deliberately.
 
     **Attribute conditions** compare a single tree attribute against a value:
-    - `attribute`: one of `dbh`, `height`, `crown_ratio`, `fia_species_code`,
-      `tree_id`
+    - `attribute`: one of `dbh` (cm), `height` (m), `crown_base_height` (m),
+      `fia_species_code`, `tree_id`
     - `operator`: `eq`, `ne`, `gt`, `lt`, `ge`, `le`
       (`fia_species_code` and `tree_id` only support `eq`/`ne`)
     - `value`: number, string, or list for `eq`/`ne`
@@ -115,8 +115,9 @@ def sync_detailed(
 
     **Expression conditions** use a boolean expression:
     - `expression`: e.g., `\"dbh < 5 and height < 2\"`
-    - Only `dbh`, `height`, `crown_ratio` are allowed in expressions
-    - Expressions always use native units (cm, m, 0-1 fraction)
+    - Only `dbh`, `height`, `crown_base_height` are allowed in expressions
+    - Expressions always use native units (`dbh` in cm, `height` and
+      `crown_base_height` in m)
 
     **Spatial conditions** test each tree's location (a point) against a
     geometry. Two variants discriminated by the required `source` field:
@@ -233,8 +234,8 @@ def sync(
     clears the inventory of all trees; use it deliberately.
 
     **Attribute conditions** compare a single tree attribute against a value:
-    - `attribute`: one of `dbh`, `height`, `crown_ratio`, `fia_species_code`,
-      `tree_id`
+    - `attribute`: one of `dbh` (cm), `height` (m), `crown_base_height` (m),
+      `fia_species_code`, `tree_id`
     - `operator`: `eq`, `ne`, `gt`, `lt`, `ge`, `le`
       (`fia_species_code` and `tree_id` only support `eq`/`ne`)
     - `value`: number, string, or list for `eq`/`ne`
@@ -247,8 +248,9 @@ def sync(
 
     **Expression conditions** use a boolean expression:
     - `expression`: e.g., `\"dbh < 5 and height < 2\"`
-    - Only `dbh`, `height`, `crown_ratio` are allowed in expressions
-    - Expressions always use native units (cm, m, 0-1 fraction)
+    - Only `dbh`, `height`, `crown_base_height` are allowed in expressions
+    - Expressions always use native units (`dbh` in cm, `height` and
+      `crown_base_height` in m)
 
     **Spatial conditions** test each tree's location (a point) against a
     geometry. Two variants discriminated by the required `source` field:
@@ -360,8 +362,8 @@ async def asyncio_detailed(
     clears the inventory of all trees; use it deliberately.
 
     **Attribute conditions** compare a single tree attribute against a value:
-    - `attribute`: one of `dbh`, `height`, `crown_ratio`, `fia_species_code`,
-      `tree_id`
+    - `attribute`: one of `dbh` (cm), `height` (m), `crown_base_height` (m),
+      `fia_species_code`, `tree_id`
     - `operator`: `eq`, `ne`, `gt`, `lt`, `ge`, `le`
       (`fia_species_code` and `tree_id` only support `eq`/`ne`)
     - `value`: number, string, or list for `eq`/`ne`
@@ -374,8 +376,9 @@ async def asyncio_detailed(
 
     **Expression conditions** use a boolean expression:
     - `expression`: e.g., `\"dbh < 5 and height < 2\"`
-    - Only `dbh`, `height`, `crown_ratio` are allowed in expressions
-    - Expressions always use native units (cm, m, 0-1 fraction)
+    - Only `dbh`, `height`, `crown_base_height` are allowed in expressions
+    - Expressions always use native units (`dbh` in cm, `height` and
+      `crown_base_height` in m)
 
     **Spatial conditions** test each tree's location (a point) against a
     geometry. Two variants discriminated by the required `source` field:
@@ -490,8 +493,8 @@ async def asyncio(
     clears the inventory of all trees; use it deliberately.
 
     **Attribute conditions** compare a single tree attribute against a value:
-    - `attribute`: one of `dbh`, `height`, `crown_ratio`, `fia_species_code`,
-      `tree_id`
+    - `attribute`: one of `dbh` (cm), `height` (m), `crown_base_height` (m),
+      `fia_species_code`, `tree_id`
     - `operator`: `eq`, `ne`, `gt`, `lt`, `ge`, `le`
       (`fia_species_code` and `tree_id` only support `eq`/`ne`)
     - `value`: number, string, or list for `eq`/`ne`
@@ -504,8 +507,9 @@ async def asyncio(
 
     **Expression conditions** use a boolean expression:
     - `expression`: e.g., `\"dbh < 5 and height < 2\"`
-    - Only `dbh`, `height`, `crown_ratio` are allowed in expressions
-    - Expressions always use native units (cm, m, 0-1 fraction)
+    - Only `dbh`, `height`, `crown_base_height` are allowed in expressions
+    - Expressions always use native units (`dbh` in cm, `height` and
+      `crown_base_height` in m)
 
     **Spatial conditions** test each tree's location (a point) against a
     geometry. Two variants discriminated by the required `source` field: