react-cheminfo 0.10.0 → 0.12.0

package/src/scatter3d/core/confidenceEllipsoid.ts

@@ -0,0 +1,139 @@
+/**
+ * The shell that summarises where a group of samples sits in the cloud.
+ *
+ * It is the outline of `scatter/core` with one dimension more, and it is
+ * described the same way — a centre and the axes of the group's own spread,
+ * in the data's units, measured by the same scan the map's outlines are — so
+ * that turning it into something an SVG can draw stays a separate step: the
+ * silhouette a camera sees of it.
+ */
+
+import { rowMatrix } from '../../chart/core/matrix.ts';
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import { DEFAULT_ELLIPSE_SIZE } from '../../scatter/core/confidenceEllipse.ts';
+import { scatterGroupMoments } from '../../scatter/core/scatterGroupMoments.ts';
+
+import { standardDeviationsForCoverage3 } from './ellipsoidCoverage.ts';
+import type { Vector3 } from './orbitCamera.ts';
+import type { SymmetricMatrix3 } from './symmetricEigen.ts';
+import { symmetricEigen3 } from './symmetricEigen.ts';
+
+/** A group's shell, in the cloud's own units. */
+export interface ConfidenceEllipsoid {
+  /** Centre of the shell, which is the group's average. */
+  center: Vector3;
+  /**
+   * Three orthogonal semi-axes, longest first, each vector as long as its own
+   * radius. A direction the group has no spread in is the zero vector, which
+   * is what flattens the shell rather than giving it a false thickness.
+   */
+  axes: readonly [Vector3, Vector3, Vector3];
+  /** How many finite points went into it. */
+  count: number;
+}
+
+/** How {@link confidenceEllipsoid} measures a group. */
+export interface ConfidenceEllipsoidOptions {
+  /**
+   * How large to draw the shell. A share is read in three dimensions, so the
+   * same share gives a wider shell here than the same call gives on the map.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many finite points a group needs before it is given a shell at all.
+   * Below four a group has no volume to measure — three points lie on a plane
+   * however they are arranged — so fewer than four is read as four.
+   * @default 4
+   */
+  minimumPoints?: number;
+}
+
+/**
+ * The shell that summarises a group of samples.
+ *
+ * Points that are not finite are skipped rather than poisoning the average,
+ * and the spread is measured with the `n - 1` divisor, so the shell estimates
+ * the group rather than describing the handful of samples that happen to have
+ * been measured — both exactly as the two-dimensional outline does.
+ * @param points - The group's samples, in the cloud's own units.
+ * @param options - See {@link ConfidenceEllipsoidOptions}.
+ * @returns The shell, or `null` when the group is too small to have a shape, when its coordinates are so large that squaring them overflows, or when the requested size is unbounded.
+ */
+export function confidenceEllipsoid(
+  points: readonly Vector3[],
+  options: ConfidenceEllipsoidOptions = {},
+): ConfidenceEllipsoid | null {
+  const { size = DEFAULT_ELLIPSE_SIZE, minimumPoints = 4 } = options;
+  const moments = scatterGroupMoments(rowMatrix(points), null, 1, 3);
+  const count = moments.counts[0] ?? 0;
+  if (moments.axes < 3 || count < Math.max(4, minimumPoints)) return null;
+
+  const { means, covariances: spread } = moments;
+  const center: Vector3 = [means[0] ?? 0, means[1] ?? 0, means[2] ?? 0];
+  const covariance: SymmetricMatrix3 = {
+    xx: spread[0] ?? 0,
+    xy: spread[1] ?? 0,
+    xz: spread[2] ?? 0,
+    yy: spread[4] ?? 0,
+    yz: spread[5] ?? 0,
+    zz: spread[8] ?? 0,
+  };
+  if (!isFinitePoint(center) || !isFiniteMatrix(covariance)) return null;
+
+  const radius = ellipsoidStandardDeviations(size);
+  if (!Number.isFinite(radius)) return null;
+
+  const { values, vectors } = symmetricEigen3(covariance);
+  const axes: Vector3[] = [];
+  for (let i = 0; i < 3; i++) {
+    const length = radius * Math.sqrt(Math.max(0, values[i] as number));
+    if (!Number.isFinite(length)) return null;
+    const direction = vectors[i] as Vector3;
+    axes.push([
+      direction[0] * length,
+      direction[1] * length,
+      direction[2] * length,
+    ]);
+  }
+
+  return {
+    center,
+    axes: [axes[0] as Vector3, axes[1] as Vector3, axes[2] as Vector3],
+    count,
+  };
+}
+
+/**
+ * How far out a size asks the shell to be drawn.
+ *
+ * Public because a legend has to be able to say what a share came to without
+ * building a shell to ask it.
+ * @param size - How large the shell was asked to be.
+ * @returns The number of standard deviations, never below zero — the same floor the map's outline keeps.
+ */
+export function ellipsoidStandardDeviations(size: EllipseSize): number {
+  if (size.kind === 'standardDeviations') {
+    return Math.max(size.standardDeviations, 0);
+  }
+  return standardDeviationsForCoverage3(size.probability);
+}
+
+function isFinitePoint(point: Vector3): boolean {
+  return (
+    Number.isFinite(point[0]) &&
+    Number.isFinite(point[1]) &&
+    Number.isFinite(point[2])
+  );
+}
+
+function isFiniteMatrix(matrix: SymmetricMatrix3): boolean {
+  return (
+    Number.isFinite(matrix.xx) &&
+    Number.isFinite(matrix.xy) &&
+    Number.isFinite(matrix.xz) &&
+    Number.isFinite(matrix.yy) &&
+    Number.isFinite(matrix.yz) &&
+    Number.isFinite(matrix.zz)
+  );
+}

package/src/scatter3d/core/cubeFrame.ts

@@ -0,0 +1,72 @@
+/**
+ * The box the cloud sits in.
+ *
+ * A cloud of dots on an empty background has no orientation at all: turn it
+ * and nothing tells the reader it turned, and a dot near the top could be near
+ * or far. Twelve faint edges and three labelled arms fix that for the cost of
+ * fifteen lines, and they are the reason the projection can stay orthographic
+ * — the frame carries the depth that perspective would otherwise have to, and
+ * unlike perspective it distorts no distance.
+ */
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** The corner the three labelled arms are drawn from. */
+export const CUBE_ORIGIN: Vector3 = [-1, -1, -1];
+
+/**
+ * The twelve edges of the cube, each as its two corners.
+ *
+ * Every edge, not just the three at the back: which edges are hidden changes
+ * as the box turns, and drawing all twelve faintly reads as a wireframe, while
+ * drawing three reads as an axis system that keeps rearranging itself.
+ * @returns The edges. The order is stable but carries no meaning.
+ */
+export function cubeEdges(): Array<[Vector3, Vector3]> {
+  const corners: Vector3[] = [];
+  for (const x of [-1, 1]) {
+    for (const y of [-1, 1]) {
+      for (const z of [-1, 1]) corners.push([x, y, z]);
+    }
+  }
+
+  const edges: Array<[Vector3, Vector3]> = [];
+  for (let i = 0; i < corners.length; i++) {
+    for (let j = i + 1; j < corners.length; j++) {
+      const a = corners[i] as Vector3;
+      const b = corners[j] as Vector3;
+      // Two corners are joined by an edge exactly when they differ in one
+      // coordinate; differing in two is a face diagonal and in three is the
+      // body diagonal, and drawing either would turn the frame into a mesh.
+      const differing =
+        (a[0] === b[0] ? 0 : 1) +
+        (a[1] === b[1] ? 0 : 1) +
+        (a[2] === b[2] ? 0 : 1);
+      if (differing === 1) edges.push([a, b]);
+    }
+  }
+  return edges;
+}
+
+/** One labelled arm of the frame. */
+export interface CubeArm {
+  /** Which of the three axes it stands for. */
+  axis: 'x' | 'y' | 'z';
+  /** The far end of the arm. */
+  end: Vector3;
+  /** Where its name is written, just beyond the end. */
+  label: Vector3;
+}
+
+/**
+ * The three arms, from the origin corner along each axis.
+ *
+ * The label sits a little past the end of its arm so that it is outside the
+ * cloud whatever the box is turned to; at the end itself it would fall on the
+ * frame from about a third of the angles.
+ */
+export const CUBE_ARMS: readonly CubeArm[] = [
+  { axis: 'x', end: [1, -1, -1], label: [1.18, -1, -1] },
+  { axis: 'y', end: [-1, 1, -1], label: [-1, 1.18, -1] },
+  { axis: 'z', end: [-1, -1, 1], label: [-1, -1, 1.18] },
+];

package/src/scatter3d/core/cubePoints.ts

@@ -0,0 +1,75 @@
+/**
+ * Three runs of numbers, stretched into the cube the cloud is drawn in.
+ *
+ * A map draws its two axes at whatever scale each one needs, and the tick
+ * labels are the reader's record of that. A cloud has no such record: it is
+ * one solid seen from an angle, so three axes drawn at three scales would make
+ * a group lean in a direction that is an artefact of the scaling and not
+ * anything in the data. Every axis is therefore stretched to the same cube,
+ * the frame is labelled with which axis is which, and the numbers stay in the
+ * card the pointer raises.
+ *
+ * The shells are fitted in this cube for the same reason the map fits its
+ * outlines in pixels: a shell has to sit on the cloud the reader is looking
+ * at, not on a cloud in units nothing draws.
+ */
+
+import {
+  chartPadExtent,
+  chartValuesExtent,
+} from '../../chart/core/chartExtent.ts';
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** How {@link cubePoints} stretches the runs it is given. */
+export interface CubePointsOptions {
+  /**
+   * Share of each axis' span left empty at both ends, so the cloud does not
+   * touch the frame.
+   * @default 0.05
+   */
+  padding?: number;
+}
+
+/**
+ * Three runs of numbers, each stretched to `[-1, 1]`.
+ * @param x - Where every sample sits along the axis that runs left to right.
+ * @param y - Along the axis that runs bottom to top, in the same order.
+ * @param z - Along the axis that runs away from the reader.
+ * @param options - See {@link CubePointsOptions}.
+ * @returns One point per sample, as many as the shortest run holds. An axis with no spread at all puts every sample at the middle of it rather than dividing by zero, and a value that is not finite stays that way so nothing draws it.
+ */
+export function cubePoints(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  z: ArrayLike<number>,
+  options: CubePointsOptions = {},
+): Vector3[] {
+  const { padding = 0.05 } = options;
+  const toCube = [x, y, z].map((values) => axisMapper(values, padding));
+  const across = toCube[0] as Mapper;
+  const up = toCube[1] as Mapper;
+  const away = toCube[2] as Mapper;
+
+  const count = Math.min(x.length, y.length, z.length);
+  const points = new Array<Vector3>(count);
+  for (let index = 0; index < count; index++) {
+    points[index] = [
+      across(x[index] as number),
+      up(y[index] as number),
+      away(z[index] as number),
+    ];
+  }
+  return points;
+}
+
+type Mapper = (value: number) => number;
+
+function axisMapper(values: ArrayLike<number>, padding: number): Mapper {
+  const { min, max } = chartPadExtent(chartValuesExtent(values), padding);
+  const span = max - min;
+  if (!Number.isFinite(span) || span <= 0) {
+    return (value: number) => (Number.isFinite(value) ? 0 : Number.NaN);
+  }
+  return (value: number) => (2 * (value - min)) / span - 1;
+}

package/src/scatter3d/core/ellipsoidCoverage.ts

@@ -0,0 +1,86 @@
+/**
+ * How far out a group's shell is drawn, and how much of the group it then
+ * holds.
+ *
+ * The two-dimensional pair in `scatter/core` cannot answer this, and the
+ * difference is not a rounding: a shell has to hold a sample in three
+ * directions at once, so the same two standard deviations that keep 86 per
+ * cent of a flat cloud keep only 74 per cent of a solid one. Quoting the flat
+ * figure beside a cloud is the usual way a legend comes to promise more than
+ * its shells contain, which is why the map and the cloud each ask their own
+ * dimension.
+ */
+
+/**
+ * The share of a three-dimensional normal cloud inside the shell drawn at a
+ * number of standard deviations.
+ * @param standardDeviations - How far out the shell is drawn.
+ * @returns The share, from 0 to 1. Zero at or below zero, since a shell of no size holds nothing.
+ */
+export function coverageForStandardDeviations3(
+  standardDeviations: number,
+): number {
+  if (!Number.isFinite(standardDeviations)) {
+    return standardDeviations > 0 ? 1 : 0;
+  }
+  if (standardDeviations <= 0) return 0;
+  const radius = standardDeviations;
+  const inside = erf(radius / Math.SQRT2);
+  const shell =
+    radius * Math.sqrt(2 / Math.PI) * Math.exp(-(radius * radius) / 2);
+  return Math.min(1, Math.max(0, inside - shell));
+}
+
+/**
+ * How far out to draw the shell that holds a share of a three-dimensional
+ * normal cloud.
+ *
+ * The inverse of {@link coverageForStandardDeviations3}. There is no closed
+ * form for it, so it is bisected — the share grows strictly with the radius,
+ * so fifty halvings settle it far below the width of the line the shell is
+ * drawn with, and the search runs once per group rather than once per face.
+ * @param coverage - The share to enclose, from 0 to 1.
+ * @returns The number of standard deviations. Zero at or below zero, and infinite at or above one, because no finite shell holds every point of a cloud with unbounded tails.
+ */
+export function standardDeviationsForCoverage3(coverage: number): number {
+  if (!Number.isFinite(coverage) || coverage <= 0) return 0;
+  if (coverage >= 1) return Number.POSITIVE_INFINITY;
+
+  let low = 0;
+  // Nine standard deviations hold every share a control can ask for: the
+  // remainder there is under 1e-17, which no `number` can tell from zero.
+  let high = 9;
+  for (let step = 0; step < 50; step++) {
+    const middle = (low + high) / 2;
+    if (coverageForStandardDeviations3(middle) < coverage) {
+      low = middle;
+    } else {
+      high = middle;
+    }
+  }
+  return (low + high) / 2;
+}
+
+/**
+ * The error function, to about a part in ten million.
+ *
+ * Abramowitz and Stegun 7.1.26. That is coarser than the library's usual
+ * standard and is deliberately so: it decides the radius of a shell drawn a
+ * few hundred pixels across, where a part in ten million is a part in ten
+ * thousand of one pixel, and the alternative is a series that costs more to
+ * read than the whole module around it.
+ * @param x - The argument.
+ * @returns The error function at `x`.
+ */
+function erf(x: number): number {
+  const sign = x < 0 ? -1 : 1;
+  const absolute = Math.abs(x);
+  const t = 1 / (1 + 0.327_591_1 * absolute);
+  const series =
+    t *
+    (0.254_829_592 +
+      t *
+        (-0.284_496_736 +
+          t * (1.421_413_741 + t * (-1.453_152_027 + t * 1.061_405_429))));
+  return sign * (1 - series * Math.exp(-absolute * absolute));
+}

package/src/scatter3d/core/ellipsoidSilhouette.ts

@@ -0,0 +1,70 @@
+/**
+ * The outline a shell has on screen, which is an ellipse and nothing else.
+ *
+ * An orthographic camera sends the unit sphere to a filled ellipse, so a shell
+ * — a sphere carried by three semi-axes — has an exact elliptical silhouette
+ * whatever it is turned to. Drawing it as that one ellipse is what keeps the
+ * glass smooth at any zoom and free of seams.
+ */
+
+import { ellipseAxes } from '../../scatter/core/ellipseAxes.ts';
+
+import type { ConfidenceEllipsoid } from './confidenceEllipsoid.ts';
+import type { OrbitCamera } from './orbitCamera.ts';
+import { rotatePoint } from './orbitCamera.ts';
+
+/** Where a shell's outline sits, in cube units, for one camera. */
+export interface EllipsoidSilhouette {
+  /** Half the outline's longest width, along the angle below. */
+  rx: number;
+  /** Half its width across that, never longer than `rx`. */
+  ry: number;
+  /**
+   * How far the long axis is turned from the horizontal, in radians, measured
+   * the way the screen measures — down from the right — since the projection
+   * flips the vertical axis on its way to pixels.
+   */
+  angle: number;
+}
+
+/**
+ * The outline of a shell, for the camera it is seen from.
+ *
+ * The three semi-axes are turned with the camera and their depth dropped,
+ * which leaves a `2 x 3` map from the unit sphere to the screen. The image of
+ * that sphere is the ellipse whose shape matrix is the map times its own
+ * transpose — a covariance in all but name — so it is decomposed by the same
+ * `ellipseAxes` a map outline is, collinear floor included.
+ *
+ * A group flat in one direction gives a matrix with a zero eigenvalue and
+ * comes back as a segment, which is the honest picture of a group that has no
+ * spread to show.
+ * @param ellipsoid - The shell, in cube units.
+ * @param camera - Where the reader is standing.
+ * @returns See {@link EllipsoidSilhouette}.
+ */
+export function ellipsoidSilhouette(
+  ellipsoid: ConfidenceEllipsoid,
+  camera: OrbitCamera,
+): EllipsoidSilhouette {
+  const [first, second, third] = ellipsoid.axes;
+  const a = rotatePoint(first, camera);
+  const b = rotatePoint(second, camera);
+  const c = rotatePoint(third, camera);
+
+  // The screen's own frame: across, and down — hence the sign on the second.
+  const acrossX = a[0];
+  const acrossY = b[0];
+  const acrossZ = c[0];
+  const downX = -a[1];
+  const downY = -b[1];
+  const downZ = -c[1];
+
+  const xx = acrossX * acrossX + acrossY * acrossY + acrossZ * acrossZ;
+  const yy = downX * downX + downY * downY + downZ * downZ;
+  const xy = acrossX * downX + acrossY * downY + acrossZ * downZ;
+
+  // The shape matrix is already in the screen's own frame, so the angle the
+  // decomposition reports is measured down from the right with no conversion.
+  return ellipseAxes({ xx, xy, yy });
+}

package/src/scatter3d/core/index.ts

@@ -0,0 +1,52 @@
+/**
+ * A cloud of samples in three dimensions: where the reader is standing, where
+ * a sample lands on screen from there, and the shell that holds a group.
+ *
+ * It is the two-dimensional `scatter` domain with one axis more, and the extra
+ * axis changes more than it looks. A shell is drawn as the silhouette the
+ * camera sees of it, painted back to front, and the three axes have to share
+ * one scale, because a solid seen from an angle has no tick labels to record
+ * three different ones with.
+ *
+ * Nothing here knows what produced the coordinates, and nothing here draws:
+ * every function is arithmetic over plain numbers, so the geometry can be
+ * checked without a DOM.
+ */
+
+export type {
+  ConfidenceEllipsoid,
+  ConfidenceEllipsoidOptions,
+} from './confidenceEllipsoid.ts';
+export {
+  confidenceEllipsoid,
+  ellipsoidStandardDeviations,
+} from './confidenceEllipsoid.ts';
+export type { CubeArm } from './cubeFrame.ts';
+export { CUBE_ARMS, CUBE_ORIGIN, cubeEdges } from './cubeFrame.ts';
+export {
+  coverageForStandardDeviations3,
+  standardDeviationsForCoverage3,
+} from './ellipsoidCoverage.ts';
+export type { EllipsoidSilhouette } from './ellipsoidSilhouette.ts';
+export { ellipsoidSilhouette } from './ellipsoidSilhouette.ts';
+export type {
+  OrbitCamera,
+  OrbitViewport,
+  ProjectedPoint,
+  Vector3,
+} from './orbitCamera.ts';
+export {
+  CUBE_HALF_DIAGONAL,
+  DEFAULT_ORBIT_CAMERA,
+  ORBIT_PITCH_LIMIT,
+  ORBIT_RADIANS_PER_PIXEL,
+  depthFraction,
+  orbitByDrag,
+  projectPoint,
+  rotatePoint,
+} from './orbitCamera.ts';
+export type { CloudGesture } from './cloudGesture.ts';
+export type { CubePointsOptions } from './cubePoints.ts';
+export { cubePoints } from './cubePoints.ts';
+export type { SymmetricEigen3, SymmetricMatrix3 } from './symmetricEigen.ts';
+export { symmetricEigen3 } from './symmetricEigen.ts';

package/src/scatter3d/core/orbitCamera.ts

@@ -0,0 +1,159 @@
+/**
+ * Where the reader is standing, and where a point in the cube lands on screen.
+ *
+ * The cloud is drawn with an orthographic projection rather than a perspective
+ * one: a scatter is read by comparing distances, and perspective makes the same
+ * distance shorter at the back of the box than at the front, so two groups
+ * equally far apart would not look it. What is left to give the picture its
+ * depth is the frame around it, the order the dots are painted in, and their
+ * size — all of which cost nothing and none of which distorts a measurement.
+ */
+
+/** A point of the cube, `[x, y, z]`, with `z` running towards the reader. */
+export type Vector3 = readonly [number, number, number];
+
+/**
+ * Where the reader is standing.
+ *
+ * The scene is turned by `pitch` about the horizontal axis and then by `yaw`
+ * about the vertical one, which is the order a hand expects: dragging sideways
+ * spins the box about its upright axis whatever it is already tilted to, and
+ * dragging up and down tips it towards the reader.
+ */
+export interface OrbitCamera {
+  /** Azimuth, in radians. A sideways drag changes it. */
+  yaw: number;
+  /** Elevation, in radians. A vertical drag changes it. */
+  pitch: number;
+}
+
+/** Where a point of the cube landed, in pixels, and how near the reader it is. */
+export interface ProjectedPoint {
+  /** Pixels from the left of the drawing area. */
+  x: number;
+  /** Pixels from its top. */
+  y: number;
+  /**
+   * Distance towards the reader, in cube units: larger is nearer. It orders
+   * the painting and sizes the dots, and is never drawn as a number.
+   */
+  depth: number;
+}
+
+/**
+ * The corner the box is first seen from.
+ *
+ * Slightly off both axes on purpose. Square-on, two of the three axes lie
+ * exactly along the screen's own and the third collapses to a point, so the
+ * first thing the reader sees is a flat scatter that hides a whole component —
+ * a quarter turn and a slight tilt say "this is a box" before the pointer has
+ * touched it.
+ */
+export const DEFAULT_ORBIT_CAMERA: OrbitCamera = { yaw: 0.6, pitch: 0.5 };
+
+/**
+ * How far the camera may tip, in radians.
+ *
+ * Just short of a right angle. Straight down the vertical axis the horizon
+ * degenerates and a further drag flips the scene over, which reads as the plot
+ * breaking rather than as the reader reaching the end of a range.
+ */
+export const ORBIT_PITCH_LIMIT = 1.4;
+
+/** How many radians one pixel of drag turns the scene. */
+export const ORBIT_RADIANS_PER_PIXEL = 0.01;
+
+/**
+ * Turn a point of the cube into the reader's own frame.
+ * @param point - The point, in cube units.
+ * @param camera - Where the reader is standing.
+ * @returns The point in the reader's frame: right, up, and towards them.
+ */
+export function rotatePoint(point: Vector3, camera: OrbitCamera): Vector3 {
+  const [x, y, z] = point;
+  const cosPitch = Math.cos(camera.pitch);
+  const sinPitch = Math.sin(camera.pitch);
+  const upright = y * cosPitch - z * sinPitch;
+  const tipped = y * sinPitch + z * cosPitch;
+  const cosYaw = Math.cos(camera.yaw);
+  const sinYaw = Math.sin(camera.yaw);
+  return [x * cosYaw + tipped * sinYaw, upright, -x * sinYaw + tipped * cosYaw];
+}
+
+/** Where the projection puts the middle of the cube, and how large it draws it. */
+export interface OrbitViewport {
+  /** Pixels per cube unit. */
+  scale: number;
+  /** Pixels from the left of the drawing area to the middle of the cube. */
+  centerX: number;
+  /** Pixels from its top to the middle of the cube. */
+  centerY: number;
+}
+
+/**
+ * Where a point of the cube lands on screen.
+ *
+ * The vertical axis is flipped, because a cube whose `y` grows upwards has to
+ * be drawn on a screen whose pixels grow downwards.
+ * @param point - The point, in cube units.
+ * @param camera - Where the reader is standing.
+ * @param viewport - Where the middle of the cube is, and how large it is drawn.
+ * @returns See {@link ProjectedPoint}.
+ */
+export function projectPoint(
+  point: Vector3,
+  camera: OrbitCamera,
+  viewport: OrbitViewport,
+): ProjectedPoint {
+  const [right, up, towards] = rotatePoint(point, camera);
+  const { scale, centerX, centerY } = viewport;
+  return {
+    x: centerX + right * scale,
+    y: centerY - up * scale,
+    depth: towards,
+  };
+}
+
+/**
+ * The camera a drag leaves behind.
+ *
+ * The pitch is held inside its limit rather than allowed to wrap, so a reader
+ * who keeps dragging upwards comes to rest looking down at the box instead of
+ * watching it turn upside down.
+ * @param camera - Where the reader was standing.
+ * @param dx - How far the pointer moved across, in pixels.
+ * @param dy - How far it moved down, in pixels.
+ * @returns Where they are standing now.
+ */
+export function orbitByDrag(
+  camera: OrbitCamera,
+  dx: number,
+  dy: number,
+): OrbitCamera {
+  const pitch = camera.pitch + dy * ORBIT_RADIANS_PER_PIXEL;
+  return {
+    yaw: camera.yaw + dx * ORBIT_RADIANS_PER_PIXEL,
+    pitch: Math.min(ORBIT_PITCH_LIMIT, Math.max(-ORBIT_PITCH_LIMIT, pitch)),
+  };
+}
+
+/**
+ * The longest a cube diagonal can be, which is the range `depth` spans.
+ *
+ * A dot is sized from where it sits between the near and far corners, and this
+ * is what that fraction is measured against — a constant rather than the
+ * cloud's own extent, so a dot does not change size when a group is filtered
+ * out from behind it.
+ */
+export const CUBE_HALF_DIAGONAL = Math.sqrt(3);
+
+/**
+ * Where a point sits between the far corner of the cube and the near one.
+ * @param depth - How far towards the reader the point is, in cube units.
+ * @returns From 0 at the back to 1 at the front.
+ */
+export function depthFraction(depth: number): number {
+  if (!Number.isFinite(depth)) return depth > 0 ? 1 : 0;
+  const fraction = (depth / CUBE_HALF_DIAGONAL + 1) / 2;
+  return Math.min(1, Math.max(0, fraction));
+}