Warning

Nightly releases are generated automatically from the latest source code and are intended for experimental purposes only. These builds may contain incomplete or untested features, bugs, or security vulnerabilities, and as such, are not for production use. Users should be aware that nightly releases may cause unexpected behavior, data loss, or system instability. Use of these releases is at the user's own risk, and it is advised to have adequate backups before testing. The software is provided as is with no guarantees or support.

ViewerHeatmapAPI

Interface ViewerHeatmapAPI

ViewerHeatmapAPI

Overview

The ViewerHeatmapAPI provides functionality to visualize a heatmap based on a given set of points.

Quick Start

Example: Adding heatmap data and configuring the heatmap:

// get an instance of the ContextAPI and the matching ViewerAPI
const context = webvis.getContext();
const viewer = context.getViewer();

// add the model
const model = context.add({ dataURI: MODEL, initialProperties: { enabled: true } });

// add matching heatmap data
const heatmapPositions = [
  0, 1, 0, // first point
  0, 1, 1, // second point
  0, 0, 2, // third point
];
const heatmapDataId = viewer.createHeatmap({ position: heatmapPositions });

// configure the heatmap
viewer.configureHeatmap({
  // set a color scheme
  colorScheme: "Blackbody",
  // calculated density is normalized, upper end of color scheme is mapped to maxValue
  maxValue: 100,
}

Events

The following events are associated with the ViewerHeatmapAPI:

interface ViewerHeatmapAPI {
    changeGlobalHeatmapConfig(config: HeatmapConfig): void;
    changeHeatmap(id: number, properties: HeatmapProperties): void;
    createHeatmap(properties: HeatmapProperties): number;
    getGlobalHeatmapConfig(): HeatmapConfig;
    getHeatmapColorSchemeLegend(): number[];
    getHeatmapData(id: number): HeatmapProperties;
    getHeatmaps(): number[];
    removeHeatmap(id: number): void;
}

Hierarchy (View Summary)

Methods

changeGlobalHeatmapConfig changeHeatmap createHeatmap getGlobalHeatmapConfig getHeatmapColorSchemeLegend getHeatmapData getHeatmaps removeHeatmap

Methods

changeGlobalHeatmapConfig

  • changeGlobalHeatmapConfig(config: HeatmapConfig): void
  • Experimental

    Experimental. May be changed in the future without notice.

    Configures global heatmap settings and triggers a ViewerHeatmapConfigChangedEvent.

    Parameters

    Returns void

    Example: Configuring the heatmap:

    viewer.changeGlobalHeatmapConfig({
  // set a color scheme
  colorScheme: webvis.HeatmapColorScheme.BLACKBODY,
  // calculated density is normalized, upper end of color scheme is mapped to maxValue
  maxValue: 100,
  // configure heatmap to be had 5 separated bands of colors (smooth gradient by default)
  colorBands: true,
  colorResolution: 5,
  // kernel defines the falloff from a point's center to its edge
  // this defaults to a gaussian curve, but other options are available
  kernel: webvis.HeatmapKernal.LINEAR,
  // scale all points' size uniformly for more/less overlap
  sizeFactor: 2,
  // scale all point's strength uniformly
  // this has the same effect as adjusting maxValue by the inverse factor
  strengthFactor: 1.5,
});

changeHeatmap

  • changeHeatmap(id: number, properties: HeatmapProperties): void
  • Experimental

    Experimental. May be changed in the future without notice.

    Changes one or more properties of the heatmap with the specified ID and triggers a ViewerHeatmapCreatedEvent.

    Parameters

    Returns void

    Example: Adding points to an existing heatmap dataset:

    // [continued createHeatmapData example]

// add points
heatmapPositions.push(
  1, 3, 0, // fourth point
  3, 0, 1, // fifth point
)

// update data by passing id and data to override
viewer.changeHeatmap(heatmapDataId, { position: heatmapPositions });

createHeatmap

  • createHeatmap(properties: HeatmapProperties): number
  • Experimental

    Experimental. May be changed in the future without notice.

    Creates a new heatmap and triggers a ViewerHeatmapCreatedEvent.

    Parameters

    Returns number

    ID of dataset or -1 if an error occurred.

    Example: Adding heatmap data:

    // positions are stored in a flat array
const heatmapPositions = [
  0, 1, 0, // first point
  0, 1, 1, // second point
  0, 0, 2, // third point
];
const heatmapDataId = viewer.createHeatmap({ position: heatmapPositions });

    Example: Adding heatmap data with varying size/strength:

    By specifying per-point size and/or strength, you can tweak ther influence on the heatmap. This example defines two points:

    • Small radius and high strength. Represents a precisely located but highly important issue.
    • High radius and low strength. Represents a low-priority issue affecting a larger area.

    Note: The number of points defined by position, size and strength must match. Since position contains the coordinates, its length must be three times that of size and strength.

    const position = [
  0, 0, 0, // first point
  1, 0, 0, // second point
];
const size = [
  0.2, // first point has small radius
  3, // second point has large radius
];
const strength = [
  2, // first point has a high impact
  0.5, // second point has a low impact
];
const heatmapDataId = viewer.createHeatmap({ position, size, strength });

getGlobalHeatmapConfig

  • getGlobalHeatmapConfig(): HeatmapConfig
  • Experimental

    Experimental. May be changed in the future without notice.

    Return the current global heatmap configuration.

    Returns HeatmapConfig

    Current global heatmap configuration.

getHeatmapColorSchemeLegend

  • getHeatmapColorSchemeLegend(): number[]
  • Experimental

    Experimental. May be changed in the future without notice.

    Returns data which can be used to create a legend. The data has 4 color channels (RGBA) each in a range between 0 and 255 packed into an Array.

    Returns number[]

    Color scheme legend data.

    Example: Creating a legend:

    Note: Canvas can be resized using CSS width/height settings to achieve desired display size.

    const legend = document.createElement("canvas");
// fetch data
const legendData = viewer.getHeatmapColorSchemeLegend();
// width matches colorResolution set using configureHeatmap
const width = legendData.length / 4;
// canvas requires ImageData as source
const img = new ImageData(new Uint8ClampedArray(legendData), width, 1);
// resize canvas render resolution
legend.width = width;
legend.height = 1;
// get canvas 2d context and fill canvas with data
const ctx = legend.getContext("2d");
ctx.putImageData(img, 0, 0);

getHeatmapData

  • getHeatmapData(id: number): HeatmapProperties
  • Experimental

    Experimental. May be changed in the future without notice.

    Returns the properties of a heatmap dataset.

    Parameters

    Returns HeatmapProperties

    Properties of the heatmap dataset.

getHeatmaps

  • getHeatmaps(): number[]
  • Experimental

    Experimental. May be changed in the future without notice.

    Returns a list of all heatmap datasets.

    Returns number[]

    Array of heatmap dataset IDs.

removeHeatmap

  • removeHeatmap(id: number): void
  • Experimental

    Experimental. May be changed in the future without notice.

    Removes the heatmap with the specified ID and triggers a ViewerHeatmapRemovedEvent.

    Parameters

    • id: number

      The ID of heatmap to remove. Obtained using createHeatmap.

    Returns void