canvas-globe 1.1.1 → 1.3.0

package/src/geo-globe.js

@@ -15,7 +15,7 @@ import {
   getLicensePresentation,
   reportLicenseStatus,
 } from "./license.js";
-import { D2R, R2D, TAU, clamp, wrapLon, resolveProjection, projectionBounds, ortho, orthoInverse, greatCircle, circleAround, distanceMeters, subsolarPoint, pointInGeometry, geometryBounds, normalizeShapes, withAlpha } from "./geo.js";
+import { D2R, R2D, TAU, clamp, wrapLon, resolveProjection, projectionBounds, ortho, orthoInverse, greatCircle, circleAround, distanceMeters, subsolarPoint, pointInGeometry, geometryBounds, normalizeShapes, withAlpha, colorScale, hexBinPoints } from "./geo.js";
 
 const DEFAULTS = {
   licenseKey: null,
@@ -40,6 +40,7 @@ const DEFAULTS = {
   timeline: null,
   transparentBackground: false,
   heatmap: false,
+  hexBins: false,
   spikes: false,
   labels: false,
   legend: null,
@@ -83,13 +84,28 @@ const DEFAULTS = {
   onCountryHover: null,
   onCountryClick: null,
   onRender: null,
+  effects: null,
 };
 
 const coord = (v) => (Array.isArray(v) ? [v[0], v[1]] : [v.lon ?? v.lng ?? v.longitude, v.lat ?? v.latitude]);
 
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+
+/**
+ * An effect's own 0→1 progress at a point on the shared clock. Derived purely
+ * from `ms`, so the same millisecond always renders the same frame.
+ */
+const phaseOf = (fx, ms) => {
+  const duration = Math.max(1, fx.duration ?? 1000);
+  const total = duration + (fx.hold ?? 0);
+  const elapsed = fx.loop === false ? Math.min(ms, total) : ((ms % total) + total) % total;
+  return Math.min(1, elapsed / duration);
+};
+
 const defaultTooltip = (target, kind) => {
   if (kind === "country") return target.name || String(target.id ?? "");
   if (kind === "cluster") return `${target.count} in this area`;
+  if (kind === "hex-bin") return `${target.markerCount} markers, value ${target.value}`;
   const name = target.city || target.name || target.label;
   const count = target.count != null ? `: ${target.count}` : "";
   return name ? `${name}${count}` : `${target.lat.toFixed(2)}, ${target.lon.toFixed(2)}${count}`;
@@ -141,6 +157,11 @@ export class GeoGlobe {
     this._licenseHits = [];
     this._licenseDismissed = false;
     this._licenseHovered = false;
+    this._fx = [];
+    this._clock = null;
+    this._t0 = now();
+    this._spinBase = this.lon;
+    this.pointer = { x: 0, y: 0, lon: 0, lat: 0, over: false };
 
     this._applyWorld();
     this._applyMarkers(this.o.markers);
@@ -152,12 +173,138 @@ export class GeoGlobe {
     this.resize();
     if (this.o.focus) this.focusOn(this.o.focus, { instant: true });
     if (this.o.showViewer) this._initViewer();
+    for (const fx of this.o.effects || []) this.use(fx);
     this._loop = this._loop.bind(this);
     this._raf = requestAnimationFrame(this._loop);
   }
 
   /* ------------------------------ public API ------------------------------ */
 
+  /* --------------------------------- effects ------------------------------- */
+
+  /** Installs an effect. Returns `this`, so calls chain. */
+  use(effect) {
+    if (!effect || typeof effect.frame !== "function") return this;
+    this._fx.push({ fx: effect, state: effect.setup?.(this) ?? {} });
+    this._fx.sort((a, b) => (a.fx.z ?? 0) - (b.fx.z ?? 0));
+    return this.invalidate();
+  }
+
+  /** Removes an effect by reference or by name. */
+  remove(effect) {
+    const i = this._fx.findIndex((e) => e.fx === effect || e.fx.name === effect);
+    if (i < 0) return this;
+    const [entry] = this._fx.splice(i, 1);
+    entry.fx.dispose?.(entry.state, this);
+    return this.invalidate();
+  }
+
+  clearEffects() {
+    while (this._fx.length) this.remove(this._fx[0].fx);
+    return this;
+  }
+
+  get effects() {
+    return this._fx.map((e) => e.fx);
+  }
+
+  /**
+   * Pins the effect clock to `ms`. Rendering becomes reproducible, which is
+   * what frame-exact export and seamless loops need. `play()` releases it.
+   */
+  seek(ms) {
+    // Capture where auto-rotation started from, so longitude can be derived
+    // from the clock instead of accumulated per frame. Only on the way in:
+    // seeking again while already seeked must not shift the origin.
+    if (this._clock == null) this._spinBase = wrapLon(this.lon - this._spinRate() * this._fxTime());
+    this._clock = Math.max(0, ms);
+    if (this._autoSpin()) this.lon = wrapLon(this._spinBase + this._spinRate() * this._clock);
+    return this.invalidate();
+  }
+
+  play() {
+    // Resume the timeline where it was paused rather than snapping back to 0.
+    if (this._clock != null) this._t0 = now() - this._clock;
+    this._clock = null;
+    return this.invalidate();
+  }
+
+  /** Draws the single frame that belongs at `ms` on the effect clock. */
+  renderFrame(ms) {
+    return this.seek(ms).render();
+  }
+
+  _fxTime() {
+    return this._clock != null ? this._clock : now() - this._t0;
+  }
+
+  /**
+   * Wall clock for looping scene animation. Pinned while seeking, so arcs,
+   * orbits and pulses land on the same phase every time a frame is redrawn.
+   */
+  _animTime() {
+    return this._clock != null ? this._clock : Date.now();
+  }
+
+  /** Degrees of auto-rotation per millisecond. */
+  _spinRate() {
+    return ((this.o.rotateSpeed || 0) * (this.o.fps || 30)) / 1000;
+  }
+
+  _runPasses(stage) {
+    if (!this._fx.length) return;
+    const ms = this._fxTime();
+    const { ctx } = this;
+    for (const entry of this._fx) {
+      if ((entry.fx.stage || "above") !== stage) continue;
+      ctx.save();
+      try {
+        entry.fx.frame(ctx, this, phaseOf(entry.fx, ms), entry.state);
+      } catch (err) {
+        // One bad effect must not take the render loop down with it.
+        if (!entry.failed) {
+          entry.failed = true;
+          console.error(`canvas-globe: effect "${entry.fx.name || "anonymous"}" failed`, err);
+        }
+      }
+      ctx.restore();
+    }
+  }
+
+  /** Land sample points as `[lon, lat]` pairs — what the dot matrix draws. */
+  landPoints(spacing) {
+    const prev = this.o.dotSpacing;
+    if (spacing != null) this.o.dotSpacing = spacing;
+    const flat = this._dotPoints();
+    this.o.dotSpacing = prev;
+    const out = [];
+    for (let i = 0; i < flat.length; i += 2) out.push([flat[i], flat[i + 1]]);
+    return out;
+  }
+
+  /** Traces a country outline into a path using the current projection. */
+  tracePath(shape, ctx = this.ctx, transform) {
+    const geom = shape?.geometry || shape;
+    if (!geom?.coordinates) return this;
+    const polys = geom.type === "Polygon" ? [geom.coordinates] : geom.coordinates;
+    for (const poly of polys) {
+      for (const ring of poly) {
+        let open = false;
+        for (const c of ring) {
+          const src = transform ? transform(c) : c;
+          const p = this.project(src[0], src[1]);
+          if (!p) {
+            open = false;
+            continue;
+          }
+          open ? ctx.lineTo(p.x, p.y) : (ctx.moveTo(p.x, p.y), (open = true));
+        }
+        if (open) ctx.closePath();
+      }
+    }
+    return this;
+  }
+
   setMarkers(markers = []) {
     this._applyMarkers(markers);
     this._focus = -1;
@@ -714,9 +861,12 @@ export class GeoGlobe {
     const { w, h } = this._size();
     ctx.setTransform(this._dpr, 0, 0, this._dpr, 0, 0);
     ctx.clearRect(0, 0, w, h);
+    this._runPasses("beneath");
     this.hits = this.o.mode === "map" ? this._paintMap(w, h) : this._paintGlobe(w, h);
     this._dirty = false;
+    this._runPasses("above");
     this.o.onRender?.(this);
+    this._runPasses("post");
     this._paintLicenseNotice(w, h);
     return this;
   }
@@ -734,6 +884,7 @@ export class GeoGlobe {
   destroy() {
     this._destroyed = true;
     cancelAnimationFrame(this._raf);
+    this.clearEffects();
     this.stopTour();
     this.stopStory();
     this.stopTimeline();
@@ -1188,6 +1339,15 @@ export class GeoGlobe {
     this._onMove = (e) => {
       const [x, y] = this._local(e);
       this._pointer = { x: e.clientX, y: e.clientY };
+      this.pointer.x = x;
+      this.pointer.y = y;
+      this.pointer.over = true;
+      const at = this.unproject(x, y);
+      if (at) {
+        this.pointer.lon = at[0];
+        this.pointer.lat = at[1];
+      }
+      if (this._fx.length) this._dirty = true;
       const licenseHovered = this._licenseHitAt(x, y);
       if (licenseHovered !== this._licenseHovered) {
         this._licenseHovered = licenseHovered;
@@ -1241,7 +1401,7 @@ export class GeoGlobe {
         this._cursor();
         this._dirty = true;
         const target = marker || this._hoveredCountry;
-        this._showTip(marker ? (marker.cluster ? "cluster" : "marker") : this._hoveredCountry ? "country" : null, target);
+        this._showTip(marker ? (marker.hexBin ? "hex-bin" : marker.cluster ? "cluster" : "marker") : this._hoveredCountry ? "country" : null, target);
       } else if (this._tipVisible) {
         this._placeTip();
       }
@@ -1258,6 +1418,7 @@ export class GeoGlobe {
     this._onLeave = (e) => {
       this._onUp(e);
       this._pointer = null;
+      this.pointer.over = false;
       this._licenseHovered = false;
       if (this._hovered || this._hoveredCountry) {
         if (this._hovered) this.o.onHover?.(null, null);
@@ -1438,13 +1599,20 @@ export class GeoGlobe {
 
   /* --------------------------------- loop --------------------------------- */
 
-  _spinning() {
+  /** Auto-rotation is configured and permitted, regardless of the clock. */
+  _autoSpin() {
     return !!this.o.autoRotate && !this._reducedMotion() && !this._drag && !this._vel && this.o.mode === "globe";
   }
 
+  /** Auto-rotation should advance on its own this frame. */
+  _spinning() {
+    return this._autoSpin() && this._clock == null;
+  }
+
   /** True while something on screen still needs to move. */
   _animating() {
     if (this._target || this._drag || this._vel) return true;
+    if (this._fx.length && this._clock == null) return true;
     if (this._spinning()) return true;
     if (this._reducedMotion()) return false;
     if (this._hasLive || this._pings.length) return true;
@@ -1718,7 +1886,7 @@ export class GeoGlobe {
     const list = this._orbitList();
     if (!list.length) return;
     const { ctx } = this;
-    const spin = this._reducedMotion() ? 0 : (Date.now() / 1000) % 3600;
+    const spin = this._reducedMotion() ? 0 : (this._animTime() / 1000) % 3600;
     ctx.lineCap = "round";
     for (const orbit of list) {
       const inc = (orbit.inclination ?? 30) * D2R;
@@ -2272,7 +2440,7 @@ export class GeoGlobe {
     const arcs = this.o.arcs;
     if (!arcs || !arcs.length) return;
     const { ctx } = this;
-    const now = Date.now();
+    const now = this._animTime();
     const still = this._reducedMotion();
     ctx.lineCap = "round";
     ctx.lineJoin = "round";
@@ -2421,6 +2589,87 @@ export class GeoGlobe {
     ctx.restore();
   }
 
+  /** Aggregate projected markers into an interactive hexagonal density layer. */
+  _paintHexBins(pts, t, cx, cy, globeRadius, w, h) {
+    const o = this.o.hexBins === true ? {} : this.o.hexBins;
+    const { ctx } = this;
+    const radius = Math.max(4, o.radius ?? 18);
+    const padding = clamp(o.padding ?? 1.5, 0, radius * 0.45);
+    const drawRadius = radius - padding;
+    const minValue = Math.max(0, o.minValue ?? 1);
+    const metric = o.value === "count" ? "count" : "value";
+    const bins = hexBinPoints(pts, radius).filter((bin) => {
+      if (bin[metric] < minValue) return false;
+      if (this.o.mode === "globe") return Math.hypot(bin.x - cx, bin.y - cy) <= globeRadius + drawRadius;
+      return bin.x >= -drawRadius && bin.x <= w + drawRadius && bin.y >= -drawRadius && bin.y <= h + drawRadius;
+    });
+    const max = Math.max(1, ...bins.map((bin) => bin[metric]));
+    const range = Array.isArray(o.colorRange) && o.colorRange.length > 1
+      ? o.colorRange
+      : [t.ocean[0], o.color || t.marker];
+    const domain = range.map((_, index) => max * index / (range.length - 1));
+    const scale = colorScale(domain, range);
+    const hits = [];
+
+    ctx.save();
+    if (this.o.mode === "globe") {
+      ctx.beginPath();
+      ctx.arc(cx, cy, globeRadius, 0, TAU);
+      ctx.clip();
+    } else {
+      ctx.beginPath();
+      ctx.rect(0, 0, w, h);
+      ctx.clip();
+    }
+
+    ctx.lineJoin = "round";
+    for (const bin of bins) {
+      const value = bin[metric];
+      ctx.beginPath();
+      for (let i = 0; i < 6; i++) {
+        const angle = (60 * i - 30) * D2R;
+        const x = bin.x + drawRadius * Math.cos(angle);
+        const y = bin.y + drawRadius * Math.sin(angle);
+        i ? ctx.lineTo(x, y) : ctx.moveTo(x, y);
+      }
+      ctx.closePath();
+      ctx.globalAlpha = clamp(o.opacity ?? 0.82, 0, 1);
+      ctx.fillStyle = scale(value) || o.color || t.marker;
+      ctx.fill();
+      if ((o.strokeWidth ?? 0.8) > 0) {
+        ctx.globalAlpha = 1;
+        ctx.strokeStyle = o.stroke || withAlpha(t.label, 0.3);
+        ctx.lineWidth = o.strokeWidth ?? 0.8;
+        ctx.stroke();
+      }
+      if (o.showCount && drawRadius >= 10) {
+        ctx.globalAlpha = 1;
+        ctx.fillStyle = o.labelColor || t.label;
+        ctx.font = `600 ${Math.max(9, Math.min(13, drawRadius * 0.7))}px Inter,system-ui,sans-serif`;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "middle";
+        ctx.fillText(String(value), bin.x, bin.y);
+      }
+      hits.push({
+        marker: {
+          hexBin: true,
+          count: bin.count,
+          value: bin.value,
+          markerCount: bin.count,
+          markers: bin.markers,
+          lon: bin.lon,
+          lat: bin.lat,
+        },
+        x: bin.x,
+        y: bin.y,
+        r: drawRadius,
+      });
+    }
+    ctx.restore();
+    this._lastHexBins = bins;
+    return hits;
+  }
+
   /** Spike height for a marker, as a fraction of the globe radius. */
   _spikeLift(m) {
     if (!this.o.spikes) return 0;
@@ -2801,9 +3050,11 @@ export class GeoGlobe {
       pts.push({ m, x: cx + x, y: cy + y, depth: 0.65 + c * 0.35 });
     }
     if (this.o.heatmap) this._paintHeatmap(pts, t);
+    const binHits = this.o.hexBins ? this._paintHexBins(pts, t, cx, cy, r, w, h) : [];
     if (this.o.spikes) this._paintSpikes(t, cx, cy, r, w, h, null);
     this._paintViewerAccuracy(t, cx, cy, r, null);
-    const hits = this._paintMarkers(pts, t);
+    const showMarkers = !this.o.hexBins || (this.o.hexBins !== true && this.o.hexBins.hideMarkers === false);
+    const hits = [...binHits, ...(showMarkers ? this._paintMarkers(pts, t) : [])];
     if (this.o.labels) this._paintLabels(pts, t, cx, cy, r, w, h);
     this._paintAnnotations(t);
     this._paintPings(t);
@@ -2878,9 +3129,11 @@ export class GeoGlobe {
       pts.push({ m, x, y, depth: 1 });
     }
     if (this.o.heatmap) this._paintHeatmap(pts, t);
+    const binHits = this.o.hexBins ? this._paintHexBins(pts, t, 0, 0, 0, w, h) : [];
     if (this.o.spikes) this._paintSpikes(t, 0, 0, 0, w, h, fwd);
     this._paintViewerAccuracy(t, 0, 0, 0, fwd);
-    const hits = this._paintMarkers(pts, t);
+    const showMarkers = !this.o.hexBins || (this.o.hexBins !== true && this.o.hexBins.hideMarkers === false);
+    const hits = [...binHits, ...(showMarkers ? this._paintMarkers(pts, t) : [])];
     if (this.o.labels) this._paintLabels(pts, t, 0, 0, 0, w, h);
     this._paintAnnotations(t);
     this._paintPings(t);
@@ -3001,7 +3254,7 @@ export class GeoGlobe {
     }
 
     if (m.live && !this._reducedMotion()) {
-      const pulse = (Date.now() % 2200) / 2200;
+      const pulse = (this._animTime() % 2200) / 2200;
       ctx.globalAlpha = 1 - pulse;
       ctx.strokeStyle = t.live;
       ctx.lineWidth = 1.4 * scale;

package/src/geo.js

@@ -254,6 +254,76 @@ export const withAlpha = (color, a) => {
   return color;
 };
 
+/**
+ * Aggregates projected points into a pointy-top hexagonal grid.
+ *
+ * The input is deliberately renderer-shaped (`{ x, y, depth, m }`) so the
+ * same helper works after either globe or flat-map projection. Each returned
+ * bin preserves its source markers for tooltips, clicks, and custom details.
+ */
+export const hexBinPoints = (points = [], radius = 18) => {
+  const size = Math.max(1, Number(radius) || 18);
+  const sqrt3 = Math.sqrt(3);
+  const cells = new Map();
+
+  const roundAxial = (q, r) => {
+    let x = q;
+    let z = r;
+    let y = -x - z;
+    let rx = Math.round(x);
+    let ry = Math.round(y);
+    let rz = Math.round(z);
+    const dx = Math.abs(rx - x);
+    const dy = Math.abs(ry - y);
+    const dz = Math.abs(rz - z);
+    if (dx > dy && dx > dz) rx = -ry - rz;
+    else if (dy > dz) ry = -rx - rz;
+    else rz = -rx - ry;
+    return [rx, rz];
+  };
+
+  for (const point of points) {
+    if (!Number.isFinite(point?.x) || !Number.isFinite(point?.y)) continue;
+    const q = (sqrt3 / 3 * point.x - point.y / 3) / size;
+    const r = (2 * point.y / 3) / size;
+    const [hq, hr] = roundAxial(q, r);
+    const key = `${hq}:${hr}`;
+    let cell = cells.get(key);
+    if (!cell) {
+      cell = {
+        q: hq,
+        r: hr,
+        x: size * sqrt3 * (hq + hr / 2),
+        y: size * 1.5 * hr,
+        count: 0,
+        value: 0,
+        depth: 0,
+        lon: 0,
+        lat: 0,
+        weight: 0,
+        markers: [],
+      };
+      cells.set(key, cell);
+    }
+    const marker = point.m || {};
+    const value = Number(marker.count);
+    const weight = Number.isFinite(value) && value > 0 ? value : 1;
+    cell.count += 1;
+    cell.value += weight;
+    cell.depth = Math.max(cell.depth, Number(point.depth) || 0);
+    cell.lon += (Number(marker.lon) || 0) * weight;
+    cell.lat += (Number(marker.lat) || 0) * weight;
+    cell.weight += weight;
+    cell.markers.push(marker);
+  }
+
+  return [...cells.values()].map((cell) => ({
+    ...cell,
+    lon: cell.weight ? cell.lon / cell.weight : 0,
+    lat: cell.weight ? cell.lat / cell.weight : 0,
+  }));
+};
+
 const parseRGB = (color) => {
   if (color.startsWith("#")) {
     const hex = color.length === 4 ? color.replace(/#(.)(.)(.)/, "#$1$1$2$2$3$3") : color;

package/src/places.js

@@ -0,0 +1,97 @@
+/**
+ * City search.
+ *
+ * An optional table of roughly 6,700 populated places  -  every national and
+ * state capital, plus the most populous cities worldwide. Import it only if
+ * you need it: it is about as large as the country geometry, and the core
+ * library already resolves countries and ~300 major cities for free through
+ * `geocode()`.
+ *
+ *   import { searchPlaces, placeSource } from "canvas-globe/places";
+ *   import { searchAndFly } from "canvas-globe/controls";
+ *
+ *   searchAndFly(globe, input, { source: placeSource() });
+ *
+ * For the long tail  -  every hamlet and village  -  point `source` at GeoNames,
+ * Nominatim or your own index instead. Nothing here needs to change.
+ */
+import { placeTable } from "./data/places.js";
+
+let index = null;
+
+/** Lowercase and strip accents, so "São Paulo" answers to "sao paulo". */
+export const fold = (s) =>
+  String(s)
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase()
+    .trim();
+
+const parse = () => {
+  if (index) return index;
+  index = [];
+  for (const row of placeTable.split(";")) {
+    const [name, lon, lat, country, pop, region] = row.split("|");
+    if (!name) continue;
+    index.push({
+      name,
+      key: fold(name),
+      lon: Number(lon) / 100,
+      lat: Number(lat) / 100,
+      country,
+      region: region || "",
+      population: Number(pop) * 1000,
+    });
+  }
+  return index;
+};
+
+const decorate = (p) => ({
+  ...p,
+  label: p.region ? `${p.name}, ${p.region}, ${p.country}` : `${p.name}, ${p.country}`,
+});
+
+/**
+ * Places matching `query`, best first.
+ *
+ * Names that start with the query always outrank names that merely contain
+ * it, so "york" still puts York above New York. Population breaks ties, which
+ * is what makes "london" mean the British one.
+ *
+ * At this table size a linear scan costs well under a millisecond, so there
+ * is no prefix tree to build or keep in sync. Build one only if you swap in a
+ * table an order of magnitude larger.
+ */
+export function searchPlaces(query, { limit = 8, country, contains = true } = {}) {
+  const q = fold(query);
+  if (!q) return [];
+  const hits = [];
+  for (const place of parse()) {
+    if (country && place.country !== country) continue;
+    const at = place.key.indexOf(q);
+    if (at < 0) continue;
+    if (at > 0 && !contains) continue;
+    hits.push({ place, tier: at === 0 ? 0 : 1, exact: place.key === q });
+  }
+  return hits
+    .sort((a, b) =>
+      a.tier - b.tier ||
+      b.exact - a.exact ||
+      b.place.population - a.place.population)
+    .slice(0, limit)
+    .map((h) => decorate(h.place));
+}
+
+/** Coordinate for an exact-ish name, matching the shape of `geocode()`. */
+export function placePoint(name, options) {
+  const [hit] = searchPlaces(name, { contains: false, ...options, limit: 1 });
+  return hit ? { lon: hit.lon, lat: hit.lat } : null;
+}
+
+/** Ready-made resolver for `searchAndFly({ source })`. */
+export function placeSource(options) {
+  return (query) => searchPlaces(query, options);
+}
+
+/** How many places the bundled table holds. */
+export const placeCount = () => parse().length;