Geodata

AcquireGroundAreaOptions

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

Extends AcquireGroundOptions with the site-level cleaning extent, the simulation-tile rectangles and the number of chunks read at once.

Extends

AcquireGroundOptions

Properties

Property	Modifier	Type	Description	Overrides	Inherited from
`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.	-	`AcquireGroundOptions`.`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.	-	`AcquireGroundOptions`.`candidateBufferDeg`
`cleaningExtent`	`readonly`	`object`	The extent the merged layers are cleaned against: the site centre (`latitude`, `longitude` in degrees) and its half-diagonal `distance` in metres.	-	-
`cleaningExtent.distance`	`readonly`	`number`	-	-	-
`cleaningExtent.latitude`	`readonly`	`number`	-	-	-
`cleaningExtent.longitude`	`readonly`	`number`	-	-	-
`defaultLayer?`	`readonly`	`string`	Material used for the background layer; a built-in default when absent.	-	-
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	-	`AcquireGroundOptions`.`fetch`
`frameOrigin?`	`readonly`	readonly [`number`, `number`]	The area-level frame origin as `[longitude, latitude]` in degrees: the south-west corner of the tiling polygon. Pass the same origin for every tile of one area so that a road fetched by two overlapping tiles is buffered identically and the duplicate can be removed. Defaults to the south-west corner of the requested bounding box.	-	`AcquireGroundOptions`.`frameOrigin`
`logger?`	`readonly`	`Logger`	Where the site-size warning is written. Defaults to `consoleLogger`.	`AcquireGroundOptions`.`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.	-	`AcquireGroundOptions`.`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`.	-	`AcquireGroundOptions`.`maxPlannedBytes`
`maxWorkers?`	`readonly`	`number`	Maximum number of chunks whose road data is read at the same time. The effective value is `min(maxWorkers, SITE_CHUNKS_IN_FLIGHT)`, so a caller can lower concurrency but never raise it above the built-in ceiling that bounds memory use.	-	-
`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.	-	`AcquireGroundOptions`.`overtureRelease`
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	-	`AcquireGroundOptions`.`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`.	-	`AcquireGroundOptions`.`stallTimeoutMs`
`tileRectangles?`	`readonly`	readonly `Bbox`[]	The query rectangles of the simulation tiles. A read chunk that meets none of them is not composed: for example the empty quadrant of an L-shaped polygon is ground no simulation will read.	-	-
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	-	`AcquireGroundOptions`.`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.	-	`AcquireGroundOptions`.`transport`
`zStep?`	`readonly`	`number`	Vertical step, in metres, used to stack material layers; defaults to 0.05 m when absent.	-	-

AcquireGroundJson

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

Ground materials composed for an area, as unparsed JSON text.

Properties

Property	Modifier	Type	Description
`json`	`readonly`	`string`	The composed `{material: FeatureCollection}` document, as text.
`overtureRelease`	`readonly`	`string`	Overture release the base themes came from, for reproducibility.

AcquireGroundOptions

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

Options for the ground-material readers.

Combines the FlatGeobuf read options, the Overture read options and ComposeFrame.

Extends

ReadFgbOptions.ReadOvertureOptions.ComposeFrame

Extended by

AcquireGroundAreaOptions

Properties

Property	Modifier	Type	Description	Inherited from
`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`
`frameOrigin?`	`readonly`	readonly [`number`, `number`]	The area-level frame origin as `[longitude, latitude]` in degrees: the south-west corner of the tiling polygon. Pass the same origin for every tile of one area so that a road fetched by two overlapping tiles is buffered identically and the duplicate can be removed. Defaults to the south-west corner of the requested bounding box.	`ComposeFrame`.`frameOrigin`
`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`

AcquireTreesOptions

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

Options for acquireTrees and acquireTreesJson: the FlatGeobuf read options plus bestAvailable.

Extends

ReadFgbOptions

Properties

Property	Modifier	Type	Description	Inherited from
`bestAvailable?`	`readonly`	`boolean`	Set to `false` to use only the global OpenStreetMap layer, even inside a registered city. By default a city's open-data overlay is merged in when the area falls inside a registered city.	-
`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`
`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`

ALLOWED_HOSTS

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

const ALLOWED_HOSTS: readonly string[]

The public data hosts the geodata readers may fetch from.

Public data URLs come from this allow-list and never carry an API key. Two entries are Infrared's public data mirrors and the third is the anonymous Overture Maps bucket. A manifest read from one of them names the object URLs the readers then fetch, so every such URL is checked against this list again before a request goes out; a stale or tampered manifest cannot redirect a range read to an arbitrary host.

assertAllowedUrl

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

assertAllowedUrl(url): string

Return a URL as a string, or throw when it is not a permitted data URL.

Parameters

Parameter	Type	Description
`url`	`string` \| `URL`	The URL, as a string or a `URL`.

Returns

string

The URL as a string.

Throws

when the URL is not https or its host is not in ALLOWED_HOSTS.

Bbox

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

A west/south/east/north bounding box in WGS84 degrees.

Properties

Property	Modifier	Type	Description
`east`	`readonly`	`number`	Eastern edge, longitude in degrees.
`north`	`readonly`	`number`	Northern edge, latitude in degrees.
`south`	`readonly`	`number`	Southern edge, latitude in degrees.
`west`	`readonly`	`number`	Western edge, longitude in degrees.

bboxAreaKm2

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

bboxAreaKm2(bbox): number

Rough area of a WGS84 rectangle in km2, for sizing decisions rather than geometry.

Parameters

Parameter	Type
`bbox`	`Bbox`

Returns

number

bboxAreaM2

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

bboxAreaM2(bbox, cosLat): number

A rectangle's area in square metres, using one flat metres-per-degree scale.

Parameters

Parameter	Type	Description
`bbox`	`Bbox`	The rectangle, in WGS84 degrees.
`cosLat`	`number`	The cosine of a single latitude used for the whole comparison, normally the site's mid latitude.

Returns

number

The area in square metres; never negative.

bboxIntersects

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

bboxIntersects(a, b): boolean

Report whether two bounding boxes overlap; boxes that only touch along an edge count as overlapping.

Parameters

Parameter	Type	Description
`a`	`Bbox`	The first box.
`b`	`Bbox`	The second box.

Returns

boolean

bytesRangeTransport

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

bytesRangeTransport(bytes, url?): RangeTransport

Create a RangeTransport that serves one in-memory object, for tests or already-downloaded buffers.

Parameters

Parameter	Type	Default value	Description
`bytes`	`Uint8Array`	`undefined`	The object's bytes.
`url`	`string`	`"https://geo.infrared.city/in-memory.fgb"`	The URL the object answers to; defaults to `https://geo.infrared.city/in-memory.fgb`. Reads of any other URL are rejected with a `GeodataFetchError`.

Returns

RangeTransport

A transport over the bytes.

clearFgbCache

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

clearFgbCache(): void

Drop the cached FlatGeobuf headers and index levels held by this runtime.

Returns

void

clearManifestCaches

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

clearManifestCaches(): void

Drop every cached manifest held by this runtime. Useful in tests and long-lived workers.

Returns

void

clearOvertureMetadataCache

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

clearOvertureMetadataCache(): void

Drop every cached Overture file footer held by this runtime. Useful in tests and long-lived workers.

Returns

void

COLUMNS_BY_COLLECTION

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

const COLUMNS_BY_COLLECTION: Readonly<Record<string, readonly string[]>>

The parquet columns read for each Overture collection (building, water, land_use, land_cover).

ColumnStatistics

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

The minimum and maximum value of a Parquet column chunk.

Properties

Property	Type
`max_value?`	`number`
`min_value?`	`number`

ComposeFrame

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

Frame option shared by the ground-material readers.

Extended by

AcquireGroundOptions

Properties

Property	Modifier	Type	Description
`frameOrigin?`	`readonly`	readonly [`number`, `number`]	The area-level frame origin as `[longitude, latitude]` in degrees: the south-west corner of the tiling polygon. Pass the same origin for every tile of one area so that a road fetched by two overlapping tiles is buffered identically and the duplicate can be removed. Defaults to the south-west corner of the requested bounding box.

DATA_USER_AGENT

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

const DATA_USER_AGENT: "infrared-sdk-ts/1.0.0"

The User-Agent value sent on public data requests (infrared-sdk-ts/<version>).

The public data host can reject an unset or default User-Agent with HTTP 403, so the SDK sets one. The host's CORS policy must allow the User-Agent header.

decompose

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

decompose(clip, rectangles): Bbox[]

The pieces of clip ∩ union(rectangles), as disjoint rectangles.

Parameters

Parameter	Type	Description
`clip`	`Bbox`	The rectangle to clip to, in WGS84 degrees.
`rectangles`	readonly `Bbox`[]	The rectangles whose union is intersected with `clip`.

Returns

Bbox[]

The disjoint rectangles that make up the intersection.

DEDUP_RADIUS_M

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

const DEDUP_RADIUS_M: 2 = 2.0

Distance in metres (2.0) below which two trees from different sources are treated as the same tree.

DEFAULT_PUBLIC_TIMEOUT_MS

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

const DEFAULT_PUBLIC_TIMEOUT_MS: 180000 = 180_000

How long one public read may take, body included, when no timeoutMs is given: 180 000 ms (three minutes).

DirectGroundResult

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

Ground materials composed for an area, parsed into objects.

Properties

Property	Modifier	Type	Description
`featureCount`	`readonly`	`number`	Features across every composed layer.
`layers`	`readonly`	`GroundLayers`	The composed layers, material name to GeoJSON feature collection.
`overtureRelease`	`readonly`	`string`	Overture release the base themes came from, for reproducibility.

DirectTreesJson

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

Trees acquired for an area, as unparsed JSON text.

Properties

Property	Modifier	Type	Description
`featuresJson`	`readonly`	`string`	The normalised, deduplicated features as JSON array text.
`sources`	`readonly`	readonly `string`[]	Data sources that contributed, in fetch order.
`warnings`	`readonly`	readonly `string`[]	Degradations you should surface, for example an unavailable city overlay.

DirectTreesResult

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

Trees acquired for an area, parsed into objects.

Properties

Property	Modifier	Type	Description
`features`	`readonly`	readonly `Record`<`string`, `unknown`>[]	GeoJSON tree features with the normalised Infrared properties.
`sources`	`readonly`	readonly `string`[]	Data sources that contributed, in fetch order.
`warnings`	`readonly`	readonly `string`[]	Degradations you should surface, for example an unavailable city overlay.

farEndErrorM

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

farEndErrorM(southLat, extentM): number

The far-end error, in metres, of one flat local frame for a site extentM across.

The error grows with the square of the extent. At 48 deg N it is about 0.9 m at 2.24 km, 3.5 m at 4.47 km and 17.4 m at 10 km.

Parameters

Parameter	Type	Description
`southLat`	`number`	The latitude of the frame origin, in degrees.
`extentM`	`number`	The site extent, in metres.

Returns

number

featureCollectionJson

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

featureCollectionJson(featuresJson): string

Wrap a JSON array text of features as a GeoJSON FeatureCollection text.

Parameters

Parameter	Type	Description
`featuresJson`	`string`	JSON text of an array of features.

Returns

string

The FeatureCollection JSON text.

featuresArrayText

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

featuresArrayText(featureCollectionText, origin): string

Extract the features array of a GeoJSON FeatureCollection text, as text.

The document is scanned once, without building JavaScript objects, so large collections are not parsed and re-encoded.

Parameters

Parameter	Type	Description
`featureCollectionText`	`string`	The FeatureCollection JSON text.
`origin`	`string`	Name of the producer, used in the error message.

Returns

string

The text of the features array, including its brackets.

Throws

when no readable features array is found.

fetchOvertureManifest

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

fetchOvertureManifest(collection, options?): Promise<{ manifestJson: string; release: string; }>

Fetch the Overture file manifest for a collection.

The latest-release pointer is read on every call; the manifest itself is fetched again only when the release changes.

Parameters

Parameter	Type	Description
`collection`	`string`	An Overture collection such as `"building"`.
`options`	`OvertureManifestOptions`	Request options; `overtureRelease` pins a release.

Returns

Promise<{ manifestJson: string; release: string; }>

The manifest text and the release it belongs to.

Throws

when the requested release cannot be pinned for the collection.

fetchPublicBytes

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

fetchPublicBytes(url, options?): Promise<PublicBytes>

GET a whole public object as undecoded bytes, under a size cap.

Use this instead of fetchPublicText when the raw bytes matter. The read sends no credentials, refuses redirects and runs under one deadline over the headers and the body. The cap is enforced on the bytes actually received.

Parameters

Parameter	Type	Description
`url`	`string`	The URL to fetch; it must be on the allow-list.
`options`	`PublicBytesOptions`	Request options plus `cap`, the largest body accepted in bytes (defaults to MAX_JSON_BYTES).

Returns

Promise<PublicBytes>

The bytes, the entity tag if sent, and whether the answer was encoded.

Throws

when the URL is not allowed.

Throws

when the request fails, is not 2xx or exceeds the cap.

fetchPublicJson

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

fetchPublicJson<T>(url, options?): Promise<T>

GET a public JSON document and parse it.

Type Parameters

Type Parameter	Description
`T`	Expected shape of the document; it is not validated.

Parameters

Parameter	Type	Description
`url`	`string`	The URL to fetch; it must be on the allow-list.
`options`	`PublicRequestOptions`	Request options.

Returns

Promise<T>

The parsed document.

Throws

when the URL is not allowed.

Throws

when the request fails or the body is not JSON.

fetchPublicText

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

fetchPublicText(url, options?): Promise<string>

GET a public JSON document and return it as unparsed text.

A failed connection, a 5xx or a 429 answer is retried. The body is capped at MAX_JSON_BYTES and must be valid UTF-8.

Parameters

Parameter	Type	Description
`url`	`string`	The URL to fetch; it must be on the allow-list.
`options`	`PublicRequestOptions`	Request options.

Returns

Promise<string>

The response body as text.

Throws

when the URL is not allowed.

Throws

when the request fails, the status is not 2xx, the size cap is exceeded or the body is not UTF-8.

fetchSources

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

fetchSources(options?): Promise<Record<string, unknown>>

Fetch the city-overlay registry (sources.json), reusing the cached copy while it is younger than SOURCES_TTL_MS.

Parameters

Parameter	Type	Description
`options`	`PublicRequestOptions` & `object`	Request options; `now` overrides the clock, in milliseconds since the epoch.

Returns

Promise<Record<string, unknown>>

The parsed registry document.

GEO_BASE_URL

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

const GEO_BASE_URL: "https://geo.infrared.city" = "https://geo.infrared.city"

Base URL of the public Infrared data mirror that hosts the sources registry and the world FlatGeobuf files.

geoUrlFor

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

geoUrlFor(key): string

Resolve a registry value ("vienna-trees-only.fgb") to a full URL.

An absolute URL is kept as given; a relative key is joined onto GEO_BASE_URL. The result is checked against the allow-list either way.

Parameters

Parameter	Type	Description
`key`	`string`	A relative object key or an absolute URL.

Returns

string

The full, allowed URL.

Throws

when the resulting URL is not allowed.

GROUND_COLLECTIONS

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

const GROUND_COLLECTIONS: readonly string[]

The Overture Maps base themes read to compose ground materials: land_cover, land_use and water.

GroundAreaResult

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

The merged ground materials of one site, as returned by acquireGroundMaterialsArea.

Properties

Property	Modifier	Type	Description
`chunks`	`readonly`	readonly `SiteChunk`[]	The read chunks the site was split into, in the order they were composed.
`layersJson`	`readonly`	`string`	The merged, cleaned layers as JSON text (material name to feature collection).
`overtureRelease`	`readonly`	`string`	Overture release the base themes came from, for reproducibility.

GroundLayers

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

GroundLayers = Record<string, { features: unknown[]; type: string; }>

Composed ground materials: material name to GeoJSON feature collection, in z order.

groundReadDistanceM

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

groundReadDistanceM(analysisType?): number

Half extent, in metres, of the area read around a tile for ground materials and trees.

It is ceil(sqrt(2) * readMarginM(analysisType)), the tile's half diagonal, so the circular crop applied when cleaning ground materials is fully covered by the square box that is fetched: 363 m for the wind analyses and 544 m for every other analysis.

Parameters

Parameter	Type	Description
`analysisType?`	`string` \| `null`	The analysis type; defaults to WIDEST_READ_ANALYSIS_TYPE when omitted.

Returns

number

The read distance in metres.

HEADER_PREFIX_BYTES

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

const HEADER_PREFIX_BYTES: 8192 = 8_192

Size, in bytes (8192), of the first read of a FlatGeobuf file. It is enough for the header of any FlatGeobuf the SDK reads.

httpRangeTransport

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

httpRangeTransport(options?): RangeTransport

Create a RangeTransport that reads objects over HTTP Range requests, with a per-instance object-size cache.

Requests go only to allowed public hosts, carry no credentials and are retried on transient failures.

Parameters

Parameter	Type	Description
`options`	`PublicRequestOptions`	Fetch, abort signal, timeout, logger and stall timeout.

Returns

RangeTransport

A transport; reuse it for all reads of one area.

INDEXED_COLLECTIONS

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

const INDEXED_COLLECTIONS: readonly string[]

The Overture collections that have a published file index: building, land_cover, water and land_use.

isAllowedUrl

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

isAllowedUrl(url): boolean

Report whether a URL may be fetched: it must use https and its host must be on ALLOWED_HOSTS.

Parameters

Parameter	Type	Description
`url`	`string` \| `URL`	The URL, as a string or a `URL`.

Returns

boolean

true when the URL is allowed; false otherwise, including when the string cannot be parsed as a URL.

jsonArrayOf

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

jsonArrayOf(elements): string

Build a JSON array text from element texts.

Parameters

Parameter	Type	Description
`elements`	readonly (`string` \| `undefined`)[]	JSON texts of the elements; `undefined` becomes `null`.

Returns

string

The array JSON text.

jsonObjectOf

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

jsonObjectOf(key, valueJson): string

Wrap a JSON text as a single-entry object text, { "<key>": <value> }.

Parameters

Parameter	Type	Description
`key`	`string`	The object key.
`valueJson`	`string`	JSON text of the value.

Returns

string

The object JSON text.

KERNEL_FGB_EXPORTS

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

const KERNEL_FGB_EXPORTS: Readonly<{ decodeRangeFeatures: "fgbDecodeRangeFeatures"; indexSearchStep: "fgbIndexSearchStep"; layout: "fgbLayout"; }>

Names of the core-library functions the FlatGeobuf reader calls, in call order: file layout, index search step and feature decoding.

LAND_COVER_MIN_MAX_ZOOM

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

const LAND_COVER_MIN_MAX_ZOOM: 8 = 8

Smallest max_zoom of an Overture land_cover feature that is kept (8).

Overture publishes land_cover at several generalisation bands. Only the finest bands (max_zoom >= 8) are real ground cover; the coarse bands' polygons can span a whole city, so the reader drops them.

MAX_BACKOFF_MS

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

const MAX_BACKOFF_MS: 1000 = 1_000

Longest wait, in milliseconds (1000), between two attempts.

MAX_HTTP_200_BYTES

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

const MAX_HTTP_200_BYTES: number

Largest body, in bytes (8 MiB), accepted when a server answers a Range request with HTTP 200.

A 200 means the server ignored the range and is sending the whole object. Larger bodies are refused while they arrive.

MAX_JSON_BYTES

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

const MAX_JSON_BYTES: number

Largest JSON document, in bytes (32 MiB), read from a public host; a larger body is refused.

MAX_PLANNED_RANGE_BYTES

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

const MAX_PLANNED_RANGE_BYTES: number

Largest single byte range, in bytes (64 MiB), one FlatGeobuf read may fetch. A larger planned range fails with a GeodataRangeError.

MAX_PLANNED_TOTAL_BYTES

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

const MAX_PLANNED_TOTAL_BYTES: number

Largest total, in bytes (256 MiB), that the ranges of one FlatGeobuf read may add up to. A larger plan fails with a GeodataRangeError.

MAX_RANGE_ATTEMPTS

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

const MAX_RANGE_ATTEMPTS: 3 = 3

Total number of attempts (3) made for one range read, the first one included.

MAX_RANGE_BYTES

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

const MAX_RANGE_BYTES: number

Largest body, in bytes (64 MiB), accepted for one range answer.

A longer answer is refused.

MAX_SLAB_TOLERANCE_DEG

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

const MAX_SLAB_TOLERANCE_DEG: 0.0001 = 1e-4

Upper limit, in degrees (1e-4), on the edge-fusion tolerance slabToleranceDeg can return.

MIN_BACKOFF_MS

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

const MIN_BACKOFF_MS: 250 = 250

Shortest wait, in milliseconds (250), between two attempts. The actual wait is a random value between this and MAX_BACKOFF_MS.

namePieces

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

namePieces(id, pieces): object[]

Give each piece of a decomposition an id.

A single piece keeps the owner's own id; several pieces are <id>-p<index> in decomposition order.

Parameters

Parameter	Type
`id`	`string`
`pieces`	readonly `Bbox`[]

Returns

object[]

OverlayCity

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

A registered city whose own data overlays the global layers.

Properties

Property	Modifier	Type	Description
`id`	`readonly`	`string`	The city id, such as `vienna`.
`layers`	`readonly`	`Readonly`<`Record`<`string`, `string`>>	Layer name to data key (path under the public data host) for each layer the city publishes.
`sourceKey`	`readonly`	`string`	Per-feature `source` label and attribution key, e.g. `vienna_ogd`.

OverlayResolution

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

The outcome of looking up a city overlay for an area.

Properties

Property	Modifier	Type	Description
`city?`	`readonly`	`OverlayCity`	The city that covers the area, or `undefined` when none does.
`warnings`	`readonly`	readonly `string`[]	Degradations the caller should surface, never a silent partial result.

OvertureManifestOptions

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

Options for fetching an Overture file manifest.

Extends

PublicRequestOptions

Properties

Property	Modifier	Type	Description	Inherited from
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`PublicRequestOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`PublicRequestOptions`.`logger`
`overtureRelease?`	`readonly`	`string`	Pin an immutable release instead of following the daily pointer.	-
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`PublicRequestOptions`.`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`.	`PublicRequestOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	`PublicRequestOptions`.`timeoutMs`

OvertureRead

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

Features read from an Overture collection, plus the release they came from.

Properties

Property	Modifier	Type	Description
`features`	`readonly`	`Record`<`string`, `unknown`>[]	The GeoJSON features inside the requested box.
`release`	`readonly`	`string`	Overture release the features came from, for reproducibility.

overtureReaderAvailable

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

overtureReaderAvailable(logger?): Promise<boolean>

Report whether the optional parquet reader packages are installed.

A boolean cannot say what is missing, so when the reader is absent the message naming what to install is written to the logger at debug level before false is returned.

Parameters

Parameter	Type	Default value	Description
`logger`	`Logger`	`silentLogger`	Where the reason is written; defaults to `silentLogger`.

Returns

Promise<boolean>

true when the parquet reader and its codecs can be loaded.

ParquetMetadata

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

The parts of a Parquet file's metadata that row-group planning reads: the row groups with their column statistics and sizes, and the schema.

Properties

Property	Type
`row_groups`	`object`[]
`schema`	`object`[]

PlannedBudget

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

The byte budget of one acquisition call.

An area read of the three ground themes shares ONE of these, because it is one process that holds all three at once; a lone read makes its own. The refusal names the collection whose plan took the total over the limit.

Properties

Property	Modifier	Type	Description
`limitBytes`	`readonly`	`number`	-
`plannedBytes`	`readonly`	`number`	Bytes planned so far across every collection of this call.

Methods

add()

add(collection, bbox, bytes, files, rowGroups): void

Add one collection's plan, refusing if the CALL total is over.

Parameters

Parameter	Type
`collection`	`string`
`bbox`	`Bbox`
`bytes`	`number`
`files`	`number`
`rowGroups`	`number`

Returns

void

planRowGroups

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

planRowGroups(metadata, bbox): [number, number][]

Row ranges of an Overture parquet file that can hold a feature inside an area, judged by the file's bounding-box statistics.

Parameters

Parameter	Type	Description
`metadata`	`ParquetMetadata`	The parquet file footer.
`bbox`	`Bbox`	The area, in WGS84 degrees.

Returns

[number, number][]

[start, end) row ranges, one per selected row group.

pointToBbox

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

pointToBbox(latitude, longitude, distanceM): Bbox

Convert a centre point and a radius into a bounding box.

The box extends distanceM metres from the centre in each direction, using METERS_PER_DEG_LAT for latitude and that value scaled by cos(latitude) for longitude (the cosine is clamped, so a pole does not divide by zero).

Parameters

Parameter	Type	Description
`latitude`	`number`	Centre latitude in degrees.
`longitude`	`number`	Centre longitude in degrees.
`distanceM`	`number`	Half-width of the box in metres.

Returns

Bbox

The bounding box in degrees.

PublicBytes

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

One whole-object read: the bytes and the entity tag.

Properties

Property	Modifier	Type	Description
`bytes`	`readonly`	`Uint8Array`	-
`encoded`	`readonly`	`boolean`	True when the answer arrived under a content coding (usually gzip).
`etag?`	`readonly`	`string`	Entity tag of the object, when the host sends one.

PublicBytesOptions

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

Options for fetchPublicBytes.

Extends

PublicRequestOptions

Properties

Property	Modifier	Type	Description	Inherited from
`cap?`	`readonly`	`number`	Largest body accepted, in bytes. Defaults to MAX_JSON_BYTES.	-
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`PublicRequestOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`PublicRequestOptions`.`logger`
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`PublicRequestOptions`.`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`.	`PublicRequestOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	`PublicRequestOptions`.`timeoutMs`

PublicRequestOptions

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

Options shared by every public data request.

Extended by

Properties

Property	Modifier	Type	Description
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.
`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`.
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.

RangeReadOptions

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

Options for one ranged read.

Properties

Property	Modifier	Type	Description
`ifMatch?`	`readonly`	`string`	Entity tag sent as `If-Match`. Every follow-up range of one logical read carries the entity tag the first range answered with, so a file replaced between two requests fails with an error instead of mixing two versions of the file.

RangeReadResult

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

One ranged read: the bytes, plus what the answer said about the object.

Properties

Property	Modifier	Type	Description
`bytes`	`readonly`	`Uint8Array`	-
`etag?`	`readonly`	`string`	Entity tag of the object this range came from, when the host sends one.
`totalSize?`	`readonly`	`number`	Total object size, from `Content-Range`, when the answer carries it.

RangeRetry

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

The retry state of one range read.

Use one instance per read. It counts the attempts, holds the entity tag every attempt must match, and decides, once per failure, whether asking again is worthwhile. Only transient failures are retried: a failed connection, HTTP 5xx, HTTP 429, and a 200 answer to a range request. At most MAX_RANGE_ATTEMPTS attempts are made.

Constructors

Constructor

new RangeRetry(url, callerIfMatch, logger?): RangeRetry

Parameters

Parameter	Type	Default value	Description
`url`	`string`	`undefined`	The object being read; only its path is logged.
`callerIfMatch`	`string` \| `undefined`	`undefined`	The entity tag the caller requires, if any.
`logger`	`Logger`	`consoleLogger`	Where each retry is reported. Defaults to the console.

Returns

RangeRetry

Accessors

attemptsMade

Get Signature

get attemptsMade(): number

The number of attempts finished so far.

Returns

number

Methods

headers()

headers(): Record<string, string>

The If-Match header for the next attempt: the entity tag of this read, if known.

Returns

Record<string, string>

next()

next(error): number | undefined

The wait before the next attempt, or undefined when the read must fail.

Call once per failed attempt: each call counts an attempt, and each retry is logged as a warning.

Parameters

Parameter	Type	Description
`error`	`unknown`	The failure of the attempt that just finished.

Returns

number | undefined

The wait in milliseconds, or undefined when the failure is not retryable or the attempts are used up.

observe()

observe(etag): void

Record the entity tag an answer carried, or refuse the answer.

The first answer of a read that named no tag pins one, so a retry cannot silently read a different file.

Parameters

Parameter	Type	Description
`etag`	`string` \| `undefined`	The entity tag of the answer, if it carried one.

Returns

void

Throws

when the tag differs from the one this read is pinned to, meaning the object was replaced during the read (status 412).

willAskAgainForWholeObject()

willAskAgainForWholeObject(): boolean

Whether a 200 answer to this range request is worth asking again.

A 200 means the server ignored the range and is offering the whole object. This is asked before the body is read, because asking again costs one request while reading a large body costs much more. It is false once the single re-ask is spent or no attempt is left; the answer is then accepted if the object is small and refused if it is large.

Returns

boolean

true when the range request should be sent again.

RangeTransport

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

A byte-range reader over remote objects.

The FlatGeobuf and Parquet readers reach the network only through this interface, so you can supply your own transport (for example one that serves bytes from memory or adds caching).

Reuse one instance across all tiles of an area: it caches object sizes, and a fresh instance per tile has to learn every size again.

Methods

byteLength()

byteLength(url): Promise<number>

Total size of the object at url, in bytes.

Parameters

Parameter	Type	Description
`url`	`string`	The object URL.

Returns

Promise<number>

read()

read(url, start, endExclusive?, options?): Promise<RangeReadResult>

Read the bytes [start, endExclusive) of the object at url; endExclusive omitted means "to the end".

Parameters

Parameter	Type	Description
`url`	`string`	The object URL.
`start`	`number`	First byte offset.
`endExclusive?`	`number`	End offset (exclusive).
`options?`	`RangeReadOptions`	Per-read options such as `ifMatch`.

Returns

Promise<RangeReadResult>

readFgbBbox

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

readFgbBbox(url, bbox, options?): Promise<Record<string, unknown>[]>

Read a FlatGeobuf object's features inside bbox, parsed into objects.

The same read as readFgbBboxJson, parsed once.

Parameters

Parameter	Type	Description
`url`	`string`	The FlatGeobuf object URL; it must be on the public data allow-list.
`bbox`	`Bbox`	The area to read, in WGS84 degrees.
`options`	`ReadFgbOptions`	Request and transport options.

Returns

Promise<Record<string, unknown>[]>

The feature objects with their raw properties.

Throws

when url is not on the public data allow-list.

Throws

when the object changes mid-read or a range limit is exceeded.

readFgbBboxJson

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

readFgbBboxJson(url, bbox, options?): Promise<string>

Read a FlatGeobuf object's features inside bbox as GeoJSON FeatureCollection text.

The text carries the file's raw properties, unparsed and not normalised. Use readFgbBbox for parsed feature objects.

Parameters

Parameter	Type	Description
`url`	`string`	The FlatGeobuf object URL; it must be on the public data allow-list.
`bbox`	`Bbox`	The area to read, in WGS84 degrees.
`options`	`ReadFgbOptions`	Request and transport options.

Returns

Promise<string>

The features as FeatureCollection text.

Throws

when url is not on the public data allow-list.

Throws

when the object changes mid-read or a range limit is exceeded.

readFgbBytes

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

readFgbBytes(bytes, bbox): Promise<Record<string, unknown>[]>

Decode FlatGeobuf bytes already in memory, such as fixtures or cached objects, and return the features inside bbox.

The bytes are the caller's own, so no size cap is applied.

Parameters

Parameter	Type	Description
`bytes`	`Uint8Array`	The complete FlatGeobuf file.
`bbox`	`Bbox`	The area to read, in WGS84 degrees.

Returns

Promise<Record<string, unknown>[]>

The feature objects with their raw properties.

ReadFgbOptions

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

Options for reading FlatGeobuf data.

Extends the public-request options (timeout, abort signal, fetch implementation).

Extends

PublicRequestOptions

Extended by

Properties

Property	Modifier	Type	Description	Inherited from
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`PublicRequestOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`PublicRequestOptions`.`logger`
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`PublicRequestOptions`.`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`.	`PublicRequestOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	`PublicRequestOptions`.`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.	-

readMarginM

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

readMarginM(analysisType?): number

Half extent, in metres, of the area read around a tile for buildings.

It is 256 m for the wind analyses (wind-speed, pedestrian-wind-comfort) and 384 m for every other analysis, which must see further because shadows are cast into a tile from more distant buildings and trees.

Parameters

Parameter	Type	Description
`analysisType?`	`string` \| `null`	The analysis type; defaults to WIDEST_READ_ANALYSIS_TYPE when omitted.

Returns

number

The read margin in metres.

readOvertureCollection

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

readOvertureCollection(collection, bbox, options?): Promise<OvertureRead>

Read one Overture collection for an area as GeoJSON features.

Parameters

Parameter	Type	Description
`collection`	`string`	The Overture collection name, for example `"water"`.
`bbox`	`Bbox`	The area's bounding box in WGS84 degrees.
`options`	`ReadOvertureOptions`	Read options (transport, file limit, release pin, byte budget).

Returns

Promise<OvertureRead>

The features and the Overture release they came from.

Throws

when the optional parquet reader packages are not installed.

readOvertureCollectionJson

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

readOvertureCollectionJson(collection, bbox, options?): Promise<{ json: string; release: string; }>

Read one Overture collection for an area as JSON array text.

The same read as readOvertureCollection, returning the features as unparsed JSON text.

Parameters

Parameter	Type	Description
`collection`	`string`	The Overture collection name, for example `"water"`.
`bbox`	`Bbox`	The area's bounding box in WGS84 degrees.
`options`	`ReadOvertureOptions`	Read options (transport, file limit, release pin, byte budget).

Returns

Promise<{ json: string; release: string; }>

The features as a JSON array text and the Overture release.

Throws

when the optional parquet reader packages are not installed.

ReadOvertureOptions

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

Options for reading Overture Maps data.

Extends the public-request options (fetch, signal, timeout, logger).

Extends

PublicRequestOptions

Extended by

Properties

Property	Modifier	Type	Description	Inherited from
`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.	-
`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.	-
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`PublicRequestOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`PublicRequestOptions`.`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.	-
`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`.	-
`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.	-
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`PublicRequestOptions`.`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`.	`PublicRequestOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT_PUBLIC_TIMEOUT_MS.	`PublicRequestOptions`.`timeoutMs`
`transport?`	`readonly`	`RangeTransport`	Byte-range reader; defaults to HTTP range requests. Pass one instance for a whole area; it carries the file-size cache.	-

requiredMarginM

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

requiredMarginM(layer, analysisType?): number

The read margin, in metres, that a layer needs for an analysis type.

Buildings need readMarginM; ground materials and trees need groundReadDistanceM.

Parameters

Parameter	Type	Description
`layer`	`string`	`"buildings"`, `"ground materials"` or `"trees"`.
`analysisType?`	`string` \| `null`	The analysis type; defaults to WIDEST_READ_ANALYSIS_TYPE when omitted.

Returns

number

The required margin in metres.

Throws

when layer is not one of the known layers.

requireFeatureCollection

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

requireFeatureCollection(json, origin): string

Check that a JSON text is an object (a GeoJSON FeatureCollection), without parsing it.

Parameters

Parameter	Type	Description
`json`	`string`	The JSON text.
`origin`	`string`	Name of the producer, used in the error message.

Returns

string

json unchanged.

Throws

when the text does not start with {.

requireJsonArray

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

requireJsonArray(json, origin): string

Check that a JSON text is an array, without parsing it.

Parameters

Parameter	Type	Description
`json`	`string`	The JSON text.
`origin`	`string`	Name of the producer, used in the error message.

Returns

string

json unchanged.

Throws

when the text does not start with [.

requireOvertureReader

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

requireOvertureReader(): Promise<void>

Check up front that the optional parquet reader packages are installed.

Call it before planning an Overture read so that a missing package is reported as such, with the install command, rather than as a later failure. Repeated calls are cheap.

Returns

Promise<void>

Throws

when the parquet reader or its codecs are not installed; the message names what to install.

resolveOverlayCity

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

resolveOverlayCity(bbox, options?): Promise<OverlayResolution>

Find the registered city overlay that covers an area, if any.

A quick bounding-box check over the registry picks candidate cities, then the city outline decides. If the registry or a city outline cannot be fetched, the result has no city and carries a warning, so a registry outage falls back to the global sources instead of failing the whole read.

Parameters

Parameter	Type	Description
`bbox`	`Bbox`	The area, in WGS84 degrees.
`options`	`PublicRequestOptions` & `object`	Request options; `now` overrides the clock, in milliseconds since the epoch.

Returns

Promise<OverlayResolution>

The matching city, if any, and any warnings.

resolveReadAnalysisType

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

resolveReadAnalysisType(analysisType?): string

Resolve the analysis type a geodata read is made for.

undefined, null and the empty string mean "none named" and become WIDEST_READ_ANALYSIS_TYPE; any other value is trimmed and returned.

Parameters

Parameter	Type	Description
`analysisType?`	`string` \| `null`	The analysis type name, if any.

Returns

string

The analysis type to read for.

RetryReason

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

RetryReason = "connection" | "server" | "throttled" | "whole-object"

Why a range read is being attempted again: the connection failed, the server answered with an error status, the server throttled the request, or the server answered a range request with the whole object.

ROADS_URL

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

const ROADS_URL: "https://geo.infrared.city/roads-surface-world.fgb"

URL of the OSM road centrelines (with a surface tag) on the public Infrared data mirror.

selectOvertureFiles

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

selectOvertureFiles(collection, bbox, options?): Promise<{ release: string; urls: string[]; }>

List the Overture parquet files whose bounding box meets an area.

Returns an empty list for a collection that has no published index.

Parameters

Parameter	Type	Description
`collection`	`string`	An Overture collection such as `"building"`.
`bbox`	`Bbox`	The area, in WGS84 degrees.
`options`	`OvertureManifestOptions`	Request options; `overtureRelease` pins a release.

Returns

Promise<{ release: string; urls: string[]; }>

The file URLs and the release they belong to.

SITE_CHUNK_EDGE_M

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

const SITE_CHUNK_EDGE_M: 2000 = 2_000

Target edge length, in metres (2000), of a read chunk, whatever the site shape.

SITE_CHUNK_THRESHOLD_KM2

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

const SITE_CHUNK_THRESHOLD_KM2: 4 = 4

A site smaller than this area, in km2 (4), is read as one rectangle.

SITE_CHUNKS_IN_FLIGHT

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

const SITE_CHUNKS_IN_FLIGHT: 2 = 2

Maximum number of site chunks fetched at once (2): one decodes while the next arrives.

SITE_EXTENT_WARNING_KM

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

const SITE_EXTENT_WARNING_KM: 5 = 5

Longest side, in km (5), up to which a single local frame is recommended.

The frame error grows with extent as well as area, so a long, narrow site can exceed it while staying under SITE_AREA_WARNING_KM2. Above it the SDK logs a warning.

SiteChunk

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

One read chunk of a site: a rectangle and the id its data is keyed by.

The id is chunk-r{row}c{col} (row-major, zero-based) and is reported in SiteReadError.failedTiles. A single-rectangle site has the id site.

Properties

Property	Modifier	Type	Description
`bbox`	`readonly`	`Bbox`	The chunk rectangle, in WGS84 degrees.
`id`	`readonly`	`string`	The chunk id.
`pieces`	`readonly`	readonly `object`[]	The rectangles to compose for this chunk, each with its id. They are the pieces of `chunk ∩ union(tile rectangles)`. A chunk with one piece covering the whole chunk keeps the chunk's own id; several pieces are `<chunk id>-p<index>`, in decomposition order.

siteChunks

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

siteChunks(site, used?, logger?): SiteChunk[]

Split a site rectangle into read chunks, in row-major (south-to-north, west-to-east) order.

A site up to SITE_CHUNK_THRESHOLD_KM2 is one chunk with the id site; larger sites are cut into chunks of about SITE_CHUNK_EDGE_M metres. A chunk that meets none of the used rectangles is dropped, so ground no simulation reads is never composed.

Parameters

Parameter	Type	Default value	Description
`site`	`Bbox`	`undefined`	The site rectangle, in WGS84 degrees.
`used?`	readonly `Bbox`[]	`undefined`	The simulation-tile rectangles. Defaults to the site itself.
`logger?`	`Logger`	`consoleLogger`	Receives the warning for a site larger than one local frame.

Returns

SiteChunk[]

The chunks, each with its compose pieces.

siteRectangle

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

siteRectangle(rectangles): Bbox

The rectangle that bounds a list of simulation-tile query rectangles.

Parameters

Parameter	Type
`rectangles`	readonly `Bbox`[]

Returns

Bbox

SLAB_TOLERANCE_FACTOR

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

const SLAB_TOLERANCE_FACTOR: 2 = 2

Safety multiplier (2) applied to half the spread of the rectangle widths when slabToleranceDeg derives the edge-fusion tolerance.

slabToleranceDeg

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

slabToleranceDeg(rectangles): number

The edge-fusion tolerance a set of rectangles earns, in degrees.

It is SLAB_TOLERANCE_FACTOR times half the spread of the rectangle widths, capped at MAX_SLAB_TOLERANCE_DEG. Rectangle edges closer together than this are treated as one edge when a site is decomposed into pieces. A set of equal-width rectangles gets 0.

Parameters

Parameter	Type	Description
`rectangles`	readonly `Bbox`[]	The rectangles, in WGS84 degrees.

Returns

number

The tolerance, in degrees.

SOURCES_TTL_MS

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

const SOURCES_TTL_MS: 300000 = 300_000

How long, in milliseconds (300000, five minutes), the city-overlay registry (sources.json) is cached before it is fetched again.

spliceJsonArrays

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

spliceJsonArrays(parts): string

Concatenate JSON array texts into one array text, without parsing them.

Parameters

Parameter	Type	Description
`parts`	readonly `string`[]	JSON texts that each hold one array.

Returns

string

One array text with the elements of all parts, in order.

Throws

when a part is not an array text.

TREES_URL

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

const TREES_URL: "https://geo.infrared.city/trees-world.fgb"

URL of the global OpenStreetMap tree layer on the public Infrared data mirror.

unionAreaM2

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

unionAreaM2(clip, rectangles, cosLat, pieces?): number

The area, in square metres, that a set of rectangles covers inside clip.

Parameters

Parameter	Type	Description
`clip`	`Bbox`	The rectangle to measure inside, in WGS84 degrees.
`rectangles`	readonly `Bbox`[]	The rectangles whose union is measured.
`cosLat`	`number`	The cosine of a single latitude used for the whole comparison, as for bboxAreaM2.
`pieces?`	readonly `Bbox`[]	The already-computed disjoint pieces of `clip ∩ union(rectangles)`. Computed when omitted.

Returns

number

The covered area in square metres.

WIDEST_READ_ANALYSIS_TYPE

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

const WIDEST_READ_ANALYSIS_TYPE: "solar-radiation" = "solar-radiation"

The analysis type a geodata read assumes when you name none: "solar-radiation".

It gives the widest read margin, which is valid for every analysis; a wind analysis reads a little more data than it needs.