react-cheminfo 0.9.0 → 0.11.0

package/lib/scatter3d/core/ellipsoidSilhouette.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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';
+/** 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 declare function ellipsoidSilhouette(ellipsoid: ConfidenceEllipsoid, camera: OrbitCamera): EllipsoidSilhouette;
+//# sourceMappingURL=ellipsoidSilhouette.d.ts.map

package/lib/scatter3d/core/ellipsoidSilhouette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoidSilhouette.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/core/ellipsoidSilhouette.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,mBAAmB,EAC9B,MAAM,EAAE,WAAW,GAClB,mBAAmB,CA4BrB"}

package/lib/scatter3d/core/ellipsoidSilhouette.js

@@ -0,0 +1,52 @@
+/**
+ * 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 { rotatePoint } from "./orbitCamera.js";
+/**
+ * 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, camera) {
+    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),
+    };
+}
+//# sourceMappingURL=ellipsoidSilhouette.js.map

package/lib/scatter3d/core/ellipsoidSilhouette.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoidSilhouette.js","sourceRoot":"","sources":["../../../src/scatter3d/core/ellipsoidSilhouette.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAgB/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA8B,EAC9B,MAAmB;IAEnB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC;IAC9C,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAErC,2EAA2E;IAC3E,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpB,MAAM,EAAE,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACrE,MAAM,EAAE,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;IACzD,MAAM,EAAE,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC;IAE/D,MAAM,MAAM,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAE3C,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QACpB,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QACpB,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/lib/scatter3d/core/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/lib/scatter3d/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EACV,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EACL,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,OAAO,GACR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/lib/scatter3d/core/index.js

@@ -0,0 +1,22 @@
+/**
+ * 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 { confidenceEllipsoid, ellipsoidStandardDeviations, } from "./confidenceEllipsoid.js";
+export { CUBE_ARMS, CUBE_ORIGIN, cubeEdges } from "./cubeFrame.js";
+export { coverageForStandardDeviations3, standardDeviationsForCoverage3, } from "./ellipsoidCoverage.js";
+export { ellipsoidSilhouette } from "./ellipsoidSilhouette.js";
+export { CUBE_HALF_DIAGONAL, DEFAULT_ORBIT_CAMERA, ORBIT_PITCH_LIMIT, ORBIT_RADIANS_PER_PIXEL, depthFraction, orbitByDrag, projectPoint, rotatePoint, } from "./orbitCamera.js";
+export { cubePoints } from "./cubePoints.js";
+export { symmetricEigen3 } from "./symmetricEigen.js";
+//# sourceMappingURL=index.js.map

package/lib/scatter3d/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/scatter3d/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,EACL,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EACL,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAO/D,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/lib/scatter3d/core/orbitCamera.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 declare const DEFAULT_ORBIT_CAMERA: OrbitCamera;
+/**
+ * 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 declare const ORBIT_PITCH_LIMIT = 1.4;
+/** How many radians one pixel of drag turns the scene. */
+export declare 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 declare function rotatePoint(point: Vector3, camera: OrbitCamera): Vector3;
+/** 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 declare function projectPoint(point: Vector3, camera: OrbitCamera, viewport: OrbitViewport): ProjectedPoint;
+/**
+ * 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 declare function orbitByDrag(camera: OrbitCamera, dx: number, dy: number): OrbitCamera;
+/**
+ * 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 declare const CUBE_HALF_DIAGONAL: number;
+/**
+ * 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 declare function depthFraction(depth: number): number;
+//# sourceMappingURL=orbitCamera.d.ts.map

package/lib/scatter3d/core/orbitCamera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orbitCamera.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/core/orbitCamera.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,CAAC,EAAE,MAAM,CAAC;IACV,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAsC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CASxE;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,GACtB,cAAc,CAQhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,EACnB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,WAAW,CAMb;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAe,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAInD"}

package/lib/scatter3d/core/orbitCamera.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+/**
+ * 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 = { 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, camera) {
+    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 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, camera, viewport) {
+    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, dx, dy) {
+    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) {
+    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));
+}
+//# sourceMappingURL=orbitCamera.js.map

package/lib/scatter3d/core/orbitCamera.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orbitCamera.js","sourceRoot":"","sources":["../../../src/scatter3d/core/orbitCamera.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiCH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAgB,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,MAAmB;IAC7D,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;IACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC;IAC5C,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;AAChF,CAAC;AAYD;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,MAAmB,EACnB,QAAuB;IAEvB,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACxD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IAC7C,OAAO;QACL,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,KAAK;QAC1B,CAAC,EAAE,OAAO,GAAG,EAAE,GAAG,KAAK;QACvB,KAAK,EAAE,OAAO;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,MAAmB,EACnB,EAAU,EACV,EAAU;IAEV,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,GAAG,EAAE,GAAG,uBAAuB,CAAC;IAC1D,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,EAAE,GAAG,uBAAuB;QAC9C,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;KACxE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/lib/scatter3d/core/symmetricEigen.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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];
+}
+/**
+ * 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 declare function symmetricEigen3(matrix: SymmetricMatrix3): SymmetricEigen3;
+//# sourceMappingURL=symmetricEigen.d.ts.map

package/lib/scatter3d/core/symmetricEigen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symmetricEigen.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/core/symmetricEigen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,gFAAgF;IAChF,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;CAC/C;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAoBzE"}

package/lib/scatter3d/core/symmetricEigen.js

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    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 = [];
+    for (let i = 0; i < 3; i++) {
+        raw.push(eigenvector(matrix, values[i], 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) {
+    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],
+            diagonal[1],
+            diagonal[2],
+        ];
+    }
+    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, b) {
+    return b - a;
+}
+function determinant3(matrix) {
+    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, value, scale) {
+    const { xx, xy, xz, yy, yz, zz } = matrix;
+    const rows = [
+        [xx - value, xy, xz],
+        [xy, yy - value, yz],
+        [xz, yz, zz - value],
+    ];
+    let best = ZERO;
+    let bestLength = 0;
+    for (let i = 0; i < 3; i++) {
+        for (let j = i + 1; j < 3; j++) {
+            const candidate = cross(rows[i], rows[j]);
+            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) {
+    const kept = [];
+    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], kept[1], kept[2]];
+}
+/**
+ * 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, accepted) {
+    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) {
+    let best = 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, b) {
+    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) {
+    return Math.hypot(vector[0], vector[1], vector[2]);
+}
+function scaleVector(vector, by) {
+    return [vector[0] * by, vector[1] * by, vector[2] * by];
+}
+const ZERO = [0, 0, 0];
+const AXES = [
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+];
+const NOTHING = { values: [0, 0, 0], vectors: AXES };
+//# sourceMappingURL=symmetricEigen.js.map