@codincod/ornament 0.0.0-stage → 0.1.0

package/src/fish_shape.ts

@@ -0,0 +1,410 @@
+/**
+ * What a fish is made of, once, for the two things that draw one.
+ *
+ * On the site, `water.ts` paints onto a canvas and `glass.ts` sets an SVG path, and both
+ * have to be drawing the same animal or the homepage and the porthole hold two
+ * different species. What they share is one `d` string per beat of the tail.
+ *
+ * ## Why the body is generated and not a path
+ *
+ * A rigid body with a hinged tail is what this used to be, and it does not read
+ * as swimming. A fish does not tow its tail about behind it: the whole animal
+ * is the engine. A wave of curvature runs head to tail down the body, growing
+ * as it goes, and the tail is only where the wave finally arrives. That is
+ * carangiform swimming, which is most of the fish anybody has watched.
+ *
+ * So the outline here is built each beat from a spine that carries that wave.
+ * The envelope is Lighthill's: nearly still a quarter of the way back from the
+ * nose, which is the node every swimming fish has, a little sway at the head
+ * because the water pushes back, and the whole excursion at the peduncle. The
+ * fins are hung on the spine at the station they grow from and lean with it, so
+ * the dorsal tips as the back curves under it and the tail sweeps because the
+ * body it is joined to has swept, not because anything rotated it.
+ *
+ * ## How far it sweeps is half of a pair
+ *
+ * `SWEEP` here and `STRIDE` in `shoal.ts` are one decision written in two
+ * files, and neither is worth changing without the other. Between them they set
+ * how much water the animal beats for how far it gets, which is the one thing
+ * an onlooker judges swimming by: a fish whose tail works harder than its
+ * travel accounts for does not read as trying, it reads as stuck. The pair is
+ * checked in `fish_shape.test.ts`.
+ *
+ * ## Why the animal is one colour
+ *
+ * It was drawn in layers once, a back over a body with a gill and a pectoral,
+ * to give it a lit side. At the size these are drawn it reads as smudge. One
+ * silhouette with the eye punched out of it is the older drawing and the better
+ * one, and it is what the porthole's hand-placed fish always were.
+ *
+ * Everything is nose-right in the 200-unit space the porthole's scenes use,
+ * with the tail joint at the origin, so a body length in that space is `SPAN`.
+ */
+
+/** Nose to tail, which is what a caller's body length buys. */
+export const SPAN = 38
+
+/** How far forward of the joint the nose sits; the spine's whole length. */
+const NOSE = 29
+
+/**
+ * The silhouette, as the cubic that used to be the whole fish.
+ *
+ * Sampling the old curve rather than inventing a profile keeps the animal the
+ * one the windows have always held. Its half-height works out to `24t(1-t)`,
+ * which peaks at 6 a little forward of the middle.
+ */
+const along = (t: number): number => 21 * t * (1 - t) ** 2 + 63 * t ** 2 * (1 - t) + 29 * t ** 3
+
+/**
+ * Half the body's depth at `t`, plus a peduncle.
+ *
+ * The old curve closed to a point where the tail joins, which is fine on a
+ * drawing that never moves and wrong on one that does: at the top of a stroke
+ * the fin is hinged on nothing and reads as having come off. Real fish have a
+ * narrow wrist there and so does this one now.
+ */
+const half = (t: number): number => 24 * t * (1 - t) + WRIST * (1 - t)
+
+/** How deep that wrist is, half of it, in body units. */
+const WRIST = 1.4
+
+/** How many stations the outline is built from, along each side. */
+const STATIONS = 20
+
+/**
+ * How far the tail's tip sweeps, peak to peak, as a share of the body.
+ *
+ * A fifth of its own length, which is what fast swimmers hold to whatever they
+ * are doing: measured across species, tail amplitude stays near a fifth of the
+ * body and it is the beat that changes with the speed. It is the number
+ * `shoal.ts` pairs its stride with, and the two together are what put this
+ * animal in the Strouhal band real ones swim in.
+ *
+ * ## What was wrong with setting the peduncle instead
+ *
+ * This used to be a tenth of the body each way, given to the peduncle, on the
+ * argument that a tenth of a body length is what a fish of this build does.
+ * That amplitude at the peduncle is right. The trouble is that the caudal fin
+ * hangs off the end of it: the fin travels with the joint and swings with it as well, and the joint's
+ * own slope reaches thirty-odd degrees at the top of a stroke, so the tip went
+ * two and a half times as far as the joint did. Measured, it swept 0.72 of a
+ * body peak to peak.
+ *
+ * A fish sweeping three and a half times what a fish sweeps does not read as
+ * swimming hard, because nothing about how far it travels agrees with it. It
+ * reads as a shape flapping in place, and that was the whole of what was wrong
+ * with this ornament. So the number set here is the one anybody watching can
+ * see, and the peduncle's swing is solved from it.
+ */
+export const SWEEP = 0.2
+
+/** How much of a wave fits on the body at once. */
+const WAVES = 0.85
+
+const TWIST = 2 * Math.PI * WAVES
+
+/**
+ * The share of the tail's swing each station gets, from the nose back.
+ *
+ * Lighthill's envelope, normalised so the peduncle gets all of it. It is a
+ * parabola with its floor a quarter of the way back, which is the node: pick a
+ * point on a swimming fish that stays put and that is where it is.
+ */
+const envelope = (u: number): number => 0.2 - 0.8 * u + 1.6 * u * u
+
+/** The wave the body carries, before any swing is given to it. */
+const wave = (u: number, phase: number): number => envelope(u) * Math.sin(TWIST * u - phase)
+
+/** How far either side of a station its own slope is read. */
+const SLOPE = 0.6
+
+/** The caudal fin: how far back it reaches, how wide it forks, and its notch. */
+const FLUKE_BACK = -9
+
+const FLUKE_SPREAD = 7
+
+const FLUKE_NOTCH = -7
+
+/** How many points of a beat the sweep is measured at. */
+const SAMPLES = 90
+
+/**
+ * How far the tail's tip travels across a beat, for a given swing at the joint.
+ *
+ * The tip is not on the spine, so this is the only honest way to ask: it rides
+ * the joint and turns with it, and the two do not peak together. Everything
+ * else here is linear in `amp`, but the joint's angle is an arctangent of it,
+ * so the answer is not a multiple of anything and has to be measured.
+ */
+function reach(amp: number): number {
+  let low = Number.POSITIVE_INFINITY
+  let high = Number.NEGATIVE_INFINITY
+
+  for (let at = 0; at < SAMPLES; at++) {
+    const phase = (at / SAMPLES) * 2 * Math.PI
+    const sway = (x: number): number => amp * wave(1 - x / NOSE, phase)
+    const angle = Math.atan2(sway(SLOPE) - sway(-SLOPE), 2 * SLOPE)
+    const tip = sway(0) + FLUKE_BACK * Math.sin(angle)
+
+    low = Math.min(low, tip)
+    high = Math.max(high, tip)
+  }
+
+  return high - low
+}
+
+/**
+ * The swing at the peduncle whose tip sweeps `SWEEP`, walked on to.
+ *
+ * A handful of passes rather than a solve, because `reach` is nearly a straight
+ * multiple over the range that matters and each pass takes what is left of the
+ * error out.
+ */
+function fitted(): number {
+  let amp = SWEEP * SPAN
+
+  for (let pass = 0; pass < 8; pass++) amp *= (SWEEP * SPAN) / reach(amp)
+
+  return amp
+}
+
+/** How far the peduncle swings each way, in body units; see `SWEEP`. */
+const AMP = fitted()
+
+/** Where the spine is at one station, and which way it is heading there. */
+interface Station {
+  angle: number
+  x: number
+  y: number
+}
+
+function spine(x: number, phase: number): number {
+  return AMP * wave(1 - x / NOSE, phase)
+}
+
+/** The spine at `x`, with the angle read off its own slope either side. */
+function station(x: number, phase: number): Station {
+  const back = spine(x - SLOPE, phase)
+  const front = spine(x + SLOPE, phase)
+
+  return { angle: Math.atan2(front - back, 2 * SLOPE), x, y: spine(x, phase) }
+}
+
+/** A point `lift` clear of the spine at `x`, square to the way the spine runs. */
+const clear = (on: Station, lift: number): [number, number] => [
+  on.x + Math.sin(on.angle) * lift,
+  on.y - Math.cos(on.angle) * lift,
+]
+
+/** The same, for a caller that has only the station it wants. */
+const above = (x: number, lift: number, phase: number): [number, number] =>
+  clear(station(x, phase), lift)
+
+const fixed = (value: number): string => value.toFixed(2)
+
+/**
+ * A closed outline through its own points, rounded.
+ *
+ * Corners land on the midpoints and the points themselves become the controls,
+ * which is the cheapest smoothing there is and the right one here: the nose and
+ * the peduncle are meant to be round, and twenty stations of a straight-edged
+ * fish would show every one of them.
+ */
+function rounded(points: readonly [number, number][]): string {
+  const mid = (a: [number, number], b: [number, number]): string =>
+    `${fixed((a[0] + b[0]) / 2)} ${fixed((a[1] + b[1]) / 2)}`
+
+  const last = points[points.length - 1]!
+  let d = `M${mid(last, points[0]!)}`
+
+  for (let at = 0; at < points.length; at++) {
+    const here = points[at]!
+    const next = points[(at + 1) % points.length]!
+    d += `Q${fixed(here[0])} ${fixed(here[1])} ${mid(here, next)}`
+  }
+
+  return `${d}Z`
+}
+
+/** A straight-sided fin, as its own subpath, wound the way the body is. */
+const fin = (points: readonly [number, number][]): string =>
+  `M${points.map(([x, y]) => `${fixed(x)} ${fixed(y)}`).join("L")}Z`
+
+/**
+ * The dorsal, standing on the back wherever the back is.
+ *
+ * Its stations are given along the body's own curve and its base is set below
+ * the local edge, so it cannot climb off a body that has just bent away from
+ * under it. That was the whole of its old trouble: fixed at a height the body
+ * only has in the middle.
+ */
+function dorsal(phase: number): string {
+  const foot = (t: number, over: number): [number, number] => {
+    const x = along(t)
+    return clear(station(x, phase), half(t) + over)
+  }
+
+  return fin([foot(0.38, -SET), foot(0.52, TIP), foot(0.66, -SET)])
+}
+
+/** How far under the body's edge the dorsal is planted, and how far over it. */
+const SET = 0.8
+
+const TIP = 5
+
+/** The body, both sides of it, off one spine. */
+function outline(phase: number): [number, number][] {
+  const top: [number, number][] = []
+  const bottom: [number, number][] = []
+
+  for (let at = 0; at <= STATIONS; at++) {
+    const t = at / STATIONS
+    const x = along(t)
+    const on = station(x, phase)
+    const lift = half(t)
+
+    top.push(clear(on, lift))
+    bottom.push(clear(on, -lift))
+  }
+
+  return [...top, ...bottom.reverse()]
+}
+
+/** How far inside the body the tail's root is buried, so the join never opens. */
+const ROOT = 2.5
+
+/**
+ * The tail, hung off the end of the spine.
+ *
+ * Its points are the old fin's, carried along whatever the peduncle is doing.
+ * Nothing rotates it: the joint has swung, so the fin has swung. They are wound
+ * the way the body is wound, because every part of the animal is one filled
+ * path and a part running the other way would punch a hole in the one under it.
+ */
+function tail(phase: number): string {
+  const joint = station(0, phase)
+  const cos = Math.cos(joint.angle)
+  const sin = Math.sin(joint.angle)
+
+  const carry = ([x, y]: [number, number]): [number, number] => [
+    joint.x + x * cos - y * sin,
+    joint.y + x * sin + y * cos,
+  ]
+
+  return fin([
+    carry([ROOT, 0]),
+    carry([FLUKE_BACK, FLUKE_SPREAD]),
+    carry([FLUKE_NOTCH, 0]),
+    carry([FLUKE_BACK, -FLUKE_SPREAD]),
+  ])
+}
+
+/** One drawing of the animal: every part of it, and where to punch the eye. */
+export interface Frame {
+  /** Which of `STEPS` this is, so a caller can cache what it built from it. */
+  readonly at: number
+  /**
+   * The same animal with a bill on the nose, for the kinds that have one.
+   *
+   * A whole second drawing rather than a bill to lay over the first. The bill's
+   * root is buried in the head, and an ornament is painted at a weight rather
+   * than solid, so two fills paint that overlap twice: the swordfish wore a
+   * bright wedge from its nose to its eye, which is the seam a reader notices
+   * before anything else in the water. One path filled once has no overlap to
+   * expose.
+   *
+   * What it costs is a string per step of the beat, which the cache pays once.
+   * The renderer picks by species, since that is the only place that knows.
+   */
+  readonly billed: string
+  readonly d: string
+  readonly eye: { readonly r: number; readonly x: number; readonly y: number }
+}
+
+/**
+ * How many drawings one beat is cut into.
+ *
+ * They are shared by every fish on the page and built once each, because a
+ * shoal of ten at sixty frames a second is otherwise six hundred outlines a
+ * second and all of them the same handful of shapes.
+ */
+export const STEPS = 48
+
+const drawn: (Frame | undefined)[] = new Array(STEPS)
+
+const EYE_R = 1.5
+
+const EYE_X = 22
+
+const EYE_LIFT = 2
+
+function build(at: number): Frame {
+  const phase = (at / STEPS) * 2 * Math.PI
+  const [x, y] = above(EYE_X, EYE_LIFT, phase)
+  const d = rounded(outline(phase)) + tail(phase) + dorsal(phase)
+
+  return {
+    at,
+    billed: d + bill(phase),
+    d,
+    eye: { r: EYE_R, x, y },
+  }
+}
+
+/**
+ * A bill, carried rigidly off the nose.
+ *
+ * Carried and not bent, the way the tail is carried off the joint. A swordfish's
+ * bill is skull: it goes where the head goes and it does not flex, so what it
+ * does over a beat is swing bodily with the front of the animal. Extending the
+ * spine's own wave past the nose would have it whipping, which is the one thing
+ * it must not do.
+ *
+ * It is rooted inside the head rather than butted against it, and wound the way
+ * the body is wound, for the same reason every other part is: they are all one
+ * filled path and a part running the other way punches a hole in what is under
+ * it. A butted bill would want the join to be exact at every step of the beat,
+ * and the one step where it was not would show as a gap in the animal's face.
+ */
+function bill(phase: number): string {
+  const nose = station(NOSE, phase)
+  const cos = Math.cos(nose.angle)
+  const sin = Math.sin(nose.angle)
+
+  const carry = ([x, y]: [number, number]): [number, number] => [
+    nose.x + x * cos - y * sin,
+    nose.y + x * sin + y * cos,
+  ]
+
+  return fin([
+    carry([-BILL_ROOT, -BILL_GIRTH]),
+    carry([BILL_REACH, 0]),
+    carry([-BILL_ROOT, BILL_GIRTH]),
+  ])
+}
+
+/**
+ * How far the bill reaches past the nose, how deep it is at the head, and how
+ * far back into the head it is buried, all in body units.
+ *
+ * Long. A bill is about a third of a swordfish and the whole silhouette turns
+ * on it: shorten it to something tasteful and what comes out is a fish with a
+ * pointed face. `SPAN` is 38, so this is not far off the real proportion.
+ */
+const BILL_REACH = 15
+
+const BILL_GIRTH = 1.1
+
+const BILL_ROOT = 3
+
+/** The drawing for a beat, to the nearest step, built once and kept. */
+export function frameAt(phase: number): Frame {
+  const at = ((Math.round((phase / (2 * Math.PI)) * STEPS) % STEPS) + STEPS) % STEPS
+  const had = drawn[at]
+  if (had) return had
+
+  const made = build(at)
+  drawn[at] = made
+  return made
+}