@nsc-earth-2/heat

Introduction

This is a package for creating heatmap layers on CesiumJS map. It provides an easy way to create and customize heatmaps using the heatmap.js library.

中文 Readme

Installation

npm install @nsc-earth-2/heat

Usage

Importing

import HeatMapLayer from "@nsc-earth-2/heat";

Creating a layer

const viewer = new Cesium.Viewer("cesiumContainer");
const data = [
  { pos: [lon1, lat1], value: value1 },
  { pos: [lon2, lat2], value: value2 },
  // ...
];
const heatmap = new HeatMapLayer({
  viewer,
  data,
});

The data parameter is an array of objects with pos and value properties. pos is an array of longitude and latitude, and value is the value at that location.

Customizing the heatmap

const heatmap = new HeatMapLayer({
  viewer,
  data,
  heatStyle: {
    radius: 20,
    maxOpacity: 0.5,
    blur: 0.8,
  },
});

The heatStyle parameter can be used to customize the appearance of the heatmap. The available options are:

• radius: the radius of each point in pixels.
• maxOpacity: the maximum opacity (transparency) of each point.
• blur: the amount of blur to apply to each point.

Auto-resizing canvas

const heatmap = new HeatMapLayer({
  viewer,
  data,
  canvasConfig: {
    autoResize: true,
    minSize: 1024,
    maxSize: 10000,
  },
});

By default, the canvas used to render the heatmap is fixed at a certain size. However, it can be set to auto-resize based on the number of data points. The canvasConfig parameter can be used to configure this behavior. The available options are:

• autoResize: whether to enable auto-resizing.
• minSize: the minimum size of the canvas in pixels.
• maxSize: the maximum size of the canvas in pixels.

Auto-adjusting radius

const heatmap = new HeatMapLayer({
  viewer,
  data,
  autoRadiusConfig: {
    enabled: true,
    min: 1000000,
    max: 10000000,
    minRadius: 1,
    maxRadius: 10,
  },
});

The radius of each point can be automatically adjusted based on the current camera height. This can be enabled by setting the enabled property of the autoRadiusConfig object to true. The min and max properties specify the range of camera heights, and the minRadius and maxRadius properties specify the corresponding range of point radii.

Updating the data

heatmap.data = newData;

The data property can be used to update the heatmap with new data.

Changing the configuration

heatmap.changeConfig({ radius: 30 });

The appearance of the heatmap can be changed dynamically by calling the changeConfig method and passing a new configuration object.

Removing the layer

heatmap.remove();

The heatmap layer can be removed from the map by calling the remove method.

Destroying the layer

heatmap.destroy();

The heatmap layer can be completely destroyed (including its container) by calling the destroy method.

Full Example

Here is an example of using the HeatMapLayer class to create a heatmap layer on a CesiumJS map:

import HeatMapLayer from "@nsc-earth-2/heat";

const viewer = new Cesium.Viewer("cesiumContainer");

// Data for the heatmap
const data = [
  { pos: [-122.4194, 37.7749], value: 20 },
  { pos: [-74.0059, 40.7128], value: 30 },
  { pos: [139.6917, 35.6895], value: 15 },
  // ...
];

// Create the heatmap layer
const heatmap = new HeatMapLayer({
  viewer,
  data,
  heatStyle: {
    radius: 20,
    maxOpacity: 0.5,
    blur: 0.8,
  },
  autoRadiusConfig: {
    enabled: true,
    min: 1000000,
    max: 10000000,
    minRadius: 1,
    maxRadius: 10,
  },
});

// Update the data after a delay
setTimeout(() => {
  const newData = [
    { pos: [-122.4194, 37.7749], value: 30 },
    { pos: [-74.0059, 40.7128], value: 10 },
    { pos: [139.6917, 35.6895], value: 25 },
    // ...
  ];
  heatmap.data = newData;
}, 5000);

// Change the configuration after a delay
setTimeout(() => {
  heatmap.changeConfig({ radius: 30 });
}, 10000);

// Remove the layer after a delay
setTimeout(() => {
  heatmap.remove();
}, 15000);

API Reference

new HeatMapLayer(options: HeatMapLayerContructorOptions)

Creates a new HeatMapLayer instance with the specified options.

options.viewer: Viewer

The CesiumJS Viewer to add the heatmap layer to.

options.data: HeatMapDataItem[]

An array of objects representing the data points of the heatmap. Each object should have a pos property, which is an array of longitude and latitude, and a value property, which is the value at that location.

options.heatStyle?: BaseHeatmapConfiguration

Optional configuration for the appearance of the heatmap. See heatmap.js documentation for more information.

options.canvasSize?: number

Deprecated. Use options.canvasConfig.width and options.canvasConfig.height instead.

options.bbox?: number[]

Deprecated. Use options.tolerance instead.

options.autoRadiusConfig?: AutoRadiusConfig

Optional configuration for automatically adjusting the point radius based on camera height. See the example above for more information.

options.tolerance?: number

Optional buffer width (in degrees) around the data range. This can be used to avoid edge effects when displaying the heatmap near the edges of the map.

options.canvasConfig?: CanvasConfig

Optional configuration for the heatmap canvas. See the example above for more information.

Properties

heatmap.data: HeatMapDataItem[]

Gets or sets the data points of the heatmap.

heatmap.show: boolean

Gets or sets whether the heatmap layer is visible on the map.

heatmap.autoRadiusConfig: Required<AutoRadiusConfig>

Gets or sets the configuration for automatically adjusting the point radius based on camera height. See the example above for more information.

heatmap.dataRange: { west: number; east: number; sourth: number; north: number; min: number; max: number; }

Returns the data range (in longitude, latitude, and value) of the current data.

Methods

heatmap.changeConfig(config: BaseHeatmapConfiguration | undefined): void

Changes the configuration of the heatmap. See heatmap.js documentation for more information.

heatmap.updateCesium(): void

Updates the heatmap on the CesiumJS map.

heatmap.convertHeatItem(heatItems: HeatMapDataItem[]): DataPoint[]

Converts an array of HeatMapDataItem objects to an array of DataPoint objects, which can be used by the heatmap.js library.

heatmap.convertPos(pos: number[]): number[]

Converts a longitude-latitude pair to an x-y pair on the canvas.

heatmap.remove(): boolean

Removes the heatmap layer from the CesiumJS map.

heatmap.destroy(): boolean

Destroys the heatmap layer (including itscontainer) and removes it from the CesiumJS map.

Type Definitions

HeatMapDataItem

An object representing a single data point of the heatmap.

interface HeatMapDataItem {
  pos: [number, number];
  value: number;
}

BaseHeatmapConfiguration

A configuration object for the appearance of the heatmap. See heatmap.js documentation for more information.

interface BaseHeatmapConfiguration {
  gradient?: Gradient | Record<string, string>;
  minOpacity?: number;
  maxOpacity?: number;
  blur?: number;
  radius?: number;
  backgroundColor?: string;
  opacity?: number;
}

AutoRadiusConfig

A configuration object for automatically adjusting the point radius based on camera height.

interface AutoRadiusConfig {
  enabled?: boolean;
  min: number;
  max: number;
  minRadius: number;
  maxRadius: number;
}

CanvasConfig

A configuration object for the heatmap canvas.

interface CanvasConfig {
  autoResize?: boolean;
  minSize?: number;
  maxSize?: number;
  width?: number;
  height?: number;
}

DataPoint

An object representing a single data point in the format expected by the heatmap.js library.

interface DataPoint {
  x: number;
  y: number;
  value: number;
}

Gradient

A gradient object used to colorize the heatmap.

type Gradient = Record<number, string>;

Credit

https://github.com/postor/cesiumjs-heat