---
title: Ground materials
source: https://infrared.city/docs/sdk/1.0/api/typescript/ground-materials/
---

# Ground materials

<a id="acquiregroundmaterials"></a>

## acquireGroundMaterials

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

> **acquireGroundMaterials**(`bbox`, `options?`): `Promise`&lt;[`DirectGroundResult`](geodata.md#directgroundresult)&gt;

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

The same composition as [acquireGroundMaterialsJson](ground-materials.md#acquiregroundmaterialsjson), parsed once for a
caller that wants objects.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `bbox` | [`Bbox`](geodata.md#bbox) | The area's bounding box in WGS84 degrees. |
| `options` | [`AcquireGroundOptions`](geodata.md#acquiregroundoptions) | Read and frame options. |

### Returns

`Promise`&lt;[`DirectGroundResult`](geodata.md#directgroundresult)&gt;

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

### Throws

when the optional parquet reader packages are
  not installed.

### Throws

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

***

<a id="acquiregroundmaterialsarea"></a>

## acquireGroundMaterialsArea

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

> **acquireGroundMaterialsArea**(`site`, `options`): `Promise`&lt;[`GroundAreaResult`](geodata.md#groundarearesult)&gt;

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

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

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `site` | [`Bbox`](geodata.md#bbox) | The site's bounding box in WGS84 degrees. |
| `options` | [`AcquireGroundAreaOptions`](geodata.md#acquiregroundareaoptions) | Cleaning extent, optional tile rectangles and read options. |

### Returns

`Promise`&lt;[`GroundAreaResult`](geodata.md#groundarearesult)&gt;

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

### Throws

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

### Throws

when the optional parquet reader packages are
  not installed.

***

<a id="acquiregroundmaterialsjson"></a>

## acquireGroundMaterialsJson

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

> **acquireGroundMaterialsJson**(`bbox`, `options?`): `Promise`&lt;[`AcquireGroundJson`](geodata.md#acquiregroundjson)&gt;

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

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

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `bbox` | [`Bbox`](geodata.md#bbox) | The area's bounding box in WGS84 degrees. |
| `options` | [`AcquireGroundOptions`](geodata.md#acquiregroundoptions) | Read and frame options. |

### Returns

`Promise`&lt;[`AcquireGroundJson`](geodata.md#acquiregroundjson)&gt;

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

### Throws

when the optional parquet reader packages are
  not installed.

### Throws

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

***

<a id="areagroundmaterials"></a>

## AreaGroundMaterials

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

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

### Properties

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

***

<a id="cleanv3local"></a>

## cleanV3Local

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

> **cleanV3Local**(`layers`, `params`): [`MaterialLayers`](ground-materials.md#materiallayers)

Clean ground materials locally, using the initialized Infrared core.

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

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

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `layers` | [`MaterialLayers`](ground-materials.md#materiallayers) | Material name to GeoJSON feature collection (WGS84 degrees). |
| `params` | [`CleanV3Params`](ground-materials.md#cleanv3params) | The centre point, crop distance and layer options. |

### Returns

[`MaterialLayers`](ground-materials.md#materiallayers)

The cleaned layers, keyed by material name.

***

<a id="cleanv3params"></a>

## CleanV3Params

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

Parameters for cleaning ground-material layers around a point.

### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="cleanv3params-defaultlayer"></a> `defaultLayer?` | `string` | Name of the default (background) material layer. |
| <a id="cleanv3params-distance"></a> `distance` | `number` | Distance from the centre point to the edge of the cropped area, in metres. |
| <a id="cleanv3params-latitude"></a> `latitude` | `number` | Latitude of the centre point, in degrees. |
| <a id="cleanv3params-longitude"></a> `longitude` | `number` | Longitude of the centre point, in degrees. |
| <a id="cleanv3params-zstep"></a> `zStep?` | `number` | Vertical step between stacked material layers, in metres. Defaults to `0.05`. |

***

<a id="featurecollection"></a>

## FeatureCollection

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

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

### Indexable

> \[`key`: `string`\]: `unknown`

### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="featurecollection-features"></a> `features?` | `Record`&lt;`string`, `unknown`&gt;\[\] | The GeoJSON features (polygons in WGS84 degrees). |
| <a id="featurecollection-type"></a> `type?` | `string` | The GeoJSON type, normally `"FeatureCollection"`. |

***

<a id="groundmaterialcleaner"></a>

## GroundMaterialCleaner

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

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

### Methods

<a id="groundmaterialcleaner-cleanv3"></a>

#### cleanV3()

> **cleanV3**(`layers`, `params`): `Promise`&lt;[`MaterialLayers`](ground-materials.md#materiallayers)&gt;

Clean the layers around the point given in `params`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `layers` | [`MaterialLayers`](ground-materials.md#materiallayers) | Material name to GeoJSON feature collection. |
| `params` | [`CleanV3Params`](ground-materials.md#cleanv3params) | The centre point, crop distance and layer options. |

##### Returns

`Promise`&lt;[`MaterialLayers`](ground-materials.md#materiallayers)&gt;

The cleaned layers.

***

<a id="groundmaterialscleaner"></a>

## GroundMaterialsCleaner

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

> **GroundMaterialsCleaner** = [`GroundMaterialCleaner`](ground-materials.md#groundmaterialcleaner)

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

***

<a id="groundmaterialsservice"></a>

## GroundMaterialsService

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

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

### Constructors

<a id="groundmaterialsservice-constructor"></a>

#### Constructor

> **new GroundMaterialsService**(`options`): `GroundMaterialsService`

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`ServiceOptions`](client.md#serviceoptions) |

##### Returns

`GroundMaterialsService`

### Methods

<a id="groundmaterialsservice-getarea"></a>

#### getArea()

> **getArea**(`polygon`, `options?`): `Promise`&lt;[`AreaGroundMaterials`](ground-materials.md#areagroundmaterials)&gt;

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

##### Parameters

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

##### Returns

`Promise`&lt;[`AreaGroundMaterials`](ground-materials.md#areagroundmaterials)&gt;

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

##### Throws

when the removed `acquisition` option is passed.

***

<a id="groundmaterialsservice-getraw"></a>

#### getRaw()

> **getRaw**(`lat`, `lon`, `distance`): `Promise`&lt;[`MaterialLayers`](ground-materials.md#materiallayers) \| `null`&gt;

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

##### Parameters

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

##### Returns

`Promise`&lt;[`MaterialLayers`](ground-materials.md#materiallayers) \| `null`&gt;

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

***

<a id="localcleaner"></a>

## LocalCleaner

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

A `GroundMaterialCleaner` that cleans locally with `cleanV3Local`.

### Implements

- [`GroundMaterialCleaner`](ground-materials.md#groundmaterialcleaner)

### Constructors

<a id="localcleaner-constructor"></a>

#### Constructor

> **new LocalCleaner**(): `LocalCleaner`

##### Returns

`LocalCleaner`

### Methods

<a id="localcleaner-cleanv3"></a>

#### cleanV3()

> **cleanV3**(`layers`, `params`): `Promise`&lt;[`MaterialLayers`](ground-materials.md#materiallayers)&gt;

Clean the layers locally. Equivalent to calling `cleanV3Local`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `layers` | [`MaterialLayers`](ground-materials.md#materiallayers) | Material name to GeoJSON feature collection. |
| `params` | [`CleanV3Params`](ground-materials.md#cleanv3params) | The centre point, crop distance and layer options. |

##### Returns

`Promise`&lt;[`MaterialLayers`](ground-materials.md#materiallayers)&gt;

The cleaned layers.

##### Implementation of

[`GroundMaterialCleaner`](ground-materials.md#groundmaterialcleaner).[`cleanV3`](ground-materials.md#groundmaterialcleaner-cleanv3)

***

<a id="materiallayers"></a>

## MaterialLayers

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

> **MaterialLayers** = `Record`&lt;`string`, [`FeatureCollection`](ground-materials.md#featurecollection)&gt;

Ground material name to GeoJSON feature collection.

***

<a id="roadstoirfeatures"></a>

## roadsToIrFeatures

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

> **roadsToIrFeatures**(`features`): `Record`&lt;`string`, `unknown`&gt;\[\]

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

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

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

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `features` | readonly `Record`&lt;`string`, `unknown`&gt;\[\] | Road features as read from the world FlatGeobuf file. |

### Returns

`Record`&lt;`string`, `unknown`&gt;\[\]

The normalised road features.

***