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

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./protein";
+export { NODES } from "./nodes";

package/src/nodes.ts

@@ -0,0 +1,18 @@
+import { Protein } from "./protein";
+
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each class's `@node()`
+ * key. The decorator only *declares* that key: nothing is registered by the mere
+ * act of importing a module, so a registry holds exactly what its owner asked
+ * for and two engines in one process can differ about it.
+ *
+ * Listing class **values** is also what survives bundling. This package declares
+ * `sideEffects: false`, which licenses a bundler to drop a module nothing
+ * imports a value from, and a document names a node type by string — so
+ * `import "./protein"` for its side effect is exactly what gets shaken out, where an
+ * array of bindings is a data dependency that cannot be.
+ */
+export const NODES = [Protein];

package/src/protein/chemistry.ts

@@ -0,0 +1,223 @@
+/**
+ * The chemistry the {@link Protein} node draws from: how big an atom is, what
+ * colour it conventionally takes, what counts as a bond, and which residues are
+ * part of a polymer chain rather than sitting beside it.
+ *
+ * Tables rather than a dependency, for the same reason `graph3d/expression.ts`
+ * is a parser rather than a maths library: this package has to stay loadable in
+ * a bare Node process with no DOM, and what a molecular-graphics library would
+ * bring with it — a renderer, a fetch layer, a DOM — is everything the scene
+ * builder was split apart to avoid.
+ *
+ * The numbers are the standard ones. Van der Waals radii are Bondi's, covalent
+ * radii are Cordero's, and the colours are the CPK scheme every molecular viewer
+ * has used since Corey and Pauling built theirs out of painted wood — which is
+ * the point of using them: a biologist reads oxygen as red before they have
+ * read the legend.
+ */
+
+/** Ångströms. What an atom's electron cloud actually occupies. */
+const VAN_DER_WAALS: Readonly<Record<string, number>> = {
+  H: 1.1,
+  C: 1.7,
+  N: 1.55,
+  O: 1.52,
+  F: 1.47,
+  NA: 2.27,
+  MG: 1.73,
+  P: 1.8,
+  S: 1.8,
+  CL: 1.75,
+  K: 2.75,
+  CA: 2.31,
+  MN: 2.05,
+  FE: 2.04,
+  CO: 2.0,
+  NI: 1.97,
+  CU: 1.96,
+  ZN: 2.01,
+  SE: 1.9,
+  BR: 1.85,
+  I: 1.98,
+}
+
+/** The fallback radius, carbon's — the element most of a protein is made of. */
+const DEFAULT_VAN_DER_WAALS = 1.7
+
+/** Ångströms. Half of how far two of these sit apart when bonded. */
+const COVALENT: Readonly<Record<string, number>> = {
+  H: 0.31,
+  C: 0.76,
+  N: 0.71,
+  O: 0.66,
+  F: 0.57,
+  NA: 1.66,
+  MG: 1.41,
+  P: 1.07,
+  S: 1.05,
+  CL: 1.02,
+  K: 2.03,
+  CA: 1.76,
+  MN: 1.39,
+  FE: 1.32,
+  CO: 1.26,
+  NI: 1.24,
+  CU: 1.32,
+  ZN: 1.22,
+  SE: 1.2,
+  BR: 1.2,
+  I: 1.39,
+}
+
+const DEFAULT_COVALENT = 0.77
+
+/**
+ * The CPK colours, as Jmol renders them.
+ *
+ * Only the elements a biological structure actually contains, plus the metals
+ * that turn up in cofactors. Anything else takes {@link UNKNOWN_ELEMENT_COLOR},
+ * which is deliberately garish — an unrecognised element should look like a
+ * question rather than blend into the carbons.
+ */
+const CPK: Readonly<Record<string, string>> = {
+  H: "#ffffff",
+  C: "#909090",
+  N: "#3050f8",
+  O: "#ff0d0d",
+  F: "#90e050",
+  NA: "#ab5cf2",
+  MG: "#8aff00",
+  P: "#ff8000",
+  S: "#ffff30",
+  CL: "#1ff01f",
+  K: "#8f40d4",
+  CA: "#3dff00",
+  MN: "#9c7ac7",
+  FE: "#e06633",
+  CO: "#f090a0",
+  NI: "#50d050",
+  CU: "#c88033",
+  ZN: "#7d80b0",
+  SE: "#ffa100",
+  BR: "#a62929",
+  I: "#940094",
+}
+
+/** What an element nobody has a colour for is drawn in. */
+export const UNKNOWN_ELEMENT_COLOR = "#ff1493"
+
+/** An element's van der Waals radius in Ångströms. */
+export function vanDerWaalsRadius(element: string): number {
+  return VAN_DER_WAALS[element] ?? DEFAULT_VAN_DER_WAALS
+}
+
+/** An element's covalent radius in Ångströms — half of a bond it makes. */
+export function covalentRadius(element: string): number {
+  return COVALENT[element] ?? DEFAULT_COVALENT
+}
+
+/** The CPK colour for an element, as a `#rrggbb` string. */
+export function elementColor(element: string): string {
+  return CPK[element] ?? UNKNOWN_ELEMENT_COLOR
+}
+
+/**
+ * The standard amino acids, plus the two modified residues common enough that
+ * treating them as foreign would put a hole in the middle of a chain:
+ * selenomethionine (`MSE`, how a crystallographer phases a new structure) and
+ * pyroglutamate (`PCA`).
+ *
+ * Both arrive as `HETATM` records, which is exactly why the set is consulted
+ * rather than the record type — "is this part of the chain" is a question about
+ * the residue, and the file answers a different one.
+ */
+const AMINO_ACIDS = new Set([
+  "ALA", "ARG", "ASN", "ASP", "CYS", "GLN", "GLU", "GLY", "HIS", "ILE",
+  "LEU", "LYS", "MET", "PHE", "PRO", "SER", "THR", "TRP", "TYR", "VAL",
+  "MSE", "PCA", "SEC", "PYL",
+])
+
+/** The nucleotides, RNA and DNA. */
+const NUCLEOTIDES = new Set([
+  "A", "C", "G", "U", "I",
+  "DA", "DC", "DG", "DT", "DI",
+])
+
+/**
+ * The waters. Named separately from the rest of the hetero atoms because they
+ * are the one kind a viewer hides by default: a crystal structure carries
+ * hundreds of them, they are chemically uninteresting to the picture being
+ * drawn, and left on they bury the molecule in red dots.
+ */
+const WATERS = new Set(["HOH", "DOD", "WAT", "H2O", "TIP"])
+
+/** What a residue is, which decides whether it joins a backbone trace. */
+export type ResidueKind = "amino" | "nucleic" | "water" | "other"
+
+/** Classifies a residue by its three-letter code. */
+export function residueKind(name: string): ResidueKind {
+  const code = name.trim().toUpperCase()
+  if (AMINO_ACIDS.has(code)) return "amino"
+  if (NUCLEOTIDES.has(code)) return "nucleic"
+  if (WATERS.has(code)) return "water"
+  return "other"
+}
+
+/**
+ * The atom a residue's backbone trace passes through: the α-carbon of an amino
+ * acid, the phosphorus of a nucleotide.
+ *
+ * One atom per residue rather than the whole backbone, because what the trace is
+ * *for* is the smooth curve a ribbon is swept along, and the N–CA–C zig-zag
+ * would put a kink at every residue. Every molecular viewer traces α-carbons for
+ * the same reason.
+ */
+export function traceAtomName(kind: ResidueKind): string | null {
+  if (kind === "amino") return "CA"
+  if (kind === "nucleic") return "P"
+  return null
+}
+
+/**
+ * The element an atom belongs to, from the file's element column when it has
+ * one and from the atom's *name* when it doesn't.
+ *
+ * The fallback matters more than it looks: the element column is right-justified
+ * in columns 77–78 of a PDB record and plenty of older files, and most files
+ * written by hand, simply stop before it. The name is then all there is, and
+ * reading it is not quite trimming the digits off — an amino acid's `CA` is a
+ * carbon and an ion's `CA` is calcium, and the two are told apart only by what
+ * residue they sit in. Hence {@link kind}.
+ */
+export function elementOf(
+  declared: string,
+  atomName: string,
+  kind: ResidueKind
+): string {
+  const stated = declared.trim().toUpperCase()
+  if (stated !== "") return stated
+
+  // PDB atom names are padded so that the element starts in column 14 for a
+  // two-letter element and column 15 for a one-letter one — but only in files
+  // that respect the alignment, which is why this reads the characters instead:
+  // strip the leading digit an alternate hydrogen carries (`1HB`), then take the
+  // letters.
+  const name = atomName.trim().toUpperCase().replace(/^\d+/, "")
+  const letters = name.replace(/[^A-Z]/g, "")
+  if (letters === "") return ""
+
+  // Inside a polymer residue the only two-letter elements are the ones that
+  // can't be confused: everything else is C, N, O, S or P followed by the
+  // position letters that name the atom (`CB`, `NZ`, `OG1`). A `CA` there is the
+  // α-carbon, never calcium.
+  if (kind === "amino" || kind === "nucleic") {
+    if (letters.startsWith("SE")) return "SE"
+    return letters.slice(0, 1)
+  }
+
+  // Outside one — a ligand, an ion, a cofactor — a two-letter element is real,
+  // so prefer the longest match the tables know before falling back to one.
+  const pair = letters.slice(0, 2)
+  if (pair in COVALENT) return pair
+  return letters.slice(0, 1)
+}

package/src/protein/index.ts

@@ -0,0 +1,34 @@
+/**
+ * The Protein node — a **native** node type (see `node-types.ts` /
+ * `NODE_CLASS_BY_KEY`) like the chart family and the 3D graph beside it: built,
+ * themed and animated from the inspector rather than loaded as a code package.
+ *
+ * It draws a molecular structure — a protein, a nucleic acid, a complex of both
+ * with whatever is bound to them — in one of four representations, from a
+ * coordinate file the Protein Data Bank publishes.
+ *
+ * Three things about it are worth knowing before reading the parts:
+ *
+ * **The file is parsed outside the render.** `buildScene` is synchronous and a
+ * coordinate file arrives over a network, so the fetch and the parse happen
+ * ahead of the build and what reaches the node is a finished
+ * {@link ProteinStructure} — the same arrangement a chart has with its rows.
+ * That is why `parse.ts` is exported: the app's structure store is its caller,
+ * not this node.
+ *
+ * **The chemistry is a table, not a dependency.** Radii, colours and what counts
+ * as a bond live in `chemistry.ts` for the same reason `graph3d/expression.ts`
+ * is a parser rather than a maths library: this package has to stay loadable in
+ * a bare Node process, and a molecular-graphics library brings a renderer, a
+ * fetch layer and a DOM with it.
+ *
+ * **There is no pointer.** The camera is three tweenable numbers rather than a
+ * drag, because the studio renders a timeline and every frame has to be
+ * reproducible under scrubbing and export. See {@link Protein}.
+ */
+export * from "./chemistry";
+export * from "./parse";
+export * from "./protein";
+export * from "./ribbon";
+export * from "./shared";
+export * from "./structure";