Ground materials

acquireGroundMaterials

Import from @infrared-city/infrared-sdk-ts/geodata.

acquireGroundMaterials(bbox, options?): Promise<DirectGroundResult>

Read and compose ground materials for an area, returning parsed layers.

The same composition as acquireGroundMaterialsJson, parsed once for a caller that wants objects.

Parameters

Parameter	Type	Description
`bbox`	`Bbox`	The area's bounding box in WGS84 degrees.
`options`	`AcquireGroundOptions`	Read and frame options.

Returns

Promise<DirectGroundResult>

The layers, the total feature count and the Overture release.

Throws

when the optional parquet reader packages are not installed.

Throws

when a data URL is not on the allow-list.

acquireGroundMaterialsArea

Import from @infrared-city/infrared-sdk-ts/geodata.

acquireGroundMaterialsArea(site, options): Promise<GroundAreaResult>

Read, compose, merge and clean the ground materials of a whole site.

The site is read in chunks of about 2 x 2 km (one rectangle below 4 km2), each with its own road read and a shared Overture read of the site. The chunks are then composed, merged and cleaned in a single step, so no per-tile documents exist. If any chunk fails to read the whole call fails.

Parameters

Parameter	Type	Description
`site`	`Bbox`	The site's bounding box in WGS84 degrees.
`options`	`AcquireGroundAreaOptions`	Cleaning extent, optional tile rectangles and read options.

Returns

Promise<GroundAreaResult>

The merged layers as JSON text, the Overture release and the chunks.

Throws

when one or more chunks cannot be read; it names every failed chunk.

Throws

when the optional parquet reader packages are not installed.

acquireGroundMaterialsJson

Import from @infrared-city/infrared-sdk-ts/geodata.

acquireGroundMaterialsJson(bbox, options?): Promise<AcquireGroundJson>

Read and compose ground materials for an area, returning JSON text.

Reads OSM roads and the Overture base themes for the bounding box and composes them into material layers, clipped to the box. The result is left unparsed so it can be passed on without building objects.

Parameters

Parameter	Type	Description
`bbox`	`Bbox`	The area's bounding box in WGS84 degrees.
`options`	`AcquireGroundOptions`	Read and frame options.

Returns

Promise<AcquireGroundJson>

The composed {material: FeatureCollection} JSON text and the Overture release it came from.

Throws

when the optional parquet reader packages are not installed.

Throws

when a data URL is not on the allow-list.

AreaGroundMaterials

Import from @infrared-city/infrared-sdk-ts.

The ground materials read for a polygon area, from GroundMaterialsService.getArea. Pass it as groundMaterials to runArea.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis the read margin was taken from.
`executionTime`	`readonly`	`number`	How long the read took, in seconds.
`failedTiles`	`readonly`	readonly `string`[]	Tiles that could not be read. Always empty: a site is read as a whole, so it succeeds or fails as one.
`layers`	`readonly`	`MaterialLayers`	The cleaned material layers, by layer name; empty when the polygon has no tiles to read.
`overtureRelease?`	`readonly`	`string`	Overture release this area was read from. The index pointer moves daily, so a result without it is not reproducible; pass it back as `overtureRelease` to pin the read.
`polygon`	`readonly`	`Polygon`	The polygon the materials were read for.
`readMarginM`	`readonly`	`number`	Half extent, in metres, of the rectangle every tile was read with: 363 for the wind analyses and 544 for the others. `runArea` refuses a run whose analysis needs a larger margin than this.
`totalFeatures`	`readonly`	`number`	The number of features across all layers.

cleanV3Local

Import from @infrared-city/infrared-sdk-ts.

cleanV3Local(layers, params): MaterialLayers

Clean ground materials locally, using the initialized Infrared core.

The layers are cropped to params.distance metres around the point, stacked by material precedence rather than by the order of the keys in layers, and given a vertical offset per layer. An undefined zStep selects the default of 0.05 m. Cleaning the result a second time keeps the same material classification.

initializeCore() must have completed before you call it. The layers are serialized to JSON text and the result parsed back, so very large inputs cost one serialization and one parse.

Parameters

Parameter	Type	Description
`layers`	`MaterialLayers`	Material name to GeoJSON feature collection (WGS84 degrees).
`params`	`CleanV3Params`	The centre point, crop distance and layer options.

Returns

MaterialLayers

The cleaned layers, keyed by material name.

CleanV3Params

Import from @infrared-city/infrared-sdk-ts.

Parameters for cleaning ground-material layers around a point.

Properties

Property	Type	Description
`defaultLayer?`	`string`	Name of the default (background) material layer.
`distance`	`number`	Distance from the centre point to the edge of the cropped area, in metres.
`latitude`	`number`	Latitude of the centre point, in degrees.
`longitude`	`number`	Longitude of the centre point, in degrees.
`zStep?`	`number`	Vertical step between stacked material layers, in metres. Defaults to `0.05`.

FeatureCollection

Import from @infrared-city/infrared-sdk-ts.

A GeoJSON feature collection, as accepted by the ground-material cleaner.

Indexable

[key: string]: unknown

Properties

Property	Type	Description
`features?`	`Record`<`string`, `unknown`>[]	The GeoJSON features (polygons in WGS84 degrees).
`type?`	`string`	The GeoJSON type, normally `"FeatureCollection"`.

GroundMaterialCleaner

Import from @infrared-city/infrared-sdk-ts.

An asynchronous ground-material cleaner. Implement it to replace the built-in local cleaner.

Methods

cleanV3()

cleanV3(layers, params): Promise<MaterialLayers>

Clean the layers around the point given in params.

Parameters

Parameter	Type	Description
`layers`	`MaterialLayers`	Material name to GeoJSON feature collection.
`params`	`CleanV3Params`	The centre point, crop distance and layer options.

Returns

Promise<MaterialLayers>

The cleaned layers.

GroundMaterialsCleaner

Import from @infrared-city/infrared-sdk-ts.

GroundMaterialsCleaner = GroundMaterialCleaner

A cleaner of your own for the cleaner option of getArea: an object implementing GroundMaterialCleaner. Leave the option unset to clean with the SDK's built-in cleaner.

GroundMaterialsService

Import from @infrared-city/infrared-sdk-ts.

Reads the ground materials (roads, water, parks and so on) around a point or a polygon from the public data hosts. Available as InfraredClient.groundMaterials.

Constructors

Constructor

new GroundMaterialsService(options): GroundMaterialsService

Creates the service from the client's transport settings (fetch, timeout and logger).

Parameters

Parameter	Type
`options`	`ServiceOptions`

Returns

GroundMaterialsService

Methods

getArea()

getArea(polygon, options?): Promise<AreaGroundMaterials>

Reads the material layers for a whole polygon area and cleans them, ready to pass to runArea as groundMaterials. Which tiles are read, and how far around each, follows the analysis (options.analysisType).

Parameters

Parameter	Type	Description
`polygon`	`Polygon`	The GeoJSON polygon to cover.
`options`	{ `analysisType?`: `string`; `cleaner?`: `GroundMaterialCleaner`; `defaultMaterial?`: `string`; `maxTilesOverride?`: `number`; `maxWorkers?`: `number`; `overtureRelease?`: `string`; `signal?`: `AbortSignal`; `zStep?`: `number`; }	Read options; see each field.
`options.analysisType?`	`string`	The analysis this read is for. It decides the tile grid and the read margin: 363 m for the two wind analyses and 544 m for every other one, which needs shadow casters further out. Omit it for the widest margin, which is valid for every analysis.
`options.cleaner?`	`GroundMaterialCleaner`	A cleaner of your own; unset uses the built-in cleaner.
`options.defaultMaterial?`	`string`	The name of the background material layer; a built-in default when unset.
`options.maxTilesOverride?`	`number`	Raises the limit on how many non-empty tiles the polygon may cover.
`options.maxWorkers?`	`number`	The most data chunks read at the same time; it can lower the built-in limit, not raise it.
`options.overtureRelease?`	`string`	Pin the Overture release this read uses.
`options.signal?`	`AbortSignal`	Aborts the read.
`options.zStep?`	`number`	The vertical step between stacked material layers, in metres. Default 0.05.

Returns

Promise<AreaGroundMaterials>

The AreaGroundMaterials, with empty layers when the polygon has no tiles to read.

Throws

when the removed acquisition option is passed.

getRaw()

getRaw(lat, lon, distance): Promise<MaterialLayers | null>

Reads the material layers of one square tile around a point.

Parameters

Parameter	Type	Description
`lat`	`number`	Centre latitude in degrees.
`lon`	`number`	Centre longitude in degrees.
`distance`	`number`	Half-width of the tile in metres.

Returns

Promise<MaterialLayers | null>

The layers, or null when the tile has no material at all.

LocalCleaner

Import from @infrared-city/infrared-sdk-ts.

A GroundMaterialCleaner that cleans locally with cleanV3Local.

Implements

GroundMaterialCleaner

Constructors

Constructor

new LocalCleaner(): LocalCleaner

Returns

LocalCleaner

Methods

cleanV3()

cleanV3(layers, params): Promise<MaterialLayers>

Clean the layers locally. Equivalent to calling cleanV3Local.

Parameters

Parameter	Type	Description
`layers`	`MaterialLayers`	Material name to GeoJSON feature collection.
`params`	`CleanV3Params`	The centre point, crop distance and layer options.

Returns

Promise<MaterialLayers>

The cleaned layers.

Implementation of

GroundMaterialCleaner.cleanV3

MaterialLayers

Import from @infrared-city/infrared-sdk-ts.

MaterialLayers = Record<string, FeatureCollection>

Ground material name to GeoJSON feature collection.

roadsToIrFeatures

Import from @infrared-city/infrared-sdk-ts/geodata.

roadsToIrFeatures(features): Record<string, unknown>[]

Normalise road features read from the FlatGeobuf file into the shape the ground composer takes as input.

Use this when you already hold feature objects. The acquisition functions do not call it; they pass the road data on as text.

The id of a road comes from its @id property only. surface and lanes are read from the feature's own properties, where the world file does not carry them, so every road composes as asphalt.

Parameters

Parameter	Type	Description
`features`	readonly `Record`<`string`, `unknown`>[]	Road features as read from the world FlatGeobuf file.

Returns

Record<string, unknown>[]

The normalised road features.