react-cheminfo 0.39.0 → 0.40.0

package/src/molecule3d/ui/measurements.ts

@@ -10,10 +10,13 @@
  * measurement.
  */
 
-import { OrderedSet } from 'molstar/lib/mol-data/int.js';
+import { OrderedSet, SortedArray } from 'molstar/lib/mol-data/int.js';
 import type { Loci } from 'molstar/lib/mol-model/loci.js';
 import type { UnitIndex } from 'molstar/lib/mol-model/structure/structure/element/util.js';
-import type { Structure } from 'molstar/lib/mol-model/structure.js';
+import type {
+  ElementIndex,
+  Structure,
+} from 'molstar/lib/mol-model/structure.js';
 import { StructureElement } from 'molstar/lib/mol-model/structure.js';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
 import { MeasurementGroupTag } from 'molstar/lib/mol-plugin-state/manager/structure/measurement.js';
@@ -31,19 +34,32 @@ import { moleculeStructure } from './renderMolecule.ts';
 // Lowercased: it is a factory, not a constructor.
 const elementLoci = StructureElement.Loci;
 
+/**
+ * Where the atoms a measurement addresses are found in the plugin's state.
+ *
+ * A site that mounts a molstar plugin of its own builds its scene under refs of
+ * its own, so it says here which structure the clicks are read against; the
+ * default is the one `<MoleculeViewer3D>` draws.
+ */
+export type MoleculeStructureSource = (
+  plugin: PluginContext,
+) => Structure | undefined;
+
 /**
  * Draw exactly `measurements` over the current molecule. An atom the structure
  * does not have skips its measurement rather than failing the scene.
  * @param plugin - The molstar context.
  * @param measurements - Everything to show, replacing what is shown.
+ * @param structureOf - See {@link MoleculeStructureSource}.
  * @returns Nothing; resolves once every label is on screen.
  */
 export async function renderMeasurements(
   plugin: PluginContext,
   measurements: readonly Measurement[],
+  structureOf: MoleculeStructureSource = moleculeStructure,
 ): Promise<void> {
   await clearMeasurements(plugin);
-  const structure = moleculeStructure(plugin);
+  const structure = structureOf(plugin);
   if (structure === undefined) return;
   const manager = plugin.managers.structure.measurement;
   for (const measurement of measurements) {
@@ -143,6 +159,29 @@ export class MeasurementPicker {
   }
 }
 
+/**
+ * Address one atom of a structure the way a {@link Measurement} does.
+ *
+ * A site that builds its own scene numbers atoms by their position in the file
+ * it drew; this is how that number becomes a reference a measurement keeps.
+ * @param structure - The structure on screen.
+ * @param element - The atom's index in the model, i.e. its position in the file.
+ * @returns The reference, or `undefined` when the structure has no such atom.
+ */
+export function atomReferenceOf(
+  structure: Structure,
+  element: ElementIndex,
+): AtomReference | undefined {
+  const units = structure.units;
+  for (let unit = 0; unit < units.length; unit++) {
+    const elements = units[unit]?.elements;
+    if (elements === undefined) continue;
+    const index = SortedArray.indexOf(elements, element);
+    if (index !== -1) return { unit, element: index };
+  }
+  return undefined;
+}
+
 function atomReference(
   structure: Structure,
   loci: Loci,

package/src/molecule3d/ui/useImageExport.ts

@@ -4,8 +4,8 @@ import { useCallback } from 'react';
 import type { FigureFormat } from '../../download/core/downloadFigure.ts';
 import type { FigurePixels } from '../../download/core/figureScale.ts';
 
+import type { SceneCapture } from './exportMoleculeImage.ts';
 import { exportMoleculeImage } from './exportMoleculeImage.ts';
-import type { Molecule3DViewer } from './viewer.ts';
 
 /** What {@link useImageExport} hands the export panel. */
 export interface ImageExport {
@@ -24,7 +24,7 @@ export interface ImageExport {
  */
 export function useImageExport(
   container: HTMLDivElement | null,
-  viewerRef: RefObject<Molecule3DViewer | null>,
+  viewerRef: RefObject<SceneCapture | null>,
   fileName: string,
 ): ImageExport {
   const canvasSize = useCallback((): FigurePixels | null => {

package/src/molecule3d/ui/viewer.ts

@@ -8,22 +8,20 @@
  * is the component's.
  */
 
-import type { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
 
+import {
+  DEFAULT_CAMERA_DURATION,
+  DEFAULT_SPIN_SPEED,
+  MolstarPlugin,
+  setSpin,
+} from '../../molstar/core/index.ts';
 import type { Molecule3DCamera } from '../core/camera.ts';
 import type { ImageSize } from '../core/exportImage.ts';
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
 import type { Molecule3DFile } from '../core/settings.ts';
 
-import {
-  DEFAULT_CAMERA_DURATION,
-  DEFAULT_SPIN_SPEED,
-  applyCamera,
-  resetCamera,
-  setSpin,
-  watchCamera,
-} from './camera.ts';
+import { applyCamera, resetCamera, watchCamera } from './camera.ts';
 import { captureScene } from './captureScene.ts';
 import {
   MeasurementPicker,
@@ -32,7 +30,6 @@ import {
 } from './measurements.ts';
 import { clearMolecule, renderMolecule } from './renderMolecule.ts';
 import { clearSurface, renderSurface } from './renderSurface.ts';
-import { mountMolecule3DPlugin } from './viewerSpec.ts';
 import type {
   Molecule3DViewerOptions,
   MoleculeStyle,
@@ -44,9 +41,8 @@ import type {
  * method resolves to nothing once `dispose` has been called.
  */
 export class Molecule3DViewer {
-  readonly #model: PluginViewModel;
+  readonly #plugin: MolstarPlugin;
   #picker: MeasurementPicker | undefined;
-  #disposed = false;
 
   /** Resolves once the canvas exists; every method awaits it internally. */
   readonly ready: Promise<void>;
@@ -57,17 +53,15 @@ export class Molecule3DViewer {
    * @param options - See {@link Molecule3DViewerOptions}.
    */
   constructor(container: HTMLElement, options: Molecule3DViewerOptions = {}) {
-    const {
-      background = '#ffffff', // tokens-ok: a WebGL clear colour
-      onMeasure = ignore,
-    } = options;
-    this.#model = mountMolecule3DPlugin(container, background);
-    this.ready = this.#model.initialized;
+    const { background, onMeasure = ignore } = options;
+    this.#plugin = new MolstarPlugin(container, { background });
+    this.ready = this.#plugin.ready;
     // Registered before any `#run`, so the picker exists by the time one runs.
-    this.ready.then(() => {
-      if (this.#disposed) return;
-      this.#picker = new MeasurementPicker(this.#model.plugin, onMeasure);
-    }, ignore);
+    void this.#plugin
+      .run((plugin) => {
+        this.#picker = new MeasurementPicker(plugin, onMeasure);
+      })
+      .catch(ignore);
   }
 
   /**
@@ -177,16 +171,7 @@ export class Molecule3DViewer {
    * the canvas exists.
    */
   watchCamera(listener: (camera: Molecule3DCamera | null) => void): () => void {
-    let stop: (() => void) | null = null;
-    let cancelled = false;
-    void this.#run((plugin) => {
-      if (!cancelled) stop = watchCamera(plugin, listener);
-    });
-    return () => {
-      cancelled = true;
-      stop?.();
-      stop = null;
-    };
+    return this.#plugin.subscribe((plugin) => watchCamera(plugin, listener));
   }
 
   /**
@@ -203,34 +188,19 @@ export class Molecule3DViewer {
 
   /** Re-read the container's size. Call from a `ResizeObserver`. */
   handleResize(): void {
-    if (this.#disposed) return;
-    this.#model.plugin.handleResize();
+    this.#plugin.handleResize();
   }
 
   /** Tear the viewer down and release its WebGL context. Idempotent. */
   dispose(): void {
-    if (this.#disposed) return;
-    this.#disposed = true;
     this.#picker?.dispose();
-    void this.ready
-      .catch(() => undefined)
-      .then(() => {
-        this.#model.plugin.dispose();
-      });
+    this.#plugin.dispose();
   }
 
-  async #run<Result>(
+  #run<Result>(
     action: (plugin: PluginContext) => Result | Promise<Result>,
   ): Promise<Result | undefined> {
-    if (this.#disposed) return undefined;
-    await this.ready;
-    if (this.#disposed) return undefined;
-    try {
-      return await action(this.#model.plugin);
-    } catch (error) {
-      if (this.#disposed) return undefined;
-      throw error;
-    }
+    return this.#plugin.run(action);
   }
 }
 

package/src/molstar/core/camera.ts

@@ -0,0 +1,61 @@
+/**
+ * The camera moves every molstar scene of ours needs, and the one measurement
+ * they all take: how big a sphere has to be framed for a handful of atoms to
+ * be legible.
+ */
+
+import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+/** Transition length used when the caller does not pick one, milliseconds. */
+export const DEFAULT_CAMERA_DURATION = 250;
+
+/** Turn rate used when the caller does not pick one, in molstar's spin unit. */
+export const DEFAULT_SPIN_SPEED = 1 / 3;
+
+/**
+ * Fraction of the bounding sphere kept as breathing room around the scene.
+ *
+ * `camera.reset()` frames with molstar's own margin, which suits a protein
+ * filling a wide viewport and leaves a small molecule a speck in the middle:
+ * measured coverage was 20% of the pixels. Framing the visible bounding sphere
+ * directly, with a small margin, is what makes a single water molecule legible.
+ */
+export const FRAMING_MARGIN = 0.08;
+
+/** Smallest radius framed, ångström, so one atom is not a close-up. */
+export const MINIMUM_FRAMING_RADIUS = 0.5;
+
+/** Axis the automatic spin turns about: screen up. */
+const SPIN_AXIS = Vec3.create(0, 1, 0);
+
+/**
+ * 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.
+ */
+export function framedRadius(radius: number): number {
+  return Math.max(radius * (1 + FRAMING_MARGIN), MINIMUM_FRAMING_RADIUS);
+}
+
+/**
+ * Turn the automatic spin on or off. It moves the camera, never the object.
+ * @param plugin - The molstar context.
+ * @param spinning - Whether the scene should keep turning.
+ * @param speed - Turn rate, in molstar's own spin unit.
+ */
+export function setSpin(
+  plugin: PluginContext,
+  spinning: boolean,
+  speed = DEFAULT_SPIN_SPEED,
+): void {
+  plugin.canvas3d?.setProps({
+    trackball: {
+      animate: spinning
+        ? { name: 'spin', params: { speed, axis: SPIN_AXIS } }
+        : { name: 'off', params: {} },
+    },
+  });
+}

package/src/molstar/core/cameraPose.ts

@@ -0,0 +1,126 @@
+/**
+ * The two directions between molstar's camera and the camera a shared link
+ * carries.
+ *
+ * A link stores the camera against what is drawn rather than against ångström —
+ * a rotation from the front view, a zoom against the distance that frames the
+ * scene, and a target offset in its own radii — so a view opens the same on any
+ * screen. Which sphere is the yardstick is the caller's to decide: a site whose
+ * scene grows after the model arrives measures against the model alone, or one
+ * view would read as two zooms.
+ */
+
+import { Quat, Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+
+import type { Molecule3DCamera } from '../../molecule3d/core/camera.ts';
+import { normalizeMolecule3DCamera } from '../../molecule3d/core/camera.ts';
+
+/** Where the camera is and where it looks, in world coordinates. */
+export interface CameraPose {
+  position: Vec3;
+  target: Vec3;
+  up: Vec3;
+}
+
+/** The sphere a stored camera is measured against. */
+export interface CameraReference {
+  center: Vec3;
+  /** Radius, ångström, framing margin included. */
+  radius: number;
+}
+
+/** How small an offset, in radii, is written as none at all. */
+export interface PoseOptions {
+  /**
+   * Target offsets below this, in radii, are read as zero. The framing centres
+   * on the scene a hair off the atoms' own centre, and that hair would
+   * otherwise be written into every link as `,0,0,0`.
+   * @default 0
+   */
+  snapOffset?: number;
+}
+
+/** The camera's own axes, which a stored rotation turns into world ones. */
+const CAMERA_UP = Vec3.create(0, 1, 0);
+const CAMERA_BACK = Vec3.create(0, 0, 1);
+
+/**
+ * Measure a pose against what is drawn.
+ * @param pose - Where the camera is.
+ * @param reference - The sphere to measure against.
+ * @param framingDistance - How far from the target the camera stands to frame
+ * the reference sphere; the length `zoom: 1` means.
+ * @param options - See {@link PoseOptions}.
+ * @returns The camera, or `null` for a degenerate pose.
+ */
+export function poseToCamera(
+  pose: CameraPose,
+  reference: CameraReference,
+  framingDistance: number,
+  options: PoseOptions = {},
+): Molecule3DCamera | null {
+  const { snapOffset = 0 } = options;
+  const { position, target, up } = pose;
+  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, reference.center);
+  Vec3.scale(offset, offset, 1 / reference.radius);
+  return normalizeMolecule3DCamera({
+    rotation: [
+      rotation[0] ?? 0,
+      rotation[1] ?? 0,
+      rotation[2] ?? 0,
+      rotation[3] ?? 1,
+    ],
+    zoom: framingDistance / distance,
+    offset: [
+      snap(offset[0], snapOffset),
+      snap(offset[1], snapOffset),
+      snap(offset[2], snapOffset),
+    ],
+  });
+}
+
+/**
+ * The pose a stored camera stands at: {@link poseToCamera} the other way round.
+ * @param camera - The stored camera.
+ * @param reference - The sphere it was measured against.
+ * @param framingDistance - See {@link poseToCamera}.
+ * @returns The pose.
+ */
+export function cameraToPose(
+  camera: Molecule3DCamera,
+  reference: CameraReference,
+  framingDistance: number,
+): CameraPose {
+  const { rotation, zoom, offset } = normalizeMolecule3DCamera(camera);
+  const turn = Quat.create(rotation[0], rotation[1], rotation[2], rotation[3]);
+  const up = Vec3.transformQuat(Vec3.zero(), CAMERA_UP, turn);
+  const back = Vec3.transformQuat(Vec3.zero(), CAMERA_BACK, turn);
+  const shift = Vec3.create(offset[0], offset[1], offset[2]);
+  const target = Vec3.scaleAndAdd(
+    Vec3.zero(),
+    reference.center,
+    shift,
+    reference.radius,
+  );
+  const position = Vec3.scaleAndAdd(
+    Vec3.zero(),
+    target,
+    back,
+    framingDistance / zoom,
+  );
+  return { position, target, up };
+}
+
+function snap(value: number | undefined, threshold: number): number {
+  return value === undefined || Math.abs(value) < threshold ? 0 : value;
+}

package/src/molstar/core/hover.ts

@@ -0,0 +1,109 @@
+/**
+ * What the pointer rests on, as a line of text.
+ *
+ * Every drawing our sites make carries a label already — `C1 sp³ σ to H5 (+)`,
+ * `C3 along [111]` — but molstar's own UI is not mounted, so nothing shows
+ * them. This turns the plugin's hover behaviour into that one string, which the
+ * canvas renders itself.
+ */
+
+import type { Loci } from 'molstar/lib/mol-model/loci.js';
+import { isEmptyLoci, isEveryLoci } from 'molstar/lib/mol-model/loci.js';
+import {
+  Bond,
+  StructureElement,
+  StructureProperties,
+} from 'molstar/lib/mol-model/structure.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import { lociLabel } from 'molstar/lib/mol-theme/label.js';
+
+/**
+ * Report whatever the pointer rests on.
+ * @param plugin - The molstar context.
+ * @param listener - Called with the loci, or `null` when the pointer is over
+ * nothing. The pointer over the background reports an empty loci, whose label
+ * is the word "Nothing" — a sentence, not an absence — so it arrives as `null`.
+ * @returns The unsubscribe function.
+ */
+export function subscribeHover(
+  plugin: PluginContext,
+  listener: (loci: Loci | null) => void,
+): () => void {
+  const subscription = plugin.behaviors.interaction.hover.subscribe((event) => {
+    const { loci } = event.current;
+    listener(isEmptyLoci(loci) || isEveryLoci(loci) ? null : loci);
+  });
+  return () => {
+    subscription.unsubscribe();
+  };
+}
+
+/**
+ * The one line a loci is worth, in molstar's own words.
+ * @param loci - What the pointer is over.
+ * @returns The label, stripped of the markup molstar writes into it, or `null`
+ * when there is nothing to say.
+ */
+export function lociText(loci: Loci): string | null {
+  if (isEmptyLoci(loci) || isEveryLoci(loci)) return null;
+  const label = stripMarkup(lociLabel(loci, { granularity: 'element' }));
+  return label === '' ? null : label;
+}
+
+/**
+ * The atoms a loci holds, in words a reader wants.
+ *
+ * molstar names one after the row it parsed — `xyz | Model 0 | Instance 1_555 |
+ * A | MOL 1 | O [idx 1]` — which is the address of a line in a file we wrote to
+ * hand it the atoms, and says nothing a student wants. The element and which
+ * atom of the scene it is do: the two hydrogens of water can then be told apart.
+ * @param loci - What the pointer rests on: an atom, or the two ends of a bond.
+ * @returns `O 1`, `Si 4 — O 8`, or `null` when the loci holds no atom.
+ */
+export function atomText(loci: Loci): string | null {
+  const atoms = StructureElement.Loci.is(loci)
+    ? loci
+    : Bond.isLoci(loci)
+      ? Bond.toStructureElementLoci(loci)
+      : null;
+  if (atoms === null) return null;
+  const names: string[] = [];
+  StructureElement.Loci.forEachLocation(atoms, (location) => {
+    names.push(
+      atomName(
+        String(StructureProperties.atom.type_symbol(location)),
+        StructureProperties.atom.sourceIndex(location),
+      ),
+    );
+  });
+  return names.length === 0 ? null : names.join(' — ');
+}
+
+/**
+ * What a site calls one atom of its scene.
+ *
+ * molstar upper-cases an element symbol on its way in, so the atom it hands
+ * back from an `Si` it was given is an `SI`, which is not how anybody writes
+ * silicon. The number is which atom of the scene it is, counting from one.
+ * @param element - Its element symbol, in any case.
+ * @param index - Its place in the file the viewer was handed, from zero.
+ * @returns `O 1`, `Si 4`.
+ */
+export function atomName(element: string, index: number): string {
+  const symbol =
+    element.charAt(0).toUpperCase() + element.slice(1).toLowerCase();
+  return `${symbol} ${index + 1}`;
+}
+
+/**
+ * Molstar's label providers return HTML, and a readout is plain text.
+ * @param label
+ */
+function stripMarkup(label: string): string {
+  return label
+    .replaceAll(/<[^>]*>/g, ' ')
+    .replaceAll('&nbsp;', ' ')
+    .replaceAll('&amp;', '&')
+    .replaceAll(/\s+/g, ' ')
+    .trim();
+}

package/src/molstar/core/index.ts

@@ -0,0 +1,13 @@
+export type { CameraPose, CameraReference, PoseOptions } from './cameraPose.ts';
+export { cameraToPose, poseToCamera } from './cameraPose.ts';
+export {
+  DEFAULT_CAMERA_DURATION,
+  DEFAULT_SPIN_SPEED,
+  FRAMING_MARGIN,
+  MINIMUM_FRAMING_RADIUS,
+  framedRadius,
+  setSpin,
+} from './camera.ts';
+export { atomName, atomText, lociText, subscribeHover } from './hover.ts';
+export type { MolstarPluginOptions } from './plugin.ts';
+export { MolstarPlugin } from './plugin.ts';