class Geometry · Computations

Declutter

Decides which shapes to show at which zoom so that the shown ones don't overlap, e.g. labels on a timeline: for each shape the smallest scale at which it is shown. Wire it to the zoom yourself: label.visible.value = scale >= minScale[i].

The shapes are given as drawn at scale 1, and they keep their size on screen while the positions scale (screen = position × scale, as with Viewports; with the zoom option of circles and boxes, along one axis only), so they come closer when zooming out. When two shown shapes touch, the one with the lower priority disappears at that scale; a shape that has disappeared hides nobody, and each shape is shown on one range of scales (from its result upwards). A result of 0 means always shown, Infinity never (it touches a stronger shape at every scale, e.g. at the same position), NaN left out (not a finite shape). The result is exact and the same for the same input. The functions compute once and are not reactive: for shapes that change, call them in Reactive.do and pass the same result every time; for a changing zoom, only the comparison with the scale changes, no new call is needed.

Static methods

boxesstatic

static boxes(boxes: Box[], priorities: number[], options?: DeclutterBoxesOptions | null, result?: number[] | null): number[]

The smallest scale at which each box is shown, e.g. city labels on a map: Declutter.boxes(labels, population, { padding: 4, anchor: [0, 0.5] }).

Two boxes overlap when they overlap along x and along y, so they are apart as soon as they are apart along one of them. Each box stays at its anchor (options.anchor, default its center) while the positions scale. The boxes are taken as drawn on screen, so the viewport must not be rotated. The zoom is taken to scale x and y alike; for a zoom along one axis set options.zoom ("x" or "y"), or use boxesAlongAxis when something ties each box to the axis. Fast for many boxes of similar size; boxes of very different sizes or many boxes at almost the same place take longer.

boxes
The boxes as drawn at scale 1, e.g. the extents of labels (label.extent).
priorities
One priority per box: of two that touch, the one with the lower priority disappears (equal: the later one in the list). A missing priority (or NaN) counts as 0.
options optional
The padding, the anchor and the zoom (see DeclutterBoxesOptions).
result optional
Optional array to store the scales in; its length is set to the number of boxes.

Returns The smallest scale at which each box is shown, in the order of the boxes.

boxesAlongAxisstatic

static boxesAlongAxis(boxes: Box[], axis: "x" | "y", priorities: number[], options?: DeclutterBoxesAlongAxisOptions | null, result?: number[] | null): number[]

The smallest scale at which each box is shown, comparing the boxes only along one axis, e.g. labels on a time axis or along a ruler: Declutter.boxesAlongAxis(labels, "x", importance, { padding: 4, anchor: "start" }).

Only the extents along the axis count: two boxes at the same x but different y overlap for "x". Each box stays at its anchor (options.anchor, default its middle) while the positions scale.

boxes
The boxes as drawn at scale 1, e.g. the extents of labels (label.extent).
axis
The axis the boxes are compared along: "x" or "y".
priorities
One priority per box: of two that touch, the one with the lower priority disappears (equal: the later one in the list). A missing priority (or NaN) counts as 0.
options optional
The padding and the anchor (see DeclutterBoxesAlongAxisOptions).
result optional
Optional array to store the scales in; its length is set to the number of boxes.

Returns The smallest scale at which each box is shown, in the order of the boxes.

circlesstatic

static circles(circles: Circle[], priorities: number[], options?: DeclutterCirclesOptions | null, result?: number[] | null): number[]

The smallest scale at which each circle is shown, e.g. city dots on a map: Declutter.circles(dots, population, { padding: 2 }), or for a scatter zoomed along x only: Declutter.circles(dots, values, { zoom: "x" }).

Each circle stays at its center while the positions scale. The zoom is taken to scale x and y alike; for a zoom along one axis set options.zoom ("x" or "y"), or use circlesAlongAxis when something ties each circle to the axis (e.g. stems). Fast for many circles of similar size; circles of very different sizes or many circles at almost the same place take longer.

circles
The circles as drawn at scale 1.
priorities
One priority per circle: of two that touch, the one with the lower priority disappears (equal: the later one in the list). A missing priority (or NaN) counts as 0.
options optional
The padding and the zoom (see DeclutterCirclesOptions).
result optional
Optional array to store the scales in; its length is set to the number of circles.

Returns The smallest scale at which each circle is shown, in the order of the circles.

circlesAlongAxisstatic

static circlesAlongAxis(circles: Circle[], axis: "x" | "y" | Vector, priorities: number[], options?: DeclutterCirclesAlongAxisOptions | null, result?: number[] | null): number[]

The smallest scale at which each circle is shown, comparing the circles only along one axis, e.g. events on a timeline: Declutter.circlesAlongAxis(dots, "x", sizes, { padding: 2 }).

Only the extents along the axis count (the diameter): two circles at the same x but different y overlap for "x". Each circle stays at its center while the positions scale.

circles
The circles as drawn at scale 1.
axis
The axis the circles are compared along: "x", "y" or a vector (a pin gives its direction).
priorities
One priority per circle: of two that touch, the one with the lower priority disappears (equal: the later one in the list). A missing priority (or NaN) counts as 0.
options optional
The padding (see DeclutterCirclesAlongAxisOptions).
result optional
Optional array to store the scales in; its length is set to the number of circles.

Returns The smallest scale at which each circle is shown, in the order of the circles.