react-cheminfo 0.9.0 → 0.11.0

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,76 @@
+/**
+ * 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. Taking it as such is what keeps the glass smooth:
+ * a tessellated shell is only as round as the number of faces it was cut into,
+ * and every seam between two of those faces is a line the reader can see.
+ */
+
+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, so the two radii are the square roots of that matrix's
+ * eigenvalues and the tilt is half the angle of its off-diagonal term.
+ *
+ * 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;
+
+  const middle = (xx + yy) / 2;
+  const spread = Math.hypot((xx - yy) / 2, xy);
+  const major = Math.max(0, middle + spread);
+  const minor = Math.max(0, middle - spread);
+
+  return {
+    rx: Math.sqrt(major),
+    ry: Math.sqrt(minor),
+    angle: 0.5 * Math.atan2(2 * xy, xx - 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. Nothing can be handed to an SVG shape any
+ * more — a shell has to be cut into faces, projected, and 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));
+}

package/src/scatter3d/core/symmetricEigen.ts

@@ -0,0 +1,273 @@
+/**
+ * The axes a symmetric three by three matrix describes.
+ *
+ * The two-dimensional outline solves the same problem in four lines, because a
+ * symmetric two by two matrix has a closed form anybody can read. Three by
+ * three also has one — the eigenvalues are the roots of a cubic whose
+ * discriminant is never negative for a symmetric matrix, so they come out of a
+ * cosine rather than out of an iteration — and having it here is what lets the
+ * cloud fit an ellipsoid without the package depending on a matrix library.
+ */
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** A symmetric three by three matrix, as its six distinct entries. */
+export interface SymmetricMatrix3 {
+  /** Row 1, column 1. */
+  xx: number;
+  /** Row 1, column 2, which is also row 2, column 1. */
+  xy: number;
+  /** Row 1, column 3, which is also row 3, column 1. */
+  xz: number;
+  /** Row 2, column 2. */
+  yy: number;
+  /** Row 2, column 3, which is also row 3, column 2. */
+  yz: number;
+  /** Row 3, column 3. */
+  zz: number;
+}
+
+/** The axes of a symmetric three by three matrix, longest first. */
+export interface SymmetricEigen3 {
+  /** The three eigenvalues, largest first. Never below zero for a covariance. */
+  values: readonly [number, number, number];
+  /** A unit eigenvector per eigenvalue, in the same order, always orthonormal. */
+  vectors: readonly [Vector3, Vector3, Vector3];
+}
+
+/**
+ * A residue this far below the largest eigenvalue is read as zero.
+ *
+ * Squaring and summing coordinates leaves a few parts in 1e16 where the exact
+ * answer is nothing at all, so a flat group — every sample on one plane, which
+ * is what four samples in three dimensions always are — would otherwise be
+ * given a sliver of thickness that differs from machine to machine.
+ */
+const FLAT_FLOOR = 1e-12;
+
+/**
+ * The axes a symmetric three by three matrix describes.
+ *
+ * The eigenvectors are orthonormalised rather than taken as they come out of
+ * the cross products, because a repeated eigenvalue — a group that is round in
+ * two of its three directions, which is the common case for a small one —
+ * leaves that plane's two directions undetermined, and any orthogonal pair in
+ * it is as good an answer as any other. What must never happen is two nearly
+ * parallel vectors, which would draw an ellipsoid collapsed to a fan.
+ * @param matrix - The matrix, as its six distinct entries.
+ * @returns See {@link SymmetricEigen3}. A matrix with an entry that is not finite gives three zero eigenvalues on the standard axes.
+ */
+export function symmetricEigen3(matrix: SymmetricMatrix3): SymmetricEigen3 {
+  const { xx, xy, xz, yy, yz, zz } = matrix;
+  if (
+    !Number.isFinite(xx) ||
+    !Number.isFinite(xy) ||
+    !Number.isFinite(xz) ||
+    !Number.isFinite(yy) ||
+    !Number.isFinite(yz) ||
+    !Number.isFinite(zz)
+  ) {
+    return NOTHING;
+  }
+
+  const values = eigenvalues(matrix);
+  const largest = Math.max(Math.abs(values[0]), Math.abs(values[2]));
+  const raw: Vector3[] = [];
+  for (let i = 0; i < 3; i++) {
+    raw.push(eigenvector(matrix, values[i] as number, largest));
+  }
+  return { values, vectors: orthonormalise(raw) };
+}
+
+/**
+ * The three eigenvalues, largest first.
+ * @param matrix - The matrix, as its six distinct entries.
+ * @returns The eigenvalues, in descending order.
+ */
+function eigenvalues(
+  matrix: SymmetricMatrix3,
+): readonly [number, number, number] {
+  const { xx, xy, xz, yy, yz, zz } = matrix;
+  const offDiagonal = xy * xy + xz * xz + yz * yz;
+  if (offDiagonal === 0) {
+    const diagonal = [xx, yy, zz].toSorted(descending);
+    return [
+      diagonal[0] as number,
+      diagonal[1] as number,
+      diagonal[2] as number,
+    ];
+  }
+
+  const mean = (xx + yy + zz) / 3;
+  const spread =
+    ((xx - mean) * (xx - mean) +
+      (yy - mean) * (yy - mean) +
+      (zz - mean) * (zz - mean) +
+      2 * offDiagonal) /
+    6;
+  const radius = Math.sqrt(spread);
+  if (!(radius > 0)) return [mean, mean, mean];
+
+  // The matrix shifted to a zero trace and scaled to a unit radius; half its
+  // determinant is the cosine of three times the angle the three roots sit at.
+  const half =
+    determinant3({
+      xx: (xx - mean) / radius,
+      xy: xy / radius,
+      xz: xz / radius,
+      yy: (yy - mean) / radius,
+      yz: yz / radius,
+      zz: (zz - mean) / radius,
+    }) / 2;
+  const angle = Math.acos(Math.min(1, Math.max(-1, half))) / 3;
+
+  const first = mean + 2 * radius * Math.cos(angle);
+  const third = mean + 2 * radius * Math.cos(angle + (2 * Math.PI) / 3);
+  return [first, 3 * mean - first - third, third];
+}
+
+function descending(a: number, b: number): number {
+  return b - a;
+}
+
+function determinant3(matrix: SymmetricMatrix3): number {
+  const { xx, xy, xz, yy, yz, zz } = matrix;
+  return (
+    xx * (yy * zz - yz * yz) -
+    xy * (xy * zz - yz * xz) +
+    xz * (xy * yz - yy * xz)
+  );
+}
+
+/**
+ * A direction the matrix only stretches.
+ *
+ * Two rows of `matrix - λI` span the plane the eigenvector is normal to, so
+ * their cross product is that eigenvector. Which two rows is not a free choice:
+ * a row can be zero, or two rows can be nearly parallel, and the cross product
+ * of those is numerical dust — so all three pairs are tried and the longest
+ * answer is kept.
+ * @param matrix - The matrix.
+ * @param value - The eigenvalue.
+ * @param scale - The size of the matrix, to judge "too short" against.
+ * @returns A unit vector, or the zero vector when the shifted matrix vanishes, which is a repeated eigenvalue and leaves the direction to the orthonormalising step.
+ */
+function eigenvector(
+  matrix: SymmetricMatrix3,
+  value: number,
+  scale: number,
+): Vector3 {
+  const { xx, xy, xz, yy, yz, zz } = matrix;
+  const rows: Vector3[] = [
+    [xx - value, xy, xz],
+    [xy, yy - value, yz],
+    [xz, yz, zz - value],
+  ];
+
+  let best: Vector3 = ZERO;
+  let bestLength = 0;
+  for (let i = 0; i < 3; i++) {
+    for (let j = i + 1; j < 3; j++) {
+      const candidate = cross(rows[i] as Vector3, rows[j] as Vector3);
+      const length = norm(candidate);
+      if (length > bestLength) {
+        best = candidate;
+        bestLength = length;
+      }
+    }
+  }
+  // A cross product of two rows is quadratic in the matrix, so the length it
+  // has to beat is too.
+  if (bestLength <= FLAT_FLOOR * Math.max(scale * scale, Number.MIN_VALUE)) {
+    return ZERO;
+  }
+  return scaleVector(best, 1 / bestLength);
+}
+
+/**
+ * Three orthonormal directions, keeping the ones that are worth keeping.
+ *
+ * A vector that survives is normalised against the ones already accepted; one
+ * that does not is replaced by whatever direction is still free, which is what
+ * gives a round group and a flat one a complete frame instead of a degenerate
+ * one.
+ * @param raw - The directions as the cross products left them.
+ * @returns Three unit vectors, mutually orthogonal.
+ */
+function orthonormalise(
+  raw: readonly Vector3[],
+): readonly [Vector3, Vector3, Vector3] {
+  const kept: Vector3[] = [];
+  for (const vector of raw) kept.push(against(vector, kept));
+  for (let i = 0; i < 3; i++) {
+    if (kept[i] !== ZERO) continue;
+    kept[i] = against(freeDirection(kept), kept);
+  }
+  return [kept[0] as Vector3, kept[1] as Vector3, kept[2] as Vector3];
+}
+
+/**
+ * One vector with every accepted direction taken out of it, then normalised.
+ * @param vector - The direction to keep only what is new about.
+ * @param accepted - The directions already settled on.
+ * @returns The unit remainder, or the zero vector when nothing was left of it.
+ */
+function against(vector: Vector3, accepted: readonly Vector3[]): Vector3 {
+  let [x, y, z] = vector;
+  for (const other of accepted) {
+    const along = x * other[0] + y * other[1] + z * other[2];
+    x -= along * other[0];
+    y -= along * other[1];
+    z -= along * other[2];
+  }
+  const length = norm([x, y, z]);
+  if (!(length > 1e-6)) return ZERO;
+  return [x / length, y / length, z / length];
+}
+
+/**
+ * A standard axis that the accepted directions do not already cover.
+ * @param accepted - The directions already settled on.
+ * @returns The axis least accounted for by them.
+ */
+function freeDirection(accepted: readonly Vector3[]): Vector3 {
+  let best: Vector3 = AXES[0];
+  let leastCovered = Number.POSITIVE_INFINITY;
+  for (const axis of AXES) {
+    let covered = 0;
+    for (const other of accepted) {
+      const along =
+        axis[0] * other[0] + axis[1] * other[1] + axis[2] * other[2];
+      covered += along * along;
+    }
+    if (covered < leastCovered) {
+      leastCovered = covered;
+      best = axis;
+    }
+  }
+  return best;
+}
+
+function cross(a: Vector3, b: Vector3): Vector3 {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+  ];
+}
+
+function norm(vector: Vector3): number {
+  return Math.hypot(vector[0], vector[1], vector[2]);
+}
+
+function scaleVector(vector: Vector3, by: number): Vector3 {
+  return [vector[0] * by, vector[1] * by, vector[2] * by];
+}
+
+const ZERO: Vector3 = [0, 0, 0];
+const AXES: readonly [Vector3, Vector3, Vector3] = [
+  [1, 0, 0],
+  [0, 1, 0],
+  [0, 0, 1],
+];
+const NOTHING: SymmetricEigen3 = { values: [0, 0, 0], vectors: AXES };