Scatter-gl NPM

ScatterGL

Interactive 3D / 2D webgl-accelerated scatter plot point renderer. Core functionality from the embedding projector, capable of rendering and interacting with tens of thousands of points.

Examples

Basic use

// where `points` is an array of 2 or 3-dimensional points as number arrays.
const dataset = new ScatterGL.Dataset(points);
const scatterGL = new ScatterGL(containerElement);
scatterGL.render(dataset);

Installation

with yarn / npm

yarn add scatter-gl

via cdn

<!-- Load three.js -->
<script src="https://cdn.jsdelivr.net/npm/three@0.106.2/build/three.min.js"></script>
<!-- Load scatter-gl.js -->
<script src="https://cdn.jsdelivr.net/npm/scatter-gl@0.0.1/lib/scatter-gl.min.js"></script>

Parameters

The ScatterGL constructor can accept a number of parameters via a ScatterGLParams object:

Parameter	Type	Description	default
`camera`	`Camera`	An object containing default parameters for the camera	Camera params object (`zoom: number`, `target: Point3D`, and `position: Point3D`)
`onClick`	`(point: Point \\| null) => void`	A callback invoked when clicking on a point or elsewhere
`onHover`	`(point: Point \\| null) => void`	A callback invoked when hovering over a point
`onSelect`	`(points: Point[]) => void`	A callback invoked when a point or points are selected
`onCameraMove`	`(cameraPosition: THREE.Vector3, cameraTarget: THREE.Vector3) => void`	A callback invoked the camera moves due to user interaction.
`pointColorer`	`(index: number, selectedIndices: Set<number>, hoverIndex: number\|null) => string`	A function to determine the color of points
`renderMode`	`RenderMode`	The render mode to display points, one of `RenderMode.POINT`, `RenderMode.SPRITE`, or `RenderMode.TEXT`	`RenderMode.POINT`
`showLabelsOnHover`	`boolean`	Whether or not to render label text on hover	`true`
`selectEnabled`	`boolean`	`true`	Whether or not a user can select points by clicking
`styles`	`Styles`	An object containing style parameters to override the default options
`rotateOnStart`	`boolean`	Whether or not the renderer automatically rotates until interaction	`true`
`orbitControls`	`OrbitControlParams`	An object containing default parameters for the orbit controls	Orbit Controls params object (`zoomSpeed: number`, `autoRotateSpeed: number`, and `mouseRotateSpeed: number`)

ScatterGL methods

Method	Description
`isOrbiting()`	Returns whether the orbit animation is currently on
`render(dataset: Dataset)`	Initializes and renders a dataset to the container element
`resize()`	Updates the render size based on the container element
`resetZoom()`	Resets the camera zoom to default
`select(pointIndices: number[])`	Selects points by index
`setPanMode()`	Sets interaction mode to 'pan'
`setPointColorer(pointColorer: PointColorer)`	Sets a function to determine colors
`setHoverPointIndex()`	Sets the hovered point
`setPointRenderMode()`	Sets point render mode
`setRenderMode(renderMode: RenderMode)`	Sets a specific render mode
`setSelectMode()`	Sets interaction mode to 'select'
`setSequences(sequences: Sequence[])`	Sets sequences with which to render polylines
`setSpriteRenderMode()`	Sets sprite render mode
`setTextRenderMode()`	Sets text render mode
`updateDataset(dataset: Dataset)`	Updates the dataset
`startOrbitAnimation()`	Begin rotating until an interaction
`stopOrbitAnimation()`	Stops automatic rotation

ScatterGL Styles

See styles.ts for interfaces and descriptions of a user-configurable styles object that can be provided to ScatterGL to configure colors, sizes, fog, etc.