Vegetation, Python SDK reference

Provides VegetationServiceClient for fetching and deduplicating tree data from the Infrared API, and the AreaVegetation result type.

VegetationServiceError

Bases: Exception

A vegetation operation failed in a way the caller must see.

Raised by the mesh converter and the direct tree acquisition when their input is malformed or an operation fails.

VegetationServiceClient

Bases: ScrubbedSessionState

Client for vegetation (tree) data read from the public sources.

api_key, base_url, gateway_base_url and telemetry are accepted for construction compatibility with the other service clients and are unused: this client sends no request of its own. It can be used as a context manager.

Parameters:

Name	Type	Description	Default
`api_key`	`str`	API key. Accepted for compatibility and unused.	required
`logger`	`Logger`	Logger that receives progress and warning messages.	required
`base_url`	`str`	Service base URL. Accepted for compatibility and unused.	required
`gateway_base_url`	`str`	Gateway base URL. Accepted for compatibility and unused.	`None`
`telemetry`	`Telemetry`	Telemetry settings. Accepted for compatibility and unused.	`None`
`converter`	`object`	Removed. Passing any value raises `TypeError`.	`REMOVED`
`acquisition`	`object`	Removed. Passing any value raises `TypeError`.	`REMOVED`

Attributes:

Name	Type	Description
`logger`	`Logger`	Logger that receives progress and warning messages.
`base_url`	`str`	Service base URL, as given at construction.

close

Python

close() -> None

Release the client's resources. Kept for API compatibility.

convert_to_mesh

Python

convert_to_mesh(
feature_collection: dict, *, converter: Any = REMOVED
) -> List[dict]

Convert GeoJSON tree points to DotBim meshes.

Parameters:

Name	Type	Description	Default
`feature_collection`	`dict`	GeoJSON FeatureCollection with a `referencePoint` field `[lon, lat]` used as the metric coordinate origin.	required
`converter`	`object`	Removed. Passing any value raises `TypeError`.	`REMOVED`

Returns:

Type	Description
`list[dict]`	DotBim mesh dicts (`mesh_id`, `coordinates`, `indices`).

Raises:

Type	Description
`VegetationServiceError`	On malformed input, a conversion error, or an SDK installation whose bundled conversion code does not match the SDK version. The method never returns an empty list in place of a failure.
`TypeError`	If the removed `converter` argument is passed.

get_area

Python

get_area(
polygon: dict,
*,
max_workers: int = 10,
timeout: int = 60,
total_timeout: int = 600,
on_progress: Optional[Callable[[TileProgress], None]] = None,
max_tiles_override: Optional[int] = None,
analysis_type: Optional[str] = None,
acquisition: Any = REMOVED,
) -> AreaVegetation

Read and deduplicate vegetation for a polygon area.

Tiles the polygon, range-reads the public world FlatGeobuf and any city overlay per tile in parallel, and deduplicates across overlapping tiles. Returns GeoJSON features (no DotBim conversion).

Parameters:

Name	Type	Description	Default
`polygon`	`dict`	GeoJSON Polygon.	required
`max_workers`	`int`	Maximum number of parallel threads.	`10`
`timeout`	`int`	Per-tile timeout, in seconds.	`60`
`total_timeout`	`int`	Total wall-clock timeout, in seconds.	`600`
`on_progress`	`callable`	Progress callback `(TileProgress) -> None`.	`None`
`max_tiles_override`	`int`	Override the default maximum number of non-empty tiles.	`None`
`analysis_type`	`str`	The analysis this acquisition is for. It decides the tile grid and the read margin, `ceil(sqrt(2) * context_size_m / 2)` for the analysis: 363 m for the two wind analyses and 544 m for every other one. Omit it for the widest margin, valid for every analysis.	`None`
`acquisition`	`object`	Removed. Passing any value raises `TypeError`.	`REMOVED`

Returns:

Type	Description
`AreaVegetation`	Deduplicated GeoJSON tree features. `failed_tiles` is always empty: a failed tile raises.

Raises:

Type	Description
`PolygonValidationError`	If the polygon is invalid, or `max_tiles_override` is not a non-negative integer.
`TiledRunError`	If any tile fails (`failed_tiles` row-major, the first error as `__cause__`), as `buildings.get_area` and `ground_materials.get_area` do.
`TypeError`	If the removed `acquisition` argument is passed.

AreaVegetation dataclass

Result of vegetation fetch for a polygon area.

features instance-attribute

Python

features: Dict[str, dict]

Tree GeoJSON features keyed by dedup key.

polygon instance-attribute

Python

polygon: dict

The input GeoJSON polygon.

total_trees instance-attribute

Python

total_trees: int

Number of unique trees after deduplication.

execution_time instance-attribute

Python

execution_time: float

Wall-clock seconds for the full fetch pipeline.

failed_tiles class-attribute instance-attribute

Python

failed_tiles: List[Dict[str, Any]] = field(default_factory=list)

Always empty since a failed tile raises TiledRunError (as on the buildings and ground paths). Kept so code that reads it keeps working.

read_margin_m class-attribute instance-attribute

Python

read_margin_m: Optional[float] = None

Half extent, in metres, of the read rectangle every tile was fetched with — ceil(sqrt(2) * context_size_m / 2) for analysis_type (363 m wind, 544 m otherwise). run_area refuses a run whose analysis needs more than this.

analysis_type class-attribute instance-attribute

Python

analysis_type: Optional[str] = None

The analysis type the read margin was taken from. None on features built by hand, which make no claim and are never refused.