@motionscript/molecule 0.0.0-stage → 0.1.0-alpha.0

package/dist/protein/protein.d.ts

@@ -0,0 +1,265 @@
+import { type Command, type CommandArgs, Canvas3D, Scene3D, type Canvas3DProps, type Color, type NodeConfig } from "@motionscript/core";
+import { type OrbitTarget } from "@motionscript/core/component";
+import { type ProteinColorScheme, type ProteinRepresentation } from "./shared.js";
+import { type ProteinStructure } from "./structure.js";
+export interface ProteinProps extends Canvas3DProps {
+    /**
+     * The molecule to draw, already parsed.
+     *
+     * A value rather than a source, and that is the whole arrangement: reading a
+     * coordinate file means a network round-trip or a file read, and this node is
+     * constructed inside a synchronous render pass. So the fetching and the
+     * parsing happen *before* the build — see `parseStructure` and the app's
+     * structure store — and what arrives here is finished data. It is the same
+     * bargain a chart makes with its rows.
+     */
+    structure: ProteinStructure;
+    /** How the molecule is drawn. See {@link ProteinRepresentation}. */
+    representation: ProteinRepresentation;
+    /** What decides an atom's colour. See {@link ProteinColorScheme}. */
+    colorScheme: ProteinColorScheme;
+    /** The colour the `uniform` scheme paints, and every scheme's fallback. */
+    color: Color;
+    /**
+     * Every colour the *other* schemes paint from — see {@link ProteinPalette},
+     * which is the shape these are read as rather than a prop of its own.
+     *
+     * Thirteen props rather than one palette because a prop is a whole value: a
+     * single one would make a `to` that reddens the helices a statement about the
+     * eight chain colours too, and the ones the author never touched would snap.
+     * Each of these carries over and tweens on its own, like every other colour in
+     * the app.
+     */
+    helixColor: string;
+    sheetColor: string;
+    coilColor: string;
+    /** The two ends of the N→C ramp, swept through HSL between them. */
+    residueStartColor: string;
+    residueEndColor: string;
+    /** One per chain, cycling past the eighth. */
+    chainColor1: string;
+    chainColor2: string;
+    chainColor3: string;
+    chainColor4: string;
+    chainColor5: string;
+    chainColor6: string;
+    chainColor7: string;
+    chainColor8: string;
+    /**
+     * Atom size as a fraction of the true van der Waals radius.
+     *
+     * 1 is the space-filling model — atoms at the size they actually are, touching
+     * their neighbours. Ball-and-stick shrinks them further on its own, so this
+     * stays "how big are the atoms" in both rather than meaning something
+     * different in each.
+     */
+    atomScale: number;
+    /** Bond stick radius, in Ångströms. */
+    bondRadius: number;
+    /** Backbone tube radius, in Ångströms. A ribbon swells past this on a helix. */
+    ribbonRadius: number;
+    /** Whether to draw ligands, ions and cofactors — everything that isn't polymer. */
+    ligands: boolean;
+    /** Whether to draw crystallographic waters. Off, because there are hundreds. */
+    waters: boolean;
+    /** Mesh detail: segments around a sphere or a stick. */
+    quality: number;
+    /** Camera orbit about the vertical axis, in **degrees**. Animate this to spin. */
+    orbit: number;
+    /** Camera elevation above the horizon, in **degrees**. */
+    elevation: number;
+    /**
+     * How far back the camera sits, as a multiple of the molecule's own radius.
+     *
+     * A multiple rather than a distance, because the things this node draws differ
+     * in size by two orders of magnitude — crambin is 12 Å across and a ribosome
+     * is 300 — and a stored distance that framed one would put the other off
+     * screen or inside the camera. As a ratio the same number frames both, and it
+     * goes on meaning the same thing when the structure is swapped.
+     */
+    zoom: number;
+    /** Strength of the ambient fill. */
+    ambientIntensity: number;
+    /** Colour of the ambient fill. White leaves the molecule's own colours alone. */
+    ambientColor: Color;
+    /** Strength of the key light; the rim light is derived from it. */
+    keyIntensity: number;
+    /** Colour of the key light, and of the rim derived from it. */
+    keyColor: Color;
+}
+/**
+ * A molecular structure viewer.
+ *
+ * Extends {@link Canvas3D} — as `Graph3D` does — so this class only has to say
+ * *what* to draw, and the bridge from the 2D scene graph into the 3D renderer is
+ * the base class's business. It overrides `buildScene3D`, the single seam both
+ * the real render and the asset declaration pass go through.
+ *
+ *   <Protein width="fill" height="fill"
+ *     structure={parseStructure(text, "6LU7")}
+ *     representation="ribbon" colorScheme="secondary" />
+ *
+ * **There is no pointer here.** Every other molecular viewer is driven by
+ * dragging the molecule around, and this one cannot be: the studio renders a
+ * timeline, so the camera has to be something a `to` command can tween and a
+ * scrub can reproduce exactly — frame 300 must be identical whether it was
+ * reached by playing forward or by dragging the playhead backwards. So the
+ * camera is three tweenable numbers (`orbit`, `elevation`, `zoom`), and spinning
+ * the molecule is a command rather than a gesture.
+ *
+ * Atoms and bonds are drawn **instanced**: one sphere geometry and one cylinder
+ * geometry, placed thousands of times in a single draw call each. A mesh per
+ * atom would be tens of thousands of draw calls a frame, which no renderer
+ * survives — and the instance lists themselves are cached (see {@link built}),
+ * because they don't change when the camera moves and the camera is what
+ * normally moves.
+ */
+export declare class Protein extends Canvas3D<ProteinProps> {
+    /**
+     * The molecule.
+     *
+     * Snaps rather than interpolating, and every other non-scalar prop here
+     * interpolates. There is no halfway point between two different molecules —
+     * atom 4,000 of one is not the same atom as atom 4,000 of the other, and
+     * blending their coordinates would produce a cloud that is neither. Swapping
+     * the structure is a change of *subject*, so it lands at the end of a tween
+     * the way a change of text does.
+     */
+    structure: ProteinStructure;
+    representation: ProteinRepresentation;
+    colorScheme: ProteinColorScheme;
+    color: Color;
+    /**
+     * The palette, thirteen props of it — see {@link ProteinProps.helixColor} for
+     * why it is thirteen and not one.
+     *
+     * No `mapper`, unlike the three `Color` props around them: these stay hex
+     * strings because a hex string is what an instance tint is handed, and
+     * {@link lerpHexColor} is the tween that goes with that. The defaults are
+     * written out rather than read off {@link DEFAULT_PROTEIN_PALETTE} because a
+     * decorator default has to be a literal the class carries; the two are pinned
+     * against each other by a test.
+     */
+    helixColor: string;
+    sheetColor: string;
+    coilColor: string;
+    residueStartColor: string;
+    residueEndColor: string;
+    chainColor1: string;
+    chainColor2: string;
+    chainColor3: string;
+    chainColor4: string;
+    chainColor5: string;
+    chainColor6: string;
+    chainColor7: string;
+    chainColor8: string;
+    atomScale: number;
+    bondRadius: number;
+    ribbonRadius: number;
+    ligands: boolean;
+    waters: boolean;
+    /**
+     * Structural, like `Graph3D.segments`: a geometry is immutable, so every
+     * intermediate value of a tween reallocates the sphere and the cylinder. Set
+     * once; the appearance schema marks it non-animatable to say the same thing
+     * from the other side.
+     */
+    quality: number;
+    orbit: number;
+    elevation: number;
+    zoom: number;
+    /**
+     * The default rig, and only the default rig — the same four controls the 3D
+     * viewport carries, in the same order and with the same defaults, because
+     * "how is this lit" is one question and a molecule is not a special case of
+     * it. Each light is a **strength and a colour**, in that order: how much
+     * light, and what colour it is.
+     *
+     * Both colours default to white rather than to a tint, so a rig nobody has
+     * touched grades nothing. A coloured default would be a look applied to every
+     * structure in every scene by a control the author never opened.
+     */
+    ambientIntensity: number;
+    ambientColor: Color;
+    keyIntensity: number;
+    keyColor: Color;
+    constructor(props?: NodeConfig<Protein, ProteinProps>);
+    /**
+     * Frame the scene at a spherical camera placement. Every axis is optional,
+     * so "pull back" and "spin round" stay separate intentions — see
+     * {@link OrbitTarget}.
+     */
+    orbitTo(args: CommandArgs<{
+        target: OrbitTarget;
+    }> & {
+        duration: number;
+    }): Command<ProteinProps>;
+    /**
+     * Drift the camera around the molecule for the command's duration — a
+     * continuous orbit at `speed` with a lateral `sway` and a `zoom` pulse
+     * (`breathe`), both on a shared `cycle` so they don't beat against each
+     * other. `settle` eases in from wherever the camera already is, so `float`
+     * after an `orbitTo` does not snap.
+     */
+    float(args: CommandArgs<{
+        speed?: number;
+        elevation?: number;
+        zoom?: number;
+        sway?: number;
+        breathe?: number;
+        cycle?: number;
+        settle?: number;
+    }> & {
+        duration?: number;
+    }): Command<ProteinProps>;
+    /**
+     * The thirteen colour props, as the one value the colourers take.
+     *
+     * Rebuilt per call rather than cached: it is thirteen property reads behind
+     * `built()`'s own cache, which is what stops it happening per frame.
+     */
+    private paletteOf;
+    protected buildScene3D(): Scene3D;
+    /** The molecule itself, in whichever representation is showing. */
+    private addMolecule;
+    /** One instanced sphere op, skipped entirely when there is nothing in it. */
+    private addSpheres;
+    /** One instanced cylinder op. */
+    private addSticks;
+    /**
+     * Everything the builder needs, cached against the inputs that decide it.
+     *
+     * This is the node's one piece of memoisation and it earns its keep. The
+     * builder runs every frame; between two frames the thing that has normally
+     * changed is the camera; and none of what is cached here depends on the
+     * camera. Without it, orbiting a 20,000-atom structure would rebuild a
+     * 20,000-entry placement list and a 40,000-entry stick list sixty times a
+     * second — for a picture whose atoms have not moved.
+     *
+     * The structure is compared by **identity** rather than by contents: it is a
+     * parsed value produced once, upstream, so a different object genuinely means
+     * a different molecule.
+     */
+    private cache;
+    private built;
+    /** Builds the placement lists for the current representation. */
+    private build;
+    /**
+     * The polymer, as whichever sweep its representation calls for.
+     *
+     * Two genuinely different builds rather than one with a radius switch, and
+     * the split is the same one the representations themselves are: `backbone`
+     * asks *where does the chain go*, which an even round tube answers exactly
+     * and completely; `ribbon` asks *what is it folded into*, which is the
+     * cartoon convention and needs a cross-section with a width, a thickness and
+     * a side (see `ribbon.ts`).
+     */
+    private addRuns;
+    /** Whether an atom passes the ligand and water filters. */
+    private isShowing;
+    /** Segments around a sphere's equator. */
+    private sphereQuality;
+    /** Segments around a stick or a tube — half a sphere's, since it has no poles. */
+    private stickQuality;
+}
+//# sourceMappingURL=protein.d.ts.map

package/dist/protein/protein.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protein.d.ts","sourceRoot":"","sources":["../../src/protein/protein.ts"],"names":[],"mappings":"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"}