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

package/src/protein/shared.ts

@@ -0,0 +1,622 @@
+/**
+ * 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,
+  Quaternion,
+  Transform3D,
+  Vector3,
+} from "@motionscript/core"
+
+import { elementColor, vanDerWaalsRadius } from "./chemistry"
+import type {
+  ProteinAtom,
+  ProteinChain,
+  ProteinStructure,
+  SecondaryStructure,
+} from "./structure"
+
+/**
+ * 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 const PROTEIN_REPRESENTATIONS = [
+  "ribbon",
+  "backbone",
+  "ballAndStick",
+  "spacefill",
+] as const
+
+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 const PROTEIN_COLOR_SCHEMES = [
+  /** Helix / sheet / coil. Fold. */
+  "secondary",
+  /** CPK — oxygen red, nitrogen blue, carbon grey. Chemistry. */
+  "element",
+  /** One hue per chain. Which subunit is which, in a complex. */
+  "chain",
+  /** A spectrum from each chain's N terminus to its C terminus. Direction. */
+  "residue",
+  /** One colour throughout, whatever the node's own `color` is. */
+  "uniform",
+] as const
+
+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 const CHAIN_COLORS = [
+  "#4f9dff",
+  "#ff8a3d",
+  "#4ddb9a",
+  "#e05fd0",
+  "#ffd166",
+  "#8b7bff",
+  "#ff6b6b",
+  "#3fd0d6",
+] as const
+
+/**
+ * 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 const SECONDARY_COLORS: Readonly<Record<SecondaryStructure, string>> = {
+  helix: "#f0605d",
+  sheet: "#f5c451",
+  coil: "#c8ccd4",
+}
+
+/** Where the residue spectrum starts and ends, as hues in degrees. */
+const SPECTRUM_START = 250
+const SPECTRUM_END = 0
+
+/** The saturation and lightness the residue spectrum is swept at. */
+const SPECTRUM_SATURATION = 0.72
+const SPECTRUM_LIGHTNESS = 0.58
+
+/**
+ * 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 const DEFAULT_PROTEIN_PALETTE: ProteinPalette = {
+  helix: SECONDARY_COLORS.helix,
+  sheet: SECONDARY_COLORS.sheet,
+  coil: SECONDARY_COLORS.coil,
+  chains: CHAIN_COLORS,
+  residueStart: hslHex(SPECTRUM_START, SPECTRUM_SATURATION, SPECTRUM_LIGHTNESS),
+  residueEnd: hslHex(SPECTRUM_END, SPECTRUM_SATURATION, SPECTRUM_LIGHTNESS),
+}
+
+/**
+ * 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 const CHAIN_COLOR_COUNT = CHAIN_COLORS.length
+
+/**
+ * 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 const PROTEIN_PALETTE_FIELDS = [
+  "helixColor",
+  "sheetColor",
+  "coilColor",
+  "residueStartColor",
+  "residueEndColor",
+  ...CHAIN_COLORS.map((_, index) => `chainColor${index + 1}` as const),
+] as const
+
+/** The default each {@link PROTEIN_PALETTE_FIELDS} entry carries, by name. */
+export const PROTEIN_PALETTE_DEFAULTS: Readonly<Record<string, string>> = {
+  helixColor: DEFAULT_PROTEIN_PALETTE.helix,
+  sheetColor: DEFAULT_PROTEIN_PALETTE.sheet,
+  coilColor: DEFAULT_PROTEIN_PALETTE.coil,
+  residueStartColor: DEFAULT_PROTEIN_PALETTE.residueStart,
+  residueEndColor: DEFAULT_PROTEIN_PALETTE.residueEnd,
+  ...Object.fromEntries(
+    DEFAULT_PROTEIN_PALETTE.chains.map((colour, index) => [
+      `chainColor${index + 1}`,
+      colour,
+    ])
+  ),
+}
+
+/**
+ * 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 function lerpHexColor(from: string, to: string, t: number): string {
+  const a = hexRgb(from)
+  const b = hexRgb(to)
+  if (!a || !b) return t < 1 ? from : to
+  const byte = (x: number, y: number): string =>
+    Math.round(x + (y - x) * t)
+      .toString(16)
+      .padStart(2, "0")
+  return `#${byte(a[0], b[0])}${byte(a[1], b[1])}${byte(a[2], b[2])}`
+}
+
+/** A `#rrggbb` string as three 0–255 channels, or `null` if it isn't one. */
+function hexRgb(value: string): [number, number, number] | null {
+  const hex = /^#?([0-9a-f]{6})$/i.exec(value.trim())
+  if (!hex) return null
+  const int = parseInt(hex[1]!, 16)
+  return [(int >> 16) & 255, (int >> 8) & 255, int & 255]
+}
+
+/**
+ * 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 function atomColors(
+  structure: ProteinStructure,
+  scheme: ProteinColorScheme,
+  uniform: string,
+  palette: ProteinPalette = DEFAULT_PROTEIN_PALETTE
+): string[] {
+  if (scheme === "uniform") return structure.atoms.map(() => uniform)
+  if (scheme === "element") {
+    return structure.atoms.map((atom) => elementColor(atom.element))
+  }
+
+  const chains = chainOrder(structure)
+  if (scheme === "chain") {
+    return structure.atoms.map((atom) =>
+      chainColor(chains, atom.chain, palette)
+    )
+  }
+
+  if (scheme === "secondary") {
+    const lookup = secondaryByResidue(structure)
+    return structure.atoms.map(
+      (atom) => palette[lookup.get(residueKey(atom)) ?? "coil"]
+    )
+  }
+
+  // `residue` — a spectrum along each chain, so position is read against the
+  // chain the residue is in rather than against the whole file. Without that, a
+  // short chain beside a long one would be drawn in a single colour.
+  const positions = residuePositions(structure)
+  return structure.atoms.map((atom) => {
+    const position = positions.get(residueKey(atom))
+    return position === undefined ? uniform : spectrum(position, palette)
+  })
+}
+
+/**
+ * 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 function traceColors(
+  structure: ProteinStructure,
+  chain: ProteinChain,
+  scheme: ProteinColorScheme,
+  uniform: string,
+  palette: ProteinPalette = DEFAULT_PROTEIN_PALETTE
+): string[] {
+  if (scheme === "uniform") return chain.trace.map(() => uniform)
+  if (scheme === "secondary") {
+    return chain.trace.map((point) => palette[point.secondary])
+  }
+  if (scheme === "residue") {
+    const last = Math.max(1, chain.trace.length - 1)
+    return chain.trace.map((point) => spectrum(point.index / last, palette))
+  }
+
+  const chains = chainOrder(structure)
+  const colour = chainColor(chains, chain.id, palette)
+  return chain.trace.map(() => colour)
+}
+
+/**
+ * A colour on the N→C spectrum, `0` at the start of a chain and `1` at its end.
+ *
+ * Interpolated in **HSL**, which is what makes the default a spectrum at all: a
+ * straight RGB blend between the two ends passes through grey, where a hue sweep
+ * runs the ramp everybody recognises. And along the *direct numeric path*
+ * between the two hues rather than the shorter way round the wheel — 250° to 0°
+ * is the familiar blue-through-green-to-red run, and taking the short arc would
+ * hop through magenta instead and cover a quarter of the colours.
+ */
+function spectrum(position: number, palette: ProteinPalette): string {
+  const from = hexHsl(palette.residueStart)
+  const to = hexHsl(palette.residueEnd)
+  const t = clamp01(position)
+  return hslHex(
+    from.h + (to.h - from.h) * t,
+    from.s + (to.s - from.s) * t,
+    from.l + (to.l - from.l) * t
+  )
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value))
+}
+
+/**
+ * HSL to a `#rrggbb` string.
+ *
+ * Written out rather than reached for, because the spectrum is the one place
+ * this package generates a colour instead of being handed one, and every other
+ * colour path here takes hex.
+ */
+function hslHex(hue: number, saturation: number, lightness: number): string {
+  const h = ((hue % 360) + 360) % 360
+  const c = (1 - Math.abs(2 * lightness - 1)) * saturation
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = lightness - c / 2
+
+  const [r, g, b] =
+    h < 60
+      ? [c, x, 0]
+      : h < 120
+        ? [x, c, 0]
+        : h < 180
+          ? [0, c, x]
+          : h < 240
+            ? [0, x, c]
+            : h < 300
+              ? [x, 0, c]
+              : [c, 0, x]
+
+  const byte = (value: number): string =>
+    Math.round((value + m) * 255)
+      .toString(16)
+      .padStart(2, "0")
+  return `#${byte(r!)}${byte(g!)}${byte(b!)}`
+}
+
+/**
+ * A `#rrggbb` string back to HSL — the inverse of {@link hslHex}, and here for
+ * the one caller that needs it: the residue ramp is authored as two colours and
+ * swept as a hue.
+ *
+ * Anything unparseable comes back as the default ramp's own start, so a half
+ * typed hex in the inspector fades toward a colour rather than painting `NaN`
+ * into every residue of the chain.
+ */
+function hexHsl(value: string): { h: number; s: number; l: number } {
+  const hex = /^#?([0-9a-f]{6})$/i.exec(value.trim())
+  if (!hex) return { h: SPECTRUM_START, s: SPECTRUM_SATURATION, l: SPECTRUM_LIGHTNESS }
+
+  const int = parseInt(hex[1]!, 16)
+  const r = ((int >> 16) & 255) / 255
+  const g = ((int >> 8) & 255) / 255
+  const b = (int & 255) / 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  const l = (max + min) / 2
+  const d = max - min
+  if (d === 0) return { h: 0, s: 0, l }
+
+  const s = d / (1 - Math.abs(2 * l - 1))
+  const h =
+    max === r
+      ? 60 * (((g - b) / d) % 6)
+      : max === g
+        ? 60 * ((b - r) / d + 2)
+        : 60 * ((r - g) / d + 4)
+  return { h: (h + 360) % 360, s, l }
+}
+
+/** The chain identifiers in the order they first appear, for palette indexing. */
+function chainOrder(structure: ProteinStructure): Map<string, number> {
+  const order = new Map<string, number>()
+  for (const atom of structure.atoms) {
+    if (!order.has(atom.chain)) order.set(atom.chain, order.size)
+  }
+  return order
+}
+
+/** The palette entry for a chain, wrapping past the end. */
+function chainColor(
+  order: Map<string, number>,
+  chain: string,
+  palette: ProteinPalette
+): string {
+  const colours =
+    palette.chains.length > 0 ? palette.chains : DEFAULT_PROTEIN_PALETTE.chains
+  const index = order.get(chain) ?? 0
+  return colours[index % colours.length]!
+}
+
+/** A residue's identity across the whole structure — its chain and its number. */
+function residueKey(atom: ProteinAtom): string {
+  return `${atom.chain}:${atom.residueSeq}`
+}
+
+/**
+ * Each residue's position along its own chain, `0`–`1`.
+ *
+ * Read off the *traces* rather than counted over the atoms, so it means the same
+ * thing the ribbon means by it — and so a residue the file resolved no backbone
+ * for simply has no position, and takes the fallback colour rather than shifting
+ * every residue after it along the spectrum.
+ */
+function residuePositions(structure: ProteinStructure): Map<string, number> {
+  const positions = new Map<string, number>()
+  for (const chain of structure.chains) {
+    const last = Math.max(1, chain.trace.length - 1)
+    for (const point of chain.trace) {
+      positions.set(`${chain.id}:${point.residueSeq}`, point.index / last)
+    }
+  }
+  return positions
+}
+
+/** Each residue's secondary structure, keyed as {@link residueKey} does. */
+function secondaryByResidue(
+  structure: ProteinStructure
+): Map<string, SecondaryStructure> {
+  const lookup = new Map<string, SecondaryStructure>()
+  for (const chain of structure.chains) {
+    for (const point of chain.trace) {
+      lookup.set(`${chain.id}:${point.residueSeq}`, point.secondary)
+    }
+  }
+  return lookup
+}
+
+// --- Geometry --------------------------------------------------------------
+
+/** An atom's drawn radius in Ångströms, at a given scale of its true size. */
+export function atomRadius(atom: ProteinAtom, scale: number): number {
+  return vanDerWaalsRadius(atom.element) * scale
+}
+
+/**
+ * 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 function stickPlacement(
+  from: Vector3,
+  to: Vector3,
+  radius: number
+): Transform3D {
+  const dx = to.x - from.x
+  const dy = to.y - from.y
+  const dz = to.z - from.z
+  const length = Math.hypot(dx, dy, dz) || 1
+
+  return {
+    position: [
+      (from.x + to.x) / 2,
+      (from.y + to.y) / 2,
+      (from.z + to.z) / 2,
+    ],
+    scale: [radius, length, radius],
+    quaternion: upTo(dx / length, dy / length, dz / length),
+  }
+}
+
+/**
+ * The shortest rotation taking **+Y** onto a unit direction.
+ *
+ * The general form is "rotate about the axis perpendicular to both, by the angle
+ * between them", which for a fixed source axis collapses to the cross product
+ * with `(0, 1, 0)` — hence the two components rather than three.
+ *
+ * The antiparallel case has to be handled outright: a direction pointing
+ * straight down has a *zero* cross product with up, so the axis is undefined and
+ * the general form produces a quaternion of all zeros, which is not a rotation
+ * at all. Any half-turn about a perpendicular axis is correct there, and X is as
+ * good as any.
+ */
+function upTo(x: number, y: number, z: number): Quaternion {
+  if (y > 0.999999) return { x: 0, y: 0, z: 0, w: 1 }
+  if (y < -0.999999) return { x: 1, y: 0, z: 0, w: 0 }
+
+  // axis = up × d, normalized; angle = acos(up · d) = acos(y).
+  const axisX = z
+  const axisZ = -x
+  const axisLength = Math.hypot(axisX, axisZ) || 1
+  const angle = Math.acos(Math.min(1, Math.max(-1, y)))
+  const sin = Math.sin(angle / 2)
+
+  return {
+    x: (axisX / axisLength) * sin,
+    y: 0,
+    z: (axisZ / axisLength) * sin,
+    w: Math.cos(angle / 2),
+  }
+}
+
+/** 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 function backboneRuns(
+  chain: ProteinChain,
+  colors: string[],
+  splitBySecondary: boolean
+): BackboneRun[] {
+  const runs: BackboneRun[] = []
+
+  for (let index = 0; index < chain.trace.length; index++) {
+    const point = chain.trace[index]!
+    const color = colors[index] ?? colors[0] ?? "#ffffff"
+    let current = runs[runs.length - 1]
+
+    const breaks =
+      !current ||
+      current.color !== color ||
+      (splitBySecondary && current.secondary !== point.secondary)
+
+    if (breaks) {
+      // Carry the previous run's last point in as this one's first, so the two
+      // sweeps butt up against each other.
+      const seed = current ? [current.points[current.points.length - 1]!] : []
+      current = { points: seed, color, secondary: point.secondary }
+      runs.push(current)
+    }
+    current.points.push({ x: point.x, y: point.y, z: point.z })
+  }
+
+  // A run of one point is not a curve — there is no direction to sweep along.
+  // It can only be the very first run when the trace starts with a lone point,
+  // since every later run is seeded with its predecessor's last point.
+  return runs.filter((run) => run.points.length > 1)
+}
+
+/** The colour a `Color` prop resolves to when a scheme wants a plain string. */
+export function hexOf(value: Color): string {
+  return typeof value === "string" ? value : "#ffffff"
+}