Copy as Markdown View as Markdown llms.txt

Landuse

Classified Overture land use for a polygon area.

Reads the Overture land_use features over a polygon and maps their free-text classes onto the shared Infrared land-use categories. See infrared_sdk.landuse.service.

OVERTURE_LANDUSE_TYPE module-attribute

OVERTURE_LANDUSE_TYPE = 'land_use'

Name of the Overture collection the land-use read uses ("land_use").

LandUseServiceClient

Bases: ScrubbedSessionState

Client for classified Overture land use.

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. The public data read goes through the shared Overture range reader, and the classification runs in-process.

logger instance-attribute

logger: Logger = logger

Logger the client reports progress to.

base_url instance-attribute

base_url: str = base_url

Base URL accepted for construction compatibility; never contacted.

close

close() -> None

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

get_area

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

Read and classify Overture land use over polygon.

The area is read once: as a single rectangle up to 4 km2, and above that as a grid of roughly 2 x 2 km read chunks, the same shape the ground-material read uses.

There is no partial answer. A read that fails, or a deadline that expires, raises TiledRunError, whose failed_tiles names the chunks. A land-use answer covering an unknown part of the polygon would be indistinguishable from one covering all of it, and the categories would be silently wrong rather than visibly absent.

The one failure that is not wrapped is GeodataDependencyError: a missing optional [geodata] extra is an install problem, not a failed read, and it reaches your own except clause unchanged.

Parameters:

Name	Type	Description	Default
polygon	dict	GeoJSON Polygon.	required
timeout	int	Per-request budget in seconds (default 60), trimmed to what is left of total_timeout.	60
total_timeout	int	Wall-clock deadline over the whole read, in seconds (default 600).	600
max_workers	int	Accepted for signature compatibility with the sibling area reads and has no effect: the Overture read is one scan over the area, so there is nothing to run in parallel.	10
overture_release	str	Pin the read to an Overture release. The public index pointer moves daily; pass back AreaLandUse.overture_release to reproduce a run.	None
analysis_type	str	The analysis the read margin follows. None reads the widest margin, which is valid for every analysis.	None
on_progress	callable	Called once per chunk read, with a TileProgress.	None
max_tiles_override	int	Raise the tile ceiling for the grid that fixes the read rectangles.	None

Returns:

Type	Description
AreaLandUse	The classified FeatureCollection and what the classification saw.

Raises:

Type	Description
PolygonValidationError	If polygon is not a valid GeoJSON Polygon, if the grid it needs exceeds the tile ceiling, or if max_tiles_override is not a non-negative integer.
TiledRunError	If the read fails or total_timeout expires.
GeodataDependencyError	If the optional [geodata] extra is not installed.

AreaLandUse dataclass

Classified Overture land use for a polygon area.

features instance-attribute

features: dict

GeoJSON FeatureCollection. Each feature carries name, overture_class (the source spelling, kept so you can audit the mapping) and category, one of the shared Infrared land-use categories.

polygon instance-attribute

polygon: dict

The input GeoJSON polygon.

total_features instance-attribute

total_features: int

Land-use features READ, before classification.

categorized instance-attribute

categorized: int

Features that survived into features. Below total_features when a feature carried no usable geometry: those are dropped. The difference is the loss, and it is reported rather than left to be inferred from two lengths.

category_counts class-attribute instance-attribute

category_counts: Dict[str, int] = field(default_factory=dict)

Feature count per category, over features. A category with no features is absent rather than zero.

unmapped_classes class-attribute instance-attribute

unmapped_classes: List[str] = field(default_factory=list)

Source class/subtype spellings the category table did not know, sampled. The list is capped, so it is evidence that something is unmapped, never a complete inventory. Every such feature still appears in features, under the fallback category.

execution_time class-attribute instance-attribute

execution_time: float = 0.0

Wall-clock seconds for the read and the classification.

overture_release class-attribute instance-attribute

overture_release: Optional[str] = None

Overture Maps release the features were read from. The public index pointer moves daily, so the same polygon can otherwise classify differently on two days with no signal to the caller; pass the value back as overture_release= to pin a later run. Several releases are joined with ", " on the rare run that straddles a refresh.

read_margin_m class-attribute instance-attribute

read_margin_m: Optional[float] = None

Half extent, in metres, of the rectangle the area was read with. It is the same margin the ground-material read uses, because both read the same Overture land_use rows.

analysis_type class-attribute instance-attribute

analysis_type: Optional[str] = None

The analysis type the read margin was taken from. None on results built by hand, which make no claim.