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

package/dist/protein/shared.d.ts

@@ -0,0 +1,221 @@
+/**
+ * What the {@link Protein} node turns a parsed molecule into: which atoms are
+ * showing, what colour each one takes, and how a bond becomes a cylinder.
+ *
+ * Everything here is **derived per structure**, not per frame. The node caches
+ * what these return against the inputs that produced them (see
+ * `Protein.instances`), because the camera moves every frame and none of this
+ * changes when it does — and a mid-sized entry is tens of thousands of atoms, so
+ * rebuilding the arrays sixty times a second to spin the view would be the
+ * difference between a smooth orbit and a slideshow.
+ */
+import type { Color, Transform3D, Vector3 } from "@motionscript/core";
+import type { ProteinAtom, ProteinChain, ProteinStructure, SecondaryStructure } from "./structure.js";
+/**
+ * How the molecule is drawn.
+ *
+ * The four that answer genuinely different questions, which is why there are
+ * four rather than a dozen:
+ *
+ * - `spacefill` — every atom at its van der Waals radius. What the molecule's
+ *   *surface* is: the shape it presents to everything around it.
+ * - `ballAndStick` — atoms shrunk, bonds drawn. What the molecule's *chemistry*
+ *   is, and the only one where an individual atom can be picked out.
+ * - `backbone` — a thin even tube through the α-carbons. Where the chain *goes*,
+ *   with nothing else in the way.
+ * - `ribbon` — the same curve, swelling along helices and strands and coloured
+ *   by them. What the protein is *folded into*, which is what a figure in a
+ *   paper is nearly always about.
+ */
+export declare const PROTEIN_REPRESENTATIONS: readonly ["ribbon", "backbone", "ballAndStick", "spacefill"];
+export type ProteinRepresentation = (typeof PROTEIN_REPRESENTATIONS)[number];
+/**
+ * What decides an atom's colour.
+ *
+ * Each one answers a question the picture might be asking, and the default
+ * differs by representation for exactly that reason: a space-filling model with
+ * no element colouring is a featureless blob, while a ribbon coloured by element
+ * is a single shade of grey.
+ */
+export declare const PROTEIN_COLOR_SCHEMES: readonly ["secondary", "element", "chain", "residue", "uniform"];
+export type ProteinColorScheme = (typeof PROTEIN_COLOR_SCHEMES)[number];
+/**
+ * The per-chain palette.
+ *
+ * Eight, spread around the wheel rather than sampled from a gradient: chains are
+ * a *nominal* scale — chain B is not between A and C in any sense — so the
+ * colours have to be distinguishable rather than ordered. A ninth chain wraps,
+ * which is the honest failure for a complex that large; the alternative is
+ * colours nobody can tell apart.
+ *
+ * Eight is therefore the *palette's* length rather than a constant anything
+ * downstream may assume: an author who edits these edits eight entries, and the
+ * wrap is modulo whatever the list holds.
+ */
+export declare const CHAIN_COLORS: readonly ["#4f9dff", "#ff8a3d", "#4ddb9a", "#e05fd0", "#ffd166", "#8b7bff", "#ff6b6b", "#3fd0d6"];
+/**
+ * Helix, sheet and coil.
+ *
+ * The conventional assignment — warm for helices, cool for strands, pale for
+ * everything else — which is old enough to be read without a legend.
+ */
+export declare const SECONDARY_COLORS: Readonly<Record<SecondaryStructure, string>>;
+/**
+ * Every colour a scheme reaches for that is **not** the node's own `color`.
+ *
+ * Three schemes paint from more than one colour — the fold's three states, the
+ * eight chain hues, the two ends of the N→C ramp — and until now all three were
+ * frozen in this file. They are conventional rather than arbitrary, which is why
+ * the defaults below are exactly what they were, but "conventional" is a good
+ * reason for a *default* and a poor one for a rule: a figure has a palette, and
+ * a molecule in it that refuses to join in is the one element on the slide
+ * somebody has to work around.
+ *
+ * A **read** shape rather than a prop. The node holds these as thirteen separate
+ * props and gathers them into one of these to hand to the colourers below, and
+ * that split is deliberate rather than clumsy: a prop is a whole value, so a
+ * single `palette` prop would make every `to` that reddens the helices a
+ * statement about all thirteen colours, snapping the twelve the author never
+ * touched back to whatever the command happened to carry. Thirteen props carry
+ * over one at a time and tween one at a time, which is what every other colour
+ * in the app does.
+ *
+ * Nothing here reaches the `element` scheme, deliberately. CPK is not a palette
+ * anybody chose — oxygen is red because oxygen is red — so it stays in
+ * `chemistry.ts` with the van der Waals radii, which are facts about the same
+ * atoms and equally not a matter of taste.
+ */
+export interface ProteinPalette {
+    /** Secondary structure, when the scheme is `secondary`. */
+    helix: string;
+    sheet: string;
+    coil: string;
+    /**
+     * One hue per chain, when the scheme is `chain`, wrapping past the end.
+     *
+     * A list rather than a fixed eight so the wrap follows what is actually here:
+     * an author who deletes down to three colours gets a three-colour cycle, which
+     * is a legible answer, where a wrap modulo a constant would index past it.
+     */
+    chains: readonly string[];
+    /** The two ends of the N→C ramp, when the scheme is `residue`. */
+    residueStart: string;
+    residueEnd: string;
+}
+/**
+ * The palette every scheme has always drawn — the conventional assignment, now
+ * stated as a value the author can take over rather than as a constant.
+ *
+ * The two spectrum ends are **computed** from the hues the ramp used to be
+ * written as, rather than typed out as hex, so the default sweep is the same
+ * blue-through-green-to-red it has always been by construction instead of by
+ * somebody having done the arithmetic correctly once.
+ */
+export declare const DEFAULT_PROTEIN_PALETTE: ProteinPalette;
+/**
+ * How many chain colours the palette offers, and therefore what the chain cycle
+ * wraps at.
+ *
+ * Eight, because that is how many hues can be told apart at a glance — the
+ * reason {@link CHAIN_COLORS} has eight — and it is named here because three
+ * places have to agree on it: the schema declares this many rows, the props
+ * mapper reads this many, and the node holds this many.
+ */
+export declare const CHAIN_COLOR_COUNT: 8;
+/**
+ * The appearance-bag field names the palette is edited as, in panel order.
+ *
+ * Three places have to agree on this list and none of them can derive it from
+ * the others: the schema declares a row per name, `proteinMotionProps` copies a
+ * row per name onto the props, and the node declares a `@property` per name.
+ * The third is the one that cannot be written as a loop — a decorator is a
+ * declaration — so what this buys is the first two staying in step with it, and
+ * a test pins the third against it.
+ *
+ * `color` is deliberately not here. It is the node's own colour rather than part
+ * of a scheme's palette: it is what `uniform` paints and what every scheme falls
+ * back to, so it lives beside `representation` as a field of the molecule.
+ */
+export declare const PROTEIN_PALETTE_FIELDS: readonly ["helixColor", "sheetColor", "coilColor", "residueStartColor", "residueEndColor", ...`chainColor${number}`[]];
+/** The default each {@link PROTEIN_PALETTE_FIELDS} entry carries, by name. */
+export declare const PROTEIN_PALETTE_DEFAULTS: Readonly<Record<string, string>>;
+/**
+ * Tween: two `#rrggbb` strings, blended per channel.
+ *
+ * The palette entries are the one family of colours here that stay **strings**
+ * rather than going through `resolveColor3D` — an instance tint is handed a hex
+ * string — so they need a tween of their own rather than {@link lerpColor3D}.
+ *
+ * Blended in RGB, unlike the residue ramp {@link spectrum} sweeps: that one is a
+ * *spectrum*, where covering the wheel is the whole point, while this is one
+ * colour becoming another, where the short straight path is what "fading to red"
+ * means. Anything unparseable snaps, which is the only honest answer for a value
+ * with no channels to interpolate.
+ */
+export declare function lerpHexColor(from: string, to: string, t: number): string;
+/**
+ * The colour of every atom, in the order the structure holds them.
+ *
+ * One flat array rather than a function called per atom, because the instance
+ * builder walks the whole list and an array is what `Graphics3D.instances` takes
+ * anyway.
+ */
+export declare function atomColors(structure: ProteinStructure, scheme: ProteinColorScheme, uniform: string, palette?: ProteinPalette): string[];
+/**
+ * The colour of each point along one chain's backbone.
+ *
+ * Separate from {@link atomColors} because a trace point is a *residue* and an
+ * atom is not: the element scheme has nothing to say about a residue (every
+ * trace atom is a carbon, so the whole ribbon would be grey), so it falls back
+ * to the chain colouring — which is what somebody who picked "element" and then
+ * switched to a ribbon actually wants to see.
+ */
+export declare function traceColors(structure: ProteinStructure, chain: ProteinChain, scheme: ProteinColorScheme, uniform: string, palette?: ProteinPalette): string[];
+/** An atom's drawn radius in Ångströms, at a given scale of its true size. */
+export declare function atomRadius(atom: ProteinAtom, scale: number): number;
+/**
+ * The placement of a stick running from `from` to `to`.
+ *
+ * A cylinder geometry is built along **+Y**, centred on the origin and one unit
+ * tall, so placing one takes all three parts of a transform: move it to the
+ * midpoint, scale it to the bond's length, and turn +Y onto the bond's
+ * direction.
+ *
+ * The turn is a quaternion rather than an Euler triple because there is no
+ * ordering of three axis rotations that doesn't gimbal somewhere, and a molecule
+ * has bonds pointing every way there is — one of them would land exactly on the
+ * degenerate axis and the stick would spin to a wrong orientation.
+ */
+export declare function stickPlacement(from: Vector3, to: Vector3, radius: number): Transform3D;
+/** One stretch of a chain drawn as a single swept tube. */
+export interface BackboneRun {
+    points: Vector3[];
+    color: string;
+    secondary: SecondaryStructure;
+}
+/**
+ * Splits a chain's trace into the runs a backbone is swept as.
+ *
+ * A run is a stretch that can be drawn as **one** `Geo.tube`, and what forces a
+ * break is anything the tube carries once for its whole length: its colour
+ * always, and — for a cartoon — its radius, since a helix that doesn't swell is
+ * not a helix anyone will recognise.
+ *
+ * Consecutive runs **overlap by one point**, which is what keeps the tubes
+ * meeting rather than leaving a gap at every transition: the shared point is the
+ * end of one sweep and the start of the next, so their ends sit in the same
+ * place.
+ *
+ * The trade this makes is worth stating. A tube is swept along a Catmull-Rom
+ * curve through its own points, so a long run comes out smooth and a two-point
+ * run comes out straight. Under the colourings a fold is usually drawn in —
+ * secondary structure, chain, one colour — runs are long and the curve is
+ * smooth. Under the residue spectrum every point is its own colour, so the
+ * chain becomes a faceted polyline with a gradient along it. That is the honest
+ * cost of colouring per residue without a mesh built vertex by vertex, and at
+ * the scale a whole fold is viewed at it reads as a curve anyway.
+ */
+export declare function backboneRuns(chain: ProteinChain, colors: string[], splitBySecondary: boolean): BackboneRun[];
+/** The colour a `Color` prop resolves to when a scheme wants a plain string. */
+export declare function hexOf(value: Color): string;
+//# sourceMappingURL=shared.d.ts.map

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

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