canvas-globe 1.1.0 → 1.2.0

package/src/fx/effects/transitions.js

@@ -0,0 +1,209 @@
+/**
+ * Transitions and camera moves.
+ *
+ * Camera effects run at the `beneath` stage so the move lands on the frame
+ * being drawn rather than the next one, and they derive the view purely from
+ * the clock, which keeps them seekable.
+ */
+import { clamp01, drawPath, easeInOut, label, lerp, panel, TAU } from "../runtime.js";
+
+const clampZoom = (globe, z) => {
+  if (Math.abs(globe.zoom - z) > 1e-4) globe.setZoom(z);
+};
+
+/**
+ * Stroke start and end travel independently, so a line snakes into place.
+ * Ports catalogue effect BT.
+ */
+export const trimPaths = ({
+  from,
+  to,
+  duration = 3400,
+  hold = 900,
+  steps = 70,
+  hue = 196,
+  width = 2.2,
+} = {}) => ({
+  name: "trimPaths",
+  stage: "above",
+  duration,
+  hold,
+  setup(globe) {
+    const hub = from || globe.markers[0];
+    const targets = to || globe.markers.slice(1, 7);
+    const routes = targets.map((c) =>
+      Array.from({ length: steps + 1 }, (_, j) => {
+        const f = j / steps;
+        return [lerp(hub.lon, c.lon, f), lerp(hub.lat, c.lat, f)];
+      })
+    );
+    return { routes };
+  },
+  frame(ctx, globe, t, state) {
+    ctx.lineCap = "round";
+    ctx.lineWidth = width;
+    state.routes.forEach((pts, i) => {
+      const k = clamp01(t * 1.5 - i * 0.07);
+      const end = easeInOut(clamp01(k * 1.6));
+      const start = easeInOut(clamp01(k * 1.6 - 0.38));
+      const i0 = Math.floor(pts.length * start), i1 = Math.ceil(pts.length * end);
+      ctx.strokeStyle = `hsl(${hue + i * 12} 92% 62%)`;
+      ctx.beginPath();
+      let open = false;
+      for (let j = i0; j < i1; j++) {
+        const p = globe.project(pts[j][0], pts[j][1]);
+        if (!p) {
+          open = false;
+          continue;
+        }
+        open ? ctx.lineTo(p.x, p.y) : (ctx.moveTo(p.x, p.y), (open = true));
+      }
+      ctx.stroke();
+    });
+  },
+});
+
+/**
+ * A wobbling blob swallows the frame instead of a hard geometric wipe.
+ * Ports catalogue effect BV.
+ */
+export const liquidWipe = ({ duration = 2600, hold = 800, lobes = 5, wobble = 0.13 } = {}) => ({
+  name: "liquidWipe",
+  stage: "post",
+  z: 80,
+  duration,
+  hold,
+  frame(ctx, globe, t) {
+    const w = globe.canvas.clientWidth, h = globe.canvas.clientHeight;
+    const dpr = globe.canvas.width / Math.max(1, w);
+    const cx = w / 2, cy = h / 2;
+    const base = t * Math.hypot(w, h) * 0.78;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.globalCompositeOperation = "destination-in";
+    ctx.beginPath();
+    for (let a = 0; a <= 72; a++) {
+      const ang = (a / 72) * TAU;
+      const wob = 1 + Math.sin(ang * lobes + t * 9) * wobble + Math.sin(ang * 3 - t * 6) * 0.09;
+      const r = base * wob;
+      const x = cx + Math.cos(ang) * r, y = cy + Math.sin(ang) * r;
+      a ? ctx.lineTo(x, y) : ctx.moveTo(x, y);
+    }
+    ctx.closePath();
+    ctx.fill();
+    ctx.globalCompositeOperation = "source-over";
+  },
+});
+
+/**
+ * Continuous push-in where each scale hands off to the next without a seam.
+ * Ports catalogue effect BU.
+ */
+export const matchCut = ({
+  duration = 5200,
+  from = { lon: 20, lat: 14 },
+  to = { lon: 72.58, lat: 23.03 },
+  cycles = 2,
+  maxZoom = 7.8,
+  fromLabel = "Origin",
+  toLabel = "Destination",
+  color = "#38bdf8",
+} = {}) => ({
+  name: "matchCut",
+  stage: "above",
+  z: 52,
+  duration,
+  frame(ctx, globe, t) {
+    const p = (t * cycles) % 1;
+    clampZoom(globe, Math.min(maxZoom, Math.pow(2, p * 2.2) * 0.9));
+    const e = easeInOut(t);
+    globe.lon = lerp(from.lon, to.lon, e);
+    globe.lat = lerp(from.lat, to.lat, e);
+    const path = Array.from({ length: 65 }, (_, i) => {
+      const k = i / 64;
+      return [lerp(from.lon, to.lon, k), lerp(from.lat, to.lat, k) + Math.sin(k * Math.PI) * 10];
+    });
+    ctx.save();
+    ctx.strokeStyle = color;
+    ctx.globalAlpha = 0.62;
+    ctx.lineWidth = 1.8;
+    ctx.setLineDash([5, 5]);
+    ctx.beginPath();
+    drawPath(ctx, globe, path);
+    ctx.stroke();
+    ctx.setLineDash([]);
+    const drawPoint = (point, labelText, active) => {
+      const q = globe.project(point.lon, point.lat);
+      if (!q) return;
+      ctx.globalAlpha = active ? 1 : 0.6;
+      ctx.fillStyle = active ? "#fff" : color;
+      ctx.strokeStyle = color;
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      ctx.arc(q.x, q.y, active ? 6 : 4, 0, TAU);
+      ctx.fill();
+      ctx.beginPath();
+      ctx.arc(q.x, q.y, active ? 13 : 9, 0, TAU);
+      ctx.stroke();
+      label(ctx, labelText, q.x, q.y - 17, { color: "#fff", size: 9, weight: 800, align: "center" });
+    };
+    drawPoint(from, fromLabel, t < 0.5);
+    drawPoint(to, toLabel, t >= 0.5);
+    const w = globe.canvas.clientWidth, h = globe.canvas.clientHeight;
+    panel(ctx, Math.max(12, w / 2 - 150), h - 58, Math.min(300, w - 24), 44, { fill: "rgba(5,10,20,.9)", stroke: "rgba(232,236,245,.18)", radius: 8 });
+    ctx.globalAlpha = 1;
+    label(ctx, fromLabel, Math.max(25, w / 2 - 134), h - 31, { color: t < 0.5 ? "#fff" : "rgba(232,236,245,.55)", size: 10, weight: 700 });
+    label(ctx, "→", w / 2, h - 31, { color, size: 15, weight: 800, align: "center" });
+    label(ctx, toLabel, Math.min(w - 25, w / 2 + 134), h - 31, { color: t >= 0.5 ? "#fff" : "rgba(232,236,245,.55)", size: 10, weight: 700, align: "right" });
+    ctx.restore();
+  },
+});
+
+/**
+ * Punches in from a distant speck to a framed region.
+ * Ports catalogue effect D.
+ */
+export const dropFromOrbit = ({
+  duration = 3000,
+  hold = 800,
+  at,
+  fromZoom = 0.55,
+  toZoom = 2.75,
+} = {}) => ({
+  name: "dropFromOrbit",
+  stage: "beneath",
+  z: -90,
+  duration,
+  hold,
+  loop: false,
+  setup(globe) {
+    return { target: at || globe.markers[0] || { lon: globe.lon, lat: globe.lat } };
+  },
+  frame(_ctx, globe, t, state) {
+    const e = easeInOut(t);
+    clampZoom(globe, lerp(fromZoom, toZoom, e));
+    globe.lon = lerp(state.target.lon - 40, state.target.lon, e);
+    globe.lat = lerp(state.target.lat - 18, state.target.lat, e);
+  },
+});
+
+/**
+ * A full twenty-four hours of terminator in one cycle. Needs `terminator: true`.
+ * Ports catalogue effect I.
+ */
+export const dayNightSweep = ({ duration = 6000, start = Date.UTC(2024, 5, 21, 0) } = {}) => ({
+  name: "dayNightSweep",
+  stage: "beneath",
+  z: -95,
+  duration,
+  setup(globe) {
+    const previous = { terminator: globe.o.terminator, time: globe.o.time };
+    globe.setOptions({ terminator: true });
+    return previous;
+  },
+  frame(_ctx, globe, t) {
+    globe.o.time = start + t * 86400000;
+  },
+  dispose(previous, globe) {
+    globe.setOptions(previous);
+  },
+});

package/src/fx/index.js

@@ -0,0 +1,52 @@
+/**
+ * Effect kit for canvas-globe. Import only what you use  -  every effect is a
+ * separate export so a bundler can drop the rest.
+ *
+ *   import { createGlobe } from "canvas-globe";
+ *   import { scanlines, counterRoll } from "canvas-globe/fx";
+ *
+ *   const globe = createGlobe(canvas, { preset: "midnight" });
+ *   globe.use(scanlines());
+ *   globe.use(counterRoll({ to: 21947, caption: "customers" }));
+ */
+
+export { particleAssemble, radarSweep, markerCascade } from "./effects/entrances.js";
+export {
+  scanlines, breathe, lightTrails, torch, meshGradient, cityLights,
+  starfield, shineSweep, glassSphere, neonFlicker,
+} from "./effects/ambient.js";
+export {
+  counterRoll, shockwave, choroplethCascade, routeDashes, tally,
+  arcLaunch, spikesRising, pinDrop, orbitSubject, markerBloom,
+} from "./effects/data.js";
+export {
+  trimPaths, liquidWipe, matchCut, dropFromOrbit, dayNightSweep,
+} from "./effects/transitions.js";
+export {
+  mapUnfold, firework, glitch, lowerThird, splitFlap, textOnCircle, countryMatte,
+  ghostTrail, windField, aurora, jellySquash, dataDesk,
+} from "./effects/scene.js";
+export {
+  magneticMarkers,
+  measureTool,
+  lassoSelect,
+  hoverLift,
+  pingProbe,
+  parallaxTilt,
+  cursorLight,
+  drillDown,
+  radialMenu,
+  spinToWin,
+  serviceRadius,
+  timezoneOverlap,
+  compareCountries,
+  geoQuiz,
+} from "./effects/interaction.js";
+
+export {
+  linear, easeIn, easeOut, easeInOut, backOut, pingPong, clamp01, lerp, stagger,
+  rng, scratch, releaseScratch, destination, ring, drawPath, centroid,
+  panel, label, readout, bar, particles, TAU,
+} from "./runtime.js";
+
+export { onTap, onDragPath, nearest, pointInPath } from "./pointer.js";

package/src/fx/pointer.js

@@ -0,0 +1,94 @@
+/** Pointer helpers for interaction effects. Each returns an unbind function. */
+
+const local = (canvas, e) => {
+  const r = canvas.getBoundingClientRect();
+  return { x: e.clientX - r.left, y: e.clientY - r.top };
+};
+
+/** Click that did not turn into a drag, so it cannot fight globe panning. */
+export function onTap(globe, handler, slop = 4) {
+  const c = globe.canvas;
+  let from = null;
+  const down = (e) => (from = local(c, e));
+  const up = (e) => {
+    if (!from) return;
+    const p = local(c, e);
+    if (Math.abs(p.x - from.x) <= slop && Math.abs(p.y - from.y) <= slop) {
+      handler(p, globe.unproject(p.x, p.y), e);
+    }
+    from = null;
+  };
+  c.addEventListener("pointerdown", down);
+  c.addEventListener("pointerup", up);
+  return () => {
+    c.removeEventListener("pointerdown", down);
+    c.removeEventListener("pointerup", up);
+  };
+}
+
+/** Freehand drag path in canvas pixels, for lassos and brushes. */
+export function onDragPath(globe, { start, move, end }, enabled = () => true) {
+  const c = globe.canvas;
+  let path = null;
+  const down = (e) => {
+    if (!enabled()) return;
+    e.preventDefault?.();
+    e.stopImmediatePropagation?.();
+    c.setPointerCapture?.(e.pointerId);
+    path = [local(c, e)];
+    start?.(path);
+  };
+  const drag = (e) => {
+    if (!path) return;
+    e.preventDefault?.();
+    e.stopImmediatePropagation?.();
+    path.push(local(c, e));
+    move?.(path);
+  };
+  const stop = (e) => {
+    if (!path) return;
+    e?.preventDefault?.();
+    e?.stopImmediatePropagation?.();
+    end?.(path);
+    path = null;
+    c.releasePointerCapture?.(e?.pointerId);
+  };
+  // Capture before the globe's own drag handlers so drawing a lasso never
+  // rotates the camera underneath the selection.
+  c.addEventListener("pointerdown", down, true);
+  c.addEventListener("pointermove", drag, true);
+  c.addEventListener("pointerup", stop, true);
+  c.addEventListener("pointercancel", stop, true);
+  c.addEventListener("pointerleave", stop, true);
+  return () => {
+    c.removeEventListener("pointerdown", down, true);
+    c.removeEventListener("pointermove", drag, true);
+    c.removeEventListener("pointerup", stop, true);
+    c.removeEventListener("pointercancel", stop, true);
+    c.removeEventListener("pointerleave", stop, true);
+  };
+}
+
+/** Nearest item to a canvas point, within a pixel radius. */
+export function nearest(globe, items, x, y, radius = 28) {
+  let best = null, bd = radius;
+  for (const item of items) {
+    const p = globe.project(item.lon, item.lat);
+    if (!p) continue;
+    const d = Math.hypot(p.x - x, p.y - y);
+    if (d < bd) {
+      bd = d;
+      best = item;
+    }
+  }
+  return best;
+}
+
+export const pointInPath = (x, y, path) => {
+  let inside = false;
+  for (let i = 0, j = path.length - 1; i < path.length; j = i++) {
+    const a = path[i], b = path[j];
+    if (a.y > y !== b.y > y && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
+  }
+  return inside;
+};

package/src/fx/runtime.js

@@ -0,0 +1,161 @@
+/**
+ * Shared machinery for effects. Everything here is deliberately stateless with
+ * respect to wall-clock time: an effect is handed a 0→1 phase and must derive
+ * its whole appearance from that, so `globe.renderFrame(ms)` is reproducible.
+ */
+
+/* --------------------------------- easing -------------------------------- */
+
+export const linear = (t) => t;
+export const easeIn = (t) => t * t * t;
+export const easeOut = (t) => 1 - Math.pow(1 - t, 3);
+export const easeInOut = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+/** Overshoots past 1 and settles  -  the "lands with weight" feel. */
+export const backOut = (t) => 1 + 2.70158 * Math.pow(t - 1, 3) + 1.70158 * Math.pow(t - 1, 2);
+export const pingPong = (t) => (t < 0.5 ? t * 2 : 1 - (t - 0.5) * 2);
+export const clamp01 = (t) => (t < 0 ? 0 : t > 1 ? 1 : t);
+export const lerp = (a, b, t) => a + (b - a) * t;
+
+/** Progress of one item in a staggered sequence. */
+export const stagger = (t, index, count, overlap = 0.55) => {
+  const step = (1 - overlap) / Math.max(1, count);
+  return clamp01((t - index * step) / Math.max(0.0001, 1 - index * step));
+};
+
+/* ------------------------------- randomness ------------------------------- */
+
+/**
+ * Deterministic RNG. Effects must never call Math.random() per frame or the
+ * same millisecond would render differently on every pass.
+ */
+export function rng(seed = 1) {
+  let s = seed >>> 0 || 1;
+  return () => {
+    s ^= s << 13;
+    s ^= s >>> 17;
+    s ^= s << 5;
+    return ((s >>> 0) % 100000) / 100000;
+  };
+}
+
+/* --------------------------------- buffers -------------------------------- */
+
+const pools = new WeakMap();
+
+/**
+ * A scratch canvas matching the globe's backing size, reused across frames.
+ * Post-processing effects each asking for their own would cost a full canvas
+ * allocation per effect per resize.
+ */
+export function scratch(globe, key = "default") {
+  let pool = pools.get(globe);
+  if (!pool) pools.set(globe, (pool = new Map()));
+  let entry = pool.get(key);
+  if (!entry) {
+    if (typeof document === "undefined") return null;
+    const canvas = document.createElement("canvas");
+    entry = { canvas, ctx: canvas.getContext("2d") };
+    pool.set(key, entry);
+  }
+  const { width, height } = globe.canvas;
+  if (entry.canvas.width !== width || entry.canvas.height !== height) {
+    entry.canvas.width = width;
+    entry.canvas.height = height;
+  }
+  return entry;
+}
+
+/** Drops every scratch canvas an effect took for a globe. */
+export function releaseScratch(globe, key) {
+  const pool = pools.get(globe);
+  if (!pool) return;
+  key ? pool.delete(key) : pool.clear();
+}
+
+/* -------------------------------- geometry -------------------------------- */
+
+const D2R = Math.PI / 180;
+export const TAU = Math.PI * 2;
+
+/** Point `degrees` away from a coordinate along a bearing. */
+export function destination(lon, lat, bearing, degrees) {
+  const f1 = lat * D2R, l1 = lon * D2R, b = bearing * D2R, d = degrees * D2R;
+  const f2 = Math.asin(Math.sin(f1) * Math.cos(d) + Math.cos(f1) * Math.sin(d) * Math.cos(b));
+  const l2 = l1 + Math.atan2(Math.sin(b) * Math.sin(d) * Math.cos(f1), Math.cos(d) - Math.sin(f1) * Math.sin(f2));
+  return [((l2 / D2R + 540) % 360) - 180, f2 / D2R];
+}
+
+/** Ring of coordinates a fixed angular distance from a centre. */
+export function ring(lon, lat, degrees, steps = 72) {
+  const out = [];
+  for (let i = 0; i <= steps; i++) out.push(destination(lon, lat, (i / steps) * 360, degrees));
+  return out;
+}
+
+/** Strokes or fills a lon/lat path, breaking it where the globe hides it. */
+export function drawPath(ctx, globe, points, close = false) {
+  let open = false;
+  for (const [lon, lat] of points) {
+    const p = globe.project(lon, lat);
+    if (!p) {
+      open = false;
+      continue;
+    }
+    open ? ctx.lineTo(p.x, p.y) : (ctx.moveTo(p.x, p.y), (open = true));
+  }
+  if (open && close) ctx.closePath();
+}
+
+export const centroid = (shape) => {
+  const geom = shape?.geometry || shape;
+  const polys = geom.type === "Polygon" ? [geom.coordinates] : geom.coordinates;
+  let x = 0, y = 0, n = 0;
+  for (const poly of polys) for (const r of poly) for (const c of r) { x += c[0]; y += c[1]; n++; }
+  return [x / n, y / n];
+};
+
+/* ----------------------------------- HUD ---------------------------------- */
+
+/** Rounded panel used by nearly every readout. */
+export function panel(ctx, x, y, w, h, { fill = "rgba(7,8,13,.9)", stroke, radius = 8 } = {}) {
+  ctx.beginPath();
+  ctx.roundRect(x, y, w, h, radius);
+  ctx.fillStyle = fill;
+  ctx.fill();
+  if (stroke) {
+    ctx.strokeStyle = stroke;
+    ctx.lineWidth = 1;
+    ctx.stroke();
+  }
+}
+
+export function label(ctx, text, x, y, { size = 11, weight = 600, color = "#e8ecf5", align = "left", font = "Inter, system-ui, sans-serif" } = {}) {
+  ctx.fillStyle = color;
+  ctx.font = `${weight} ${size}px ${font}`;
+  ctx.textAlign = align;
+  ctx.fillText(text, x, y);
+  ctx.textAlign = "left";
+}
+
+/** Caption above a value  -  the readout pattern used across the data effects. */
+export function readout(ctx, x, y, caption, value, { accent = "#34d399", width = 168 } = {}) {
+  panel(ctx, x, y, width, 38, { stroke: accent });
+  label(ctx, caption, x + 10, y + 16, { size: 9, weight: 600, color: accent });
+  label(ctx, value, x + 10, y + 31, { size: 15, weight: 800, color: "#fff" });
+}
+
+export function bar(ctx, x, y, w, h, fraction, { fill = "#34d399", track = "rgba(232,236,245,.1)", radius = 3 } = {}) {
+  panel(ctx, x, y, w, h, { fill: track, radius });
+  if (fraction > 0) panel(ctx, x, y, Math.max(2, w * clamp01(fraction)), h, { fill, radius });
+}
+
+/* -------------------------------- particles ------------------------------- */
+
+/**
+ * Fixed-size particle set. Positions are a pure function of phase, so a
+ * particle effect still exports frame-for-frame.
+ */
+export function particles(count, seed = 7, make) {
+  const random = rng(seed);
+  return Array.from({ length: count }, (_, i) => make(random, i));
+}