@codincod/ornament 0.0.0-stage → 0.2.0

package/src/sizes.ts

@@ -0,0 +1,86 @@
+/**
+ * How big a thing is drawn, given how big it is and how far off it is.
+ *
+ * One statement of scale for the whole scene, because the alternative is what
+ * this water had: every file picking a share of the box's width that looked
+ * right on its own, and a boat coming out the size of a turtle. Nothing catches
+ * that. Each number is defensible where it is written and the picture is still
+ * wrong, because the thing being got wrong lives between the files.
+ *
+ * So each animal and each hull is written down in metres, at a distance in
+ * metres, and this turns the pair into a share of the box's width. A reader who
+ * doubts a size can look the animal up.
+ *
+ * ## Why it is not the angle a thing subtends
+ *
+ * Drawn strictly to the angle, this scene has no picture in it. A reef fish is
+ * a fifth of a metre and a green turtle is well over a metre, so the fish comes
+ * out at a handful of pixels: a speck, and a speck will not hold a drawing. Go
+ * the other way and size the fish to read, and a submarine is wider than the
+ * screen.
+ *
+ * The root is the compression that fixes it. Doubling a real length still draws
+ * bigger, so the order of things is never wrong and a shark never comes out
+ * under a turtle; but the ends are pulled in, so the smallest thing in the
+ * water is still a shape and the largest still fits. It is the same bargain a
+ * map makes with a river's width, and for the same reason: what is being kept
+ * is which is bigger, not by how much.
+ *
+ * ## The distances are the honest part
+ *
+ * A boat is not small. It is far: the surface is a long way up from a seabed,
+ * and a hull crossing it is a shape on the ceiling rather than a thing you are
+ * swimming beside. Writing that down as a distance rather than as a smaller
+ * boat is what keeps the next boat from being wrong again.
+ *
+ * ## Where the animals are written down
+ *
+ * Here is the sum and nothing else. What each thing measures stays beside the
+ * thing, because a table of lengths in one file is a table nobody updates when
+ * an animal changes: `shoal.ts` carries the fish, `visitors.ts` the large ones
+ * crossing, `jellies.ts` the bells, `walkers.ts` the floor, `cephalopods.ts`
+ * the squid and the octopus, `passers.ts` the hulls. Two of them are deliberate
+ * exceptions and say so where they stand. A fish inside a flock is measured
+ * against the flock (`swarm.ts`) and a clownfish against its anemone
+ * (`nemos.ts`), because in both cases the two things are at one distance and
+ * nothing between them wants compressing. Marine snow (`drift.ts`) is a texture
+ * rather than an animal.
+ *
+ * How many of each there are is the other half, and it is `census.ts`.
+ */
+
+/**
+ * How much of the box's width a thing a metre off would take.
+ *
+ * The one number the scene is tuned by. It was fixed by the shark, which is the
+ * animal this water was drawn around: at four and a half metres and eight off,
+ * it comes out where it always was, and everything else moved to meet it.
+ */
+const AT_ARM = 0.15
+
+/**
+ * How far off the things that swim past you are.
+ *
+ * They are in the same water, so they share a distance, and what still tells
+ * them apart is `Visitor.depth`, which is the nearer and further of this.
+ */
+export const SWIMMING_OFF = 8
+
+/**
+ * How far off the floor of the picture is.
+ *
+ * Further than the animals crossing the water, because the bed is under them
+ * and behind them: what a reader is looking at is a stretch of ground that
+ * starts a little beyond arm's reach and goes back until the haze takes it.
+ * Everything that lives down there shares it, which is the point of writing it
+ * once. A crab, a starfish and an octopus at the mouth of a den are the sizes
+ * they are against each other because they are the same distance away, and a
+ * crab that came out smaller than the stones it walks between is a crab that
+ * was given a number of its own.
+ */
+export const BED_OFF = 10
+
+/** A share of the box's width, for something this long and this far away. */
+export function drawnAt(metres: number, off: number): number {
+  return AT_ARM * Math.sqrt(Math.max(metres, 0) / Math.max(off, 0.001))
+}

package/src/sun.ts

@@ -0,0 +1,500 @@
+/**
+ * Where the sun is.
+ *
+ * The ornament draws a window into water, and water at four in the morning is
+ * not water at noon. This works out which of those it is, from the clock and
+ * from where the clock says it is being read, and hands back the two numbers
+ * every renderer needs: how light it is, and how near the light is to a sunset.
+ *
+ * The moon is here too, and it is the real one: where it is tonight, and what
+ * shape the sun has left of it. It rises later each night, is a different
+ * sliver each night, and comes back to the same shape after 29.53 of them.
+ *
+ * It lives in this package rather than beside the site's hook because the desktop
+ * background wants the same sky. `seascape` bundles this package into its
+ * renderer, so a moon that rises on the site at
+ * half past nine rises on the desktop at half past nine, from these lines. That
+ * is the whole reason the two are one piece of code.
+ *
+ * Nothing here asks for a permission and nothing leaves the machine. The
+ * position is estimated: longitude from the time zone's current offset from
+ * UTC, which is 15 degrees an hour and already correct for daylight saving, and
+ * latitude from the zone's own name. That is accurate to a few hundred
+ * kilometres, which moves sunset by minutes. Nobody is navigating by this.
+ *
+ * Daylight saving needs no handling of its own. The altitude is computed from
+ * absolute time, so a clock that jumps an hour changes nothing about where the
+ * sun is; only the offset used for longitude moves, and it moves with the zone.
+ */
+
+const RAD = Math.PI / 180
+
+/**
+ * Days since J2000.0, the epoch every term below is expressed in.
+ */
+const J2000_OFFSET_DAYS = 10957.5
+const DAY_MS = 86_400_000
+
+/**
+ * Earth's axial tilt.
+ */
+const OBLIQUITY = 23.4397 * RAD
+
+/**
+ * Latitude by time-zone region, in degrees, north positive.
+ *
+ * A region is a continent and a continent is not a latitude, so these are the
+ * middle of where people in that region actually live, and they are what a zone
+ * the table below has never heard of falls back to. The error that shows is a
+ * reader put in the wrong hemisphere: it inverts the seasons, and a scene that
+ * is dark at eight in the evening in Buenos Aires in January would be wrong by
+ * hours rather than by minutes.
+ */
+const REGION_LATITUDE: Record<string, number> = {
+  Africa: 5,
+  America: 38,
+  Antarctica: -70,
+  Arctic: 78,
+  Asia: 30,
+  Atlantic: 35,
+  Australia: -30,
+  Europe: 50,
+  Indian: -15,
+  Pacific: -20,
+}
+
+/**
+ * Where a zone's people actually are, north and east positive.
+ *
+ * A zone is named after a city and a city is not its meridian: Brussels keeps
+ * the meridian of Prague, which is ten degrees and forty minutes of moonset. So
+ * the zones most readers are in say where they are, and everything else falls
+ * back to the middle of its region and the middle of its offset.
+ */
+const ZONE_PLACE: Record<string, readonly [number, number]> = {
+  "Africa/Cairo": [30, 31.2],
+  "Africa/Casablanca": [33.6, -7.6],
+  "Africa/Johannesburg": [-26.2, 28],
+  "Africa/Lagos": [6.5, 3.4],
+  "Africa/Nairobi": [-1.3, 36.8],
+  "America/Argentina/Buenos_Aires": [-34.6, -58.4],
+  "America/Bogota": [4.7, -74.1],
+  "America/Chicago": [41.9, -87.6],
+  "America/Denver": [39.7, -105],
+  "America/Halifax": [44.6, -63.6],
+  "America/Lima": [-12, -77],
+  "America/Los_Angeles": [34.1, -118.2],
+  "America/Mexico_City": [19.4, -99.1],
+  "America/New_York": [40.7, -74],
+  "America/Phoenix": [33.4, -112.1],
+  "America/Santiago": [-33.4, -70.7],
+  "America/Sao_Paulo": [-23.5, -46.6],
+  "America/Toronto": [43.7, -79.4],
+  "America/Vancouver": [49.3, -123.1],
+  "Asia/Bangkok": [13.8, 100.5],
+  "Asia/Dubai": [25.2, 55.3],
+  "Asia/Hong_Kong": [22.3, 114.2],
+  "Asia/Jakarta": [-6.2, 106.8],
+  "Asia/Jerusalem": [31.8, 35.2],
+  "Asia/Karachi": [24.9, 67],
+  "Asia/Kolkata": [22.6, 88.4],
+  "Asia/Manila": [14.6, 121],
+  "Asia/Seoul": [37.6, 127],
+  "Asia/Shanghai": [31.2, 121.5],
+  "Asia/Singapore": [1.3, 103.8],
+  "Asia/Taipei": [25, 121.5],
+  "Asia/Tehran": [35.7, 51.4],
+  "Asia/Tokyo": [35.7, 139.7],
+  "Atlantic/Reykjavik": [64.1, -21.9],
+  "Australia/Brisbane": [-27.5, 153],
+  "Australia/Melbourne": [-37.8, 145],
+  "Australia/Perth": [-31.9, 115.9],
+  "Australia/Sydney": [-33.9, 151.2],
+  "Europe/Amsterdam": [52.4, 4.9],
+  "Europe/Athens": [38, 23.7],
+  "Europe/Berlin": [52.5, 13.4],
+  "Europe/Brussels": [50.8, 4.4],
+  "Europe/Bucharest": [44.4, 26.1],
+  "Europe/Dublin": [53.3, -6.3],
+  "Europe/Helsinki": [60.2, 24.9],
+  "Europe/Istanbul": [41, 29],
+  "Europe/Kyiv": [50.5, 30.5],
+  "Europe/Lisbon": [38.7, -9.1],
+  "Europe/London": [51.5, -0.1],
+  "Europe/Madrid": [40.4, -3.7],
+  "Europe/Moscow": [55.8, 37.6],
+  "Europe/Oslo": [59.9, 10.8],
+  "Europe/Paris": [48.9, 2.4],
+  "Europe/Prague": [50.1, 14.4],
+  "Europe/Rome": [41.9, 12.5],
+  "Europe/Stockholm": [59.3, 18.1],
+  "Europe/Vienna": [48.2, 16.4],
+  "Europe/Warsaw": [52.2, 21],
+  "Europe/Zurich": [47.4, 8.5],
+  "Pacific/Auckland": [-36.9, 174.8],
+  "Pacific/Fiji": [-18.1, 178.4],
+  "Pacific/Honolulu": [21.3, -157.9],
+}
+
+export interface Position {
+  latitude: number
+  longitude: number
+}
+
+/**
+ * A guess at where this is being read, from the time zone alone.
+ *
+ * The `try` is not defensive dressing. This runs under Qt's JavaScript engine
+ * as well as in a browser, and an engine built without ICU has no `Intl` to
+ * ask; the fallback is the middle of the northern hemisphere, which is wrong by
+ * a few degrees for most readers and never wrong by a season.
+ */
+export function position(now: Date): Position {
+  const longitude = clamp(-standard(now) / 4, -180, 180)
+
+  let zone = ""
+  try {
+    zone = Intl.DateTimeFormat().resolvedOptions().timeZone ?? ""
+  } catch {
+    zone = ""
+  }
+
+  const place = ZONE_PLACE[zone]
+  if (place) return { latitude: place[0], longitude: place[1] }
+
+  const region = zone.split("/")[0] ?? ""
+  return { latitude: REGION_LATITUDE[region] ?? 45, longitude }
+}
+
+/**
+ * The zone's own offset from UTC in minutes, with summer time taken back out.
+ *
+ * A zone is a meridian and summer time is a law, so a clock put forward an hour
+ * is not a reader who moved fifteen degrees east. Reading the offset as it
+ * stands put Brussels on the meridian of Kyiv every summer, which is an hour of
+ * error in every rise and set: the moon left the water while it was still up
+ * outside the window, and the sun set an hour early from March to October.
+ *
+ * The standard offset is the larger of midwinter's and midsummer's, since
+ * `getTimezoneOffset` counts minutes behind UTC and summer time can only take
+ * that number down. That holds in both hemispheres and on zones that never move
+ * their clocks at all.
+ */
+function standard(now: Date): number {
+  const year = now.getFullYear()
+  const january = new Date(year, 0, 1).getTimezoneOffset()
+  const july = new Date(year, 6, 1).getTimezoneOffset()
+
+  return Math.max(january, july)
+}
+
+/**
+ * The sun's altitude above the horizon in degrees.
+ *
+ * The low-precision solar position from the Astronomical Almanac, the same
+ * formulation SunCalc uses: mean anomaly, then ecliptic longitude, then a
+ * rotation into the observer's horizon. Good to about a minute of arc, which is
+ * four orders of magnitude better than the position it is fed.
+ */
+export function solarAltitude(now: Date, position: Position): number {
+  const days = epochDays(now)
+
+  return horizon(days, position, equatorial(sunEcliptic(days), 0)).altitude
+}
+
+/**
+ * The moon's altitude above the horizon in degrees.
+ *
+ * The sibling of `solarAltitude`, and the reason there is one: a moon is up for
+ * its own hours rather than for the hours the sun is not. It is a couple of
+ * tenths of a degree out, which is a fraction of the disc's own width and a few
+ * minutes of the time it rises.
+ */
+export function lunarAltitude(now: Date, position: Position): number {
+  const days = epochDays(now)
+  const { latitude, longitude } = moonEcliptic(days)
+
+  return horizon(days, position, equatorial(longitude, latitude)).altitude
+}
+
+/**
+ * Days since J2000.0, which every series below is written in.
+ */
+function epochDays(now: Date): number {
+  return now.getTime() / DAY_MS - J2000_OFFSET_DAYS
+}
+
+/**
+ * The sun's ecliptic longitude in radians.
+ *
+ * Mean anomaly, then the equation of the centre, then round to the longitude of
+ * perihelion. Good to about a minute of arc, which is four orders of magnitude
+ * better than the position it is fed.
+ */
+function sunEcliptic(days: number): number {
+  const meanAnomaly = (357.5291 + 0.98560028 * days) * RAD
+
+  return (
+    meanAnomaly +
+    (1.9148 * Math.sin(meanAnomaly) +
+      0.02 * Math.sin(2 * meanAnomaly) +
+      0.0003 * Math.sin(3 * meanAnomaly)) *
+      RAD +
+    102.9372 * RAD +
+    Math.PI
+  )
+}
+
+/**
+ * The moon's ecliptic longitude and latitude in radians.
+ *
+ * The shortest lunar theory anybody publishes: a mean longitude, a mean
+ * anomaly and an argument of latitude, each turning at its own rate, each with
+ * the one correction that matters. It lands within a fraction of a degree,
+ * which moves moonrise by a few minutes and the shape of the disc by an hour or
+ * two of a month. Nobody can tell an hour of a month by looking.
+ *
+ * Those three rates are the month. The longitude turns a little over thirteen
+ * degrees a day and the sun turns one, so the moon laps it every 29.53 days,
+ * and that lap is what the disc's shape is.
+ */
+function moonEcliptic(days: number): { latitude: number; longitude: number } {
+  const argument = (93.272 + 13.22935 * days) * RAD
+  const meanAnomaly = (134.963 + 13.064993 * days) * RAD
+  const meanLongitude = (218.316 + 13.176396 * days) * RAD
+
+  return {
+    latitude: 5.128 * RAD * Math.sin(argument),
+    longitude: meanLongitude + 6.289 * RAD * Math.sin(meanAnomaly),
+  }
+}
+
+/**
+ * An ecliptic position turned into the frame the sky turns in.
+ *
+ * The sun never leaves the ecliptic and is handed a latitude of zero, which
+ * drops the two terms that then vanish; the moon is up to five degrees off it,
+ * and dropping them for the moon would put it a disc's width from where it is.
+ */
+function equatorial(
+  longitude: number,
+  latitude: number,
+): { declination: number; rightAscension: number } {
+  return {
+    declination: Math.asin(
+      Math.sin(latitude) * Math.cos(OBLIQUITY) +
+        Math.cos(latitude) * Math.sin(OBLIQUITY) * Math.sin(longitude),
+    ),
+    rightAscension: Math.atan2(
+      Math.sin(longitude) * Math.cos(OBLIQUITY) - Math.tan(latitude) * Math.sin(OBLIQUITY),
+      Math.cos(longitude),
+    ),
+  }
+}
+
+/**
+ * How high a body is and which side of the sky it is on, from where it is read.
+ *
+ * The hour angle comes back with the altitude because it is what says which
+ * side, and a body that rises where it set is a body on a loop. It is zero at
+ * local transit, negative on the way up and positive on the way down.
+ */
+function horizon(
+  days: number,
+  { latitude, longitude }: Position,
+  { declination, rightAscension }: { declination: number; rightAscension: number },
+): { altitude: number; hourAngle: number } {
+  const siderealTime = (280.16 + 360.9856235 * days) * RAD + longitude * RAD
+  const hourAngle = siderealTime - rightAscension
+
+  const phi = latitude * RAD
+  const altitude = Math.asin(
+    Math.sin(phi) * Math.sin(declination) +
+      Math.cos(phi) * Math.cos(declination) * Math.cos(hourAngle),
+  )
+
+  return { altitude: altitude / RAD, hourAngle }
+}
+
+/**
+ * Where a body is in its own passage across the sky.
+ *
+ * `march` is 0 where it comes up and 1 where it goes down, so a renderer that
+ * knows nothing about astronomy can put a disc at `left + march * (right -
+ * left)` and have it cross by the clock. `arc` is 0 at either horizon and 1 at
+ * the top, which is what lifts the middle of the passage and lets the light
+ * under it stand more upright the higher the body gets. `up` is whether the
+ * thing is there to be drawn at all: 1 once it is clear of the horizon and 0
+ * while it is under it.
+ *
+ * Twelve hours from one horizon to the other, because that is what an hour
+ * angle gives: half a turn of the Earth. The real figure is longer in summer
+ * and shorter in winter and this does not model that. It is a disc on a
+ * wallpaper, and being an hour out at the solstice costs nothing; what would
+ * cost something is the moon jumping.
+ *
+ * `up` is the one that has to be honest, and it is honest because it is the
+ * altitude rather than the hour angle. A moon three days past full is under the
+ * ground for the first half of the night, and a renderer that took `march`
+ * alone would park it on the horizon and leave it there, lit, in an empty sky.
+ * The fade runs over a few degrees so it goes out where it sets rather than
+ * being switched off.
+ */
+export interface Passage {
+  arc: number
+  march: number
+  up: number
+}
+
+function passage({ altitude, hourAngle }: { altitude: number; hourAngle: number }): Passage {
+  const wrapped = wrap(hourAngle)
+  const march = clamp(0.5 + wrapped / Math.PI, 0, 1)
+
+  return { arc: Math.sin(march * Math.PI), march, up: clamp((altitude + 1) / 6, 0, 1) }
+}
+
+/**
+ * How much of the moon the sun has hold of, and which way it is going.
+ *
+ * `lit` is the share of the disc in the light, 0 at the new moon and 1 at the
+ * full one. `waxing` is which side that share is on, and it is the right side
+ * of the disc for the half of the month the moon is filling up.
+ *
+ * The elongation is taken along the ecliptic alone, which ignores the moon's
+ * few degrees off it and the fact that the sun is not infinitely far away.
+ * Both are worth about a percent of the lit share at the quarters and nothing
+ * at either end of the month, and neither changes the shape a person sees.
+ */
+export interface Phase {
+  lit: number
+  waxing: boolean
+}
+
+export function phase(now: Date): Phase {
+  const days = epochDays(now)
+  const elongation = wrap(moonEcliptic(days).longitude - sunEcliptic(days))
+
+  return { lit: (1 - Math.cos(elongation)) / 2, waxing: elongation > 0 }
+}
+
+/**
+ * The lit part of the moon, as an SVG path about a point.
+ *
+ * Two arcs. The limb is the disc's own edge, a half circle on the side the sun
+ * is; the terminator is the other edge of the light, and it is a half ellipse
+ * because it is a circle around the moon seen at an angle. That ellipse is
+ * squeezed flat at the quarters, bulges away from the light through the
+ * crescent, and bulges into the dark through the gibbous, which is the whole of
+ * why a gibbous moon looks fat and a crescent looks thin.
+ *
+ * The centre is asked for rather than assumed, because a renderer that has to
+ * move the path afterwards has to move the box it is drawn in as well, and a
+ * shape that leaves its box is a shape somebody's toolkit will quietly cut in
+ * half.
+ *
+ * At the quarters the ellipse has no width left, and an arc with a zero radius
+ * is a straight line by the SVG rules, which is exactly the edge a half moon
+ * has. Nothing here special-cases it.
+ */
+export function crescent(x: number, y: number, radius: number, { lit, waxing }: Phase): string {
+  const limb = waxing ? 1 : 0
+  const terminator = lit > 0.5 ? limb : 1 - limb
+  const waist = round(radius * Math.abs(2 * lit - 1))
+  const r = round(radius)
+  const top = `${round(x)} ${round(y - radius)}`
+  const foot = `${round(x)} ${round(y + radius)}`
+
+  return `M${top}A${r} ${r} 0 0 ${limb} ${foot}A${waist} ${r} 0 0 ${terminator} ${top}Z`
+}
+
+/**
+ * How far into the light a point on the disc is, as a share of the radius.
+ *
+ * Positive in the light, negative in the dark, and near zero on the terminator
+ * itself. It is here so a renderer can put the same craters on the moon every
+ * night and have them go out as the terminator crosses them, rather than
+ * carrying a mark on a part of the moon nothing is lighting.
+ *
+ * The point is in units of the radius, x to the right and y down, which is what
+ * a renderer holds anyway.
+ */
+export function sunlit(x: number, y: number, { lit, waxing }: Phase): number {
+  const across = waxing ? x : -x
+
+  return across + (2 * lit - 1) * Math.sqrt(Math.max(0, 1 - y * y))
+}
+
+/**
+ * The two numbers a renderer reads, from an altitude in degrees.
+ *
+ * Daylight runs out at -6 degrees, the end of civil twilight, which is when a
+ * person outside stops being able to read. It is full by +6, a little after
+ * sunrise, because the half hour either side of the horizon is the part worth
+ * drawing differently. Dusk peaks at the horizon itself and is gone 8 degrees
+ * away, so it rises and falls twice a day and is zero at noon and at midnight.
+ */
+export function light(altitude: number): { daylight: number; dusk: number } {
+  return {
+    daylight: clamp((altitude + 6) / 12, 0, 1),
+    dusk: clamp(1 - Math.abs(altitude) / 8, 0, 1),
+  }
+}
+
+/**
+ * The whole sky, right now and where this is running.
+ *
+ * How light it is, how near a sunset, where each of the two bodies has got to
+ * in its own crossing, and what shape the moon is in tonight. `Date` is read
+ * here rather than passed, because every caller wants the actual time and the
+ * arithmetic above is already testable without it.
+ *
+ * Both bodies come back, not the one that happens to be up. They are drawn as
+ * two discs that fade with `daylight` and against it, which is the only way the
+ * changeover works: a single disc that swapped identity at dusk would set in
+ * the west and reappear a moment later in the east, and the sky would have
+ * jumped. Fading a setting sun out where it set while a moon comes up on the
+ * other side is what actually happens, and it costs one more circle.
+ *
+ * The moon is worked out rather than put opposite the sun. Opposite the sun is
+ * the full moon's path and only the full moon's: it has the moon rising at
+ * sunset every night of the year, which is right twice a month and an hour or
+ * more out the rest of the time. The real one rises about fifty minutes later
+ * each night and is a different shape every one of them, and a wallpaper that
+ * gets that right is a wallpaper somebody can look up from and check.
+ */
+export function sunNow(): {
+  daylight: number
+  dusk: number
+  moon: Passage & Phase
+  sun: Passage
+} {
+  const now = new Date()
+  const here = position(now)
+  const days = epochDays(now)
+
+  const sun = horizon(days, here, equatorial(sunEcliptic(days), 0))
+  const moon = moonEcliptic(days)
+
+  return {
+    ...light(sun.altitude),
+    moon: {
+      ...passage(horizon(days, here, equatorial(moon.longitude, moon.latitude))),
+      ...phase(now),
+    },
+    sun: passage(sun),
+  }
+}
+
+function clamp(value: number, low: number, high: number): number {
+  return Math.min(high, Math.max(low, value))
+}
+
+/** An angle brought back into the half turn either side of zero. */
+function wrap(angle: number): number {
+  return Math.atan2(Math.sin(angle), Math.cos(angle))
+}
+
+/** Enough of a number for a path, and no more of one. */
+function round(value: number): number {
+  return Math.round(value * 1000) / 1000
+}