Appearance
plugin-heat-map
热力图。
样例
安装
bash
npm install @soonspacejs/plugin-heat-map -S
# or
yarn add @soonspacejs/plugin-heat-map -S使用方法
js
import SoonSpace from 'soonspacejs';
import HeatMapPlugin from '@soonspacejs/plugin-heat-map';
const ssp = new SoonSpace({
el: '#view',
options: {},
events: {},
});
const heatMap = ssp.registerPlugin(HeatMapPlugin, 'heatMap');
consolo.log(heatMap);方法
create
创建热力图
定义
ts
interface SceneDataPoint {
x: number;
z: number;
value: number;
radius: number;
}
interface CreateParam {
// base
id: string;
name?: PluginObject['name'];
data: SceneDataPoint[];
// position
yAxisHeight: number;
minPosition: PlaneIVector2;
maxPosition: PlaneIVector2;
// value
min?: number;
max?: number;
radius?: number;
}
function create(param: CreateParam): PluginObject;用法：
js
heatMap.create({
id: 'hm1',
name: 'hm_name',
yAxisHeight: 100,
max: 100,
min: 1,
minPosition: {
x: 0,
z: 0,
},
maxPosition: {
x: 200,
z: 200,
},
data: [
{
x: 100,
z: 100,
radius: 100,
value: 80,
},
{
x: 200,
z: 50,
radius: 50,
value: 80,
},
{
x: 100,
z: 50,
radius: 50,
value: 80,
},
],
});参数：
param
- 描述: 创建热力图参数
- 必填:
- 类型:
CreateParam
CreateParam
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| id | 热力图对象 ID | string | ||
| name | 热力图对象名称 | string | ||
| data | 热力图数据 | DataPoint | ||
| max | 数据中单点值大于等于该值时，以最深热力颜色展示 | number | 100 | |
| min | 数据中单点值小于等于该值时，以最浅热力颜色展示 | number | 1 | |
| radius | 热力点半径 | number | 100 | |
| yAxisHeight | 空间高度 | number | ||
| minPosition | 热力图绘制区域最小点 | PlaneIVector2 | ||
| maxPosition | 热力图绘制区域最大点 | PlaneIVector2 |
DataPoint
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| x | 点位在空间平面内的水平位置 | number | ||
| z | 点位在空间平面内的垂直位置 | number | ||
| value | 热力值 | number | ||
| radius | 热力点半径 | number | 100 |
注意
x、z 的位置需要在 minPosition 和 maxPosition 之间，否则不会渲染
radius 的显示范围会随着画布区域放大与缩小
setData
设置（重置）数据
定义：
ts
function setData(id: CreateParam['id'], data: SceneDataPoint[]): PluginObject | void;用法：
js
heatMap.setData('hm1', [
{
x: 100,
z: 100,
radius: 100,
value: Math.floor(Math.random() * 100),
},
{
x: 200,
z: 50,
radius: 50,
value: Math.floor(Math.random() * 100),
},
{
x: 100,
z: 50,
radius: 50,
value: Math.floor(Math.random() * 100),
},
]);参数：
id
- 描述: 已创建热力图的 id
- 必填:
- 类型: CreateParam['id']
data
- 描述: 新点位数据
- 必填:
- 类型: SceneDataPoint[]
createPolygon
创建一个具有多边形边界的热力图。
通过 points 选项来设置多边形的顶点的世界坐标。
它会根据你传入的顶点，来创建多边形边界，该多边形边界会以前 3 个顶点所确定的平面来作为多边形边界的所在平面，对于那些不与该多边形共面的点，会向该平面上投影，然后将最终的投影点作为多边形边界的顶点。
热力图所需的数据点也是世界坐标系下的三维坐标，它会自动将数据点转换成在多边形平面上的投影点并将该投影点作为热力图最终的数据点。
样例
与create()对比
用户在使用热力图时，一般期望的逻辑是：
- 传给热力图的数据都是世界坐标系下的数据，这样用户不必做数据的转换
- 可以自定义热力图的边界，因为经常会在不规则的区域内绘制热力图，比如：地铁的站台层、大厅 或 非矩形的房间等。
- 如果移动了热力图对象，原来的热力点的数据也能下确映射。
在这种场景下，使用 create() 创建热力图会有以下缺点：
- 热力图区域只能是 水平的 且是 矩形的，不可以是任意多边形，用户只能手动旋转来让水平的热力图变得倾斜，但这样的话，用户又必须自己将热力点数据从世界坐标系转到 倾斜状态下的局部坐标系。
- 热力图的数据点是 二维局部坐标，用户需要将世界坐标系的点转为二维的 且是 局部的坐标（如果有对热力图对象被移动、旋转或缩放等变换之后）。
- 如果热力图绘制好后，更改了位置、旋转，则用户需要重新将世界坐标系下的热力点针对新的位置和旋转再次进行转换。
createPolygon()就是为了解决上述缺点而生，所以 createPolygon() 具备以下特点
- 用户可以传递世界坐标系下的三维顶点列表
points来作为热力图的绘制区域，所以热力图区域可以是任意多边形 且 可以是斜着的。 - 热力图的数据点是 三维的世界坐标，用户不需要额外的转换。
- 如果热力图绘制好后，更改了位置、旋转等，原来的热力图数据点不需要专门转换，
createPolygon()和setDataPolygon()会自动进行转换。
定义
ts
interface ScenePolygonDataPoint {
x: number;
y: number;
z: number;
value: number;
radius: number;
}
export interface CreatePolygonParam {
id: string;
name?: PluginObject['name'];
data: ScenePolygonDataPoint[];
points: IVector3[];
min?: number;
max?: number;
radius?: number;
}
createPolygon ( param: CreatePolygonParam ): PluginObject;用法：
js
heatMap.createPolygon({
id: 'hm1',
name: 'hm_name',
max: 100,
min: 1,
points:[
{
x: 0,
y: 0,
z: 0,
},
{
x: 0,
y: 0,
z: 100,
},
{
x: 0,
y: 100,
z: 100,
},
]
data: [
{
x: 100,
y: 100,
z: 100,
radius: 100,
value: 80
},
{
x: 200,
y: 200,
z: 50,
radius: 50,
value: 80
},
{
x: 100,
y: 100,
z: 50,
radius: 50,
value: 80
},
]
})参数：
param
- 描述: 创建热力图参数
- 必填:
- 类型:
CreatePolygonParam
CreateParam
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| id | 热力图对象 ID | string | ||
| name | 热力图对象名称 | string | ||
| data | 热力图数据 | ScenePolygonDataPoint[] | ||
| max | 数据中单点值大于等于该值时，以最深热力颜色展示 | number | 100 | |
| min | 数据中单点值小于等于该值时，以最浅热力颜色展示 | number | 1 | |
| radius | 热力点半径 | number | 100 | |
| points | 多边形的顶点列表 | IVector3[] |
ScenePolygonDataPoint
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| x | 点在世界坐标系下3维坐标的 x | number | ||
| y | 点在世界坐标系下3维坐标的 y | number | ||
| z | 点在世界坐标系下3维坐标的 z | number | ||
| value | 热力值 | number | ||
| radius | 热力点半径 | number | 100 |
注意
如果坐标点在多边形平面的投影点不在多边形区域内的话，就不会渲染该热力点
radius 的显示范围会随着画布区域放大与缩小
setDataPolygon
设置（重置）数据
定义：
ts
setDataPolygon ( id: CreateParam['id'], data: CreatePolygonParam['data'] ): PluginObject | void用法：
js
heatMap.setDataPolygon('hm1', [
{
x: 100,
y: 100,
z: 100,
radius: 100,
value: Math.floor(Math.random() * 100),
},
{
x: 200,
y: 200,
z: 50,
radius: 50,
value: Math.floor(Math.random() * 100),
},
{
x: 100,
y: 100,
z: 50,
radius: 50,
value: Math.floor(Math.random() * 100),
},
]);参数：
id
- 描述: 已创建热力图的 id
- 必填:
- 类型: CreateParam['id']
data
- 描述: 新点位数据
- 必填:
- 类型: ScenePolygonDataPoint[]
getById
通过 id 创建热力图
用法：
js
heatMap.getById('hm1');参数：
- id: string
getByName
通过 name 创建热力图
用法：
js
heatMap.getByName('hm_name');参数：
- name: string
removeById
通过 id 删除热力图
用法：
js
heatMap.removeById('hm1');参数：
- id: string
createDrawing
通过鼠标操作在多边形内快速绘制热力图。
通过 points 选项来设置多边形的顶点的世界坐标。
它会根据你传入的顶点，来创建多边形边界，该多边形边界会以前 3 个顶点所确定的平面来作为多边形边界的所在平面，对于那些不与该多边形共面的点，会向该平面上投影，然后将最终的投影点作为多边形边界的顶点。
样例
用法：
js
const drawingHeatObj = heatMapPlugin.createDrawing({
id: 'polygon',
name: 'polygon_name',
points: [
{
x: 0,
y: 0,
z: 0,
},
{
x: 0,
y: 0,
z: 100,
},
{
x: 0,
y: 100,
z: 100,
},
],
onAdd: (point, data) => {
console.log('新增热力点：', point, data);
},
onUndo: (point, data) => {
console.log('删除热力点：', point, data);
},
});
drawingHeatObj
.start()
.then((res) => {
console.log('绘制完成', res);
})
.catch((res) => {
console.log('取消绘制', res);
});参数：
param
- 描述: 快速绘制热力图参数
- 必填:
- 类型:
DrawingParam
DrawingParam
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| id | 热力图对象 ID | string | ||
| name | 热力图对象名称 | string | ||
| points | 多边形的顶点列表 | IVector3[] | ||
| data | 热力图数据 | ScenePolygonDataPoint[] | ||
| max | 数据中单点值大于等于该值时，以最深热力颜色展示 | number | 100 | |
| min | 数据中单点值小于等于该值时，以最浅热力颜色展示 | number | 1 | |
| radius | 热力点半径 | number | 100 | |
| value | 热力点值，该值为number时，所有热力点值为该值，该值为数组时，热力点值在此区间随机生成 | number | [number, number] | min-max间的随机数 | |
| timeInterval | 节流时间间隔(ms) | number | 60 | |
| distanceInterval | 节流距离间隔 | number | 5 | |
| addTriggerType | 增加热力点方式 | ['time', 'drag', 'click', 'mouseMove', 'rightClick', 'dblClick'] | ['click', 'mouseMove'] | |
| doneTriggerType | 完成绘制方式 | ['click', 'mouseMove', 'rightClick', 'dblClick', { keyDown: [ 'Enter' ], }] | ['dblClick', { keyDown: [ 'Enter' ], }] | |
| undoTriggerType | 撤销热力点方式 | ['click', 'mouseMove', 'rightClick', 'dblClick', {keyDown: ['Backspace']}] | ['rightClick', {keyDown: ['Backspace']}] | |
| onAdd | 添加热力点的回调函数 | ( point: ScenePolygonDataPoint, data: ScenePolygonDataPoint[] ) => void | ||
| onUndo | 撤销热力点的回调函数 | ( point: ScenePolygonDataPoint, data: ScenePolygonDataPoint[] ) => void | ||
| beforePointUpdate | 更新（添加、删除）前回调函数，返回值为true 或 ScenePolygonDataPoint更新，返回值为false不更新 | (type: 'add' | 'undo', point: ScenePolygonDataPoint) => boolean | ScenePolygonDataPoint |
方法：
start
开始绘制热力点
cancel
取消绘制热力点，清除绘制的热力点，reject 数据，在 catch 中获取
dispose
销毁热力图