---
title: Vegetation
source: https://infrared.city/docs/sdk/1.0/api/typescript/vegetation/
---

# Vegetation

<a id="acquiretrees"></a>

## acquireTrees

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

> **acquireTrees**(`bbox`, `options?`): `Promise`&lt;[`DirectTreesResult`](geodata.md#directtreesresult)&gt;

Read trees for an area, returning parsed feature objects.

The same read as [acquireTreesJson](vegetation.md#acquiretreesjson), parsed once.

### Parameters

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

### Returns

`Promise`&lt;[`DirectTreesResult`](geodata.md#directtreesresult)&gt;

The tree features, the contributing sources and any warnings.

### Throws

when the global OpenStreetMap read fails.

### Throws

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

***

<a id="acquiretreesjson"></a>

## acquireTreesJson

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

> **acquireTreesJson**(`bbox`, `options?`): `Promise`&lt;[`DirectTreesJson`](geodata.md#directtreesjson)&gt;

Read trees for an area straight from the public data hosts, as JSON text.

Reads the global OpenStreetMap tree layer and, when the area falls inside a
registered city (and `bestAvailable` is not `false`), that city's open-data
overlay, in parallel. The two are normalised and merged, with the city's trees
winning over coincident OpenStreetMap trees. If only the overlay fails, the
result is still returned and a `<city>_overlay_unavailable` warning is added.

### Parameters

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

### Returns

`Promise`&lt;[`DirectTreesJson`](geodata.md#directtreesjson)&gt;

The features as JSON array text, the contributing sources and any
  warnings.

### Throws

when the global OpenStreetMap read fails.

### Throws

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

***

<a id="areavegetation"></a>

## AreaVegetation

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

Trees read for an area.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areavegetation-analysistype"></a> `analysisType` | `readonly` | `string` | The analysis type the read margin was taken from. |
| <a id="areavegetation-executiontime"></a> `executionTime` | `readonly` | `number` | Time the read took, in seconds. |
| <a id="areavegetation-failedtiles"></a> `failedTiles` | `readonly` | readonly `string`\[\] | Ids of the tiles whose read failed; their trees are missing from `features`. |
| <a id="areavegetation-features"></a> `features` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt;&gt;&gt; | The tree features, keyed by tree id, after duplicates between tiles are removed. |
| <a id="areavegetation-polygon"></a> `polygon` | `readonly` | [`Polygon`](tiling.md#polygon) | The polygon that was read. |
| <a id="areavegetation-readmarginm"></a> `readMarginM` | `readonly` | `number` | Half extent, in metres, of the read rectangle every tile was fetched with: 363 for the wind analyses and 544 for the others. `runArea` refuses a run whose analysis needs more than this. |
| <a id="areavegetation-totaltrees"></a> `totalTrees` | `readonly` | `number` | Number of trees in `features`. |

***

<a id="convertpointstomesheslocal"></a>

## convertPointsToMeshesLocal

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

> **convertPointsToMeshesLocal**(`featureCollection`, `options?`): [`VegetationMesh`](vegetation.md#vegetationmesh)\[\]

Converts tree Point features to dotbim meshes, locally.

Errors are typed and never collapse to `[]`: an empty result means the input
held no convertible trees, never that the conversion failed.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `featureCollection` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | A feature collection with `referencePoint: [lon, lat]` and `features` (GeoJSON Point features). |
| `options` | `Pick`&lt;[`ToMeshesOptions`](vegetation.md#tomeshesoptions), `"registryJson"`&gt; | `registryJson` replaces the built-in tree registry. |

### Returns

[`VegetationMesh`](vegetation.md#vegetationmesh)\[\]

One mesh per convertible tree.

### Throws

when `featureCollection` is not an object, has no
  valid `referencePoint` or no `features` array, or the conversion fails.

***

<a id="geojsonfeaturecollection"></a>

## GeoJsonFeatureCollection

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

> **GeoJsonFeatureCollection** = `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; & `object`

A GeoJSON feature collection: `type` is `"FeatureCollection"` and `features`
holds the features.

### Type Declaration

| Name | Type |
| ------ | ------ |
| `features?` | `ReadonlyArray`&lt;`Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt;&gt; |
| `type?` | `string` |

***

<a id="tomeshesoptions"></a>

## ToMeshesOptions

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

Options for `VegetationService.toMeshes`.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="tomeshesoptions-converter"></a> `converter?` | `readonly` | `"local"` | Where the conversion runs. Only `"local"` is supported, and it is the default. |
| <a id="tomeshesoptions-registryjson"></a> `registryJson?` | `readonly` | `string` | Replaces the built-in tree registry document with your own, as JSON text. |

***

<a id="treesfeaturecollection"></a>

## treesFeatureCollection

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

> **treesFeatureCollection**(`result`): `Record`&lt;`string`, `unknown`&gt;

Convert an acquired tree result into a GeoJSON FeatureCollection.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `result` | [`DirectTreesResult`](geodata.md#directtreesresult) | The result of [acquireTrees](vegetation.md#acquiretrees). |

### Returns

`Record`&lt;`string`, `unknown`&gt;

A `FeatureCollection` object holding the tree features.

***

<a id="vegetationmesh"></a>

## VegetationMesh

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

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

### Extends

- `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt;

### Indexable

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

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="vegetationmesh-coordinates"></a> `coordinates` | `readonly` | readonly `number`\[\] | Flat vertex coordinates `[x, y, z, ...]`, in metres in the local frame. |
| <a id="vegetationmesh-indices"></a> `indices` | `readonly` | readonly `number`\[\] | Flat triangle vertex indices. |
| <a id="vegetationmesh-mesh_id"></a> `mesh_id` | `readonly` | `number` | Identifier of the mesh. |

***

<a id="vegetationregistrydocument"></a>

## vegetationRegistryDocument

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

> **vegetationRegistryDocument**(): `string`

The built-in tree registry document, as JSON text.

Pass an edited copy as `registryJson` to replace it.

### Returns

`string`

The registry document.

***

<a id="vegetationservice"></a>

## VegetationService

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

Reads tree locations from the public data hosts and converts them to meshes.

The service takes only the transport settings of `ServiceOptions` (`fetch`,
`timeoutMs`, `logger`) and sends no API key anywhere.

### Constructors

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

#### Constructor

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

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ServiceOptions`](client.md#serviceoptions) | Transport settings: `fetch`, `timeoutMs` and `logger` are used for the public reads; `baseUrl` and `auth` are accepted but not used. |

##### Returns

`VegetationService`

### Methods

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

#### getArea()

> **getArea**(`polygon`, `options?`): `Promise`&lt;[`AreaVegetation`](vegetation.md#areavegetation)&gt;

Reads the trees over a polygon area, tile by tile.

Tiles are read concurrently, and trees found in more than one tile are
listed once. A tile whose read fails is skipped and listed in `failedTiles`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `polygon` | [`Polygon`](tiling.md#polygon) | The area to read: a GeoJSON `Polygon` with one closed ring of `[longitude, latitude]` positions. |
| `options` | \{ `analysisType?`: `string`; `maxTilesOverride?`: `number`; `maxWorkers?`: `number`; `signal?`: `AbortSignal`; \} | `maxWorkers` is the number of tiles read at once (default 10), `maxTilesOverride` raises the tile limit, `analysisType` sets the tile grid and read margin, and `signal` cancels the read. |
| `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. Omit it for the widest margin, which is valid for every analysis. |
| `options.maxTilesOverride?` | `number` | Raises the cap on non-empty tiles (100 by default); a larger area is refused without it. |
| `options.maxWorkers?` | `number` | Number of tiles read at once. Default 10. |
| `options.signal?` | `AbortSignal` | Stops the read: requests in flight abort, and no tile starts after it. |

##### Returns

`Promise`&lt;[`AreaVegetation`](vegetation.md#areavegetation)&gt;

The trees with the read's margin and any failed tiles.

##### Throws

when the read of every tile fails.

##### Throws

when `options` carries the removed `acquisition` option.

***

<a id="vegetationservice-getgeojson"></a>

#### getGeoJson()

> **getGeoJson**(`lat`, `lon`, `distance`): `Promise`&lt;[`GeoJsonFeatureCollection`](vegetation.md#geojsonfeaturecollection) \| `null`&gt;

Reads the trees around one point.

##### Parameters

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

##### Returns

`Promise`&lt;[`GeoJsonFeatureCollection`](vegetation.md#geojsonfeaturecollection) \| `null`&gt;

A feature collection, or `null` when there are no trees there. Any
  read warnings are listed under `_warnings`.

***

<a id="vegetationservice-tomeshes"></a>

#### toMeshes()

> **toMeshes**(`featureCollection`, `options?`): [`VegetationMesh`](vegetation.md#vegetationmesh)\[\]

Converts tree Point features to dotbim meshes, locally.

`converter` accepts only `"local"`; any other value is an error rather than
a silent local run.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `featureCollection` | [`GeoJsonFeatureCollection`](vegetation.md#geojsonfeaturecollection) | A feature collection with `referencePoint: [lon, lat]` and `features` (GeoJSON Point features). |
| `options` | [`ToMeshesOptions`](vegetation.md#tomeshesoptions) | Optional `converter` and `registryJson`. |

##### Returns

[`VegetationMesh`](vegetation.md#vegetationmesh)\[\]

One mesh per convertible tree.

##### Throws

when `converter` is not `"local"`, the input is
  malformed, or the conversion fails.

***