Copy as Markdown View as Markdown llms.txt

Vegetation

Vegetation (tree) service client and types.

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

close() -> None

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

convert_to_mesh

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

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. Tiles that failed are listed in failed_tiles.

Raises:

Type	Description
PolygonValidationError	If the polygon is invalid, or max_tiles_override is not a non-negative integer.
TiledRunError	If every tile fails.
TypeError	If the removed acquisition argument is passed.

AreaVegetation dataclass

Result of vegetation fetch for a polygon area.

features instance-attribute

features: Dict[str, dict]

Tree GeoJSON features keyed by dedup key.

polygon instance-attribute

polygon: dict

The input GeoJSON polygon.

total_trees instance-attribute

total_trees: int

Number of unique trees after deduplication.

execution_time instance-attribute

execution_time: float

Wall-clock seconds for the full fetch pipeline.

failed_tiles class-attribute instance-attribute

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

Per-tile failure records (tile_id, row, col, error) for tiles that failed after all retries; empty when every tile succeeded. Use len(area.failed_tiles) to detect partial-coverage results. Mirrors AreaBuildings.failed_tiles.

read_margin_m class-attribute instance-attribute

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

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.