Vegetation state and treatment contract
The state contract carries the vegetation state, the treatment actions, the treatment transitions, and
the observations. The schema version is brushline.state.v1. The contract is validated by
brushline.model.state.validate_state_contract().
Objects
Object |
Meaning |
|---|---|
|
One functional group’s state on one segment in one year, with height, cover, density, biomass, age, uncertainty, treatment history, and provenance. |
|
Standard deviations and a confidence value for the state. |
|
A planned, applied, or cancelled treatment with a method, season, intensity, efficacy, cost hooks, and status. |
|
The before-and-after state of a treatment, with the method, efficacy, regrowth delay, and source. |
|
A remote or field observation with a sensor, date, product, coverage, error, model card, and provenance. |
Functional groups and classes
Functional groups: unknown, shrub, deciduous_sprout, conifer, grass_herb.
State classes: unknown, partial, grass_herb, shrub, young_tree, mixed,
mature_edge.
An unknown state uses the unknown functional group and zero height and cover. A known state
must name a functional group. A partial state is allowed and is reported as a warning.
Treatment methods and sensors
Treatment methods: manual, mechanical, chemical, mowing, grazing,
prescribed_fire, other.
Seasons: spring, summer, fall, winter, any.
Sensors: lidar, uav_lidar, imagery, field, inspection, other.
Invariants
The models and the validator check:
the state key
(segment_id, state_year, functional_group)is unique;height and density are non-negative; cover is between 0 and 100;
an unknown state is empty and uses the unknown group;
a known state names a functional group;
years are between 1900 and 2200;
a treatment action’s intensity and efficacy are between 0 and 1;
a treatment transition does not increase height or cover;
an observation’s coverage is between 0 and 100 and its errors are non-negative;
every treatment, transition, and observation references a segment with a state;
every required segment has at least one state;
partial states, low confidence, partial coverage, and long regrowth delays are warnings.
Named errors use the prefixes STATE-ID, STATE-REF, and STATE-MISSING. Named warnings use
STATE-PARTIAL, STATE-UNCERTAIN, STATE-COVERAGE, and STATE-DELAY.
Example
{
"schema_version": "brushline.state.v1",
"states": [
{
"segment_id": "s1",
"state_year": 2026,
"functional_group": "shrub",
"state_class": "shrub",
"height_m": 2.0,
"cover_pct": 50.0,
"density_per_ha": 1200.0,
"age_years": 3,
"uncertainty": {"height_m_sd": 0.2, "cover_pct_sd": 5.0, "confidence": 0.9},
"source": "synthetic",
"source_version": "1.0"
}
],
"treatments": [
{
"action_id": "a1",
"segment_id": "s1",
"year": 2026,
"season": "summer",
"method": "mowing",
"intensity": 0.8,
"efficacy": 0.7,
"cost_per_ha": 1200.0,
"status": "applied"
}
],
"transitions": [
{
"transition_id": "t1",
"segment_id": "s1",
"year": 2026,
"method": "mowing",
"before_height_m": 2.0,
"after_height_m": 0.5,
"before_cover_pct": 50.0,
"after_cover_pct": 10.0,
"efficacy": 0.75,
"regrowth_delay_years": 2,
"source": "synthetic"
}
],
"observations": [
{
"observation_id": "o1",
"segment_id": "s1",
"observed_date": "2026-07-01",
"sensor": "lidar",
"product": "CHM",
"coverage_pct": 100.0,
"height_m": 2.0,
"cover_pct": 50.0,
"height_error_m": 0.2,
"cover_error_pct": 5.0,
"source": "synthetic",
"source_version": "1.0"
}
]
}
Python use
from pathlib import Path
from brushline.model.state import StateContract, validate_state_contract
contract = StateContract.model_validate_json(Path("state.json").read_text())
report = validate_state_contract(contract, required_segment_ids={"s1", "s2"})
if not report.is_valid:
raise SystemExit("\n".join(report.errors))