npm package: @ruijingrs/ol-raster-tile-layer
Description: A raster tile layer for OpenLayers
Latest version: 0.9.5

# 基于 Openlayers 的栅格数据瓦片图层

## 1. 介绍

**欢迎使用中科锐景数据产品。**

基于中科锐景的栅格数据瓦片服务，提供基于`Openlayers`的栅格数据瓦片图层，方便用户快速集成数据瓦片图层。

## 2. 安装

```bash
npm install @ruijingrs/ol-raster-tile-layer
# or
yarn add @ruijingrs/ol-raster-tile-layer
```

## 3. 基础使用(以 PM2.5 为例)

```js
import { RasterTileLayer } from '@ruijingrs/ol-raster-tile-layer';

const instance = new RasterTileLayer({
  type: 'PM25',
  agg: 'daily',
  time: '2023/01/01 00:00:00',
  token: 'token from ruijing',
  opacity: 0.88,
  clipGeoJsonUrl: '/geojson/450000.json',
  pickTrigger: 'hover',
  pickDataCallback: (value) => {
    if (value) {
      // do something with value
    }
  },
});

const { dataTileLayer, clipLayer } = instance;

new Map({
  layers: [tianditu, tiandituAn, dataTileLayer, clipLayer],
  target: 'map',
  view: new View({
    projection: 'EPSG:3857',
    center: fromLonLat([108, 23]),
    zoom: 7,
    minZoom: 4,
    maxZoom: 16,
  }),
});
```

### 4. 参数说明

| 类型             | 是否必填 | 默认值  | 说明                                                                                                                                                                                                                                                              |
| ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type             | 必填     | -       | 数据类型，目前支持 `PM25`、 `PM10`、 `O3`、 `O3TCD`、 `NO2`、`NO2TCD`、 `SO2`、 `CO2`、 `CH4`、 `CO`、 `HCHO`、 `TMP`、 `PRE`、 `VIS`、 `RH`、 `PRS`、 `UVA`、 `UVB`、`UVT`、`AOD`、 `TCOLOR`、 `DCOLOR`。                                                        |
| agg              | 必填     | -       | 栅格数据聚合类型, 目前支持`none`、`daily`、`monthly`                                                                                                                                                                                                              |
| time             | 必填     | -       | 栅格数据时间，格式为`YYYY/MM/DD HH:mm:ss`                                                                                                                                                                                                                         |
| token            | 必填     | -       | 获取栅格数据瓦片用户凭证                                                                                                                                                                                                                                          |
| domainAndColors  | 选填     | -       | 数据值域及颜色配置，如需配置，建议数组长度大于`4`，如`[{ min: 0, max: 45, color: '#01a0ff', }, { min: 45, max: 55, color: '#00c8c7', }, { min: 55, max: 65, color: '#00dc00', }, { min: 65, max: 75, color: '#a1e632', }, { min: 75, max: 85, color: '#e6dc33'}]` |
| visible          | 选填     | true    | 图层是否可见                                                                                                                                                                                                                                                      |
| opacity          | 选填     | 1       | 图层透明度                                                                                                                                                                                                                                                        |
| clipGeoJsonUrl   | 选填     | -       | 裁剪图层的 geojson 文件地址                                                                                                                                                                                                                                       |
| pickTrigger      | 选填     | 'click' | 触发 pickDataCallback 的事件类型，目前支持 'click', 'hover'                                                                                                                                                                                                       |
| pickDataCallback | 选填     | -       | 当鼠标 hover 或者 click 时，返回当前像素点携带的数据                                                                                                                                                                                                              |

#### 4.1 type(必填)

当前数据类型，指定后，将使用对应的解码公式解析源瓦片像素点所携带的数值。目前支持 `PM25`、 `PM10`、 `O3`、 `O3TCD`、 `NO2`、`NO2TCD`、 `SO2`、 `CO2`、 `CH4`、 `CO`、 `HCHO`、 `TMP`、 `PRE`、 `VIS`、 `RH`、 `PRS`、 `UVA`、 `UVB`、`UVT`、`AOD`、 `TCOLOR`、 `DCOLOR`。

| 类型   | 说明                             |
| ------ | -------------------------------- |
| PM25   | 粒径小于或等于 2.5 微米的 颗粒物 |
| PM10   | 粒径在 10 微米以下的颗粒物       |
| O3     | 臭氧                             |
| O3TCD  | 臭氧柱浓度                       |
| NO2    | 二氧化氮                         |
| NO2TCD | 二氧化氮柱浓度                   |
| SO2    | 二氧化硫                         |
| CO2    | 二氧化碳                         |
| CH4    | 甲烷                             |
| CO     | 一氧化碳                         |
| HCHO   | 甲醛                             |
| TMP    | 温度                             |
| PRE    | 降水                             |
| VIS    | 能见度                           |
| RH     | 相对湿度                         |
| PRS    | 气压                             |
| UVA    | 紫外线 A                         |
| UVB    | 紫外线 B                         |
| UVT    | 总辐射                           |
| AOD    | 大气光学厚度                     |
| TCOLOR | 真彩图                           |
| DCOLOR | 假彩图                           |

#### 4.2 agg(必填)

栅格数据瓦片聚合类型

- `type`取值`CO2` 时，`agg`只能设置为`monthly`
- `type`取值`O3`、`O3TCD`、`NO2`、`NO2TCD`、`SO2`、`CH4`、`CO`、`HCHO`时，`agg`只能设置为`daily`
- `type`取值`TCOLOR`、`DCOLOR`时，`agg`只能设置为`none`
- `type`取值`PM25`、`PM10`、`AOD`、`TMP`、`PRE`、`VIS`、`RH`、`PRS`、`UVA`、`UVB`、`UVT`时，`agg`可设置为`none`或`daily`

#### 4.3 time(必填)

栅格数据瓦片的数据时间，格式为`YYYY/MM/DD HH:mm:ss`，如`2023/01/01 00:00:00`。

- `agg`取值为`none`时，`time`可按小时聚合设置为`2023/02/01 09:00:00`、`2023/02/01 10:00:00`
- `agg`取值为`daily`时，小时只能为`00`点, 如`2023/02/20 00:00:00`
- `agg`取值为`monthly`时，`time`可设置为当月第一天的`00`点，如`2023/02/01 00:00:00`

#### 4.4 token(必填)

获取栅格数据瓦片的用户凭证

#### 4.5 domainAndColor(可选)

包含值域最大值和最小值及颜色的数组，如

```js
const domainAndColor = [
  {
    min: 0,
    max: 5,
    color: '#34b300',
  },
  {
    min: 5,
    max: 10,
    color: '#3ecf00',
  },
  {
    min: 10,
    max: 15,
    color: '#46e800',
  },
  {
    min: 15,
    max: 20,
    color: '#99fd0b',
  },
  {
    min: 20,
    max: 25,
    color: '#a9ff00',
  },
  {
    min: 25,
    max: 30,
    color: '#daff00',
  },
  // ...
];
```

#### 4.6 visible(可选)

图层是否可见，默认为 true。

#### 4.7 opacity(可选)

图层的透明度，范围：0-1，默认为 1。

#### 4.8 clipGeoJsonUrl(可选)

用于裁切图层的 GeoJSON 数据地址，如果不配置，则不进行裁切。

#### 4.9 pickDataCallback(可选)

鼠标划过或者点击时，返回当前像素点携带的数据，返回值为数字或 null。

- `TCOLOR`及`DCOLOR`类型不支持取值回调
- 裁切瓦片后未显示部分也会返回数据，需根据经纬度范围自行判断。

数据类型对应单位

| 类型   | 单位           |
| ------ | -------------- |
| PM25   | ug/m³          |
| PM10   | ug/m³          |
| O3     | ug/m³          |
| O3TCD  | ug/m³          |
| NO2    | ug/m³          |
| NO2TCD | 1e16molec./c㎡ |
| SO2    | du             |
| CO2    | PPM            |
| CH4    | ppb            |
| CO     | 1e19molec./cm² |
| HCHO   | 1e16molec./c㎡ |
| TMP    | ℃              |
| PRE    | mm             |
| VIS    | km             |
| RH     | %              |
| PRS    | hPa            |
| UVA    | W/m²           |
| UVB    | W/m²           |
| UVT    | W/m²           |
| AOD    | 无             |

#### 4.10 pickTrigger(可选)

`pickDataCallback`的触发方式，目前支持`hover`和`click`，默认为`click`。

### 5. 实例方法

#### 5.1 setType(type)

重新设置图层的数据类型

```js
const instance = new RasterTileLayer({
  type: 'PM25',
  agg: 'daily',
  time: '2023/01/01 00:00:00',
  token: 'token from ruijing',
});

const { dataTileLayer, clipLayer } = instance;

document.querySelector('#typeSelect').addEventListener('change', (e) => {
  const { value } = e.target; // PM25 | PM10 | ....

  instance.setType(value);
});
```

#### 5.2 setAgg(agg)

重新设置图层的数据聚合类型，注：`setAgg`一般与`setTime`配合使用

```js
const instance = new RasterTileLayer({
  type: 'PM25',
  agg: 'daily',
  time: '2023/01/01 00:00:00',
  token: 'token from ruijing',
});

const { dataTileLayer, clipLayer } = instance;

document.querySelector('#aggSelect').addEventListener('change', (e) => {
  const { value } = e.target; // none | daily | monthly

  instance.setAgg(value);
});
```

#### 5.3 setTime(time)

重新设置图层的数据聚合类型

```js
const instance = new RasterTileLayer({
  type: 'PM25',
  agg: 'daily',
  time: '2023/01/01 00:00:00',
  token: 'token from ruijing',
});

const { dataTileLayer, clipLayer } = instance;

document.querySelector('#changeTimeBtn').addEventListener('click', (e) => {
  instance.setTime('2023/02/01 00:00:00');
});
```

#### 5.4 setDomainAndColor(domainAndColor)

根据瓦片携带的数据，以配置的值域及颜色进行显示，`TCOLOR`及`DCOLOR`类型不支持设置值域及颜色

```js
const instance = new RasterTileLayer({
  type: 'PM25',
  agg: 'daily',
  time: '2023/01/01 00:00:00',
  token: 'token from ruijing',
});

// 更新图层值域范围及颜色
const btn = document.querySelector('#btn');
btn.addEventListener('click', () => {
  instance.setDomainAndColors([
    {
      min: 0,
      max: 5,
      color: '#c60000',
    },
    {
      min: 5,
      max: 10,
      color: '#9d0056',
    },
    // ...
  ]);
});
```

#### 5.5 getCurrentDomainAndColor()

获取当前图层值域范围和颜色，用于图例展示等。

```js
const instance = new RasterTileLayer({
  type: 'PM25',
  agg: 'daily',
  time: '2023/01/01 00:00:00',
  token: 'token from ruijing',
});

const domainAndColor = instance.getCurrentDomainAndColor();
```

### 6. 图层方法

#### 6.1 setOpacity(number)

设置图层透明度

```js
// ...
const { dataTileLayer, clipLayer } = instance;

const rangeInput = document.querySelector('#range');
rangeInput.addEventListener('change', (e) => {
  dataTileLayer.setOpacity(e.target.value / 100);
});
```

#### 6.2 setVisible(boolean)

设置图层可见性

```js
// ...
const { dataTileLayer, clipLayer } = instance;

const btn = document.querySelector('#btn');
btn.addEventListener('click', () => {
  dataTileLayer.setVisible(!dataTileLayer.getVisible());
});
```