react-cheminfo 0.17.0 → 0.19.0

package/src/molecule3d/core/camera.ts

@@ -0,0 +1,212 @@
+/**
+ * Where the camera stands, in a form a link can carry.
+ *
+ * A position in ångström would not survive the trip: the molecule a link names
+ * is built again on the other side, and a distance that frames a benzene leaves
+ * a peptide off screen. So the camera is stored against the scene rather than
+ * against the coordinates — a rotation from the front view, a zoom against the
+ * distance that frames the whole model, and a target as an offset from the
+ * scene centre in bounding-sphere radii. All three read the same whatever the
+ * molecule and whatever the size of the canvas showing it.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+import { roundTo } from '../../format/core/roundTo.ts';
+// Deep import on purpose: the codec is the one way a link carries a camera, and
+// `share/core` knows nothing of molecules, so nothing is pulled in by it.
+import type { ShareParamCodec } from '../../share/core/params.ts';
+
+/** A rotation, as a unit quaternion `[x, y, z, w]`. */
+export type Molecule3DRotation = readonly [number, number, number, number];
+
+/** A point or a direction, `[x, y, z]`. */
+export type Molecule3DVector = readonly [number, number, number];
+
+/** Where the camera stands, against the scene rather than its coordinates. */
+export interface Molecule3DCamera {
+  /**
+   * Rotation of the camera from the front view — looking down -z with y up —
+   * as a unit quaternion.
+   */
+  rotation: Molecule3DRotation;
+  /**
+   * How close the camera is. `1` frames the whole model, as the reset button
+   * does; `2` is twice as close, so the model is drawn twice as large.
+   */
+  zoom: number;
+  /**
+   * Where the camera looks, as an offset from the centre of the model, in
+   * bounding-sphere radii. `[0, 0, 0]` looks at the centre.
+   */
+  offset: Molecule3DVector;
+}
+
+/** Looking at the centre of the model from the front, framing all of it. */
+export const DEFAULT_MOLECULE_3D_CAMERA: Molecule3DCamera = {
+  rotation: [0, 0, 0, 1],
+  zoom: 1,
+  offset: [0, 0, 0],
+};
+
+/** The closest and furthest a link may ask the camera to stand. */
+export const MOLECULE_3D_ZOOM_RANGE = { minimum: 0.01, maximum: 100 } as const;
+
+/** Furthest a link may push the target from the centre, in radii. */
+const MAX_OFFSET = 100;
+
+/** Decimals kept of a quaternion component: 0.0001 is under a hundredth of a degree. */
+const ROTATION_DECIMALS = 4;
+
+/** Decimals kept of the zoom and of the target offset. */
+const POSITION_DECIMALS = 3;
+
+/**
+ * Write a camera as the text a link carries.
+ *
+ * The four components of the rotation come first, then the zoom, then the
+ * target offset — which is left out entirely while the camera looks at the
+ * centre of the model, as it does until someone pans.
+ * @param camera - The camera to write.
+ * @returns Comma-separated numbers: five, or eight when the camera is panned.
+ */
+export function formatMolecule3DCamera(camera: Molecule3DCamera): string {
+  const { rotation, zoom, offset } = normalizeMolecule3DCamera(camera);
+  const parts: string[] = [];
+  for (let index = 0; index < 4; index++) {
+    parts.push(String(roundTo(rotation[index] ?? 0, ROTATION_DECIMALS)));
+  }
+  parts.push(String(roundTo(zoom, POSITION_DECIMALS)));
+  if (offset[0] !== 0 || offset[1] !== 0 || offset[2] !== 0) {
+    for (const value of offset) {
+      parts.push(String(roundTo(value, POSITION_DECIMALS)));
+    }
+  }
+  return parts.join(',');
+}
+
+/**
+ * Read a camera out of the text a link carries.
+ *
+ * A rotation that is not a rotation — four zeros, a stray word — is what makes
+ * the whole value unusable; everything else is brought back into range rather
+ * than rejected, so a link written against an older range still opens.
+ * @param raw - The text of the parameter.
+ * @returns The camera, or `null` when the text does not describe one.
+ */
+export function parseMolecule3DCamera(raw: string): Molecule3DCamera | null {
+  const parts = raw.split(',');
+  if (parts.length !== 5 && parts.length !== 8) return null;
+  const numbers: number[] = [];
+  for (const part of parts) {
+    const value = Number(part.trim());
+    if (!Number.isFinite(value)) return null;
+    numbers.push(value);
+  }
+  const rotation = normalizeRotation([
+    numbers[0] ?? 0,
+    numbers[1] ?? 0,
+    numbers[2] ?? 0,
+    numbers[3] ?? 1,
+  ]);
+  if (rotation === null) return null;
+  return {
+    rotation,
+    zoom: clampZoom(numbers[4] ?? 1),
+    offset: [
+      clampOffset(numbers[5] ?? 0),
+      clampOffset(numbers[6] ?? 0),
+      clampOffset(numbers[7] ?? 0),
+    ],
+  };
+}
+
+/**
+ * A camera with its rotation made a unit quaternion and its numbers in range.
+ * @param camera - The camera to repair.
+ * @returns A camera safe to hand the viewer; the default when the rotation is
+ * degenerate.
+ */
+export function normalizeMolecule3DCamera(
+  camera: Molecule3DCamera,
+): Molecule3DCamera {
+  const rotation = normalizeRotation(camera.rotation);
+  if (rotation === null) return DEFAULT_MOLECULE_3D_CAMERA;
+  return {
+    rotation,
+    zoom: clampZoom(camera.zoom),
+    offset: [
+      clampOffset(camera.offset[0]),
+      clampOffset(camera.offset[1]),
+      clampOffset(camera.offset[2]),
+    ],
+  };
+}
+
+/**
+ * Whether two cameras are the same once written into a link.
+ *
+ * What a link carries is rounded, so two cameras a drag apart by less than the
+ * rounding are one camera as far as the address is concerned — which is what
+ * keeps a settling animation from rewriting it a dozen times.
+ * @param first - One camera, or `null` for none.
+ * @param second - The other.
+ * @returns True when a link would carry the same text for both.
+ */
+export function sameMolecule3DCamera(
+  first: Molecule3DCamera | null,
+  second: Molecule3DCamera | null,
+): boolean {
+  if (first === null || second === null) return first === second;
+  return formatMolecule3DCamera(first) === formatMolecule3DCamera(second);
+}
+
+/**
+ * The codec a site mirrors the camera in the address with.
+ *
+ * The default framing is written as nothing at all, so the address of a page
+ * nobody has turned yet stays a plain link.
+ * @returns The codec, whose value is `null` while the camera is where a reset
+ * would leave it.
+ */
+export function molecule3DCameraParam(): ShareParamCodec<Molecule3DCamera | null> {
+  return {
+    parse(raw) {
+      return raw === null ? null : parseMolecule3DCamera(raw);
+    },
+    serialize(value) {
+      if (value === null) return null;
+      const text = formatMolecule3DCamera(value);
+      return text === formatMolecule3DCamera(DEFAULT_MOLECULE_3D_CAMERA)
+        ? null
+        : text;
+    },
+  };
+}
+
+function normalizeRotation(
+  rotation: Molecule3DRotation,
+): Molecule3DRotation | null {
+  let squared = 0;
+  for (let index = 0; index < 4; index++) {
+    const value = rotation[index] ?? 0;
+    if (!Number.isFinite(value)) return null;
+    squared += value * value;
+  }
+  if (squared <= 0) return null;
+  const scale = 1 / Math.sqrt(squared);
+  return [
+    rotation[0] * scale,
+    rotation[1] * scale,
+    rotation[2] * scale,
+    rotation[3] * scale,
+  ];
+}
+
+function clampZoom(zoom: number): number {
+  const { minimum, maximum } = MOLECULE_3D_ZOOM_RANGE;
+  return clamp(zoom, minimum, maximum, 1);
+}
+
+function clampOffset(value: number): number {
+  return clamp(value, -MAX_OFFSET, MAX_OFFSET, 0);
+}

package/src/molecule3d/core/index.ts

@@ -1,3 +1,17 @@
+export type {
+  Molecule3DCamera,
+  Molecule3DRotation,
+  Molecule3DVector,
+} from './camera.ts';
+export {
+  DEFAULT_MOLECULE_3D_CAMERA,
+  MOLECULE_3D_ZOOM_RANGE,
+  formatMolecule3DCamera,
+  molecule3DCameraParam,
+  normalizeMolecule3DCamera,
+  parseMolecule3DCamera,
+  sameMolecule3DCamera,
+} from './camera.ts';
 export type { ImageSize } from './exportImage.ts';
 export { dataUriBytes, rasterSvgMarkup } from './exportImage.ts';
 export type { Molecule3DGesture, Molecule3DGestureKey } from './gestures.ts';

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -6,10 +6,9 @@
  */
 
 import type { CSSProperties, ReactElement } from 'react';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
-import type { Molecule3DFile } from '../core/settings.ts';
 import {
   normalizeMolecule3DSettings,
   resolveMolecule3DTools,
@@ -19,13 +18,13 @@ import { Molecule3DExport } from './Molecule3DExport.tsx';
 import { Molecule3DOptions } from './Molecule3DOptions.tsx';
 import { Molecule3DToolbar } from './Molecule3DToolbar.tsx';
 import { DEFAULT_SPIN_SPEED } from './camera.ts';
-import { drawScene } from './drawScene.ts';
+import { createMolecule3DViewer } from './createViewer.ts';
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
 import { useControlledState } from './useControlledState.ts';
 import { useImageExport } from './useImageExport.ts';
+import { useMoleculeScene } from './useMoleculeScene.ts';
 import { usePolarSurfaceArea } from './usePolarSurfaceArea.ts';
 import type { Molecule3DViewer } from './viewer.ts';
-import { createMolecule3DViewer } from './viewer.ts';
 
 /** Props of {@link MoleculeCanvas3D}. */
 export interface MoleculeCanvas3DProps extends Omit<
@@ -84,11 +83,6 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
   // effect keyed on it runs again, in order, after the viewer exists.
   const [container, setContainer] = useState<HTMLDivElement | null>(null);
   const viewerRef = useRef<Molecule3DViewer | null>(null);
-  const framedRef = useRef<{
-    molfile: Molecule3DFile;
-    viewer: Molecule3DViewer;
-  } | null>(null);
-
   // The viewer is created once, so what its callbacks read is kept fresh here.
   const latest = useRef({
     measurements,
@@ -126,37 +120,6 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     };
   }, [container]);
 
-  // One animation frame of coalescing, so dragging a slider costs one rebuild.
-  useEffect(() => {
-    const viewer = viewerRef.current;
-    if (container === null || viewer === null) return;
-    let cancelled = false;
-    const frame = requestAnimationFrame(() => {
-      // Framed on a new molecule or a new viewer, never on a restyle: a slider
-      // that snapped the camera back would undo the reader's orientation.
-      const framed = framedRef.current;
-      const isNew =
-        molfile !== null &&
-        (framed?.molfile !== molfile || framed.viewer !== viewer);
-      framedRef.current = molfile === null ? null : { molfile, viewer };
-      const frameCamera = isNew ? frameNewMolecule : 'none';
-      void drawScene(viewer, molfile, settings, measurements, frameCamera)
-        .then(() => {
-          if (!cancelled) latest.current.onFailureChange(null);
-        })
-        .catch((error: unknown) => {
-          if (cancelled) return;
-          latest.current.onFailureChange(
-            error instanceof Error ? error.message : String(error),
-          );
-        });
-    });
-    return () => {
-      cancelled = true;
-      cancelAnimationFrame(frame);
-    };
-  }, [container, molfile, frameNewMolecule, settings, measurements]);
-
   useEffect(() => {
     void viewerRef.current?.setSpin(spinning, spinSpeed);
   }, [container, spinning, spinSpeed]);
@@ -165,9 +128,17 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     void viewerRef.current?.setMeasureKind(measureKind);
   }, [container, measureKind]);
 
-  const resetView = useCallback(() => {
-    void viewerRef.current?.resetCamera();
-  }, []);
+  const { resetView } = useMoleculeScene({
+    container,
+    viewerRef,
+    molfile,
+    frameNewMolecule,
+    settings,
+    measurements,
+    spinning,
+    onFailureChange,
+    camera: props,
+  });
 
   const { canvasSize, exportImage } = useImageExport(
     container,

package/src/molecule3d/ui/camera.ts

@@ -1,11 +1,17 @@
 /**
- * The two camera moves the molecule viewer needs: frame whatever is on screen,
- * and the slow spin that makes a still picture of a 3D molecule readable.
+ * The camera moves the molecule viewer needs: frame whatever is on screen, the
+ * slow spin that makes a still picture of a 3D molecule readable, and the two
+ * directions between molstar's camera and the scene-relative camera a link
+ * carries.
  */
 
-import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import type { Camera } from 'molstar/lib/mol-canvas3d/camera.js';
+import { Quat, Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
 
+import type { Molecule3DCamera } from '../core/camera.ts';
+import { normalizeMolecule3DCamera } from '../core/camera.ts';
+
 /** Transition length used when the caller does not pick one, milliseconds. */
 export const DEFAULT_CAMERA_DURATION = 250;
 
@@ -32,6 +38,21 @@ const MIN_FRAMING_RADIUS = 0.5;
 const FRONT_UP = Vec3.create(0, 1, 0);
 const FRONT_DIRECTION = Vec3.create(0, 0, -1);
 
+/** The camera's own axes, which the stored rotation turns into world ones. */
+const CAMERA_UP = Vec3.create(0, 1, 0);
+const CAMERA_BACK = Vec3.create(0, 0, 1);
+
+/**
+ * The radius a reset frames, which is the length every stored camera is
+ * measured against — so reading a camera and applying it are the same move in
+ * opposite directions.
+ * @param radius - Radius of the scene's visible bounding sphere.
+ * @returns The framed radius.
+ */
+function framedRadius(radius: number): number {
+  return Math.max(radius * (1 + FRAMING_MARGIN), MIN_FRAMING_RADIUS);
+}
+
 /**
  * Frame everything currently in the scene.
  *
@@ -54,10 +75,7 @@ export function resetCamera(
     durationMs: durationMilliseconds,
     snapshot: (scene, camera) => {
       const { center, radius } = scene.boundingSphereVisible;
-      const framed = Math.max(
-        radius * (1 + FRAMING_MARGIN),
-        MIN_FRAMING_RADIUS,
-      );
+      const framed = framedRadius(radius);
       return fromFront
         ? camera.getFocus(center, framed, FRONT_UP, FRONT_DIRECTION)
         : camera.getFocus(center, framed);
@@ -84,3 +102,106 @@ export function setSpin(
     },
   });
 }
+
+/**
+ * Where the camera stands, against the scene rather than its coordinates.
+ *
+ * An empty scene has no camera to read: a canvas showing nothing still has one,
+ * pointing at the origin from molstar's default distance, and measuring that
+ * against a sphere of no radius describes a view that means nothing — which
+ * would then be applied to the first molecule drawn.
+ * @param plugin - The molstar context.
+ * @returns The camera, or `null` when there is no canvas or nothing to measure
+ * it against.
+ */
+export function readCamera(plugin: PluginContext): Molecule3DCamera | null {
+  const canvas = plugin.canvas3d;
+  if (canvas === undefined) return null;
+  const { center, radius } = canvas.boundingSphereVisible;
+  if (!(radius > 0)) return null;
+  const framed = framedRadius(radius);
+  const camera = canvas.camera;
+  const { position, target, up } = camera.getSnapshot();
+  const back = Vec3.sub(Vec3.zero(), position, target);
+  const distance = Vec3.magnitude(back);
+  if (distance <= 0) return null;
+  Vec3.scale(back, back, 1 / distance);
+  // The trackball keeps up and back close to square, never exactly so.
+  const trueUp = Vec3.scaleAndAdd(Vec3.zero(), up, back, -Vec3.dot(up, back));
+  if (Vec3.magnitude(trueUp) <= 0) return null;
+  Vec3.normalize(trueUp, trueUp);
+  const right = Vec3.cross(Vec3.zero(), trueUp, back);
+  const rotation = Quat.fromBasis(Quat.identity(), right, trueUp, back);
+  const offset = Vec3.sub(Vec3.zero(), target, center);
+  Vec3.scale(offset, offset, 1 / framed);
+  return normalizeMolecule3DCamera({
+    rotation: [
+      rotation[0] ?? 0,
+      rotation[1] ?? 0,
+      rotation[2] ?? 0,
+      rotation[3] ?? 1,
+    ],
+    zoom: camera.getTargetDistance(framed) / distance,
+    offset: [offset[0] ?? 0, offset[1] ?? 0, offset[2] ?? 0],
+  });
+}
+
+/**
+ * Put the camera back where a link says it stood.
+ *
+ * Ordered through `requestCameraReset` for the same reason {@link resetCamera}
+ * is: the bounding sphere the camera is measured against is only refreshed when
+ * the canvas commits the scene, so the move is computed then rather than now.
+ * @param plugin - The molstar context.
+ * @param camera - Where to stand.
+ * @param durationMilliseconds - Transition length. Pass 0 for an instant jump.
+ */
+export function applyCamera(
+  plugin: PluginContext,
+  camera: Molecule3DCamera,
+  durationMilliseconds = 0,
+): void {
+  const { rotation, zoom, offset } = normalizeMolecule3DCamera(camera);
+  const turn = Quat.create(rotation[0], rotation[1], rotation[2], rotation[3]);
+  plugin.canvas3d?.requestCameraReset({
+    durationMs: durationMilliseconds,
+    snapshot: (scene, current) => {
+      const { center, radius } = scene.boundingSphereVisible;
+      const framed = framedRadius(radius);
+      const up = Vec3.transformQuat(Vec3.zero(), CAMERA_UP, turn);
+      const back = Vec3.transformQuat(Vec3.zero(), CAMERA_BACK, turn);
+      const target = Vec3.create(
+        (center[0] ?? 0) + offset[0] * framed,
+        (center[1] ?? 0) + offset[1] * framed,
+        (center[2] ?? 0) + offset[2] * framed,
+      );
+      const distance = current.getTargetDistance(framed) / zoom;
+      const position = Vec3.scaleAndAdd(Vec3.zero(), target, back, distance);
+      return { target, position, up, radius: framed };
+    },
+  });
+}
+
+/**
+ * Follow the camera, however it moves — a drag, the reset button, the spin.
+ * @param plugin - The molstar context.
+ * @param listener - Called after every move, with the camera it left.
+ * @returns A function that stops calling the listener.
+ */
+export function watchCamera(
+  plugin: PluginContext,
+  listener: (camera: Molecule3DCamera | null) => void,
+): () => void {
+  const camera: Camera | undefined = plugin.canvas3d?.camera;
+  if (camera === undefined) return noop;
+  const subscription = camera.changed.subscribe(() => {
+    listener(readCamera(plugin));
+  });
+  return () => {
+    subscription.unsubscribe();
+  };
+}
+
+function noop(): void {
+  // Nothing was subscribed, so there is nothing to unsubscribe.
+}

package/src/molecule3d/ui/captureScene.ts

@@ -0,0 +1,31 @@
+/**
+ * A picture of the scene, rendered off screen at a size of its own.
+ */
+
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+import type { ImageSize } from '../core/exportImage.ts';
+
+/**
+ * Render the scene without its selection highlights or its axes.
+ * @param plugin - The molstar context.
+ * @param size - Pixel size of the picture.
+ * @returns The PNG as a data URI.
+ * @throws {Error} When the plugin has no screenshot helper.
+ */
+export async function captureScene(
+  plugin: PluginContext,
+  size: ImageSize,
+): Promise<string> {
+  const helper = plugin.helpers.viewportScreenshot;
+  if (helper === undefined) {
+    throw new Error('This viewer cannot take a picture of its scene.');
+  }
+  helper.behaviors.values.next({
+    ...helper.values,
+    resolution: { name: 'custom', params: size },
+    axes: { name: 'off', params: {} },
+    transparent: false,
+  });
+  return helper.getImageDataUri();
+}

package/src/molecule3d/ui/createViewer.ts

@@ -0,0 +1,24 @@
+/**
+ * How a molecule viewer comes into being, and why it does so synchronously.
+ *
+ * React 19 runs an effect, its cleanup and the effect again on every mount in
+ * development, so an awaited constructor hands the cleanup nothing to dispose
+ * and leaks a WebGL context per mount. Returning the handle immediately means
+ * `dispose()` can always be called; the work is queued behind `ready`.
+ */
+
+import { Molecule3DViewer } from './viewer.ts';
+import type { Molecule3DViewerOptions } from './viewerTypes.ts';
+
+/**
+ * Create a viewer inside `container` and start initialising it.
+ * @param container - A positioned element; molstar inserts its canvas into it.
+ * @param options - See {@link Molecule3DViewerOptions}.
+ * @returns A handle that is safe to dispose immediately.
+ */
+export function createMolecule3DViewer(
+  container: HTMLElement,
+  options: Molecule3DViewerOptions = {},
+): Molecule3DViewer {
+  return new Molecule3DViewer(container, options);
+}

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 
 import type { ViewerCapability } from '../../orbital/ui/capability.ts';
+import type { Molecule3DCamera } from '../core/camera.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type {
   Molecule3DFile,
@@ -78,6 +79,26 @@ export interface MoleculeViewer3DProps {
    * @default undefined
    */
   onMeasurementsChange?: (measurements: readonly Measurement[]) => void;
+  /**
+   * Where the camera stands when the first molecule is framed — what a shared
+   * link carries. The camera belongs to whoever is dragging it afterwards, so
+   * this is read once and a later change is ignored; the viewer reports every
+   * move through `onCameraChange` instead.
+   * @default null — the molecule is framed as `frameNewMolecule` says
+   */
+  initialCamera?: Molecule3DCamera | null;
+  /**
+   * Called once the camera has come to rest, with where it stands. Not called
+   * while the model is spinning: a spinning camera has no orientation to keep.
+   * @default undefined
+   */
+  onCameraChange?: (camera: Molecule3DCamera) => void;
+  /**
+   * How long the camera must be still before `onCameraChange` is called,
+   * milliseconds, so one drag is one report rather than one per frame.
+   * @default 400
+   */
+  cameraSettleDelay?: number;
   /**
    * Name of an exported image, without its extension.
    * @default 'molecule'