react-cheminfo 0.10.0 → 0.12.0

package/lib/scatter3d/ui/CloudFrameLayer.d.ts

@@ -0,0 +1,33 @@
+import type { ReactElement } from 'react';
+import type { OrbitCamera, OrbitViewport } from '../core/orbitCamera.ts';
+/** What {@link CloudFrameLayer} draws. */
+export interface CloudFrameLayerProps {
+    /** Where the reader is standing. */
+    camera: OrbitCamera;
+    /** Where the middle of the cube is, and how large it is drawn. */
+    viewport: OrbitViewport;
+    /** What the axis running left to right is called. */
+    xLabel: string;
+    /** What the axis running bottom to top is called. */
+    yLabel: string;
+    /** What the axis running away from the reader is called. */
+    zLabel: string;
+}
+/**
+ * The box the cloud sits in, and the three arms that name its axes.
+ *
+ * A cloud of dots on an empty background has no orientation: turn it and
+ * nothing says it turned, and a dot near the top of the picture could be near
+ * or far. The frame is what fixes that, and it is why the projection can stay
+ * orthographic — it carries the depth that perspective would otherwise have
+ * to, and unlike perspective it distorts no distance the reader is there to
+ * compare.
+ *
+ * All twelve edges are drawn, not the three at the back: which edges are
+ * hidden changes as the box turns, and a frame that kept rearranging itself
+ * would read as three axes rather than as one box.
+ * @param props - See {@link CloudFrameLayerProps}.
+ * @returns The frame.
+ */
+export declare const CloudFrameLayer: import("react").MemoExoticComponent<(props: CloudFrameLayerProps) => ReactElement>;
+//# sourceMappingURL=CloudFrameLayer.d.ts.map

package/lib/scatter3d/ui/CloudFrameLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudFrameLayer.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/ui/CloudFrameLayer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAI1C,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAKzE,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,MAAM,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,QAAQ,EAAE,aAAa,CAAC;IACxB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,8CACnB,oBAAoB,KAC1B,YAAY,CAiDb,CAAC"}

package/lib/scatter3d/ui/CloudFrameLayer.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo } from 'react';
+import { CUBE_ARMS, CUBE_ORIGIN, cubeEdges } from "../core/cubeFrame.js";
+import { projectPoint } from "../core/orbitCamera.js";
+import { projectSegments } from "./cloudGeometry.js";
+/**
+ * The box the cloud sits in, and the three arms that name its axes.
+ *
+ * A cloud of dots on an empty background has no orientation: turn it and
+ * nothing says it turned, and a dot near the top of the picture could be near
+ * or far. The frame is what fixes that, and it is why the projection can stay
+ * orthographic — it carries the depth that perspective would otherwise have
+ * to, and unlike perspective it distorts no distance the reader is there to
+ * compare.
+ *
+ * All twelve edges are drawn, not the three at the back: which edges are
+ * hidden changes as the box turns, and a frame that kept rearranging itself
+ * would read as three axes rather than as one box.
+ * @param props - See {@link CloudFrameLayerProps}.
+ * @returns The frame.
+ */
+export const CloudFrameLayer = memo(function CloudFrameLayer(props) {
+    const { camera, viewport, xLabel, yLabel, zLabel } = props;
+    const edges = projectSegments(EDGES, camera, viewport);
+    const origin = projectPoint(CUBE_ORIGIN, camera, viewport);
+    const names = { x: xLabel, y: yLabel, z: zLabel };
+    return (_jsxs("g", { "data-layer": "frame", pointerEvents: "none", children: [edges.map((edge, at) => (_jsx("line", { x1: edge.x1, y1: edge.y1, x2: edge.x2, y2: edge.y2, stroke: "var(--border)", strokeWidth: 1 }, EDGE_KEYS[at]))), CUBE_ARMS.map((arm) => {
+                const end = projectPoint(arm.end, camera, viewport);
+                const label = projectPoint(arm.label, camera, viewport);
+                return (_jsxs("g", { children: [_jsx("line", { x1: origin.x, y1: origin.y, x2: end.x, y2: end.y, stroke: "var(--border-strong)", strokeWidth: 1.5 }), _jsx("text", { x: label.x, y: label.y, textAnchor: "middle", dominantBaseline: "central", fontSize: ARM_LABEL_SIZE, fontWeight: 600, fill: "var(--text-muted)", children: names[arm.axis] })] }, arm.axis));
+            })] }));
+});
+/** Cut once, because the corners of a cube do not depend on the camera. */
+const EDGES = cubeEdges();
+/** Each edge named by its two corners, which stay put however the box turns. */
+const EDGE_KEYS = EDGES.map(([from, to]) => `${from.join(' ')}|${to.join(' ')}`);
+/** The same size a chart writes an axis title at, so the two read alike. */
+const ARM_LABEL_SIZE = 11;
+//# sourceMappingURL=CloudFrameLayer.js.map

package/lib/scatter3d/ui/CloudFrameLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudFrameLayer.js","sourceRoot":"","sources":["../../../src/scatter3d/ui/CloudFrameLayer.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAgBrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,eAAe,CAC1D,KAA2B;IAE3B,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAE3D,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAElD,OAAO,CACL,2BAAc,OAAO,EAAC,aAAa,EAAC,MAAM,aACvC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,CACvB,eAEE,EAAE,EAAE,IAAI,CAAC,EAAE,EACX,EAAE,EAAE,IAAI,CAAC,EAAE,EACX,EAAE,EAAE,IAAI,CAAC,EAAE,EACX,EAAE,EAAE,IAAI,CAAC,EAAE,EACX,MAAM,EAAC,eAAe,EACtB,WAAW,EAAE,CAAC,IANT,SAAS,CAAC,EAAE,CAAC,CAOlB,CACH,CAAC,EACD,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACrB,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACpD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACxD,OAAO,CACL,wBACE,eACE,EAAE,EAAE,MAAM,CAAC,CAAC,EACZ,EAAE,EAAE,MAAM,CAAC,CAAC,EACZ,EAAE,EAAE,GAAG,CAAC,CAAC,EACT,EAAE,EAAE,GAAG,CAAC,CAAC,EACT,MAAM,EAAC,sBAAsB,EAC7B,WAAW,EAAE,GAAG,GAChB,EACF,eACE,CAAC,EAAE,KAAK,CAAC,CAAC,EACV,CAAC,EAAE,KAAK,CAAC,CAAC,EACV,UAAU,EAAC,QAAQ,EACnB,gBAAgB,EAAC,SAAS,EAC1B,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,GAAG,EACf,IAAI,EAAC,mBAAmB,YAEvB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GACX,KAnBD,GAAG,CAAC,IAAI,CAoBZ,CACL,CAAC;YACJ,CAAC,CAAC,IACA,CACL,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,2EAA2E;AAC3E,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;AAE1B,gFAAgF;AAChF,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CACzB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACpD,CAAC;AAEF,4EAA4E;AAC5E,MAAM,cAAc,GAAG,EAAE,CAAC"}

package/lib/scatter3d/ui/CloudShellLayer.d.ts

@@ -0,0 +1,51 @@
+import type { ReactElement } from 'react';
+import type { ConfidenceEllipsoid } from '../core/confidenceEllipsoid.ts';
+import type { OrbitCamera, OrbitViewport } from '../core/orbitCamera.ts';
+/** One group's shell, fitted once and ready to be turned. */
+export interface CloudShell {
+    /** A stable key, so a re-render does not rebuild every shell. */
+    id: string;
+    /** Its colour, which is its group's. */
+    color: string;
+    /** The shape it summarises, in cube units. */
+    ellipsoid: ConfidenceEllipsoid;
+    /**
+     * How strongly it is drawn, from a legend entry switching its group off.
+     * @default 1
+     */
+    opacity?: number;
+}
+/** What {@link CloudShellLayer} draws. */
+export interface CloudShellLayerProps {
+    /** The shells, one per group that has one. */
+    shells: readonly CloudShell[];
+    /** Where the reader is standing. */
+    camera: OrbitCamera;
+    /** Where the middle of the cube is, and how large it is drawn. */
+    viewport: OrbitViewport;
+    /**
+     * How solid one wall of the glass is. Turn it down when many groups overlap,
+     * since two shells crossing compound to twice this.
+     * @default 0.1
+     */
+    fillOpacity?: number;
+}
+/**
+ * The group shells, as translucent glass.
+ *
+ * Each one is drawn as a single ellipse, because that is exactly what a shell
+ * looks like: an orthographic camera sends a sphere carried by three axes to
+ * an ellipse, whatever it is turned to. So the outline is a curve rather than
+ * a ring of facets, it stays a curve at any zoom, and there are no seams
+ * between neighbouring faces to read as a wireframe.
+ *
+ * The depth is carried by the fill. A ray through a shell crosses it twice —
+ * the near wall and the far one — so the glass is darkest where the reader
+ * looks through both walls at a glancing angle, which is the rim, and lightest
+ * through the middle where the far wall is turned away. One radial gradient
+ * says the shell is a solid.
+ * @param props - See {@link CloudShellLayerProps}.
+ * @returns The shells.
+ */
+export declare const CloudShellLayer: import("react").MemoExoticComponent<(props: CloudShellLayerProps) => ReactElement>;
+//# sourceMappingURL=CloudShellLayer.d.ts.map

package/lib/scatter3d/ui/CloudShellLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudShellLayer.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/ui/CloudShellLayer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAKzE,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,mBAAmB,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,oCAAoC;IACpC,MAAM,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,8CACnB,oBAAoB,KAC1B,YAAY,CA8Cb,CAAC"}

package/lib/scatter3d/ui/CloudShellLayer.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo, useId } from 'react';
+import { projectShellOutline } from "./cloudGeometry.js";
+import { SHELL_FILL_OPACITY, shellGlassStops } from "./cloudShellStyles.js";
+/**
+ * The group shells, as translucent glass.
+ *
+ * Each one is drawn as a single ellipse, because that is exactly what a shell
+ * looks like: an orthographic camera sends a sphere carried by three axes to
+ * an ellipse, whatever it is turned to. So the outline is a curve rather than
+ * a ring of facets, it stays a curve at any zoom, and there are no seams
+ * between neighbouring faces to read as a wireframe.
+ *
+ * The depth is carried by the fill. A ray through a shell crosses it twice —
+ * the near wall and the far one — so the glass is darkest where the reader
+ * looks through both walls at a glancing angle, which is the rim, and lightest
+ * through the middle where the far wall is turned away. One radial gradient
+ * says the shell is a solid.
+ * @param props - See {@link CloudShellLayerProps}.
+ * @returns The shells.
+ */
+export const CloudShellLayer = memo(function CloudShellLayer(props) {
+    const { shells, camera, viewport, fillOpacity = SHELL_FILL_OPACITY } = props;
+    const prefix = useId();
+    const drawn = [];
+    for (const shell of shells) {
+        const outline = projectShellOutline(shell.ellipsoid, camera, viewport);
+        if (outline === null)
+            continue;
+        drawn.push({ shell, outline });
+    }
+    // Furthest first, so a shell in front of another is drawn over it.
+    drawn.sort((a, b) => a.outline.depth - b.outline.depth);
+    return (_jsx("g", { "data-layer": "shells", pointerEvents: "none", children: drawn.map(({ shell, outline }) => {
+            const paint = `${prefix}${shell.id}`;
+            return (_jsxs("g", { "data-shell": shell.id, children: [_jsx("defs", { children: _jsx("radialGradient", { id: paint, children: shellGlassStops((shell.opacity ?? 1) * fillOpacity).map((stop) => (_jsx("stop", { offset: stop.offset, stopColor: shell.color, stopOpacity: stop.opacity }, stop.offset))) }) }), _jsx("ellipse", { cx: outline.cx, cy: outline.cy, rx: outline.rx, ry: outline.ry, transform: `rotate(${outline.angle} ${outline.cx} ${outline.cy})`, fill: `url(#${paint})` })] }, shell.id));
+        }) }));
+});
+//# sourceMappingURL=CloudShellLayer.js.map

package/lib/scatter3d/ui/CloudShellLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudShellLayer.js","sourceRoot":"","sources":["../../../src/scatter3d/ui/CloudShellLayer.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAKpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAiC5E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,eAAe,CAC1D,KAA2B;IAE3B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,kBAAkB,EAAE,GAAG,KAAK,CAAC;IAC7E,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC;IAEvB,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACvE,IAAI,OAAO,KAAK,IAAI;YAAE,SAAS;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IACjC,CAAC;IACD,mEAAmE;IACnE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAExD,OAAO,CACL,0BAAc,QAAQ,EAAC,aAAa,EAAC,MAAM,YACxC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,GAAG,MAAM,GAAG,KAAK,CAAC,EAAE,EAAE,CAAC;YACrC,OAAO,CACL,2BAA8B,KAAK,CAAC,EAAE,aACpC,yBACE,yBAAgB,EAAE,EAAE,KAAK,YACtB,eAAe,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,GAAG,CACtD,CAAC,IAAI,EAAE,EAAE,CAAC,CACR,eAEE,MAAM,EAAE,IAAI,CAAC,MAAM,EACnB,SAAS,EAAE,KAAK,CAAC,KAAK,EACtB,WAAW,EAAE,IAAI,CAAC,OAAO,IAHpB,IAAI,CAAC,MAAM,CAIhB,CACH,CACF,GACc,GACZ,EACP,kBACE,EAAE,EAAE,OAAO,CAAC,EAAE,EACd,EAAE,EAAE,OAAO,CAAC,EAAE,EACd,EAAE,EAAE,OAAO,CAAC,EAAE,EACd,EAAE,EAAE,OAAO,CAAC,EAAE,EACd,SAAS,EAAE,UAAU,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,EAAE,GAAG,EACjE,IAAI,EAAE,QAAQ,KAAK,GAAG,GACtB,KAtBI,KAAK,CAAC,EAAE,CAuBZ,CACL,CAAC;QACJ,CAAC,CAAC,GACA,CACL,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/lib/scatter3d/ui/ScatterCloud.d.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+import type { ScatterCloudProps } from './scatterCloudProps.ts';
+/**
+ * A cloud of samples in a box the reader can turn, with a glass shell around
+ * each group.
+ *
+ * It is the flat scatter's twin and shares with it everything it can — the
+ * selection, the lasso, the keyboard cursor, the hover card, the labels and
+ * the group colours are the same hooks and the same layers — because a reader
+ * who has learned the map must not have to learn this separately. What it
+ * cannot share is the frame: three axes seen from an angle have no room for
+ * three sets of tick labels, so the axes are all stretched to one cube, the
+ * frame names them, and the numbers stay in the card the pointer raises.
+ *
+ * It draws in SVG rather than in WebGL, and that is a decision about saving
+ * rather than about drawing. Every other figure in this package is saved from
+ * the bar above it as an SVG, and a canvas laid over the same picture would
+ * leave a hole in that file exactly where the shells are.
+ * @param props - See {@link ScatterCloudProps}.
+ * @returns The cloud.
+ */
+export declare function ScatterCloud(props: ScatterCloudProps): ReactElement;
+//# sourceMappingURL=ScatterCloud.d.ts.map

package/lib/scatter3d/ui/ScatterCloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScatterCloud.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/ui/ScatterCloud.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiC,YAAY,EAAE,MAAM,OAAO,CAAC;AAwBzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAyLnE"}

package/lib/scatter3d/ui/ScatterCloud.js

@@ -0,0 +1,151 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { CHART_WHEEL_DWELL, useWheelZoom, } from "../../chart/ui/useWheelZoom.js";
+import { ScatterMarkLayer } from "../../scatter/ui/ScatterMarkLayer.js";
+import { ScatterOverlayLayers } from "../../scatter/ui/ScatterOverlayLayers.js";
+import { ScatterPointLayer } from "../../scatter/ui/ScatterPointLayer.js";
+import { scatterGroupInk } from "../../scatter/ui/scatterPlotModel.js";
+import { useScatterInteraction } from "../../scatter/ui/useScatterInteraction.js";
+import { useScatterLabels } from "../../scatter/ui/useScatterLabels.js";
+import { cubePoints } from "../core/cubePoints.js";
+import { DEFAULT_ORBIT_CAMERA } from "../core/orbitCamera.js";
+import { CloudFrameLayer } from "./CloudFrameLayer.js";
+import { CloudShellLayer } from "./CloudShellLayer.js";
+import { cloudPointRadii, cloudView, projectCloud } from "./cloudGeometry.js";
+import { clampCloudZoom } from "./cloudZoom.js";
+import { cloudLabel, cloudShells } from "./scatterCloudModel.js";
+import { useOrbitDrag } from "./useOrbitDrag.js";
+/**
+ * A cloud of samples in a box the reader can turn, with a glass shell around
+ * each group.
+ *
+ * It is the flat scatter's twin and shares with it everything it can — the
+ * selection, the lasso, the keyboard cursor, the hover card, the labels and
+ * the group colours are the same hooks and the same layers — because a reader
+ * who has learned the map must not have to learn this separately. What it
+ * cannot share is the frame: three axes seen from an angle have no room for
+ * three sets of tick labels, so the axes are all stretched to one cube, the
+ * frame names them, and the numbers stay in the card the pointer raises.
+ *
+ * It draws in SVG rather than in WebGL, and that is a decision about saving
+ * rather than about drawing. Every other figure in this package is saved from
+ * the bar above it as an SVG, and a canvas laid over the same picture would
+ * leave a hole in that file exactly where the shells are.
+ * @param props - See {@link ScatterCloudProps}.
+ * @returns The cloud.
+ */
+export function ScatterCloud(props) {
+    const { x, y, z, width, height, xLabel, yLabel, zLabel } = props;
+    const { groupOf, groups, mutedGroups, ellipsoid = null } = props;
+    const { ellipsoidMinimumPoints, ellipsoidFillOpacity } = props;
+    const { showGroupLabels = false, pointLabels, pointRadius = 3.5 } = props;
+    const { outlinedFrom, selected, defaultSelected, onSelectionChange } = props;
+    const { selectMode = 'replace', onHoverChange, onPinChange } = props;
+    const { onLassoChange, onPointDoubleClick, overlay } = props;
+    const { gesture = 'turn', wheelZoom = true, wheelZoomDelay } = props;
+    const { label, className, testId } = props;
+    const [ownCamera, setOwnCamera] = useState(DEFAULT_ORBIT_CAMERA);
+    const [ownZoom, setOwnZoom] = useState(1);
+    const camera = props.camera ?? ownCamera;
+    const zoom = props.zoom ?? ownZoom;
+    const selecting = gesture === 'select';
+    const view = useMemo(() => cloudView(width, height, zoom), [height, width, zoom]);
+    const cube = useMemo(() => cubePoints(x, y, z), [x, y, z]);
+    const cloud = useMemo(() => projectCloud(cube, camera, view.viewport), [camera, cube, view.viewport]);
+    const radii = useMemo(() => cloudPointRadii(cloud.depths, pointRadius), [cloud.depths, pointRadius]);
+    const ink = useMemo(() => scatterGroupInk(groups, mutedGroups), [groups, mutedGroups]);
+    const shells = useMemo(() => ellipsoid === null || groupOf === undefined || groups === undefined
+        ? NO_SHELLS
+        : cloudShells({
+            cube,
+            groupOf,
+            groups,
+            ink,
+            size: ellipsoid,
+            minimumPoints: ellipsoidMinimumPoints,
+        }), [cube, ellipsoid, ellipsoidMinimumPoints, groupOf, groups, ink]);
+    const interaction = useScatterInteraction({
+        points: cloud.points,
+        selected,
+        defaultSelected,
+        onSelectionChange,
+        selectMode,
+        enabled: selecting,
+        touchLasso: selecting,
+        hoverRadius: pointRadius + HOVER_SLACK,
+        onHoverChange,
+        onPinChange,
+        onLassoChange,
+    });
+    const labels = useScatterLabels(cloud.points, {
+        pointLabels,
+        showGroupLabels,
+        groups,
+        groupOf,
+        colors: ink.colors,
+        radius: pointRadius,
+        bounds: view.rect,
+    });
+    // Everything a gesture callback reads is taken from here rather than from
+    // the closure, so a caller that owns the camera and answers with an inline
+    // arrow — which is how every caller writes it — does not rebuild the drag
+    // sixty times during its own turn.
+    const live = useRef({ camera, zoom, interaction, props });
+    useLayoutEffect(() => {
+        live.current = { camera, zoom, interaction, props };
+    });
+    const onOrbit = useCallback((turn) => {
+        const next = turn(live.current.camera);
+        // Written back so the frames of one drag compose, rather than each of them
+        // turning the camera React has not re-rendered with yet.
+        live.current.camera = next;
+        if (live.current.props.camera === undefined)
+            setOwnCamera(next);
+        live.current.props.onCameraChange?.(next);
+    }, []);
+    const onTap = useCallback((tapX, tapY, mode) => {
+        live.current.interaction.clickAt(tapX, tapY, mode);
+    }, []);
+    const onWheel = useCallback((_x, _y, factor) => {
+        // A factor above one widens a frame, which on a box means standing back.
+        const next = clampCloudZoom(live.current.zoom / factor);
+        live.current.zoom = next;
+        if (live.current.props.zoom === undefined)
+            setOwnZoom(next);
+        live.current.props.onZoomChange?.(next);
+    }, []);
+    function handleDoubleClick(event) {
+        if (onPointDoubleClick === undefined)
+            return;
+        const opened = interaction.openAt(event);
+        if (opened !== null)
+            onPointDoubleClick(opened);
+    }
+    const orbit = useOrbitDrag({
+        enabled: !selecting,
+        onOrbit,
+        onTap,
+        onMove: interaction.hover.moveTo,
+        onLeave: interaction.hover.leave,
+        mode: selectMode,
+    });
+    const { ref: wheelSurface } = useWheelZoom({
+        enabled: wheelZoom,
+        delay: wheelZoomDelay ?? CHART_WHEEL_DWELL,
+        onZoom: onWheel,
+    });
+    return (_jsxs("div", { className: className, "data-testid": testId, style: { position: 'relative', width, height }, role: "img", "aria-label": label ?? cloudLabel(xLabel, yLabel, zLabel, cube.length), children: [_jsxs("svg", { width: width, height: height, style: SVG_STYLE, children: [_jsx(CloudFrameLayer, { camera: camera, viewport: view.viewport, xLabel: xLabel, yLabel: yLabel, zLabel: zLabel }), _jsx(CloudShellLayer, { shells: shells, camera: camera, viewport: view.viewport, fillOpacity: ellipsoidFillOpacity }), _jsx(ScatterPointLayer, { points: cloud.points, order: cloud.order, radii: radii, groupOf: groupOf, colors: ink.colors, opacities: ink.opacities, radius: pointRadius, outlinedFrom: outlinedFrom }), _jsx(ScatterMarkLayer, { points: cloud.points, selected: interaction.selection.mask, hovered: interaction.hover.hovered, focused: interaction.keyboard.cursor, radius: pointRadius }), _jsx(ScatterOverlayLayers, { labels: labels, radius: pointRadius, lassoPath: interaction.lasso.pathData }), _jsx("rect", { x: 0, y: 0, width: Math.max(0, width), height: Math.max(0, height), ref: wheelSurface, fill: "transparent", tabIndex: 0, onKeyDown: interaction.keyboard.onKeyDown, onDoubleClick: handleDoubleClick, ...(selecting ? interaction.surface : orbit.surface) })] }), overlay] }));
+}
+/**
+ * How much further than a dot's own radius the pointer may be and still catch
+ * it.
+ *
+ * More slack than the map allows, because a dot in a cloud is a smaller target
+ * than the same dot on a map: the box is turned, so the dots are packed into a
+ * hexagon rather than spread over a rectangle, and the ones at the back are
+ * drawn smaller still.
+ */
+const HOVER_SLACK = 8.5;
+const NO_SHELLS = [];
+const SVG_STYLE = { display: 'block', touchAction: 'none' };
+//# sourceMappingURL=ScatterCloud.js.map

package/lib/scatter3d/ui/ScatterCloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScatterCloud.js","sourceRoot":"","sources":["../../../src/scatter3d/ui/ScatterCloud.tsx"],"names":[],"mappings":"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"}

package/lib/scatter3d/ui/cloudGeometry.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Where the cube, the cloud and the shells land on screen for one camera.
+ *
+ * Everything a cloud draws is fitted once, in cube units, and re-projected on
+ * every turn — so an orbit costs one rotation per sample and one silhouette
+ * per shell, and nothing is fitted again while the box is turning.
+ */
+import type { ScreenPoints } from '../../scatter/core/screenPoints.ts';
+import type { ConfidenceEllipsoid } from '../core/confidenceEllipsoid.ts';
+import type { OrbitCamera, OrbitViewport, Vector3 } from '../core/orbitCamera.ts';
+/** Room kept between the figure's edge and the cube, in pixels. */
+export declare const CLOUD_MARGIN = 16;
+/**
+ * How much of the shorter side the cube spans before the reader zooms.
+ *
+ * Well short of the whole: the cube is drawn turned, so its silhouette is a
+ * hexagon as wide as its body diagonal, and a cube sized to the box edge-on
+ * would push two of its corners past the frame the moment it was turned.
+ */
+export declare const CLOUD_FILL = 0.62;
+/** The rectangle the cloud is drawn in, and how the cube maps into it. */
+export interface CloudView {
+    /** The drawing area, ready to spread onto a `<rect>`. */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Where the middle of the cube sits, and how large it is drawn. */
+    viewport: OrbitViewport;
+}
+/**
+ * The drawing area and the cube's place in it.
+ * @param width - Total width of the figure, in pixels.
+ * @param height - Total height.
+ * @param zoom - What the reader has zoomed to; `1` is the resting size.
+ * @returns See {@link CloudView}.
+ */
+export declare function cloudView(width: number, height: number, zoom: number): CloudView;
+/** Where every sample landed, and in what order they are painted. */
+export interface CloudCloud {
+    /** The positions, in the same space a gesture arrives in. */
+    points: ScreenPoints;
+    /** How far towards the reader each one is, in cube units. */
+    depths: Float64Array;
+    /** The rows, furthest first, which is the order they are drawn in. */
+    order: Uint32Array;
+}
+/**
+ * Every sample, projected and ordered back to front.
+ *
+ * The order is what makes the cloud read as a solid: a dot at the front drawn
+ * over a dot at the back says which is which, where the same two dots in row
+ * order say nothing at all. It is a separate array rather than a sorted copy
+ * of the points because the hit test, the labels and the selection all index
+ * by row and must not be reordered with the painting.
+ * @param cube - Every sample, 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 CloudCloud}.
+ */
+export declare function projectCloud(cube: readonly Vector3[], camera: OrbitCamera, viewport: OrbitViewport): CloudCloud;
+/**
+ * How large each dot is drawn, from how near the front of the box it sits.
+ *
+ * A fifth larger at the front than at the back: enough that the eye reads it
+ * as depth when it is looking for depth, and little enough that nobody takes
+ * it for a value — a dot size that carried a measurement would be a fourth
+ * dimension nothing labelled. It is read from the projection rather than from
+ * the data, so a turn changes it and a filter does not.
+ * @param depths - How far towards the reader each sample is, in cube units.
+ * @param radius - Radius of a dot at the middle of the box, in pixels.
+ * @returns One radius per sample, in pixels.
+ */
+export declare function cloudPointRadii(depths: Float64Array, radius: number): Float64Array;
+/** One shell's outline, ready to be filled. */
+export interface CloudOutline {
+    /** Where its middle landed, in pixels from the left. */
+    cx: number;
+    /** And from the top. */
+    cy: number;
+    /** Half its longest width, in pixels. */
+    rx: number;
+    /** Half its width across that, in pixels. */
+    ry: number;
+    /** How far the long axis is turned from the horizontal, in degrees. */
+    angle: number;
+    /** How far towards the reader its middle is, in cube units. */
+    depth: number;
+}
+/**
+ * Where one shell's outline lands on screen.
+ * @param ellipsoid - The shell, 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 CloudOutline}, or `null` when the camera sends the shell nowhere a browser can draw.
+ */
+export declare function projectShellOutline(ellipsoid: ConfidenceEllipsoid, camera: OrbitCamera, viewport: OrbitViewport): CloudOutline | null;
+/** A segment of the frame, in pixels. */
+export interface CloudSegment {
+    /** Where it starts. */
+    x1: number;
+    /** Where it starts. */
+    y1: number;
+    /** Where it ends. */
+    x2: number;
+    /** Where it ends. */
+    y2: number;
+}
+/**
+ * A run of cube-space segments, projected.
+ * @param segments - The segments, as pairs of corners 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 The segments, in pixels, in the order they were given.
+ */
+export declare function projectSegments(segments: ReadonlyArray<readonly [Vector3, Vector3]>, camera: OrbitCamera, viewport: OrbitViewport): CloudSegment[];
+//# sourceMappingURL=cloudGeometry.d.ts.map

package/lib/scatter3d/ui/cloudGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudGeometry.d.ts","sourceRoot":"","sources":["../../../src/scatter3d/ui/cloudGeometry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,OAAO,EACR,MAAM,wBAAwB,CAAC;AAGhC,mEAAmE;AACnE,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,OAAO,CAAC;AAE/B,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,oEAAoE;IACpE,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,SAAS,CAYX;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,MAAM,EAAE,YAAY,CAAC;IACrB,6DAA6D;IAC7D,MAAM,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,GACtB,UAAU,CAmBZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,GACb,YAAY,CAOd;AAQD,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,mBAAmB,EAC9B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,GACtB,YAAY,GAAG,IAAI,CAerB;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,EACpD,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,GACtB,YAAY,EAAE,CAahB"}

package/lib/scatter3d/ui/cloudGeometry.js

@@ -0,0 +1,140 @@
+/**
+ * Where the cube, the cloud and the shells land on screen for one camera.
+ *
+ * Everything a cloud draws is fitted once, in cube units, and re-projected on
+ * every turn — so an orbit costs one rotation per sample and one silhouette
+ * per shell, and nothing is fitted again while the box is turning.
+ */
+import { chartRoundPixel } from "../../chart/core/chartScale.js";
+import { ellipsoidSilhouette } from "../core/ellipsoidSilhouette.js";
+import { depthFraction, projectPoint } from "../core/orbitCamera.js";
+/** Room kept between the figure's edge and the cube, in pixels. */
+export const CLOUD_MARGIN = 16;
+/**
+ * How much of the shorter side the cube spans before the reader zooms.
+ *
+ * Well short of the whole: the cube is drawn turned, so its silhouette is a
+ * hexagon as wide as its body diagonal, and a cube sized to the box edge-on
+ * would push two of its corners past the frame the moment it was turned.
+ */
+export const CLOUD_FILL = 0.62;
+/**
+ * The drawing area and the cube's place in it.
+ * @param width - Total width of the figure, in pixels.
+ * @param height - Total height.
+ * @param zoom - What the reader has zoomed to; `1` is the resting size.
+ * @returns See {@link CloudView}.
+ */
+export function cloudView(width, height, zoom) {
+    const inner = Math.max(0, width - CLOUD_MARGIN * 2);
+    const tall = Math.max(0, height - CLOUD_MARGIN * 2);
+    const factor = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
+    return {
+        rect: { x: CLOUD_MARGIN, y: CLOUD_MARGIN, width: inner, height: tall },
+        viewport: {
+            scale: (Math.min(inner, tall) / 2) * CLOUD_FILL * factor,
+            centerX: CLOUD_MARGIN + inner / 2,
+            centerY: CLOUD_MARGIN + tall / 2,
+        },
+    };
+}
+/**
+ * Every sample, projected and ordered back to front.
+ *
+ * The order is what makes the cloud read as a solid: a dot at the front drawn
+ * over a dot at the back says which is which, where the same two dots in row
+ * order say nothing at all. It is a separate array rather than a sorted copy
+ * of the points because the hit test, the labels and the selection all index
+ * by row and must not be reordered with the painting.
+ * @param cube - Every sample, 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 CloudCloud}.
+ */
+export function projectCloud(cube, camera, viewport) {
+    const count = cube.length;
+    const x = new Float64Array(count);
+    const y = new Float64Array(count);
+    const depths = new Float64Array(count);
+    for (let index = 0; index < count; index++) {
+        const at = projectPoint(cube[index], camera, viewport);
+        x[index] = at.x;
+        y[index] = at.y;
+        depths[index] = at.depth;
+    }
+    const rows = new Uint32Array(count);
+    for (let index = 0; index < count; index++)
+        rows[index] = index;
+    const order = rows.toSorted((a, b) => depths[a] - depths[b]);
+    return { points: { x, y }, depths, order };
+}
+/**
+ * How large each dot is drawn, from how near the front of the box it sits.
+ *
+ * A fifth larger at the front than at the back: enough that the eye reads it
+ * as depth when it is looking for depth, and little enough that nobody takes
+ * it for a value — a dot size that carried a measurement would be a fourth
+ * dimension nothing labelled. It is read from the projection rather than from
+ * the data, so a turn changes it and a filter does not.
+ * @param depths - How far towards the reader each sample is, in cube units.
+ * @param radius - Radius of a dot at the middle of the box, in pixels.
+ * @returns One radius per sample, in pixels.
+ */
+export function cloudPointRadii(depths, radius) {
+    const radii = new Float64Array(depths.length);
+    for (let index = 0; index < depths.length; index++) {
+        const fraction = depthFraction(depths[index]);
+        radii[index] = radius * (NEAREST_SHRINK + DEPTH_RANGE * fraction);
+    }
+    return radii;
+}
+/** How much smaller than `radius` the dot at the very back is drawn. */
+const NEAREST_SHRINK = 0.9;
+/** How much the radius grows from the back of the box to its front. */
+const DEPTH_RANGE = 0.4;
+/**
+ * Where one shell's outline lands on screen.
+ * @param ellipsoid - The shell, 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 CloudOutline}, or `null` when the camera sends the shell nowhere a browser can draw.
+ */
+export function projectShellOutline(ellipsoid, camera, viewport) {
+    const at = projectPoint(ellipsoid.center, camera, viewport);
+    const { rx, ry, angle } = ellipsoidSilhouette(ellipsoid, camera);
+    const outline = {
+        cx: chartRoundPixel(at.x),
+        cy: chartRoundPixel(at.y),
+        rx: chartRoundPixel(rx * viewport.scale),
+        ry: chartRoundPixel(ry * viewport.scale),
+        angle: chartRoundPixel((angle * 180) / Math.PI),
+        depth: at.depth,
+    };
+    for (const value of [outline.cx, outline.cy, outline.rx, outline.ry]) {
+        if (!Number.isFinite(value))
+            return null;
+    }
+    return outline;
+}
+/**
+ * A run of cube-space segments, projected.
+ * @param segments - The segments, as pairs of corners 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 The segments, in pixels, in the order they were given.
+ */
+export function projectSegments(segments, camera, viewport) {
+    const lines = [];
+    for (const [from, to] of segments) {
+        const start = projectPoint(from, camera, viewport);
+        const end = projectPoint(to, camera, viewport);
+        lines.push({
+            x1: chartRoundPixel(start.x),
+            y1: chartRoundPixel(start.y),
+            x2: chartRoundPixel(end.x),
+            y2: chartRoundPixel(end.y),
+        });
+    }
+    return lines;
+}
+//# sourceMappingURL=cloudGeometry.js.map