react-cheminfo 0.9.0 → 0.11.0

package/src/scatter3d/ui/CloudFrameLayer.tsx

@@ -0,0 +1,97 @@
+import type { ReactElement } from 'react';
+import { memo } from 'react';
+
+import { CUBE_ARMS, CUBE_ORIGIN, cubeEdges } from '../core/cubeFrame.ts';
+import type { OrbitCamera, OrbitViewport } from '../core/orbitCamera.ts';
+import { projectPoint } from '../core/orbitCamera.ts';
+
+import { projectSegments } from './cloudGeometry.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 const CloudFrameLayer = memo(function CloudFrameLayer(
+  props: CloudFrameLayerProps,
+): ReactElement {
+  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 (
+    <g data-layer="frame" pointerEvents="none">
+      {edges.map((edge, at) => (
+        <line
+          key={at}
+          x1={edge.x1}
+          y1={edge.y1}
+          x2={edge.x2}
+          y2={edge.y2}
+          stroke="var(--border)"
+          strokeWidth={1}
+        />
+      ))}
+      {CUBE_ARMS.map((arm) => {
+        const end = projectPoint(arm.end, camera, viewport);
+        const label = projectPoint(arm.label, camera, viewport);
+        return (
+          <g key={arm.axis}>
+            <line
+              x1={origin.x}
+              y1={origin.y}
+              x2={end.x}
+              y2={end.y}
+              stroke="var(--border-strong)"
+              strokeWidth={1.5}
+            />
+            <text
+              x={label.x}
+              y={label.y}
+              textAnchor="middle"
+              dominantBaseline="central"
+              fontSize={ARM_LABEL_SIZE}
+              fontWeight={600}
+              fill="var(--text-muted)"
+            >
+              {names[arm.axis]}
+            </text>
+          </g>
+        );
+      })}
+    </g>
+  );
+});
+
+/** Cut once, because the corners of a cube do not depend on the camera. */
+const EDGES = cubeEdges();
+
+/** The same size a chart writes an axis title at, so the two read alike. */
+const ARM_LABEL_SIZE = 11;

package/src/scatter3d/ui/CloudPointLayer.tsx

@@ -0,0 +1,132 @@
+import type { ReactElement } from 'react';
+import { memo } from 'react';
+
+import type { ScreenPoints } from '../../scatter/core/screenPoints.ts';
+import { depthFraction } from '../core/orbitCamera.ts';
+
+/** What {@link CloudPointLayer} draws. */
+export interface CloudPointLayerProps {
+  /** Where every sample sits, in the figure's pixels. */
+  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 painted in. */
+  order: Uint32Array;
+  /**
+   * Which group each sample belongs to, as an index into `colors`. An entry of
+   * `-1`, or one outside the range, is a sample in no group.
+   * @default undefined — every sample is one crowd
+   */
+  groupOf?: ArrayLike<number>;
+  /**
+   * The colour of each group, in group order.
+   * @default undefined — every sample takes `fallbackColor`
+   */
+  colors?: readonly string[];
+  /**
+   * How strongly each group is drawn, in the same order.
+   * @default undefined — every group is drawn at full strength
+   */
+  opacities?: readonly number[];
+  /**
+   * Colour of a sample belonging to no group.
+   * @default 'var(--text-faint)'
+   */
+  fallbackColor?: string;
+  /**
+   * Radius of a dot at the middle of the cube, in pixels. A dot at the front
+   * is drawn larger and one at the back smaller, about this.
+   * @default 3.5
+   */
+  radius?: number;
+  /**
+   * The index from which samples are drawn as outlines rather than filled,
+   * which is how one the model was fitted on is told from one placed into it
+   * afterwards.
+   * @default undefined — every sample is filled
+   */
+  outlinedFrom?: number;
+}
+
+/**
+ * Every sample as one dot, painted from the back of the box forwards.
+ *
+ * Two things carry the depth, and neither costs an event handler: the order,
+ * so a dot in front covers one behind it, and the size, so a dot at the front
+ * of the box is a fifth larger than the same dot at the back. Both are read
+ * from the projection rather than from the data, so a turn changes them and a
+ * filter does not.
+ *
+ * Like the flat cloud's own layer, this one carries no handler and no closure
+ * per dot: every gesture lands on one transparent rectangle above it and is
+ * answered from a coordinate array.
+ * @param props - See {@link CloudPointLayerProps}.
+ * @returns The cloud.
+ */
+export const CloudPointLayer = memo(function CloudPointLayer(
+  props: CloudPointLayerProps,
+): ReactElement {
+  const { points, depths, order, groupOf, colors, opacities } = props;
+  const { fallbackColor = 'var(--text-faint)', radius = 3.5 } = props;
+  const { outlinedFrom } = props;
+
+  const xs = points.x;
+  const ys = points.y;
+  const count = Math.min(xs.length, ys.length, order.length);
+  const hollowFrom = outlineStart(outlinedFrom, count);
+
+  const dots: ReactElement[] = [];
+  for (let step = 0; step < count; step++) {
+    const index = order[step] as number;
+    const x = xs[index];
+    const y = ys[index];
+    if (x === undefined || y === undefined) continue;
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+    const group = groupOf?.[index] ?? -1;
+    const color = colors?.[group] ?? fallbackColor;
+    const alpha = opacities?.[group] ?? 1;
+    const hollow = index >= hollowFrom;
+    dots.push(
+      <circle
+        key={index}
+        cx={round(x)}
+        cy={round(y)}
+        r={round(radius * depthScale(depths[index] as number))}
+        fill={hollow ? 'none' : color}
+        stroke={hollow ? color : undefined}
+        strokeWidth={hollow ? OUTLINE_WIDTH : undefined}
+        opacity={alpha === 1 ? undefined : alpha}
+      />,
+    );
+  }
+
+  return <g data-layer="points">{dots}</g>;
+});
+
+/**
+ * How much larger a dot is drawn for sitting near the front of the box.
+ *
+ * A fifth from back to front. Enough that the eye reads it as depth when it is
+ * looking for depth, and little enough that nobody mistakes it for a value:
+ * a dot size that carried a measurement would be a fourth dimension nothing
+ * labelled.
+ * @param depth - How far towards the reader the sample is, in cube units.
+ * @returns The factor to draw its radius at.
+ */
+function depthScale(depth: number): number {
+  return 0.9 + DEPTH_RANGE * depthFraction(depth);
+}
+
+function outlineStart(outlinedFrom: number | undefined, count: number): number {
+  if (outlinedFrom === undefined || !Number.isFinite(outlinedFrom)) {
+    return count;
+  }
+  return Math.max(0, Math.floor(outlinedFrom));
+}
+
+const DEPTH_RANGE = 0.4;
+
+/** The same weight the flat cloud draws a hollow dot at, so the two read alike. */
+const OUTLINE_WIDTH = 1.5;
+
+const round = (value: number): number => Math.round(value * 100) / 100;

package/src/scatter3d/ui/CloudShellLayer.tsx

@@ -0,0 +1,107 @@
+import type { ReactElement } from 'react';
+import { memo, useId } from 'react';
+
+import type { ConfidenceEllipsoid } from '../core/confidenceEllipsoid.ts';
+import type { OrbitCamera, OrbitViewport } from '../core/orbitCamera.ts';
+
+import { projectShellOutline } from './cloudGeometry.ts';
+import { SHELL_FILL_OPACITY, shellGlassStops } from './cloudShellStyles.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.
+ *
+ * What the faces were for is kept in 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. That is one
+ * gradient, and it says the shell is a solid the same way a hundred and sixty
+ * stacked polygons did.
+ * @param props - See {@link CloudShellLayerProps}.
+ * @returns The shells.
+ */
+export const CloudShellLayer = memo(function CloudShellLayer(
+  props: CloudShellLayerProps,
+): ReactElement {
+  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 (
+    <g data-layer="shells" pointerEvents="none">
+      {drawn.map(({ shell, outline }) => {
+        const paint = `${prefix}${shell.id}`;
+        return (
+          <g key={shell.id} data-shell={shell.id}>
+            <defs>
+              <radialGradient id={paint}>
+                {shellGlassStops((shell.opacity ?? 1) * fillOpacity).map(
+                  (stop) => (
+                    <stop
+                      key={stop.offset}
+                      offset={stop.offset}
+                      stopColor={shell.color}
+                      stopOpacity={stop.opacity}
+                    />
+                  ),
+                )}
+              </radialGradient>
+            </defs>
+            <ellipse
+              cx={outline.cx}
+              cy={outline.cy}
+              rx={outline.rx}
+              ry={outline.ry}
+              transform={`rotate(${outline.angle} ${outline.cx} ${outline.cy})`}
+              fill={`url(#${paint})`}
+            />
+          </g>
+        );
+      })}
+    </g>
+  );
+});

package/src/scatter3d/ui/ScatterCloud.tsx

@@ -0,0 +1,312 @@
+import type { MouseEvent as ReactMouseEvent, ReactElement } from 'react';
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+import {
+  CHART_WHEEL_DWELL,
+  useWheelZoom,
+} from '../../chart/ui/useWheelZoom.ts';
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import { nearestPointIndex } from '../../scatter/core/screenPoints.ts';
+import { ScatterLabelLayer } from '../../scatter/ui/ScatterLabelLayer.tsx';
+import { ScatterMarkLayer } from '../../scatter/ui/ScatterMarkLayer.tsx';
+import { surfacePosition } from '../../scatter/ui/lassoGesture.ts';
+import {
+  SCATTER_GROUP_LABEL_SIZE,
+  SCATTER_LABEL_SIZE,
+} from '../../scatter/ui/scatterLabelBoxes.ts';
+import { placeScatterLabels } from '../../scatter/ui/scatterLabelPlacement.ts';
+import {
+  scatterGroupLabels,
+  scatterPointLabels,
+} from '../../scatter/ui/scatterLabels.ts';
+import {
+  LASSO_STYLE,
+  scatterGroupInk,
+} from '../../scatter/ui/scatterPlotModel.ts';
+import { useScatterInteraction } from '../../scatter/ui/useScatterInteraction.ts';
+import { cubePoints } from '../core/cubePoints.ts';
+import type { OrbitCamera } from '../core/orbitCamera.ts';
+import { DEFAULT_ORBIT_CAMERA } from '../core/orbitCamera.ts';
+
+import { CloudFrameLayer } from './CloudFrameLayer.tsx';
+import { CloudPointLayer } from './CloudPointLayer.tsx';
+import type { CloudShell } from './CloudShellLayer.tsx';
+import { CloudShellLayer } from './CloudShellLayer.tsx';
+import { cloudView, projectCloud } from './cloudGeometry.ts';
+import { clampCloudZoom } from './cloudZoom.ts';
+import { cloudLabel, cloudShells } from './scatterCloudModel.ts';
+import type { ScatterCloudProps } from './scatterCloudProps.ts';
+import { useOrbitDrag } from './useOrbitDrag.ts';
+
+export type { CloudGesture, 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 hover card, the labels and the group colours are
+ * the same hooks and the same helpers — 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: ScatterCloudProps): ReactElement {
+  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, overlay } = props;
+  const { onPointDoubleClick } = props;
+  const { gesture = 'turn', wheelZoom = true, label, testId } = props;
+
+  const [ownCamera, setOwnCamera] = useState<OrbitCamera>(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 ink = useMemo(
+    () => scatterGroupInk(groups, mutedGroups),
+    [groups, mutedGroups],
+  );
+  const shells = useMemo<readonly CloudShell[]>(
+    () =>
+      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,
+  });
+
+  // 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, points: cloud.points, props });
+  useLayoutEffect(() => {
+    live.current = { camera, zoom, points: cloud.points, props };
+  });
+
+  const { select, mask } = interaction.selection;
+  const { moveTo, leave, pin, unpin, hovered } = interaction.hover;
+
+  const onOrbit = useCallback((turn: (was: OrbitCamera) => OrbitCamera) => {
+    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: number, tapY: number, mode: ScatterSelectionMode) => {
+      const radius = (live.current.props.pointRadius ?? 3.5) + HOVER_SLACK;
+      const index = nearestPointIndex(live.current.points, tapX, tapY, radius);
+      if (index === -1) {
+        unpin();
+        if (mode === 'replace') interaction.selection.clear();
+        return;
+      }
+      select([index], mode, 'point');
+      pin(index);
+    },
+    [interaction.selection, pin, select, unpin],
+  );
+
+  const onWheel = useCallback((_x: number, _y: number, factor: number) => {
+    // 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: ReactMouseEvent<SVGRectElement>): void {
+    if (onPointDoubleClick === undefined) return;
+    const at = surfacePosition(event, 0, 0);
+    const radius = (live.current.props.pointRadius ?? 3.5) + HOVER_SLACK;
+    const index = nearestPointIndex(live.current.points, at.x, at.y, radius);
+    if (index === -1) return;
+    onPointDoubleClick({
+      index,
+      x: at.x,
+      y: at.y,
+      clientX: event.clientX,
+      clientY: event.clientY,
+    });
+  }
+
+  const orbit = useOrbitDrag({
+    enabled: !selecting,
+    onOrbit,
+    onTap,
+    onMove: moveTo,
+    onLeave: leave,
+    mode: selectMode,
+  });
+  const { ref: wheelSurface } = useWheelZoom<SVGRectElement>({
+    enabled: wheelZoom,
+    delay: CHART_WHEEL_DWELL,
+    onZoom: onWheel,
+  });
+
+  const named = useMemo(
+    () =>
+      pointLabels === undefined
+        ? undefined
+        : placeScatterLabels(
+            scatterPointLabels(cloud.points, pointLabels, {
+              groupOf,
+              colors: ink.colors,
+            }),
+            {
+              fontSize: SCATTER_LABEL_SIZE,
+              radius: pointRadius,
+              bounds: view.rect,
+            },
+          ),
+    [cloud.points, groupOf, ink.colors, pointLabels, pointRadius, view.rect],
+  );
+  const crowds = useMemo(
+    () =>
+      showGroupLabels && groups !== undefined
+        ? placeScatterLabels(
+            scatterGroupLabels(
+              cloud.points,
+              groups.map((group) => group.label),
+              { groupOf, colors: ink.colors },
+            ),
+            {
+              fontSize: SCATTER_GROUP_LABEL_SIZE,
+              bold: true,
+              centered: true,
+              radius: pointRadius,
+              bounds: view.rect,
+            },
+          )
+        : undefined,
+    [
+      cloud.points,
+      groupOf,
+      groups,
+      ink.colors,
+      pointRadius,
+      showGroupLabels,
+      view.rect,
+    ],
+  );
+
+  return (
+    <div
+      data-testid={testId}
+      style={{ position: 'relative', width, height }}
+      role="img"
+      aria-label={label ?? cloudLabel(xLabel, yLabel, zLabel, cube.length)}
+    >
+      <svg width={width} height={height} style={SVG_STYLE}>
+        <CloudFrameLayer
+          camera={camera}
+          viewport={view.viewport}
+          xLabel={xLabel}
+          yLabel={yLabel}
+          zLabel={zLabel}
+        />
+        <CloudShellLayer
+          shells={shells}
+          camera={camera}
+          viewport={view.viewport}
+          fillOpacity={ellipsoidFillOpacity}
+        />
+        <CloudPointLayer
+          points={cloud.points}
+          depths={cloud.depths}
+          order={cloud.order}
+          groupOf={groupOf}
+          colors={ink.colors}
+          opacities={ink.opacities}
+          radius={pointRadius}
+          outlinedFrom={outlinedFrom}
+        />
+        <ScatterMarkLayer
+          points={cloud.points}
+          selected={mask}
+          hovered={hovered}
+          radius={pointRadius}
+        />
+        {named === undefined ? null : (
+          <ScatterLabelLayer labels={named} radius={pointRadius} />
+        )}
+        {crowds === undefined ? null : (
+          <ScatterLabelLayer labels={crowds} radius={pointRadius} strong />
+        )}
+        {interaction.lasso.pathData === '' ? null : (
+          <path d={interaction.lasso.pathData} {...LASSO_STYLE} />
+        )}
+        <rect
+          x={0}
+          y={0}
+          width={Math.max(0, width)}
+          height={Math.max(0, height)}
+          ref={wheelSurface}
+          fill="transparent"
+          onDoubleClick={handleDoubleClick}
+          {...(selecting ? interaction.surface : orbit.surface)}
+        />
+      </svg>
+      {overlay}
+    </div>
+  );
+}
+
+/**
+ * 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: readonly CloudShell[] = [];
+
+const SVG_STYLE = { display: 'block', touchAction: 'none' } as const;