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.
optionsoptional- The padding, the anchor and the zoom (see
DeclutterBoxesOptions). resultoptional- 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.
optionsoptional- The padding and the anchor (see
DeclutterBoxesAlongAxisOptions). resultoptional- 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.
optionsoptional- The padding and the zoom (see
DeclutterCirclesOptions). resultoptional- 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.
optionsoptional- The padding (see
DeclutterCirclesAlongAxisOptions). resultoptional- 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.
