react-cheminfo 0.66.0 → 0.67.0

package/src/molecule3d/ui/moleculeFrames.ts

@@ -0,0 +1,88 @@
+/**
+ * The frames of the file a viewer shows: how many there are, whether they
+ * play, and a picture of each.
+ *
+ * Kept apart from the viewer because every redraw of the scene has to go
+ * through it: a running animation must not step a state tree being rebuilt —
+ * it finds no model and stops itself — so the frames are stopped first and
+ * started again once the new file is drawn.
+ */
+
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+import type { FramePlayback, MolstarPlugin } from '../../molstar/core/index.ts';
+import {
+  captureFrames,
+  setTrajectoryPlayback,
+  stopTrajectory,
+} from '../../molstar/core/index.ts';
+import { DEFAULT_FRAMES_PER_SECOND } from '../core/animatedPng.ts';
+import type { ImageSize } from '../core/exportImage.ts';
+
+/** The frames of what one viewer shows. */
+export class MoleculeFrames {
+  readonly #plugin: MolstarPlugin;
+  readonly #onCountChange: (frameCount: number) => void;
+  // Kept across redraws, so the next file plays as the last one did.
+  #playback: FramePlayback = {
+    playing: false,
+    framesPerSecond: DEFAULT_FRAMES_PER_SECOND,
+  };
+
+  /**
+   * Follow the frames of what `plugin` draws.
+   * @param plugin - The canvas.
+   * @param onCountChange - Called with how many frames each scene drawn holds.
+   */
+  constructor(
+    plugin: MolstarPlugin,
+    onCountChange: (frameCount: number) => void,
+  ) {
+    this.#plugin = plugin;
+    this.#onCountChange = onCountChange;
+  }
+
+  /**
+   * Redraw the scene with the frames stopped, then report how many the new
+   * scene holds and play them if playback is on.
+   * @param plugin - The molstar context.
+   * @param draw - Draws the scene, and resolves with how many frames it holds.
+   * @returns Nothing; resolves once the scene is drawn and playing.
+   */
+  async redraw(
+    plugin: PluginContext,
+    draw: () => Promise<number>,
+  ): Promise<void> {
+    await stopTrajectory(plugin);
+    this.#onCountChange(await draw());
+    const { playing, framesPerSecond } = this.#playback;
+    await setTrajectoryPlayback(plugin, playing, framesPerSecond);
+  }
+
+  /**
+   * Play the frames in a loop, or stop them, now and for every scene drawn
+   * afterwards. A scene of one frame stays still.
+   * @param playing - Whether to play.
+   * @param framesPerSecond - How fast.
+   * @returns Nothing; resolves once the animation is started or stopped.
+   */
+  play(playing: boolean, framesPerSecond: number): Promise<void> {
+    this.#playback = { playing, framesPerSecond };
+    return this.#plugin.run((plugin) =>
+      setTrajectoryPlayback(plugin, playing, framesPerSecond),
+    );
+  }
+
+  /**
+   * Render every frame off screen, as a still picture of the scene is
+   * rendered. Playback pauses while they are taken.
+   * @param size - Pixel size of each picture.
+   * @returns The pictures, in order; `undefined` once the canvas is disposed.
+   * @throws {Error} When the plugin has no screenshot helper.
+   */
+  capture(size: ImageSize): Promise<ImageData[] | undefined> {
+    return this.#plugin.run((plugin) =>
+      captureFrames(plugin, size, this.#playback),
+    );
+  }
+}

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -2,13 +2,10 @@ import type { ReactNode } from 'react';
 
 import type { ViewerCapability } from '../../orbital/ui/capability.ts';
 import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Molecule3DFile } from '../core/file.ts';
 import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement } from '../core/measurement.ts';
-import type {
-  Molecule3DFile,
-  Molecule3DSettings,
-  Molecule3DTools,
-} from '../core/settings.ts';
+import type { Molecule3DSettings, Molecule3DTools } from '../core/settings.ts';
 
 /**
  * Props of `MoleculeViewer3D`.
@@ -69,6 +66,18 @@ export interface MoleculeViewer3DProps {
    * @default 1 / 3
    */
   spinSpeed?: number;
+  /**
+   * Whether the frames of a file holding several are played in a loop. A file
+   * of one model stays still whatever this says.
+   * @default false
+   */
+  playing?: boolean;
+  /**
+   * How many frames are shown per second while playing, and in an animated
+   * PNG; molstar plays between 5 and 60.
+   * @default 25
+   */
+  framesPerSecond?: number;
   /**
    * The measurements drawn over the model, when the site owns them. They name
    * atoms by position, so they carry over to another conformer of the same

package/src/molecule3d/ui/renderMolecule.ts

@@ -15,7 +15,8 @@ import { StructureFromModel } from 'molstar/lib/mol-plugin-state/transforms/mode
 import { StructureRepresentation3D } from 'molstar/lib/mol-plugin-state/transforms/representation.js';
 import type { StateTransformer } from 'molstar/lib/mol-state/index.js';
 
-import type { Molecule3DFile, RepresentationId } from '../core/settings.ts';
+import type { Molecule3DFile } from '../core/file.ts';
+import type { RepresentationId } from '../core/settings.ts';
 
 import type { MoleculeStyle } from './viewerTypes.ts';
 
@@ -48,7 +49,7 @@ const STICK_SCALE = 1.2;
  * @param plugin - The molstar context.
  * @param molfile - Molfile text plus the format id.
  * @param style - See {@link MoleculeStyle}.
- * @returns Nothing; resolves once the model is on screen.
+ * @returns How many frames the file holds, the first of which is on screen.
  * @throws {Error} When the file parses to zero atoms. molstar's `mol` parser returns
  * exactly that on a V3000 file, with no error, so without this check the viewer
  * would show an empty scene and report nothing.
@@ -57,7 +58,7 @@ export async function renderMolecule(
   plugin: PluginContext,
   molfile: Molecule3DFile,
   style: MoleculeStyle = {},
-): Promise<void> {
+): Promise<number> {
   const { representation = 'ball-and-stick', sizeFactor = 1 } = style;
   await clearMolecule(plugin);
   const data = await plugin.builders.data.rawData(
@@ -99,6 +100,7 @@ export async function renderMolecule(
       ),
     )
     .commit();
+  return trajectory.data?.frameCount ?? 1;
 }
 
 /**

package/src/molecule3d/ui/sceneDrawer.ts

@@ -11,9 +11,10 @@
  */
 
 import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Molecule3DFile } from '../core/file.ts';
 import type { Measurement } from '../core/measurement.ts';
 import { sameMeasurements } from '../core/measurement.ts';
-import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import type { Molecule3DSettings } from '../core/settings.ts';
 import { sameMolecule3DSettings } from '../core/settings.ts';
 
 import type { SceneViewer } from './drawScene.ts';
@@ -103,7 +104,7 @@ export class SceneDrawer {
     const { molfile, settings, measurements, frameNewMolecule } = request;
     const isNew =
       molfile !== null &&
-      (this.#framed === null || !sameFile(this.#framed, molfile));
+      (this.#framed === null || !sameMolecule(this.#framed, molfile));
     this.#framed = molfile;
     // A link's camera is spent on the first molecule framed; afterwards the
     // camera is the reader's and a new molecule is framed as usual.
@@ -119,6 +120,17 @@ export class SceneDrawer {
   }
 }
 
+// Two files a site names alike draw one molecule, whatever their text.
+function sameMolecule(first: Molecule3DFile, second: Molecule3DFile): boolean {
+  if (
+    first.moleculeId !== undefined &&
+    first.moleculeId === second.moleculeId
+  ) {
+    return true;
+  }
+  return sameFile(first, second);
+}
+
 function sameFile(
   first: Molecule3DFile | null,
   second: Molecule3DFile | null,

package/src/molecule3d/ui/useImageExport.ts

@@ -5,6 +5,7 @@ import type { FigureNotice } from '../../download/core/copyFigure.ts';
 import { copyFigure } from '../../download/core/copyFigure.ts';
 import type { FigureFormat } from '../../download/core/downloadFigure.ts';
 import type { FigurePixels } from '../../download/core/figureScale.ts';
+import { DEFAULT_FRAMES_PER_SECOND } from '../core/animatedPng.ts';
 
 import type { SceneCapture } from './exportMoleculeImage.ts';
 import {
@@ -16,8 +17,15 @@ import {
 export interface ImageExport {
   /** Size of the canvas on screen, or `null` before it is laid out. */
   canvasSize: () => FigurePixels | null;
-  /** Render the scene at `scale` and download it as `format`. */
-  exportImage: (format: FigureFormat, scale: number) => Promise<void>;
+  /**
+   * Render the scene at `scale` and download it as `format` — every frame of
+   * it, as an animated PNG, when `animated` is set and the format is PNG.
+   */
+  exportImage: (
+    format: FigureFormat,
+    scale: number,
+    animated?: boolean,
+  ) => Promise<void>;
   /**
    * Render the scene at `scale` and put it on the clipboard as a PNG. Call it
    * from the click itself: Safari only allows a write the click started.
@@ -30,12 +38,15 @@ export interface ImageExport {
  * @param container - The element molstar draws into.
  * @param viewerRef - The viewer, once created.
  * @param fileName - File name without its extension.
+ * @param framesPerSecond - How fast an animated PNG plays its frames.
+ * @default 25
  * @returns See {@link ImageExport}.
  */
 export function useImageExport(
   container: HTMLDivElement | null,
   viewerRef: RefObject<SceneCapture | null>,
   fileName: string,
+  framesPerSecond = DEFAULT_FRAMES_PER_SECOND,
 ): ImageExport {
   const canvasSize = useCallback((): FigurePixels | null => {
     if (container === null) return null;
@@ -45,15 +56,21 @@ export function useImageExport(
   }, [container]);
 
   const exportImage = useCallback(
-    async (format: FigureFormat, scale: number) => {
+    async (format: FigureFormat, scale: number, animated = false) => {
       const viewer = viewerRef.current;
       const size = canvasSize();
       if (viewer === null || size === null) {
         throw new Error('There is no picture to export yet.');
       }
-      await exportMoleculeImage(viewer, { format, scale, size, fileName });
+      await exportMoleculeImage(viewer, {
+        format,
+        scale,
+        size,
+        fileName,
+        framesPerSecond: animated ? framesPerSecond : undefined,
+      });
     },
-    [canvasSize, viewerRef, fileName],
+    [canvasSize, viewerRef, fileName, framesPerSecond],
   );
 
   const copyImage = useCallback(

package/src/molecule3d/ui/useMoleculeScene.ts

@@ -12,8 +12,9 @@
 import type { RefObject } from 'react';
 import { useCallback, useEffect, useRef } from 'react';
 
+import type { Molecule3DFile } from '../core/file.ts';
 import type { Measurement } from '../core/measurement.ts';
-import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import type { Molecule3DSettings } from '../core/settings.ts';
 
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
 import { SceneDrawer } from './sceneDrawer.ts';

package/src/molecule3d/ui/useMoleculeViewer.ts

@@ -0,0 +1,46 @@
+/**
+ * The molstar viewer of one canvas: created once its element exists, kept to
+ * the element's size, and disposed with it.
+ */
+
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+import { createMolecule3DViewer } from './createViewer.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+import type { Molecule3DViewerOptions } from './viewerTypes.ts';
+
+/**
+ * Mount a viewer in `container` for as long as it exists.
+ * @param container - The element molstar draws in, or `null` before it exists.
+ * @param options - Read when the viewer is created; a later change is ignored,
+ * so a callback reads what it needs from a ref of its own.
+ * @returns The viewer, holding `null` while there is none.
+ */
+export function useMoleculeViewer(
+  container: HTMLElement | null,
+  options: Molecule3DViewerOptions,
+): RefObject<Molecule3DViewer | null> {
+  const viewerRef = useRef<Molecule3DViewer | null>(null);
+  const latestOptions = useRef(options);
+  useEffect(() => {
+    latestOptions.current = options;
+  });
+
+  useEffect(() => {
+    if (container === null) return;
+    const viewer = createMolecule3DViewer(container, latestOptions.current);
+    viewerRef.current = viewer;
+    const observer = new ResizeObserver(() => {
+      viewer.handleResize();
+    });
+    observer.observe(container);
+    return () => {
+      observer.disconnect();
+      viewerRef.current = null;
+      viewer.dispose();
+    };
+  }, [container]);
+
+  return viewerRef;
+}

package/src/molecule3d/ui/usePolarSurfaceArea.ts

@@ -1,14 +1,14 @@
 import { useEffect, useState } from 'react';
 
-import type { Molecule3DFile } from '../core/settings.ts';
+import type { Molecule3DFile } from '../core/file.ts';
 
 /**
  * Ertl's topological polar surface area of the molecule, from openchemlib,
  * loaded only once a caller asks for it.
  * @param molfile - The molecule, or `null`.
  * @param enabled - Whether to compute it at all.
- * @returns The area in Ų, or `null` while unknown, disabled, or when
- * openchemlib is not installed or cannot read the molfile.
+ * @returns The area in Ų, or `null` while unknown, disabled, for an XYZ
+ * file, or when openchemlib is not installed or cannot read the molfile.
  */
 export function usePolarSurfaceArea(
   molfile: Molecule3DFile | null,
@@ -18,7 +18,9 @@ export function usePolarSurfaceArea(
     data: string;
     area: number | null;
   } | null>(null);
-  const data = enabled ? (molfile?.data ?? null) : null;
+  // An XYZ file has no bonds for openchemlib to find the polar atoms by.
+  const data =
+    enabled && molfile?.format !== 'xyz' ? (molfile?.data ?? null) : null;
 
   useEffect(() => {
     if (data === null) return;

package/src/molecule3d/ui/viewer.ts

@@ -8,7 +8,6 @@
  * is the component's.
  */
 
-import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
 import { Color } from 'molstar/lib/mol-util/color/color.js';
 
 import {
@@ -24,11 +23,12 @@ import {
 } from '../../molstar/core/index.ts';
 import type { Molecule3DCamera } from '../core/camera.ts';
 import type { ImageSize } from '../core/exportImage.ts';
+import type { Molecule3DFile } from '../core/file.ts';
 import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
-import type { Molecule3DFile } from '../core/settings.ts';
 
 import { applyCamera, resetCamera, watchCamera } from './camera.ts';
+import { MoleculeFrames } from './moleculeFrames.ts';
 import {
   MODEL_REPRESENTATION_REF,
   clearMolecule,
@@ -54,16 +54,24 @@ export class Molecule3DViewer {
   /** Resolves once the canvas exists; every method awaits it internally. */
   readonly ready: Promise<void>;
 
+  /** The frames of the file on screen: playing them, and their pictures. */
+  readonly frames: MoleculeFrames;
+
   /**
    * Mount the canvas and start initialising the plugin.
    * @param container - A positioned element.
    * @param options - See {@link Molecule3DViewerOptions}.
    */
   constructor(container: HTMLElement, options: Molecule3DViewerOptions = {}) {
-    const { background, onMeasure = ignore } = options;
+    const {
+      background,
+      onMeasure = ignore,
+      onFrameCountChange = 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.frames = new MoleculeFrames(this.#plugin, onFrameCountChange);
+    // Registered before any other `run`, so the picker exists by the time one runs.
     void this.#plugin
       .run((plugin) => {
         this.#picker = new MeasurementPicker(
@@ -84,10 +92,12 @@ export class Molecule3DViewer {
    * @throws {Error} When the file parses to zero atoms.
    */
   showMolecule(molfile: Molecule3DFile, style?: MoleculeStyle): Promise<void> {
-    return this.#run(async (plugin) => {
-      await clearMeasurements(plugin);
-      await renderMolecule(plugin, molfile, style);
-    });
+    return this.#plugin.run((plugin) =>
+      this.frames.redraw(plugin, async () => {
+        await clearMeasurements(plugin);
+        return renderMolecule(plugin, molfile, style);
+      }),
+    );
   }
 
   /**
@@ -95,10 +105,13 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the scene is empty.
    */
   hideMolecule(): Promise<void> {
-    return this.#run(async (plugin) => {
-      await clearMeasurements(plugin);
-      await clearMolecule(plugin);
-    });
+    return this.#plugin.run((plugin) =>
+      this.frames.redraw(plugin, async () => {
+        await clearMeasurements(plugin);
+        await clearMolecule(plugin);
+        return 0;
+      }),
+    );
   }
 
   /**
@@ -107,7 +120,7 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the surface is on screen.
    */
   showSurface(style?: SurfaceStyle): Promise<void> {
-    return this.#run((plugin) => renderSurface(plugin, style));
+    return this.#plugin.run((plugin) => renderSurface(plugin, style));
   }
 
   /**
@@ -115,7 +128,7 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the surface is gone.
    */
   hideSurface(): Promise<void> {
-    return this.#run((plugin) => clearSurface(plugin));
+    return this.#plugin.run((plugin) => clearSurface(plugin));
   }
 
   /**
@@ -124,7 +137,7 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the labels are on screen.
    */
   showMeasurements(measurements: readonly Measurement[]): Promise<void> {
-    return this.#run((plugin) =>
+    return this.#plugin.run((plugin) =>
       renderMeasurements(plugin, measurements, moleculeStructure),
     );
   }
@@ -140,7 +153,7 @@ export class Molecule3DViewer {
     highlights: readonly Molecule3DHighlight[],
     color: string,
   ): Promise<void> {
-    return this.#run(() => {
+    return this.#plugin.run(() => {
       this.#painter?.set(highlights, Color.fromHexStyle(color));
     });
   }
@@ -151,7 +164,7 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the plugin has switched mode.
    */
   setMeasureKind(kind: MeasurementKind | null): Promise<void> {
-    return this.#run(() => {
+    return this.#plugin.run(() => {
       this.#picker?.setKind(kind);
     });
   }
@@ -164,7 +177,7 @@ export class Molecule3DViewer {
    * @throws {Error} When the plugin has no screenshot helper.
    */
   captureImage(size: ImageSize): Promise<string | undefined> {
-    return this.#run((plugin) => captureScene(plugin, size));
+    return this.#plugin.run((plugin) => captureScene(plugin, size));
   }
 
   /**
@@ -177,7 +190,7 @@ export class Molecule3DViewer {
     durationMilliseconds = DEFAULT_CAMERA_DURATION,
     fromFront = false,
   ): Promise<void> {
-    return this.#run((plugin) => {
+    return this.#plugin.run((plugin) => {
       resetCamera(plugin, durationMilliseconds, fromFront);
     });
   }
@@ -189,7 +202,7 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the move has been ordered.
    */
   setCamera(camera: Molecule3DCamera, durationMilliseconds = 0): Promise<void> {
-    return this.#run((plugin) => {
+    return this.#plugin.run((plugin) => {
       applyCamera(plugin, camera, durationMilliseconds);
     });
   }
@@ -211,7 +224,7 @@ export class Molecule3DViewer {
    * @returns Nothing; resolves once the trackball has been reconfigured.
    */
   setSpin(spinning: boolean, speed = DEFAULT_SPIN_SPEED): Promise<void> {
-    return this.#run((plugin) => {
+    return this.#plugin.run((plugin) => {
       setSpin(plugin, spinning, speed);
     });
   }
@@ -227,12 +240,6 @@ export class Molecule3DViewer {
     this.#painter?.dispose();
     this.#plugin.dispose();
   }
-
-  #run<Result>(
-    action: (plugin: PluginContext) => Result | Promise<Result>,
-  ): Promise<Result | undefined> {
-    return this.#plugin.run(action);
-  }
 }
 
 function ignore(): void {

package/src/molecule3d/ui/viewerTypes.ts

@@ -19,6 +19,12 @@ export interface Molecule3DViewerOptions {
    * @default undefined
    */
   onMeasure?: (measurement: Measurement) => void;
+  /**
+   * Called with how many frames the file on screen holds, each time a file is
+   * drawn, and with 0 once the scene is emptied.
+   * @default undefined
+   */
+  onFrameCountChange?: (frameCount: number) => void;
 }
 
 /** How to draw the model. */

package/src/molstar/core/captureScene.ts

@@ -1,11 +1,22 @@
 /**
- * A picture of the scene, rendered off screen at a size of its own.
+ * A picture of the scene, rendered off screen at a size of its own — one
+ * frame, or every frame of the trajectory on screen.
  */
 
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import type { ViewportScreenshotHelper } from 'molstar/lib/mol-plugin/util/viewport-screenshot.js';
+import { Task } from 'molstar/lib/mol-task/index.js';
 
 import type { ImageSize } from '../../molecule3d/core/exportImage.ts';
 
+import {
+  setTrajectoryPlayback,
+  showTrajectoryFrame,
+  shownTrajectoryFrame,
+  stopTrajectory,
+  trajectoryFrameCount,
+} from './trajectory.ts';
+
 /**
  * Render the scene without its selection highlights or its axes.
  * @param plugin - The molstar context.
@@ -17,6 +28,78 @@ export async function captureScene(
   plugin: PluginContext,
   size: ImageSize,
 ): Promise<string> {
+  return pictureHelper(plugin, size).getImageDataUri();
+}
+
+/** How a series of frames is played, so it can be resumed once captured. */
+export interface FramePlayback {
+  playing: boolean;
+  framesPerSecond: number;
+}
+
+/**
+ * Render every frame of the trajectory on screen, in order, as the scene shows
+ * it: the model, its surface and the measurements over it, each at that frame.
+ * The animation is stopped while the frames are taken and resumed afterwards,
+ * and the scene is left on the frame it showed.
+ * @param plugin - The molstar context.
+ * @param size - Pixel size of each picture.
+ * @param playback - What to resume once the frames are taken.
+ * @returns One picture per frame; a scene of one model gives one.
+ * @throws {Error} When the plugin has no screenshot helper.
+ */
+export async function captureFrames(
+  plugin: PluginContext,
+  size: ImageSize,
+  playback: FramePlayback,
+): Promise<ImageData[]> {
+  const pass = pictureHelper(plugin, size).imagePass;
+  const loop = plugin.animationLoop;
+  const shown = shownTrajectoryFrame(plugin);
+  const count = Math.max(1, trajectoryFrameCount(plugin));
+  await stopTrajectory(plugin);
+  loop.stop({ noDraw: true });
+  try {
+    await pass.updateBackground();
+    const frames: ImageData[] = [];
+    for (let index = 0; index < count; index++) {
+      // eslint-disable-next-line no-await-in-loop -- each frame is a commit of the state tree, and commits must not interleave
+      if (count > 1) await showTrajectoryFrame(plugin, index);
+      // The scene is otherwise committed on the next animation frame, after
+      // the picture has been taken of the previous one.
+      plugin.canvas3d?.commit(true);
+      // eslint-disable-next-line no-await-in-loop -- one render at a time on the one image pass
+      const image = await plugin.runTask(
+        Task.create('Render a frame', (runtime) =>
+          pass.getImageData(runtime, size.width, size.height),
+        ),
+      );
+      frames.push(image);
+    }
+    return frames;
+  } finally {
+    if (count > 1) await showTrajectoryFrame(plugin, shown);
+    loop.start({ immediate: true });
+    await setTrajectoryPlayback(
+      plugin,
+      playback.playing,
+      playback.framesPerSecond,
+    );
+  }
+}
+
+/**
+ * The screenshot helper, set to draw a picture of `size` with no axes and an
+ * opaque background.
+ * @param plugin - The molstar context.
+ * @param size - Pixel size of the picture.
+ * @returns The helper.
+ * @throws {Error} When the plugin has no screenshot helper.
+ */
+function pictureHelper(
+  plugin: PluginContext,
+  size: ImageSize,
+): ViewportScreenshotHelper {
   const helper = plugin.helpers.viewportScreenshot;
   if (helper === undefined) {
     throw new Error('This viewer cannot take a picture of its scene.');
@@ -27,5 +110,5 @@ export async function captureScene(
     axes: { name: 'off', params: {} },
     transparent: false,
   });
-  return helper.getImageDataUri();
+  return helper;
 }

package/src/molstar/core/index.ts

@@ -1,6 +1,7 @@
 /**
  * The molstar layer under the 3D views: the plugin lifecycle, the camera, the
- * hover labels, the measurements, the highlights and the picture of a scene.
+ * hover labels, the measurements, the highlights, the frames of a trajectory
+ * and the picture of a scene.
  *
  * Three of our sites mount a headless molstar canvas — the molecule viewer
  * here, lcao's orbitals and symmetry's crystals — and each of them had its own
@@ -49,7 +50,8 @@ export {
 } from './hover.ts';
 export type { MolstarPluginOptions } from './plugin.ts';
 export { MolstarPlugin } from './plugin.ts';
-export { captureScene } from './captureScene.ts';
+export type { FramePlayback } from './captureScene.ts';
+export { captureFrames, captureScene } from './captureScene.ts';
 export type { MoleculeStructureSource } from './measurements.ts';
 export {
   MeasurementPicker,
@@ -57,3 +59,12 @@ export {
   clearMeasurements,
   renderMeasurements,
 } from './measurements.ts';
+export {
+  PLAYBACK_FPS_RANGE,
+  clampFramesPerSecond,
+  setTrajectoryPlayback,
+  showTrajectoryFrame,
+  shownTrajectoryFrame,
+  stopTrajectory,
+  trajectoryFrameCount,
+} from './trajectory.ts';