Buildings

acquireBuildings

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

acquireBuildings(bbox, options?): Promise<DirectBuildingsResult>

Read building footprints for an area, parsed into feature objects.

The same read as acquireBuildingsJson, parsed once for a caller that wants feature objects.

Parameters

Parameter	Type	Description
`bbox`	`Bbox`	The area to read, in WGS84 degrees.
`options`	`AcquireBuildingsOptions`	Read options.

Returns

Promise<DirectBuildingsResult>

The footprint features, the source, any warnings and the Overture release.

Throws

when the planned Overture read exceeds the byte limit.

Throws

when Overture must be read and the optional parquet packages are not installed.

acquireBuildingsArea

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

acquireBuildingsArea(site, options): Promise<BuildingsAreaResult>

Read and extrude every building footprint of one site, in one frame.

A registered city overlay is used when one covers the site, otherwise the global Overture building layer. The site is read once and extruded once, so every mesh shares the origin in BuildingsAreaResult.origin.

Parameters

Parameter	Type	Description
`site`	`Bbox`	The site rectangle, in WGS84 degrees.
`options`	`AcquireBuildingsAreaOptions`	Read options; `defaultHeightM` is required.

Returns

Promise<BuildingsAreaResult>

The building meshes keyed by id, the frame origin, the source and any warnings.

Throws

when the planned Overture read exceeds the byte limit.

Throws

when Overture must be read and the optional parquet packages are not installed.

AcquireBuildingsAreaOptions

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

Options for acquireBuildingsArea.

Extends AcquireBuildingsOptions. The whole site is read once and extruded in one local frame, so there is no concurrency option.

Extends

AcquireBuildingsOptions

Properties

Property	Modifier	Type	Description	Inherited from
`bestAvailable?`	`readonly`	`boolean`	Set `false` to read the global Overture layer even inside a registered city. By default a registered city's own footprints are used when one covers the area.	`AcquireBuildingsOptions`.`bestAvailable`
`budget?`	`readonly`	`PlannedBudget`	The byte budget of the call this read belongs to. An area read of several ground layers passes one budget to all of them, so the limit covers the whole call rather than each layer. A read with no budget makes its own.	`AcquireBuildingsOptions`.`budget`
`candidateBufferDeg?`	`readonly`	`number`	Extra margin, in degrees, added around the area when choosing which files to read. It never changes which features are returned. A file whose recorded bounding box stops just short of the area is still considered. Features are still filtered against the exact area, so the margin costs at most one extra file read.	`AcquireBuildingsOptions`.`candidateBufferDeg`
`defaultHeightM`	`readonly`	`number`	Default extrusion height, in metres, for a footprint that carries none.	-
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`AcquireBuildingsOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`AcquireBuildingsOptions`.`logger`
`maxFiles?`	`readonly`	`number`	Maximum number of parquet files to read. A read that matches more files fails with an `OvertureFileLimitError` instead of returning a partial answer. A guard for very large areas.	`AcquireBuildingsOptions`.`maxFiles`
`maxPlannedBytes?`	`readonly`	`number`	Compressed bytes this read may plan, when it makes its own budget. Defaults to the runtime's ceiling. A larger plan fails with an `OvertureReadTooLargeError`.	`AcquireBuildingsOptions`.`maxPlannedBytes`
`overtureRelease?`	`readonly`	`string`	Pin the Overture release, e.g. `"2026-08-19.0"`. Without a pin the latest release is used, which is refreshed daily, so the same area read on two days can return different data. A pinned release is reproducible.	`AcquireBuildingsOptions`.`overtureRelease`
`rectangles?`	`readonly`	readonly `Bbox`[]	The simulation-tile query rectangles whose union is the site rectangle. They decide two things: whether the site has one building source (a site whose rectangles resolve to different sources is read rectangle by rectangle), and which parts of the site are extruded, so a long, narrow site does not extrude the empty corners of its bounding box. When omitted, the site rectangle stands for itself.	-
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`AcquireBuildingsOptions`.`signal`
`stallTimeoutMs?`	`readonly`	`number`	How long one attempt of a retried read may receive no data before it is aborted and asked again. Defaults to `STALL_TIMEOUT_MS`.	`AcquireBuildingsOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	`AcquireBuildingsOptions`.`timeoutMs`
`transport?`	`readonly`	`RangeTransport`	Byte reader; defaults to HTTP range requests. Tests can serve bytes from memory. Pass one instance for a whole area: it carries the object-size cache, and a fresh one per tile re-learns every object's size.	`AcquireBuildingsOptions`.`transport`

acquireBuildingsJson

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

acquireBuildingsJson(bbox, options?): Promise<DirectBuildingsJson>

Read building footprints for an area straight from the public data hosts, as GeoJSON text.

A registered city's footprint layer is used when one covers the area, otherwise Overture's building layer. The text is returned unparsed so it can be passed straight on; use acquireBuildings for parsed features.

Parameters

Parameter	Type	Description
`bbox`	`Bbox`	The area to read, in WGS84 degrees.
`options`	`AcquireBuildingsOptions`	Read options.

Returns

Promise<DirectBuildingsJson>

The footprints as FeatureCollection text, the source, any warnings and the Overture release.

Throws

when the planned Overture read exceeds the byte limit.

Throws

when Overture must be read and the optional parquet packages are not installed.

AcquireBuildingsOptions

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

Options for acquireBuildings and acquireBuildingsJson.

Combines the FlatGeobuf read options and the Overture read options.

Extends

ReadFgbOptions.ReadOvertureOptions

Extended by

AcquireBuildingsAreaOptions

Properties

Property	Modifier	Type	Description	Inherited from
`bestAvailable?`	`readonly`	`boolean`	Set `false` to read the global Overture layer even inside a registered city. By default a registered city's own footprints are used when one covers the area.	-
`budget?`	`readonly`	`PlannedBudget`	The byte budget of the call this read belongs to. An area read of several ground layers passes one budget to all of them, so the limit covers the whole call rather than each layer. A read with no budget makes its own.	`ReadOvertureOptions`.`budget`
`candidateBufferDeg?`	`readonly`	`number`	Extra margin, in degrees, added around the area when choosing which files to read. It never changes which features are returned. A file whose recorded bounding box stops just short of the area is still considered. Features are still filtered against the exact area, so the margin costs at most one extra file read.	`ReadOvertureOptions`.`candidateBufferDeg`
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`ReadFgbOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`ReadFgbOptions`.`logger`
`maxFiles?`	`readonly`	`number`	Maximum number of parquet files to read. A read that matches more files fails with an `OvertureFileLimitError` instead of returning a partial answer. A guard for very large areas.	`ReadOvertureOptions`.`maxFiles`
`maxPlannedBytes?`	`readonly`	`number`	Compressed bytes this read may plan, when it makes its own budget. Defaults to the runtime's ceiling. A larger plan fails with an `OvertureReadTooLargeError`.	`ReadOvertureOptions`.`maxPlannedBytes`
`overtureRelease?`	`readonly`	`string`	Pin the Overture release, e.g. `"2026-08-19.0"`. Without a pin the latest release is used, which is refreshed daily, so the same area read on two days can return different data. A pinned release is reproducible.	`ReadOvertureOptions`.`overtureRelease`
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`ReadFgbOptions`.`signal`
`stallTimeoutMs?`	`readonly`	`number`	How long one attempt of a retried read may receive no data before it is aborted and asked again. Defaults to `STALL_TIMEOUT_MS`.	`ReadFgbOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	`ReadFgbOptions`.`timeoutMs`
`transport?`	`readonly`	`RangeTransport`	Byte reader; defaults to HTTP range requests. Tests can serve bytes from memory. Pass one instance for a whole area: it carries the object-size cache, and a fresh one per tile re-learns every object's size.	`ReadFgbOptions`.`transport`

AreaBuildings

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

Buildings read for an area, as dotbim meshes keyed by building.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis type the read margin was taken from.
`buildingIds`	`readonly`	readonly `number`[]	Always an empty array: the public sources this service reads carry no building ids.
`buildings`	`readonly`	`Readonly`<`Record`<`string`, `DotBimMesh`>>	The building meshes, keyed by building id.
`executionTime`	`readonly`	`number`	Time the read took, in seconds.
`failedTiles`	`readonly`	readonly `string`[]	Always empty: the site is read as one request, which succeeds or fails as a whole.
`origin`	`readonly`	readonly [`number`, `number`]	`[lon, lat]` the meshes are framed around: the polygon's south-west corner. The whole area is extruded once, in this one frame, so the meshes render as one consistent site. When you submit them in a run, each simulation tile receives them re-anchored into its own frame.
`overtureRelease?`	`readonly`	`string`	Overture release this read used, absent when a city overlay supplied the footprints.
`readMarginM`	`readonly`	`number`	Half extent, in metres, of the read rectangle every tile was fetched with: 256 for the wind analyses and 384 for the others. `runArea` refuses a run whose analysis needs more than this.
`skippedFootprints?`	`readonly`	readonly `object`[]	Footprints that could not be extruded, with their geometry type. A non-empty list means those buildings are missing from `buildings`.
`totalBuildings`	`readonly`	`number`	Number of buildings in `buildings`.
`warnings`	`readonly`	readonly `string`[]	What the read degraded, as human-readable warnings. Empty when nothing degraded. `<city>_overlay_unavailable` means a registered city's high-fidelity footprints could not be read and the whole site fell back to Overture, a visible drop in building quality for the whole area. A city registry that could not be reached adds its own warning the same way. The same warnings are also sent to the client's `logger.warn`, so a caller who does not read this field is still told.

BuildingsAreaResult

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

Footprints read for a whole site and extruded into one frame.

Properties

Property	Modifier	Type	Description
`buildings`	`readonly`	`Record`<`string`, `Record`<`string`, `unknown`>>	Building meshes keyed by building id, in the site frame, extruded once.
`origin`	`readonly`	readonly [`number`, `number`]	The frame the meshes are in: the site rectangle's south-west corner, `[lon, lat]`.
`overtureRelease`	`readonly`	`string`	Overture release the footprints came from, or `""` when Overture was not read.
`source`	`readonly`	`string`	Which source answered for the site; several sources are joined with `+`.
`warnings`	`readonly`	readonly `string`[]	Degradations the caller should surface, such as an unavailable city overlay.

BuildingsConfig

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

Options for BuildingsService.getBuildingsInArea.

Properties

Property	Modifier	Type	Description
`analysisType?`	`readonly`	`string`	The analysis this read is for. It decides the tile grid and the read margin: 256 m for the two wind analyses and 384 m for every other one, which needs the shadow casters further out. Omit it for the widest margin, which is valid for every analysis.
`maxTilesOverride?`	`readonly`	`number`	Raises the cap on non-empty tiles (100 by default); a larger area is refused without it.
`maxWorkers?`	`readonly`	`number`	Accepted for compatibility; it changes nothing. The site's footprints are fetched in one read, so there is no per-tile fan-out left for it to bound. Passing it is neither refused nor honoured: the call keeps working and returns the same answer.
`overtureRelease?`	`readonly`	`string`	Pin the Overture release this read uses.
`signal?`	`readonly`	`AbortSignal`	Aborts the whole site read, not just one request.

BuildingsService

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

Reads building footprints for an area from the public data hosts and extrudes them locally into dotbim meshes.

The service takes only the transport settings of ServiceOptions (fetch, timeoutMs, logger) and sends no API key anywhere. buildingIds is always an empty array, because the public sources carry no building ids.

Constructors

Constructor

new BuildingsService(options): BuildingsService

Parameters

Parameter	Type	Description
`options`	`ServiceOptions`	Transport settings: `fetch`, `timeoutMs` and `logger` are used for the public reads; `baseUrl` and `auth` are accepted but not used.

Returns

BuildingsService

Methods

getBuildingsInArea()

getBuildingsInArea(polygon, options?): Promise<AreaBuildings>

Reads and extrudes the buildings of a polygon area.

The footprints are read once for the whole site and extruded in one frame, returned as origin. The read margin follows options.analysisType.

Parameters

Parameter	Type	Description
`polygon`	`Polygon`	The area to read: a GeoJSON `Polygon` with one closed ring of `[longitude, latitude]` positions.
`options`	`BuildingsConfig`	Optional read settings; see `BuildingsConfig`.

Returns

Promise<AreaBuildings>

The meshes keyed by building id, with the read's frame, margin and any warnings.

Throws

when options carries a removed option (acquisition, compress, optimizations or outputFormat).

CleanedMesh

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

The result of cleanMesh.

Properties

Property	Modifier	Type	Description
`coordinates`	`readonly`	`Float32Array`<`ArrayBufferLike`> \| `Float64Array`<`ArrayBufferLike`>	Flat `[x, y, z, ...]`, in the input's precision.
`indices`	`readonly`	`Uint32Array`	Flat triangle indices.
`report`	`readonly`	`MeshCleanReport`	What was done. When nothing changed, the input arrays are returned as they are.

cleanMesh

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

cleanMesh(coordinates, indices): CleanedMesh

Cleans one mesh the way analyses clean each building.

Vertices at bit-identical positions are joined (-0.0 equals +0.0, no tolerance), degenerate and exact duplicate triangles are dropped, the winding is made consistent (the authored majority wins), and closed parts are turned outward. An open part keeps its authored direction.

Clean each building on its own: two objects that touch must stay apart.

Parameters

Parameter	Type	Description
`coordinates`	`Float32Array`<`ArrayBufferLike`> \| `Float64Array`<`ArrayBufferLike`> \| `ArrayLike`<`number`>	Flat vertex coordinates `[x, y, z, ...]`. A `Float64Array` stays double precision; any other input is converted to single precision.
`indices`	`ArrayLike`<`number`> \| `Uint32Array`<`ArrayBufferLike`>	Flat triangle vertex indices.

Returns

CleanedMesh

The cleaned coordinates and indices, and a report of what changed.

Throws

for a non-finite coordinate or an index out of range.

Throws

for an index that is not a whole number in 0..2**32-1; an index is never truncated or wrapped into another triangle.

DirectBuildingsJson

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

Building footprints read for an area, as GeoJSON FeatureCollection text.

Properties

Property	Modifier	Type	Description
`collectionJson`	`readonly`	`string`	The normalised footprints as GeoJSON FeatureCollection text.
`overtureRelease`	`readonly`	`string`	Overture release the footprints came from, or `""` when Overture was not read.
`source`	`readonly`	`string`	Which source answered: a city overlay key, or `"overture"`.
`warnings`	`readonly`	readonly `string`[]	Degradations the caller should surface, such as an unavailable city overlay.

DirectBuildingsResult

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

Building footprints read for an area, as parsed GeoJSON feature objects.

Properties

Property	Modifier	Type	Description
`features`	`readonly`	readonly `Record`<`string`, `unknown`>[]	The normalised building footprint features.
`overtureRelease`	`readonly`	`string`	Overture release the footprints came from, or `""` when Overture was not read.
`source`	`readonly`	`string`	Which source answered: a city overlay key, or `"overture"`.
`warnings`	`readonly`	readonly `string`[]	Degradations the caller should surface, such as an unavailable city overlay.

DotBimMesh

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

One building mesh in dotbim form: flat vertex coordinates plus triangle indices.

Coordinates are in metres in the frame returned as AreaBuildings.origin.

Extends

Readonly<Record<string, unknown>>

Indexable

[key: string]: unknown

Properties

Property	Modifier	Type	Description
`coordinates`	`readonly`	readonly `number`[]	Flat vertex coordinates `[x, y, z, ...]`, in metres.
`indices?`	`readonly`	readonly `number`[]	Flat triangle vertex indices.
`mesh_id`	`readonly`	`number`	Identifier of the mesh within its building.

MeshCleanReport

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

What cleanMesh did to one mesh.

Properties

Property	Modifier	Type	Description
`closedComponents`	`readonly`	`number`	Closed parts (watertight pieces, turned outward).
`degenerateFacesRemoved`	`readonly`	`number`	Triangles removed as degenerate (a repeated corner, or zero area).
`duplicateFacesRemoved`	`readonly`	`number`	Triangles removed as exact duplicates of an earlier one.
`facesFlipped`	`readonly`	`number`	Kept triangles whose winding is the reverse of their input winding.
`nonManifoldEdges`	`readonly`	`number`	Edges shared by three or more triangles.
`openComponents`	`readonly`	`number`	Open parts (kept at their authored majority direction).
`verticesWelded`	`readonly`	`number`	Input vertices joined into an earlier one by the exact weld.

MeshNotRepresentable

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

Returned instead of a PackedMesh when the mesh cannot be expressed in the compact form.

Properties

Property	Modifier	Type	Description
`not_representable`	`readonly`	`string`	Why the mesh cannot be packed.

MeshPackVerdict

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

MeshPackVerdict = PackedMesh | MeshNotRepresentable

The outcome of packMesh: either a PackedMesh or a MeshNotRepresentable.

PackedMesh

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

A mesh packed into the compact transfer form.

Properties

Property	Modifier	Type	Description
`coordinates_bin`	`readonly`	`string`	The vertex coordinates, packed and base64-encoded.
`indices_bin`	`readonly`	`string`	The triangle indices, packed and base64-encoded.

packMesh

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

packMesh(coordinates, indices): MeshPackVerdict

Pack a triangle mesh into the compact form used for request bodies.

initializeCore() must have completed. Check the result for a not_representable field before using it as a PackedMesh.

Parameters

Parameter	Type	Description
`coordinates`	`Float64Array`<`ArrayBufferLike`> \| readonly `number`[]	Flat vertex coordinates (`x, y, z, x, y, z, ...`).
`indices`	readonly `number`[]	Flat triangle vertex indices, three per triangle.

Returns

MeshPackVerdict

The packed mesh, or a verdict saying why the mesh cannot be packed.

Throws

when coordinates or indices contains a non-finite number.