Results and legend, TypeScript SDK reference

AreaGridDtype

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/tiling.

AreaGridDtype = "f16" \| "f32" \| "i16" \| "f64"

The type of AreaResult.mergedGrid: the type the server stored.

"f16": a Uint16Array of raw IEEE half-precision bits (solar radiation, sky view factor, thermal comfort statistics, wind speed). Read it with areaGridValuesF32.
"f32": a Float32Array (direct sun hours, daylight availability, and the class codes of a categorical result).
"i16": an Int16Array of stored integers (thermal comfort index saved before 2026-10-07; UTCI is "f16" since then): physical value = stored value / valueDivisor, and valid tells which cells have a value.
"f64": a Float64Array (a run that mixes types).

areaGridHasValue

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/tiling.

areaGridHasValue(result, cell): boolean

Tells whether a cell of mergedGrid has a value. Use it for every valueDtype: NaN ("f16" bits, "f32", "f64") or a clear valid bit ("i16") means no value.

Parameters

Parameter	Type	Description
`result`	`AreaResult`	The area result.
`cell`	`number`	The cell index, row-major, from `0` to `mergedGrid.length - 1`.

Returns

boolean

True when the cell has a value.

areaGridValuesF32

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/tiling.

areaGridValuesF32(result): Float32Array

Returns the physical values of mergedGrid as 32-bit floats, NaN for a cell without a value: the type and the divisor are applied in one call. An old "i16" UTCI grid (saved before 2026-10-07; UTCI is "f16" with no divisor since then) read without the divisor is 10 times too large; use this function, it handles both. The result is a new array; mergedGrid does not change. Call initializeCore() first.

A categorical result (pedestrian wind comfort) gives class CODES, unchanged: a code is an index into result.legend, which holds only the classes of THIS run, sorted. The same code can be a different class in another run. Map each code through result.legend before you count or compare classes.

Parameters

Parameter	Type	Description
`result`	`AreaResult`	The area result.

Returns

Float32Array

One value per cell.

AreaResult

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/tiling.

The merged grid of an area run, with its shape, legend range, geographic bounds and the tiles that did not contribute.

Properties

Property	Modifier	Type	Description
`bounds?`	`readonly`	readonly \[`number`, `number`, `number`, `number`\]	Geographic bounds of the grid as four numbers, when known.
`executionTime`	`readonly`	`number`	Time the merge took, in seconds.
`failedJobs`	`readonly`	readonly `TileFailure`\[\]	The tiles whose job failed.
`failedTiles?`	`readonly`	readonly `TileFailure`\[\]	Every tile that did not contribute. Empty when all tiles did.
`gridShape`	`readonly`	readonly \[`number`, `number`\]	The grid size as `[rows, columns]`.
`legend?`	`readonly`	readonly `string`\[\]	Sorted observed labels indexed by categorical `mergedGrid` ordinals.
`maxLegend?`	`readonly`	`number`	Upper end of the colour-scale range; set exactly when `minLegend` is.
`mergedGrid`	`readonly`	`Float32Array`<`ArrayBufferLike`> \	`Float64Array`<`ArrayBufferLike`> \	`Uint16Array`<`ArrayBufferLike`> \	`Int16Array`<`ArrayBufferLike`>	The merged values as one flat row-major array, laid out as described by `gridShape`, in the type the server stored (`valueDtype`): a `Uint16Array` of half-precision bits (`"f16"`), a `Float32Array`, an `Int16Array` of stored integers (`"i16"`, UTCI saved before 2026-10-07; UTCI is `"f16"` since then) or a `Float64Array` (a run that mixes types). Read physical values with `areaGridValuesF32` and test a cell with `areaGridHasValue`. An old `"i16"` UTCI grid read without `valueDivisor` is 10 times too large; `areaGridValuesF32` handles both.
`minLegend?`	`readonly`	`number`	Lower end of the colour-scale range: the exact minimum of the finite cells of the finished grid. Absent when no cell is finite, and for a categorical result (`legend`), whose grid holds class codes rather than measurements. Other display ranges (trimmed, fixed, shared across results) are available through `legendRange` and `sharedLegendRange`.
`skippedJobs`	`readonly`	readonly `string`\[\]	Ids of the tiles that were skipped.
`valid?`	`readonly`	`Uint8Array`<`ArrayBufferLike`>	`"i16"` only: one bit per cell of `mergedGrid` (least significant bit first), set when the cell has a value. The float types use NaN for no value.
`valueDivisor`	`readonly`	`number`	`"i16"` only: physical value = stored value / `valueDivisor`. `1` for the other types.
`valueDtype`	`readonly`	`AreaGridDtype`	The type of `mergedGrid`.

BuildingAggregate

Import from @infrared-city/infrared-sdk.

Aggregate statistics of the surfaces of one building: area, mean and peak.

Properties

Property	Modifier	Type	Description
`area`	`readonly`	`number`	Total area.
`mean`	`readonly`	`number`	Mean value.
`peak`	`readonly`	`number`	Peak value.

clearRegistryCache

Import from @infrared-city/infrared-sdk.

clearRegistryCache(): void

Drop the cached registry document, so the next read fetches it again. Useful in tests, or when you know a new registry release is out.

Returns

void

DaylightFactorResult

Import from @infrared-city/infrared-sdk.

A daylight-factor result as columns. Sensor i of group g is element groups[g].start + i of x, y, z, values and room.

The columns are typed-array views over one binary frame, so no object is created per sensor. values holds the daylight factor as 32-bit floats; toJson() gives the same result as plain JSON numbers (each value rounded to 4 significant digits).

Constructors

Constructor

new DaylightFactorResult(frame): DaylightFactorResult

Validates frame and creates the views over it.

The views share the buffer of frame when it starts on an 8-byte boundary; otherwise it is copied once.

Parameters

Parameter	Type	Description
`frame`	`Uint8Array`	A binary daylight-factor result.

Returns

DaylightFactorResult

Throws

When the frame exceeds the result size limit.

Throws

When the frame is not a valid daylight-factor result.

Properties

buildings

readonly buildings: readonly string\[\]

Building names, indexed by DaylightGroup.building.

frame

readonly frame: Uint8Array

The binary frame every view reads. Do not change it.

groups

readonly groups: readonly DaylightGroup\[\]

The sensor groups, in frame order.

kind

readonly kind: "daylight-points"

Result discriminator: always "daylight-points".

layout

readonly layout: DaylightLayout

How the sensors are grouped.

maxLegend

readonly maxLegend: number

Upper end of the colour legend.

minLegend

readonly minLegend: number

Lower end of the colour legend, as for a grid or facade result.

room

readonly room: Uint16Array

Index into rooms per sensor, or NO_ROOM for a sensor without a room.

rooms

readonly rooms: readonly DaylightRoom\[\]

The room rows, which groups and room index into.

sensorCount

readonly sensorCount: number

Total number of sensors (the length of every per-sensor column).

validity

readonly validity: Uint8Array

Bit i % 8 of byte i / 8: values[i] is present (as a grid result's validity).

values

readonly values: Float32Array

The daylight factor per sensor: the values column of the grid and facade results.

version

readonly version: number

The frame's schema version.

warnings

readonly warnings: readonly string\[\]

Warnings the analysis reported for the whole result.

x

readonly x: Float64Array

Sensor x coordinates.

y

readonly y: Float64Array

Sensor y coordinates.

z

readonly z: Float64Array

Sensor z coordinates.

Methods

toJson()

toJson(): unknown

Returns the result as the parsed JSON value, the same value the "json" result format gives.

Returns

unknown

The parsed JSON document.

toJsonBytes()

toJsonBytes(): Uint8Array

Returns the result as the analysis's JSON document, as UTF-8 bytes.

Returns

Uint8Array

The JSON bytes.

DaylightGroup

Import from @infrared-city/infrared-sdk.

One group of sensors in a daylight-factor result: a floor, a building floor, a surface, or the whole result. It matches one output list of the JSON result.

Properties

Property	Modifier	Type	Description
`building`	`readonly`	`number` \	`null`	`"buildings"` layout: index into `DaylightFactorResult.buildings`. Otherwise `null`.
`end`	`readonly`	`number`	End of the group's sensor range (exclusive).
`hasRooms`	`readonly`	`boolean`	True when the sensors carry a room and the group has room rows and mean values.
`key`	`readonly`	`string`	Floor key, surface id, or `""` for the `"single"` layout.
`meanDf`	`readonly`	`number` \	`null`	Mean daylight factor of the group (`mean-df` in the JSON result); `null` when absent.
`meanDfAll`	`readonly`	`number` \	`null`	Mean daylight factor over all of the group's sensors (`mean-df-all`); `null` when absent.
`roomEnd`	`readonly`	`number`	End of the group's rows in `DaylightFactorResult.rooms` (exclusive).
`roomStart`	`readonly`	`number`	First row of the group in `DaylightFactorResult.rooms`.
`start`	`readonly`	`number`	First sensor of the group: sensors `start` up to (not including) `end` of every column.

DaylightLayout

Import from @infrared-city/infrared-sdk.

DaylightLayout = "floors" \| "buildings" \| "surfaces" \| "single"

How the sensors of a daylight-factor result are grouped: "floors", "buildings", "surfaces" or "single" (one group for the whole result).

DaylightResultFormat

Import from @infrared-city/infrared-sdk.

DaylightResultFormat = "irbf" \| "json"

The format of a daylight-factor result.

"irbf": a DaylightFactorResult (typed-array views over one binary frame, with toJson() on demand). Parts ask the server for binary results when it offers them; JSON part results from an older server are converted to the same frame.
"json": the plain JSON value.

DaylightRoom

Import from @infrared-city/infrared-sdk.

One room row of a daylight-factor result. A value of null is the JSON null (not available).

Properties

Property	Modifier	Type	Description
`areaPctDfGe2`	`readonly`	`number` \	`null`	Percentage of the room's area with a daylight factor of at least 2, or `null`.
`floorArea`	`readonly`	`number` \	`null`	Floor area of the room, or `null`.
`id`	`readonly`	`string`	Room id.
`irc`	`readonly`	`number` \	`null`	The room's `irc` value, or `null`.
`maxDf`	`readonly`	`number` \	`null`	Highest daylight factor in the room, or `null`.
`meanDf`	`readonly`	`number` \	`null`	Mean daylight factor of the room, or `null`.
`medianDf`	`readonly`	`number` \	`null`	Median daylight factor of the room, or `null`.
`minDf`	`readonly`	`number` \	`null`	Lowest daylight factor in the room, or `null`.
`name`	`readonly`	`string`	Room name.
`sensors`	`readonly`	`number`	Number of sensors in the room.
`windowArea`	`readonly`	`number` \	`null`	Window area of the room, or `null`.

decompressResultArchive

Import from @infrared-city/infrared-sdk.

decompressResultArchive(content, options?): Uint8Array

Expands one result archive (ZIP or GZIP) into the result document, with bounded output. Raw JSON is not accepted: the content must be an archive.

The limits bound the downloaded compressed bytes and the expanded document. They do not bound the object graph of the JSON parsed from it. Joining the output chunks also needs a temporary destination buffer.

Parameters

Parameter	Type	Description
`content`	`Uint8Array`	The downloaded archive bytes.
`options`	`DecompressResultArchiveOptions`	Size limits; see `DecompressResultArchiveOptions`.

Returns

Uint8Array

The expanded document (JSON or binary result bytes).

Throws

When a limit is not a positive safe integer.

Throws

When the content is not a ZIP or GZIP archive, is truncated, or exceeds a limit.

DecompressResultArchiveOptions

Import from @infrared-city/infrared-sdk.

Size limits for expanding a downloaded result archive.

Properties

Property	Modifier	Type	Description
`maxCompressedBytes?`	`readonly`	`number`	Maximum downloaded archive size in bytes. The default is 64 MiB.
`maxExpandedBytes?`	`readonly`	`number`	Maximum expanded document size in bytes. The default is 512 MiB.

decompressResultValue

Import from @infrared-city/infrared-sdk.

decompressResultValue(jobs, content, options?): unknown

Decodes a downloaded result archive and returns only the decoded value.

JobsService.decompress returns a ParsedResult that also says which route the result took. This function drops that and returns the bare payload, for code written against the older raw-value contract.

Parameters

Parameter	Type	Description
`jobs`	`Pick`<`JobsService`, `"decompress"`>	A `JobsService`, or any object with its `decompress` method.
`content`	`Uint8Array`	The downloaded result archive bytes.
`options?`	`ParseResultOptions`	Optional decoding settings.

Returns

unknown

The decoded payload.

DEFAULT_DAYLIGHT_RESULT_FORMAT

Import from @infrared-city/infrared-sdk.

const DEFAULT\_DAYLIGHT\_RESULT\_FORMAT: DaylightResultFormat = "irbf"

The daylight-factor result format used when none is given: "irbf".

DEFAULT_MAX_LONG_AXIS_PX

Import from @infrared-city/infrared-sdk.

const DEFAULT\_MAX\_LONG\_AXIS\_PX: 960 = 960

The default cap on the long axis of a rendered image, in pixels (960).

A grid at or below the cap renders 1:1, one pixel per cell. A larger grid is sampled nearest-neighbour on its values, so the aspect ratio and no-data cells are kept.

deserializeToCamelCase

Import from @infrared-city/infrared-sdk.

deserializeToCamelCase(value): unknown

Converts the keys of an API response to camelCase, recursively, and leaves the input unchanged.

Parameters

Parameter	Type	Description
`value`	`unknown`	The response object, or any value found inside one.

Returns

unknown

A converted copy; values that are not plain objects or arrays are returned as they are.

DownloadResult

Import from @infrared-city/infrared-sdk.

A downloaded result archive.

Properties

Property	Modifier	Type	Description
`content`	`readonly`	`Uint8Array`	The archive bytes.
`contentType`	`readonly`	`string`	Content type reported for the download.
`jobId`	`readonly`	`string`	Id of the job the results belong to.
`presignedUrl`	`readonly`	`string`	The download URL the archive was fetched from.

FetchRegistryOptions

Import from @infrared-city/infrared-sdk.

Options for fetchVisualConfigurations.

Properties

Property	Type	Description
`fetch?`	\{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; \}	Injectable `fetch`, for tests and for hosts with a custom transport.
`signal?`	`AbortSignal`	The caller's own stop signal. Honoured together with `timeoutMs`.
`timeoutMs?`	`number`	Total time for the answer AND its body, in ms. Defaults to 30 seconds.
`ttlMs?`	`number`	Cache lifetime in ms. Defaults to 15 minutes.
`url?`	`string`	Defaults to REGISTRY\_URL. A custom URL bypasses the cache.

fetchVisualConfigurations

Import from @infrared-city/infrared-sdk.

fetchVisualConfigurations(options?): Promise<RegistryDocument>

Fetch the colour configurations from the public registry.

The answer is cached for ttlMs (15 minutes by default), and the returned object is frozen. A custom url bypasses the cache, so a pinned document never replaces the shared entry. No credentials are sent: the registry is public, and the request is a plain fetch, not the SDK's authenticated connection. Redirects are refused.

Parameters

Parameter	Type	Description
`options`	`FetchRegistryOptions`	Optional URL, cache lifetime, `fetch` implementation, abort signal and timeout (30 seconds by default, covering the answer and its body).

Returns

Promise<RegistryDocument>

The colour configurations and the registry version.

Throws

If the URL is not HTTPS on the registry host, the read fails, times out or is aborted, or the document is not usable.

flattenVisualConfigs

Import from @infrared-city/infrared-sdk.

flattenVisualConfigs(configurations): Record<string, VisualConfig>

Flatten visualConfigurations to a flat lookup table: a simple type keeps its process id, and a multi-variant one contributes process:variant for each variant that carries colors.

Parameters

Parameter	Type	Description
`configurations`	`VisualConfigurations`	The registry's `visualConfigurations` document.

Returns

Record<string, VisualConfig>

Lookup key to colour configuration.

GridCell

Import from @infrared-city/infrared-sdk.

GridCell = number \| string \| null \| undefined

A cell as the API returns it: a number, a wind-comfort class label, or no data.

GridExpectedKind

Import from @infrared-city/infrared-sdk.

GridExpectedKind = "numeric" \| "categorical"

The kind of grid result a caller expects: "numeric" or "categorical".

GridImageSize

Import from @infrared-city/infrared-sdk.

The size of a rendered image, and how many pixels it spends per grid cell.

Properties

Property	Type	Description
`height`	`number`	Image height in pixels.
`scale`	`number`	Output pixels per grid cell on the long axis: `1` for a 1:1 image.
`width`	`number`	Image width in pixels.

gridImageSize

Import from @infrared-city/infrared-sdk.

gridImageSize(png, gridWidth, gridHeight): GridImageSize

The rendered size and the scale factor of a PNG from renderGridPng, for aligning an overlay.

The dimensions are read from the PNG itself. A capped image maps output pixel (x, y) to grid cell (floor((x + 0.5) * gridWidth / width), floor((y + 0.5) * gridHeight / height)), the nearest-neighbour rule.

Parameters

Parameter	Type	Description
`png`	`Uint8Array`	PNG bytes from `renderGridPng`.
`gridWidth`	`number`	Width of the rendered grid, in cells.
`gridHeight`	`number`	Height of the rendered grid, in cells.

Returns

GridImageSize

The image width and height in pixels and the pixels per cell.

Throws

when png is not a PNG or a grid dimension is not positive.

isVertical

Import from @infrared-city/infrared-sdk.

isVertical(result, row): boolean

Tells whether a surface is a wall: its grid normal is at most 30° from horizontal.

Parameters

Parameter	Type	Description
`result`	`SurfaceColumns`	The surface columns.
`row`	`number`	The surface row.

Returns

boolean

True for a wall.

LegendMode

Import from @infrared-city/infrared-sdk.

LegendMode = "exact" \| "trimmed" \| "fixed"

How a legend range is chosen: "exact" (true min/max), "trimmed" (2nd to 98th percentile) or "fixed" (a caller-supplied scale).

LegendRange

Import from @infrared-city/infrared-sdk.

LegendRange = readonly \[number, number\]

A legend range as [min, max], in the units of the result.

legendRange

Import from @infrared-city/infrared-sdk.

legendRange(source, mode?, options?): LegendRange \| undefined

The legend range for one result in the given display mode.

Parameters

Parameter	Type	Default value	Description
`source`	`LegendSource`	`undefined`	An area result, or its grid as a typed array (a `Uint16Array` holds half-precision bits; an `Int16Array` needs the area result for its divisor and `valid`).
`mode`	`LegendMode`	`"exact"`	`"exact"` (default), `"trimmed"` or `"fixed"`.
`options`	`LegendRangeOptions`	`{}`	`fixed` is required for `"fixed"` and refused with any other mode.

Returns

LegendRange \| undefined

The range, or undefined when no cell is finite or, in a measured mode, when the result is categorical.

Throws

on an unknown mode, on "fixed" without a valid fixed range, and on fixed with any other mode.

Throws

when source is not an area result or a typed array.

LegendRangeOptions

Import from @infrared-city/infrared-sdk.

Options for legendRange and sharedLegendRange.

Properties

Property	Modifier	Type	Description
`fixed?`	`readonly`	`LegendRange`	Required for mode `"fixed"` (finite, `min < max`); refused with any other mode.

LegendSource

Import from @infrared-city/infrared-sdk.

LegendSource = Pick<AreaResult, "mergedGrid" \| "legend"> & Partial<Pick<AreaResult, "valueDtype" \| "valueDivisor" \| "valid">> \| Uint16Array \| Float32Array \| Int16Array \| Float64Array

A result to range over: an area result, or its grid on its own.

MAX_REGISTRY_BYTES

Import from @infrared-city/infrared-sdk.

const MAX\_REGISTRY\_BYTES: number

The largest registry document, in bytes, that the SDK will read (8 MiB). A larger answer is refused with a RegistryFetchError.

NO_ROOM

Import from @infrared-city/infrared-sdk.

const NO\_ROOM: 65535 = 0xffff

The room value of a sensor that has no room ("room": null in the JSON result, or a group without rooms).

normalizeGrid

Import from @infrared-city/infrared-sdk.

normalizeGrid(grid): object

Convert a grid as returned by the API into a flat Float32Array plus its size.

null / undefined cells become no-data (NaN). When the last row holds any string, the whole grid is read as wind-comfort classes: an unknown label is no-data and a number stays a number.

Parameters

Parameter	Type	Description
`grid`	readonly readonly `GridCell`\[\]\[\]	Rows of cells: numbers, class labels, `null` or `undefined`.

Returns

object

The row-major values and the grid width and height.

Name	Type
`height`	`number`
`values`	`Float32Array`
`width`	`number`

Throws

when the grid is empty, ragged, holds a non-numeric cell or mixes text into a numeric result.

ParsedResult

Import from @infrared-city/infrared-sdk.

ParsedResult = ParsedSurfaceResult \| \{ route: "json"; value: unknown; \} \| \{ route: "daylight-points"; value: DaylightFactorResult; \}

A parsed result document, tagged by route: "surface" for a surface result, "daylight-points" for a binary daylight-factor result, and "json" for any other result (the decoded JSON value).

ParsedSurfaceResult

Import from @infrared-city/infrared-sdk.

A parsed surface result.

Properties

Property	Modifier	Type	Description
`cellGeometry`	`readonly`	`"complete"` \	`"omitted"`	`"complete"` when every surface has cell geometry, `"omitted"` otherwise.
`route`	`readonly`	`"surface"`	Result discriminator: always `"surface"`.
`value`	`readonly`	`SurfaceResultValue`	The validated surface result.

parseResultArchive

Import from @infrared-city/infrared-sdk.

parseResultArchive(content, options?): ParsedResult

Expands a downloaded result archive and parses the document inside it.

Parameters

Parameter	Type	Description
`content`	`Uint8Array`	The downloaded archive bytes.
`options`	`ParseResultOptions`	Archive limits, expected grid kind and surface options.

Returns

ParsedResult

The parsed result, tagged by route.

Throws

When the archive cannot be expanded or the result is not valid.

ParseResultOptions

Import from @infrared-city/infrared-sdk.

Options for parsing a result.

Properties

Property	Modifier	Type	Description
`archive?`	`readonly`	`DecompressResultArchiveOptions`	Size limits for expanding the archive.
`expectedGridKind?`	`readonly`	`GridExpectedKind`	Require a grid result of this kind; a grid of the other kind is rejected.
`surface?`	`readonly`	`ParseSurfaceOptions`	Options for parsing a surface result.

ParseSurfaceOptions

Import from @infrared-city/infrared-sdk.

Options for parsing a surface result.

Properties

Property	Modifier	Type	Description
`requireCellGeometry?`	`readonly`	`boolean`	Reject a result whose cell geometry (`cell-tris`) was omitted. The parser does not synthesise geometry.

parseSurfaceResult

Import from @infrared-city/infrared-sdk.

parseSurfaceResult(document, options?): ParsedSurfaceResult

Parses and validates one JSON surface result.

Parameters

Parameter	Type	Description
`document`	`Uint8Array`	The UTF-8 JSON bytes of the result.
`options`	`ParseSurfaceOptions`	Surface parse options.

Returns

ParsedSurfaceResult

The validated result with route: "surface".

Throws

When the document does not have the shape of a surface result.

Throws

When requireCellGeometry is set and cell geometry is omitted.

REGISTRY_URL

Import from @infrared-city/infrared-sdk.

const REGISTRY\_URL: "https://registry.infrared.city/models/latest.json" = "https://registry.infrared.city/models/latest.json"

The address of the public registry document that colour configurations are read from. It is served over HTTPS and needs no credentials.

RegistryDocument

Import from @infrared-city/infrared-sdk.

The public colour registry: the colour configurations used to draw results, and the registry version they came from.

Properties

Property	Type	Description
`configurations`	`VisualConfigurations`	The colour configurations, keyed by name. The object is frozen.
`version`	`string` \	`null`	The registry version, or `null` when the document does not state one.

registryFixedRange

Import from @infrared-city/infrared-sdk.

registryFixedRange(analysisType, options?): Promise<LegendRange \| undefined>

The metric's full scale from the public colour registry, for use as legendRange(result, "fixed", { fixed }).

Reads the same cached visualConfigurations document that grid rendering uses.

Parameters

Parameter	Type	Description
`analysisType`	`string`	The analysis whose scale to look up.
`options`	`RegistryFixedRangeOptions`	Variant selectors (`criteria`, `subtype`), an already-fetched registry document, or fetch overrides.

Returns

Promise<LegendRange \| undefined>

The scale, or undefined when the registry has no entry for analysisType, or its steps are class labels or absent (true of many analyses today).

RegistryFixedRangeOptions

Import from @infrared-city/infrared-sdk.

Options for registryFixedRange.

Properties

Property	Modifier	Type	Description
`criteria?`	`readonly`	`string`	Variant selector for analyses with several variants; wins over `subtype`.
`registry?`	`readonly`	`FetchRegistryOptions`	Overrides for the registry fetch.
`subtype?`	`readonly`	`string`	Variant selector, used only when `criteria` is absent.
`visualConfigurations?`	`readonly`	`VisualConfigurations`	Already-fetched `visualConfigurations`; omit it to fetch (and cache).

renderGridPng

Import from @infrared-city/infrared-sdk.

renderGridPng(grid, options?): Promise<Uint8Array<ArrayBufferLike>>

Render a result grid to PNG bytes with the initialized Infrared core.

The image is 1:1, one pixel per grid cell, up to a 960 px long axis; maxLongAxisPx moves that cap and 0 removes it. Colours come from the registry visualConfigurations entry the options resolve to; without one, a default magma_r ramp applies. Read the result size with gridImageSize. initializeCore() must have completed.

The promise only awaits the registry: pass visualConfigurations (or omit analysisType) and it resolves without any network request.

Parameters

Parameter	Type	Description
`grid`	readonly readonly `GridCell`\[\]\[\]	Rows of cells: numbers, class labels, `null` or `undefined`.
`options`	`RenderGridPngOptions`	Analysis type, variant selectors, row order and size cap.

Returns

Promise<Uint8Array<ArrayBufferLike>>

PNG file bytes.

Throws

when the grid is invalid or local rendering fails.

Throws

when the colour registry has to be fetched and the fetch fails.

RenderGridPngOptions

Import from @infrared-city/infrared-sdk.

Options for renderGridPng.

Properties

Property	Type	Description
`analysisType?`	`string`	Analysis process id, e.g. `"pedestrian-wind-comfort"`.
`criteria?`	`string`	Variant selector for analyses with several variants; wins over `subtype`.
`maxLongAxisPx?`	`number`	Cap on the long axis of the image, in pixels. Defaults to `DEFAULT_MAX_LONG_AXIS_PX` (960); `0` renders every cell. Above the cap the grid is sampled nearest-neighbour on its values before it is coloured, so the aspect ratio holds and a no-data cell stays no-data; no blended value appears between two classes.
`registry?`	`FetchRegistryOptions`	Overrides for the registry fetch.
`reverseRows?`	`boolean`	`true` if the caller's grid is already bottom-up. Defaults to `false`.
`subtype?`	`string`	Variant selector, used only when `criteria` is absent.
`visualConfigurations?`	`VisualConfigurations`	Already-fetched `visualConfigurations`. Supply it to skip the network entirely; omit it and the registry is fetched (and cached) on demand.

resolveVisualConfig

Import from @infrared-city/infrared-sdk.

resolveVisualConfig(configurations, analysisType, selectors?): VisualConfig \| undefined

The colour configuration for one analysis type, or undefined when the registry has none.

The bare analysisType wins; only if it is absent does criteria (then subtype) select a variant. undefined is not an error: the renderer falls back to its default magma_r ramp.

Parameters

Parameter	Type	Description
`configurations`	`VisualConfigurations`	The registry's `visualConfigurations` document.
`analysisType`	`string`	Analysis process id, e.g. `"pedestrian-wind-comfort"`.
`selectors`	\{ `criteria?`: `string`; `subtype?`: `string`; \}	Optional variant selectors; `criteria` wins over `subtype`.
`selectors.criteria?`	`string`	-
`selectors.subtype?`	`string`	-

Returns

VisualConfig \| undefined

The matching configuration, or undefined.

sharedLegendRange

Import from @infrared-city/infrared-sdk.

sharedLegendRange(sources, mode?, options?): LegendRange \| undefined

One legend range pooled over several results.

Every finite cell of every result is pooled and mode is applied once, so "trimmed" is the percentile of the pooled data, never a union of per-result percentiles. Categorical results are left out in the measured modes.

Parameters

Parameter	Type	Default value	Description
`sources`	readonly `LegendSource`\[\]	`undefined`	Area results, or their grids.
`mode`	`LegendMode`	`"exact"`	`"exact"` (default), `"trimmed"` or `"fixed"`.
`options`	`LegendRangeOptions`	`{}`	`fixed` is required for `"fixed"` and refused with any other mode.

Returns

LegendRange \| undefined

The pooled range, or undefined when nothing finite remains.

Throws

when sources is not an array, or an entry is not an area result or a typed array.

SurfaceAnalysisResponse

Import from @infrared-city/infrared-sdk.

A surface analysis result: the sensor grid of each surface, per-building aggregates and the legend range.

Properties

Property	Modifier	Type	Description
`aggregates`	`readonly`	`Readonly`<`Record`<`string`, `Readonly`<`Record`<`string`, `BuildingAggregate`>>>>	Aggregates by group (for example `buildings`), then by id within the group.
`maxLegend`	`readonly`	`number`	Upper end of the colour legend.
`minLegend`	`readonly`	`number`	Lower end of the colour legend.
`sensorCount`	`readonly`	`number`	Total number of sensors.
`surfaces`	`readonly`	`Readonly`<`Record`<`string`, `SurfaceSensorGrid`>>	The sensor grid of each surface, by surface id.

SurfaceColumns

Import from @infrared-city/infrared-sdk.

The merged surface result of an area run, as columns.

There is one typed array per per-surface field (S surfaces), one per per-cell field (C cells in total) and a triangle table, rather than an object per surface. Every array owns its whole buffer, so the result can be transferred to another thread as it is, and a renderer can upload triangles.positions[g] without a copy.

Surface i has the id ids.slice(idOffsets[i], idOffsets[i + 1]), its vectors are origin[3i..3i+3] (and likewise the axes), and its cells are values[cellOffsets[i]..cellOffsets[i + 1]]. Look a surface up by id with surfaceIndex. Join two results by surface id and cell index, never by row: the row order follows the run's entries, not the order the jobs were submitted in.

Properties

Property	Modifier	Type	Description
`aggregates`	`readonly`	`Readonly`<`Record`<`string`, `Readonly`<`Record`<`string`, `BuildingAggregate`>>>>	Aggregates by group (for example `buildings`), then by id within the group.
`area`	`readonly`	`Float64Array`	`S`: the area of each surface.
`cellArea?`	`readonly`	`Float32Array`<`ArrayBufferLike`>	`C`, present when some surface sent an array: NaN for `null` (and for other surfaces' cells).
`cellAreaState`	`readonly`	`Uint8Array`	`S`: the wire's `cell-area` for the surface: 0 absent, 1 `null`, 2 an array.
`cellOffsets`	`readonly`	`Uint32Array`	`S + 1`: cuts every per-cell column into surfaces.
`cellTrisFallback?`	`readonly`	readonly `string`\[\]	Absent unless triangles were requested and at least one job fell back: the sorted reasons (for example `"hash_mismatch"`). Each fallback is also logged at `warn`.
`extra?`	`readonly`	`Readonly`<`Record`<`number`, `Readonly`<`Record`<`string`, `unknown`>>>>	The fields no column holds, by surface row. Absent when no surface sent one.
`gridSize`	`readonly`	`Float64Array`	`S`: the cell edge length of each surface.
`idOffsets`	`readonly`	`Uint32Array`	`S + 1`: cuts `ids` (string indices).
`ids`	`readonly`	`string`	Every surface id, back to back.
`kind`	`readonly`	`"surface-columns"`	Result discriminator: always `"surface-columns"`.
`layoutKey?`	`readonly`	`string`	The key of the layout of the values (surfaces, frames, outline): the same for every analysis and run on the same geometry, surface settings and packing, so build render geometry once per key. Absent when a job had no layout hash.
`maxLegend`	`readonly`	`number`	Upper end of the colour legend.
`mean`	`readonly`	`Float64Array`	`S`: the mean value of each surface.
`minLegend`	`readonly`	`number`	Lower end of the colour legend.
`nu`	`readonly`	`Uint32Array`	`S`: the number of cells along the u axis of each surface.
`nv`	`readonly`	`Uint32Array`	`S`: the number of cells along the v axis of each surface.
`origin`	`readonly`	`Float64Array`	`3S`: each surface grid's origin in the run's frame.
`outline?`	`readonly`	`Float32Array`<`ArrayBufferLike`>	`6T`, present on a facade or roof run of this client (the join rebuilds the layout from the kept capture): the outline triangles of all surfaces in row order, in cell units from the corner of cell (0,0), `s0 t0 s1 t1 s2 t2`. `surfaceRenderBuffers` reads it; a saved layout gives the outline through `options.layout` instead.
`outlineOffsets?`	`readonly`	`Uint32Array`<`ArrayBufferLike`>	`S + 1`, with `outline`: surface row `i` owns outline triangles `outlineOffsets[i]..[i + 1]`.
`peak`	`readonly`	`Float64Array`	`S`: the peak value of each surface.
`sensorCount`	`readonly`	`number`	Total number of sensors.
`surfaceCount`	`readonly`	`number`	`S`, the number of surfaces.
`triangles?`	`readonly`	`SurfaceTriangles`	Present when triangles were requested (`emitCellTris`) or the server sent some.
`uAxis`	`readonly`	`Float64Array`	`3S`: the direction of each surface grid's u axis.
`valid?`	`readonly`	`Uint8Array`<`ArrayBufferLike`>	Present only when `valueDtype` is `"i16"`: one bit per cell, least significant bit first (cell `c` is bit `c % 8` of byte `c >> 3`), set when the cell has a value.
`valueDivisor`	`readonly`	`number`	`1` unless `valueDtype` is `"i16"`; then physical value = value / `valueDivisor`.
`valueDtype`	`readonly`	`SurfaceValueDtype`	The type of `values`.
`values`	`readonly`	`SurfaceValues`	`C`: the value of each cell, in the type the server stored it (`valueDtype`). This keeps the result at 2 or 4 bytes per cell, not 8. Do not read a number from it directly: use `surfaceHasValue` to test a cell and `surfaceValuesF32` for the physical values. - `"f16"`: a `Uint16Array` of IEEE half-precision BITS (JavaScript has no common 16-bit float array). NaN bits mean no value. - `"f32"`, `"f64"`: NaN means no value. - `"i16"`: scaled integers; physical value = value / `valueDivisor`. An `Int16Array` has no NaN: `valid` tells which cells have a value.
`vAxis`	`readonly`	`Float64Array`	`3S`: the direction of each surface grid's v axis.
`version`	`readonly`	`2`	Layout version of this result: always `2` (since 1.0.0 `values` keeps the server's type).

surfaceColumnsFromBytes

Import from @infrared-city/infrared-sdk.

surfaceColumnsFromBytes(bytes): object

Loads the blob of surfaceColumnsToBytes. The columns have no outline: pass the saved layout to surfaceRenderBuffers. They also have no triangles.

Parameters

Parameter	Type	Description
`bytes`	`Uint8Array`	The blob.

Returns

object

The columns and the layoutKey saved with them (undefined when none was given).

Name	Type
`columns`	`SurfaceColumns`
`layoutKey?`	`string`

Throws

When the bytes are not a blob, or its version is unknown.

surfaceColumnsToBytes

Import from @infrared-city/infrared-sdk.

surfaceColumnsToBytes(columns, options?): Uint8Array

Saves the values of one result as one blob: the values in the type the server stored, the surface ids, the grid placement of each surface, the per-surface numbers, the legend and the aggregates. It holds no outline and no triangles: the outline comes from the saved layout (surfaceRenderBuffers(columns, { layout })). The blob starts with a version; a reader refuses a version it does not know.

Store one layout per geometry (FacadeLayout.toBytes) and one blob per simulation. Give the layoutKey of the layout the result belongs to; read it back with surfaceColumnsFromBytes and pass it as expectedLayoutKey to attachValues.

Parameters

Parameter	Type	Description
`columns`	`SurfaceColumns`	The surface columns of a run.
`options`	\{ `layoutKey?`: `string`; \}	`layoutKey`, the key of the layout the result belongs to.
`options.layoutKey?`	`string`	-

Returns

Uint8Array

The blob.

Throws

When the columns hold a field the blob has no place for (extra).

SurfaceEntry

Import from @infrared-city/infrared-sdk.

One surface of a surface result, keyed as in the JSON document (origin, u-axis, v-axis, grid-size, nu, nv, area, mean, peak, values, and optionally cell-area and cell-tris).

Extends

Record<string, unknown>

Indexable

\[key: string\]: unknown

Properties

Property	Type	Description
`cell-tris?`	(`number`\[\] \	`null`)\[\] \	`null`	Render triangles of each cell (9 numbers per triangle); absent or `null` when omitted.
`cellTris?`	`Float32Array`<`ArrayBufferLike`>	The per-cell triangles `runAndWait` draws for one facade job with `emitCellTris: true` (9 floats per triangle; a view on one buffer shared by the surfaces).
`cellTrisOffsets?`	`Uint32Array`<`ArrayBufferLike`>	`cells + 1`: cell `c` owns `cellTris[cellTrisOffsets[c]..cellTrisOffsets[c + 1]]`.
`values`	`Float64Array`<`ArrayBufferLike`> \	(`number` \	`null`)\[\]	The value of each cell (`nu * nv` entries); `null` or `NaN` marks a cell without a value.

surfaceHasValue

Import from @infrared-city/infrared-sdk.

surfaceHasValue(result, cell): boolean

Tells whether a cell has a value. Use it for every type of values: NaN ("f16" bits, "f32", "f64") or a clear valid bit ("i16") means no value.

Parameters

Parameter	Type	Description
`result`	`SurfaceColumns`	The surface columns.
`cell`	`number`	The cell index, from `0` to `cellOffsets[surfaceCount] - 1`.

Returns

boolean

True when the cell has a value.

surfaceId

Import from @infrared-city/infrared-sdk.

surfaceId(result, row): string

Returns the id of a surface.

Parameters

Parameter	Type	Description
`result`	`SurfaceColumns`	The surface columns.
`row`	`number`	The surface row, from `0` to `surfaceCount - 1`.

Returns

string

The surface id.

surfaceIndex

Import from @infrared-city/infrared-sdk.

surfaceIndex(result): ReadonlyMap<string, number>

Maps each surface id to its row. The map is built on first use and kept with the result.

Parameters

Parameter	Type	Description
`result`	`SurfaceColumns`	The surface columns.

Returns

ReadonlyMap<string, number>

A map from surface id to row.

SurfaceRenderBuffers

Import from @infrared-city/infrared-sdk.

The buffers a renderer needs to draw a surface result: one record per frame, the outline triangles of each frame, one value per cell and a validity bit per cell.

A renderer draws each frame as the triangles of its outline. A vertex (s, t) of the outline is at corner + s * uStep + t * vStep, where s and t count cells. The fragment stage finds the cell of a point and reads its value. Every array owns its buffer: you can transfer it to another thread, and it stays valid for as long as you keep it.

Properties

Property	Modifier	Type	Description
`anchor`	`readonly`	`Float64Array`	`3`: the centroid of the frame corners, in the run's frame. Add it back in 64-bit floats.
`anyValid`	`readonly`	`boolean`	`false` when no cell has a value.
`dims`	`readonly`	`Uint32Array`	`3S`: for each frame `nu`, `nv` and `cellStart` (the first cell of the frame in `values`).
`frames`	`readonly`	`Float32Array`	`9S`: for each frame `corner`, `uStep`, `vStep`, relative to `anchor`.
`outline`	`readonly`	`Float32Array`	`6T`: the outline triangles of all frames, `s0 t0 s1 t1 s2 t2`, in cell units.
`outlineOffsets`	`readonly`	`Uint32Array`	`S + 1`: frame `f` owns outline triangles `outlineOffsets[f]..outlineOffsets[f + 1]`.
`validity`	`readonly`	`Uint8Array`	`ceil(C / 8)`: cell `k` is bit `k & 7` of byte `k >> 3`; set when the cell has a value.
`valueDtype`	`readonly`	`"f16"` \	`"f32"`	The type of `values`.
`valueMax`	`readonly`	`number`	The greatest value over the valid cells, `0` when there is none.
`valueMin`	`readonly`	`number`	The least value over the valid cells, `0` when there is none.
`values`	`readonly`	`Float32Array`<`ArrayBufferLike`> \	`Uint16Array`<`ArrayBufferLike`>	`C`: the value of a valid cell, `0` for a cell without a value. Half float BITS in a `Uint16Array` when `valueDtype` is `"f16"`, else a `Float32Array`. Never NaN or infinite.

surfaceRenderBuffers

Import from @infrared-city/infrared-sdk.

surfaceRenderBuffers(columns, options?): SurfaceRenderBuffers

Builds the render buffers of a surface result.

The outline comes from options.layout (a saved layout: FacadeLayout.fromBytes), or from the columns themselves: a facade or roof result of this client has one.

Parameters

Parameter	Type	Description
`columns`	`SurfaceColumns`	The surface columns.
`options`	`SurfaceRenderOptions`	`layout`, the layout that holds the outline.

Returns

SurfaceRenderBuffers

The render buffers, as owned typed arrays.

Throws

When there is no outline, when a surface is not in the layout, or when a column breaks the contract (for example a frame with cells and no outline triangle, or a grid larger than 65,535 cells on a side). The message names the frame.

SurfaceRenderOptions

Import from @infrared-city/infrared-sdk.

The options of surfaceRenderBuffers.

Properties

Property	Modifier	Type	Description
`layout?`	`readonly`	`FacadeLayout`	A saved or rebuilt layout that holds the outline of each surface. Each surface of the columns is found in it by id. Check the pair first with `attachValues`.

SurfaceResultValue

Import from @infrared-city/infrared-sdk.

A validated surface result: the surfaces by id, plus any other fields of the document.

Extends

Record<string, unknown>

Indexable

\[key: string\]: unknown

Properties

Property	Type	Description
`surfaces`	`Record`<`string`, `SurfaceEntry`>	The surfaces, by surface id.

SurfaceSensorGrid

Import from @infrared-city/infrared-sdk.

The sensor grid of one surface: its placement, cell values and summary statistics.

The surface result of a single job is read as a map of these. An area run's merged surface result is SurfaceColumns instead.

Extends

Readonly<Record<string, unknown>>

Indexable

\[key: string\]: unknown

Properties

Property	Modifier	Type	Description
`area`	`readonly`	`number`	Total area of the surface's cells.
`cellArea?`	`readonly`	readonly (`number` \	`null`)\[\]	Area of each cell, when the result carries it.
`cellTris?`	`readonly`	readonly (readonly `number`\[\] \	`null`)\[\]	Render triangles of each cell (9 numbers per triangle), when the result carries them.
`gridSize`	`readonly`	`number`	Cell edge length.
`mean`	`readonly`	`number`	Mean value over the surface.
`nu`	`readonly`	`number`	Number of cells along the u axis.
`nv`	`readonly`	`number`	Number of cells along the v axis.
`origin`	`readonly`	readonly `number`\[\]	Grid origin `[x, y, z]`.
`peak`	`readonly`	`number`	Peak value over the surface.
`uAxis`	`readonly`	readonly `number`\[\]	Direction of the grid's u axis `[x, y, z]`.
`values`	`readonly`	`Float64Array`<`ArrayBufferLike`> \	readonly (`number` \	`null`)\[\]	The value of each cell (`nu * nv` entries); `null` or `NaN` marks a cell without a value.
`vAxis`	`readonly`	readonly `number`\[\]	Direction of the grid's v axis `[x, y, z]`.

SurfaceTriangles

Import from @infrared-city/infrared-sdk.

The render triangles of a run, in groups. One group is one job (a tile, or a batch of one). Positions are 32-bit float metres in the job's tile-local frame, and anchors[2g], anchors[2g + 1] is the tile's south-west offset they still owe to x and y. Keep the anchor out of the float data and add it as the mesh's position (a 64-bit float in JavaScript), which keeps city-scale coordinates exact.

Properties

Property	Modifier	Type	Description
`anchors`	`readonly`	`Float64Array`	`2G`: each group's tile SW offset, owed to x and y.
`cellOffsets`	`readonly`	`Uint32Array`	`C + 1`: cell `c` owns triangles `cellOffsets[c]..cellOffsets[c + 1]` (global index).
`drawn`	`readonly`	`Uint8Array`	`C`: 1 when the cell has geometry, 0 for a cell without a sensor.
`groupEngaged`	`readonly`	`Uint8Array`	`G`: 1 when the group has triangles, 0 when its job fell back.
`groupSurfaces`	`readonly`	`Uint32Array`	`G + 1`: group `g` holds surfaces `groupSurfaces[g]..groupSurfaces[g + 1]`.
`groupTriangles`	`readonly`	`Uint32Array`	`G + 1`: group `g` holds triangles `groupTriangles[g]..groupTriangles[g + 1]`.
`positions`	`readonly`	readonly `Float32Array`<`ArrayBufferLike`>\[\]	`G`: 9 floats per triangle; the triangles of group `g` in its cell order.

SurfaceValueDtype

Import from @infrared-city/infrared-sdk.

SurfaceValueDtype = "f16" \| "f32" \| "i16" \| "f64"

The type of SurfaceColumns.values, as the server stored the values: "f16" (raw half bits in a Uint16Array), "f32", "i16" (scaled integers: physical value = value / valueDivisor) or "f64" (a JSON result, or a run that mixes types).

SurfaceValues

Import from @infrared-city/infrared-sdk.

SurfaceValues = Uint16Array \| Float32Array \| Int16Array \| Float64Array

The typed array of SurfaceColumns.values, one per SurfaceValueDtype.

surfaceValuesF32

Import from @infrared-city/infrared-sdk.

surfaceValuesF32(result, first?, last?): Float32Array

Returns the physical values of cells first to last - 1 as 32-bit floats, NaN for a cell without a value. It applies the type and the divisor in one call for the range. The result is a new array; values does not change. Call initializeCore() first.

Parameters

Parameter	Type	Default value	Description
`result`	`SurfaceColumns`	`undefined`	The surface columns.
`first`	`number`	`0`	The first cell. Default `0`.
`last`	`number`	`result.values.length`	One past the last cell. Default: every cell.

Returns

Float32Array

One value per cell of the range.

vertexValues

Import from @infrared-city/infrared-sdk.

vertexValues(result, group): Float32Array

Returns the value of each vertex of a group's triangles (three per triangle, aligned with triangles.positions[group]): the physical value of the cell the triangle draws, NaN for a cell without one. A renderer can upload it as an attribute next to the positions.

Parameters

Parameter	Type	Description
`result`	`SurfaceColumns`	The surface columns.
`group`	`number`	The triangle group (one job).

Returns

Float32Array

One value per vertex.

Throws

When the result has no triangles.

VisualConfig

Import from @infrared-city/infrared-sdk.

One colour configuration from the registry: the colours of a result and how to step through them.

Indexable

\[key: string\]: unknown

Properties

Property	Type
`colorInterpolation?`	`string`
`colors`	`number`\[\]\[\]
`steps?`	(`string` \	`number`)\[\] \	`null`

VisualConfigurations

Import from @infrared-city/infrared-sdk.

VisualConfigurations = Record<string, unknown>

The registry's visualConfigurations object, with all variants included, keyed by configuration name.

windClassOrdinals

Import from @infrared-city/infrared-sdk.

windClassOrdinals(): Record<string, number>

The wind-comfort class table, mapping a class label to its ordinal, e.g. {A: 0, .., S: 5, S15: 5, S20: 6}.

A label outside the table is treated as no-data, never as a clamped class. initializeCore() must have completed.

Returns

Record<string, number>

Class label to ordinal.