@asterisk-labs/rumi 0.0.0-stage → 0.27.0-alpha.1

package/playground/app.js

@@ -0,0 +1,374 @@
+import { openRumi } from "/rumi/index.js";
+import * as maplibregl from "https://cdn.jsdelivr.net/npm/maplibre-gl@6.9.0/dist/maplibre-gl.mjs";
+import { affineCorners, rasterRgba } from "./render.js";
+
+const SOURCE = "rumi-image";
+const LAYER = "rumi-image";
+const PROJ4_URL = "https://cdn.jsdelivr.net/npm/proj4@2.15.0/+esm";
+const DATE_LIMIT_MS = 8_640_000_000_000_000n;
+const MAX_PREVIEW_PIXELS = 2048 * 2048;
+
+const element = Object.fromEntries([
+  "url-form", "rumi-url", "file-input", "status", "message", "controls",
+  "source-name", "source-info", "time-field", "time", "band-fields", "red",
+  "green", "blue", "opacity", "opacity-value", "render", "close", "busy",
+  "drop-zone", "metadata-panel", "metadata-title", "metadata-body",
+  "show-metadata",
+].map((id) => [id.replaceAll("-", ""), document.getElementById(id)]));
+
+const map = new maplibregl.Map({
+  container: "map",
+  center: [-76.9, -12.05],
+  zoom: 8,
+  attributionControl: false,
+  style: {
+    version: 8,
+    sources: {
+      basemap: {
+        type: "raster",
+        tiles: ["https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}"],
+        tileSize: 256,
+        maxzoom: 16,
+      },
+      labels: {
+        type: "raster",
+        tiles: ["https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Reference/MapServer/tile/{z}/{y}/{x}"],
+        tileSize: 256,
+        maxzoom: 16,
+      },
+    },
+    layers: [
+      { id: "basemap", type: "raster", source: "basemap" },
+      { id: "labels", type: "raster", source: "labels" },
+    ],
+  },
+});
+map.addControl(new maplibregl.NavigationControl(), "bottom-right");
+const mapReady = new Promise((resolve) => map.on("load", resolve));
+let dataset;
+
+function setStatus(text, state = "ready") {
+  element.status.className = `status ${state}`;
+  element.status.querySelector("span").textContent = text;
+}
+
+function showError(text) {
+  element.message.textContent = text;
+  element.message.className = "message error";
+  element.message.hidden = false;
+  setStatus("Error", "error");
+}
+
+function clearMessage() {
+  element.message.hidden = true;
+  element.message.textContent = "";
+}
+
+function busy(active) {
+  element.busy.hidden = !active;
+}
+
+function formatInstant(seconds) {
+  const milliseconds = seconds * 1000n;
+  if (milliseconds >= -DATE_LIMIT_MS && milliseconds <= DATE_LIMIT_MS) {
+    return new Date(Number(milliseconds)).toISOString().replace(".000Z", "Z");
+  }
+  return `${seconds} seconds since 1970-01-01T00:00:00Z`;
+}
+
+function formatTime(value) {
+  return Array.isArray(value)
+    ? `${formatInstant(value[0])} — ${formatInstant(value[1])}`
+    : formatInstant(value);
+}
+
+function optionText(label, index) {
+  return label ? `${index} · ${label}` : `Band ${index}`;
+}
+
+function bandOptions(select, labels, count, selected) {
+  select.replaceChildren(...Array.from({ length: count }, (_, band) => {
+    const option = document.createElement("option");
+    option.value = band;
+    option.textContent = optionText(labels?.[band], band);
+    option.title = labels?.[band] ?? `Band ${band}`;
+    option.selected = band === selected;
+    return option;
+  }));
+}
+
+function namedBand(labels, expression, fallback, count) {
+  const found = labels?.findIndex((label) => expression.test(label)) ?? -1;
+  return found >= 0 ? found : Math.min(fallback, count - 1);
+}
+
+function metadataRow(name, value, code = false) {
+  const row = document.createElement("div");
+  row.className = "metadata-row";
+  const term = document.createElement("dt");
+  term.textContent = name;
+  const description = document.createElement("dd");
+  if (code) {
+    const block = document.createElement("span");
+    block.className = "code-value";
+    block.textContent = value;
+    description.append(block);
+  } else {
+    description.textContent = value;
+  }
+  row.append(term, description);
+  return row;
+}
+
+function metadataGroup(title, rows) {
+  const section = document.createElement("section");
+  section.className = "metadata-group";
+  const heading = document.createElement("h3");
+  heading.textContent = title;
+  const list = document.createElement("dl");
+  for (const row of rows) list.append(metadataRow(...row));
+  section.append(heading, list);
+  return section;
+}
+
+function bandGroup(labels, count) {
+  const section = document.createElement("section");
+  section.className = "metadata-group";
+  const heading = document.createElement("h3");
+  heading.textContent = `Bands · ${count}`;
+  const list = document.createElement("ol");
+  list.className = "band-list";
+  for (let band = 0; band < count; band += 1) {
+    const item = document.createElement("li");
+    const index = document.createElement("b");
+    index.textContent = String(band).padStart(2, "0");
+    const text = document.createElement("span");
+    text.textContent = labels?.[band] ?? `Band ${band}`;
+    item.append(index, text);
+    list.append(item);
+  }
+  section.append(heading, list);
+  return section;
+}
+
+function showMetadata(info, name) {
+  const bandCount = info.shape.length === 3 ? info.shape[0] : info.shape[1];
+  const timeCount = info.shape.length === 4 ? info.shape[0] : 1;
+  element.metadatatitle.textContent = name;
+  element.metadatabody.replaceChildren(
+    metadataGroup("Array", [
+      ["Shape", info.shape.join(" × ")],
+      ["Axes", info.axes.join(" · ")],
+      ["Data type", `${info.dtype.name} · ${info.dtype.bits} bit`],
+      ["Tile", info.tileShape.join(" × ")],
+      ["Tile grid", info.gridShape.join(" × ")],
+      ["Frame layout", info.frameLayout],
+      ["Frames", String(info.frameCount)],
+    ]),
+    metadataGroup("Acquisition", [
+      ["Kind", info.timeKind ?? "Unavailable"],
+      ["Steps", String(timeCount)],
+      ...(info.time?.map((value, index) => [`Time ${index}`, formatTime(value)]) ?? []),
+    ]),
+    metadataGroup("Georeferencing", [
+      ["CRS", info.crs ?? "Undefined"],
+      ["Raster type", info.pixelIsPoint ? "Pixel is point" : "Pixel is area"],
+      ["Transform", info.transform?.map((value) => Number(value).toPrecision(10)).join(", ") ?? "Undefined", true],
+    ]),
+    bandGroup(info.bands, bandCount),
+  );
+  element.metadatapanel.hidden = false;
+  element.metadatapanel.setAttribute("aria-hidden", "false");
+  requestAnimationFrame(() => element.metadatapanel.classList.add("open"));
+}
+
+function setupControls(info, name) {
+  const bandCount = info.shape.length === 3 ? info.shape[0] : info.shape[1];
+  const timeCount = info.shape.length === 4 ? info.shape[0] : 1;
+  element.sourcename.textContent = name;
+  element.sourceinfo.textContent = `${info.shape.join(" × ")} · ${info.dtype.name} · ${info.crs ?? "no CRS"}`;
+  element.timefield.hidden = info.time === null;
+  element.time.replaceChildren(...Array.from({ length: timeCount }, (_, time) => {
+    const option = document.createElement("option");
+    option.value = time;
+    option.textContent = info.time?.[time] !== undefined ? formatTime(info.time[time]) : `Time ${time}`;
+    return option;
+  }));
+  const red = namedBand(info.bands, /^B0?4\b/i, 0, bandCount);
+  const green = namedBand(info.bands, /^B0?3\b/i, 1, bandCount);
+  const blue = namedBand(info.bands, /^B0?2\b/i, 2, bandCount);
+  bandOptions(element.red, info.bands, bandCount, red);
+  bandOptions(element.green, info.bands, bandCount, green);
+  bandOptions(element.blue, info.bands, bandCount, blue);
+  element.bandfields.hidden = bandCount === 1;
+  element.controls.hidden = false;
+  showMetadata(info, name);
+}
+
+function supportedDtype(dtype) {
+  return !dtype.name.startsWith("complex")
+    && !dtype.name.startsWith("float8")
+    && !["float16", "bfloat16"].includes(dtype.name);
+}
+
+async function projector(epsg) {
+  if (epsg === 4326) return (point) => point;
+  if (epsg === 3857) {
+    return ([x, y]) => [
+      (x / 6378137) * (180 / Math.PI),
+      (2 * Math.atan(Math.exp(y / 6378137)) - Math.PI / 2) * (180 / Math.PI),
+    ];
+  }
+  const north = epsg >= 32601 && epsg <= 32660;
+  const south = epsg >= 32701 && epsg <= 32760;
+  if (!north && !south) throw new Error(`The viewer cannot project EPSG:${epsg} yet.`);
+  const zone = epsg - (south ? 32700 : 32600);
+  const proj4 = (await import(PROJ4_URL)).default;
+  const definition = `+proj=utm +zone=${zone}${south ? " +south" : ""} +datum=WGS84 +units=m +no_defs`;
+  return (point) => proj4(definition, "EPSG:4326", point);
+}
+
+async function imageCorners(info) {
+  if (info.transform && info.epsg) {
+    const toLonLat = await projector(info.epsg);
+    return {
+      corners: affineCorners(info.transform, info.shape.at(-1), info.shape.at(-2)).map(toLonLat),
+      fallback: false,
+    };
+  }
+  const bounds = map.getBounds();
+  return {
+    corners: [bounds.getNorthWest(), bounds.getNorthEast(), bounds.getSouthEast(), bounds.getSouthWest()]
+      .map(({ lng, lat }) => [lng, lat]),
+    fallback: true,
+  };
+}
+
+async function render() {
+  if (!dataset) return;
+  busy(true);
+  clearMessage();
+  setStatus("Rendering", "loading");
+  try {
+    const info = dataset.info();
+    if (!supportedDtype(info.dtype)) throw new Error(`${info.dtype.name} rendering is not supported yet.`);
+    const bandCount = info.shape.length === 3 ? info.shape[0] : info.shape[1];
+    const width = info.shape.at(-1);
+    const height = info.shape.at(-2);
+    if (width * height > MAX_PREVIEW_PIXELS) {
+      throw new Error("This image is too large for the browser preview (maximum 2048 × 2048 pixels).");
+    }
+    const bands = bandCount === 1
+      ? [0]
+      : [element.red, element.green, element.blue].map((select) => Number(select.value));
+    const result = await dataset.read({
+      time: [Number(element.time.value || 0)],
+      bands,
+    });
+    const image = rasterRgba(result.data, width, height, bands.length);
+    const canvas = document.createElement("canvas");
+    canvas.width = image.width;
+    canvas.height = image.height;
+    canvas.getContext("2d").putImageData(new ImageData(image.rgba, image.width, image.height), 0, 0);
+    const placement = await imageCorners(info);
+
+    await mapReady;
+    if (map.getLayer(LAYER)) map.removeLayer(LAYER);
+    if (map.getSource(SOURCE)) map.removeSource(SOURCE);
+    map.addSource(SOURCE, { type: "image", url: canvas.toDataURL(), coordinates: placement.corners });
+    map.addLayer({
+      id: LAYER,
+      type: "raster",
+      source: SOURCE,
+      paint: { "raster-opacity": Number(element.opacity.value) / 100, "raster-fade-duration": 0 },
+    }, "labels");
+    const bounds = new maplibregl.LngLatBounds();
+    placement.corners.forEach((corner) => bounds.extend(corner));
+    const padding = window.innerWidth > 900
+      ? { top: 70, right: 420, bottom: 70, left: 380 }
+      : 45;
+    map.fitBounds(bounds, { padding, maxZoom: 15, duration: 700 });
+    setStatus(placement.fallback ? "No CRS" : "Rendered", "ready");
+  } catch (error) {
+    showError(error.message ?? String(error));
+  } finally {
+    busy(false);
+  }
+}
+
+async function openSource(source, name) {
+  busy(true);
+  clearMessage();
+  setStatus("Reading", "loading");
+  try {
+    dataset = await openRumi(source);
+    setupControls(dataset.info(), name);
+    await render();
+  } catch (error) {
+    dataset = undefined;
+    element.controls.hidden = true;
+    element.metadatapanel.hidden = true;
+    showError(error.message ?? String(error));
+  } finally {
+    busy(false);
+  }
+}
+
+function hideMetadata() {
+  element.metadatapanel.classList.remove("open");
+  element.metadatapanel.setAttribute("aria-hidden", "true");
+  setTimeout(() => {
+    if (!element.metadatapanel.classList.contains("open")) element.metadatapanel.hidden = true;
+  }, 200);
+}
+
+element.urlform.addEventListener("submit", (event) => {
+  event.preventDefault();
+  const url = element.rumiurl.value.trim();
+  if (url) void openSource(url, url.split("/").pop() || url);
+});
+
+element.fileinput.addEventListener("change", () => {
+  const [file] = element.fileinput.files;
+  if (file) void openSource(file, file.name);
+});
+
+let dragDepth = 0;
+document.addEventListener("dragenter", (event) => {
+  event.preventDefault();
+  dragDepth += 1;
+  element.dropzone.hidden = false;
+});
+document.addEventListener("dragover", (event) => event.preventDefault());
+document.addEventListener("dragleave", (event) => {
+  event.preventDefault();
+  dragDepth = Math.max(0, dragDepth - 1);
+  if (dragDepth === 0) element.dropzone.hidden = true;
+});
+document.addEventListener("drop", (event) => {
+  event.preventDefault();
+  dragDepth = 0;
+  element.dropzone.hidden = true;
+  const file = [...event.dataTransfer.files].find((candidate) => candidate.name.endsWith(".rumi"));
+  if (file) void openSource(file, file.name);
+  else showError("Drop a .rumi file.");
+});
+
+element.render.addEventListener("click", () => void render());
+element.opacity.addEventListener("input", () => {
+  element.opacityvalue.value = `${element.opacity.value}%`;
+  if (map.getLayer(LAYER)) map.setPaintProperty(LAYER, "raster-opacity", Number(element.opacity.value) / 100);
+});
+element.close.addEventListener("click", hideMetadata);
+element.showmetadata.addEventListener("click", () => {
+  if (!dataset) return;
+  element.metadatapanel.hidden = false;
+  element.metadatapanel.setAttribute("aria-hidden", "false");
+  requestAnimationFrame(() => element.metadatapanel.classList.add("open"));
+});
+
+const initialUrl = new URL(window.location.href).searchParams.get("url");
+if (initialUrl) {
+  element.rumiurl.value = initialUrl;
+  void openSource(initialUrl, initialUrl.split("/").pop() || initialUrl);
+}

package/playground/asterisk-mark.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 109.05 22.32" role="img" aria-label="Asterisk Labs">
+  <style>
+    path[fill="#E6EDF3"] { fill: #1a1a1a }
+    path[fill="#0D1117"] { fill: #fff }
+    text { fill: #1a1a1a }
+  </style>
+  <path fill="#E6EDF3" d="M9.08,3.27c.38-.22,1-.22,1.38,0l5.79,3.35c.38.22.69.76.69,1.2v6.69c0,.44-.31.98-.69,1.2l-5.79,3.35c-.38.22-1,.22-1.38,0l-5.79-3.35c-.38-.22-.69-.76-.69-1.2v-6.69c0-.44.31-.98.69-1.2l5.79-3.35Z"/>
+  <path fill="#E6EDF3" d="M9.42.08c.19-.11.5-.11.69,0l1.9,1.1c.19.11.35.38.35.6v2.19c0,.22-.16.49-.35.6l-1.9,1.1c-.19.11-.5.11-.69,0l-1.9-1.1c-.19-.11-.35-.38-.35-.6V1.78c0-.22.16-.49.35-.6L9.42.08Z"/>
+  <path fill="#E6EDF3" d="M16.6,12.49c.19-.11.5-.11.69,0l1.9,1.1c.19.11.35.38.35.6v2.19c0,.22-.16.49-.35.6l-1.9,1.1c-.19.11-.5.11-.69,0l-1.9-1.1c-.19-.11-.35-.38-.35-.6v-2.19c0-.22.16-.49.35-.6l1.9-1.1Z"/>
+  <path fill="#E6EDF3" d="M2.25,4.18c.19-.11.5-.11.69,0l1.9,1.1c.19.11.35.38.35.6v2.19c0,.22-.16.49-.35.6l-1.9,1.1c-.19.11-.5.11-.69,0l-1.9-1.1c-.19-.11-.35-.38-.35-.6v-2.19c0-.22.16-.49.35-.6l1.9-1.1Z"/>
+  <path fill="#E6EDF3" d="M16.6,4.18c.19-.11.5-.11.69,0l1.9,1.1c.19.11.35.38.35.6v2.19c0,.22-.16.49-.35.6l-1.9,1.1c-.19.11-.5.11-.69,0l-1.9-1.1c-.19-.11-.35-.38-.35-.6v-2.19c0-.22.16-.49.35-.6l1.9-1.1Z"/>
+  <path fill="#E6EDF3" d="M9.42,16.65c.19-.11.5-.11.69,0l1.9,1.1c.19.11.35.38.35.6v2.19c0,.22-.16.49-.35.6l-1.9,1.1c-.19.11-.5.11-.69,0l-1.9-1.1c-.19-.11-.35-.38-.35-.6v-2.19c0-.22.16-.49.35-.6l1.9-1.1Z"/>
+  <path fill="#E6EDF3" d="M2.25,12.49c.19-.11.5-.11.69,0l1.9,1.1c.19.11.35.38.35.6v2.19c0,.22-.16.49-.35.6l-1.9,1.1c-.19.11-.5.11-.69,0l-1.9-1.1c-.19-.11-.35-.38-.35-.6v-2.19c0-.22.16-.49.35-.6l1.9-1.1Z"/>
+  <path fill="#0D1117" d="M9.1,6.25c.36-.21.96-.21,1.32,0l3.26,1.88c.36.21.66.73.66,1.15v3.77c0,.42-.3.94-.66,1.15l-3.26,1.88c-.36.21-.96.21-1.32,0l-3.26-1.88c-.36-.21-.66-.73-.66-1.15v-3.77c0-.42.3-.94.66-1.15l3.26-1.88Z"/>
+  <path fill="#F8CE00" d="M9.76,1.04h.02l1.58.91v1.84l-1.58.91h-.02l-1.58-.91V1.95l1.58-.91Z"/>
+  <path fill="#A2FFA2" d="M2.58,5.14h.02l1.58.91v1.84L2.6,8.8h-.02L1,7.89V6.05l1.58-.91Z"/>
+  <path fill="#4E04EB" d="M16.93,5.14h.02l1.58.91v1.84l-1.58.91h-.02l-1.58-.91V6.05l1.58-.91Z"/>
+  <path fill="#4E04EB" d="M9.76,17.61h.02l1.58.91v1.84l-1.58.91h-.02l-1.58-.91v-1.84l1.58-.91Z"/>
+  <path fill="#F8CE00" d="M2.58,13.45h.02l1.58.91v1.84l-1.58.91h-.02L1,16.2v-1.84l1.58-.91Z"/>
+  <path fill="#A2FFA2" d="M16.93,13.45h.02l1.58.91v1.84l-1.58.91h-.02l-1.58-.91v-1.84l1.58-.91Z"/>
+  <text font-family="Futura,'Century Gothic',system-ui,sans-serif" font-size="15.36" font-weight="500" transform="translate(23.89 15.47)"><tspan x="0" y="0">asterisk labs</tspan></text>
+</svg>

package/playground/index.html

@@ -0,0 +1,101 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="Open and inspect a Rumi image on a MapLibre map.">
+  <title>Rumi viewer</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.9.0/dist/maplibre-gl.css">
+  <link rel="stylesheet" href="./styles.css">
+</head>
+<body>
+  <header class="topbar">
+    <a class="brand" href="https://asterisk.coop/rumi/" target="_blank" rel="noopener noreferrer" aria-label="Rumi home">
+      <img src="./rumi-mark.svg" alt="">
+      <span><strong>RUMI</strong><small>viewer</small></span>
+    </a>
+
+    <form id="url-form" class="source-picker">
+      <input id="rumi-url" type="text" placeholder="https://example.com/image.rumi" aria-label="Rumi file URL" spellcheck="false">
+      <button class="primary" type="submit">Open</button>
+      <label class="file-button" for="file-input">
+        Local file
+        <input id="file-input" type="file" accept=".rumi,application/octet-stream">
+      </label>
+    </form>
+
+    <div id="status" class="status ready" role="status"><i></i><span>Ready</span></div>
+  </header>
+
+  <main>
+    <div id="map" aria-label="Rumi image map"></div>
+    <div id="message" class="message" hidden></div>
+
+    <section id="controls" class="render-panel" aria-labelledby="render-title" hidden>
+      <header>
+        <div><p>Display</p><h2 id="render-title">Band composition</h2></div>
+        <button id="show-metadata" class="panel-link" type="button">Metadata</button>
+      </header>
+      <div class="source-summary">
+        <strong id="source-name"></strong>
+        <span id="source-info"></span>
+      </div>
+      <div id="time-field" class="field" hidden>
+        <label for="time">Time</label>
+        <select id="time"></select>
+      </div>
+      <div id="band-fields" class="band-grid">
+        <div class="field"><label for="red">Red</label><select id="red"></select></div>
+        <div class="field"><label for="green">Green</label><select id="green"></select></div>
+        <div class="field"><label for="blue">Blue</label><select id="blue"></select></div>
+      </div>
+      <div class="opacity-field">
+        <label for="opacity">Opacity</label>
+        <output id="opacity-value">90%</output>
+        <input id="opacity" type="range" min="0" max="100" value="90">
+      </div>
+      <button id="render" class="render-button" type="button">Render bands</button>
+    </section>
+
+    <aside id="metadata-panel" class="metadata-panel" aria-labelledby="metadata-title" aria-hidden="true" hidden>
+      <header>
+        <div><p>Rumi metadata</p><h2 id="metadata-title">Image</h2></div>
+        <button id="close" class="icon-button" type="button" aria-label="Close metadata">×</button>
+      </header>
+      <div id="metadata-body" class="metadata-body"></div>
+    </aside>
+
+    <div id="drop-zone" class="drop-overlay" hidden>
+      <img src="./rumi-mark.svg" alt="">
+      <strong>Drop a .rumi file</strong>
+      <span>It stays in this browser.</span>
+    </div>
+
+    <div id="busy" class="loading" hidden>
+      <div class="rumi-loader" aria-hidden="true">
+        <img src="./rumi-mark.svg" alt="">
+        <div><span>🛰️</span></div>
+      </div>
+      <strong>Reading Rumi</strong>
+    </div>
+
+    <footer class="colophon">
+      <span>Made with</span>
+      <span class="heart" aria-label="love" role="img">♥</span>
+      <span>by</span>
+      <a class="by" href="https://asterisk.coop" target="_blank" rel="noopener noreferrer" aria-label="Asterisk Labs">
+        <img src="./asterisk-mark.svg" alt="Asterisk Labs">
+      </a>
+    </footer>
+  </main>
+
+  <script type="importmap">
+    {
+      "imports": {
+        "@asterisk-labs/geozl": "/geozl/geozl_api.js"
+      }
+    }
+  </script>
+  <script type="module" src="./app.js"></script>
+</body>
+</html>

package/playground/render.js

@@ -0,0 +1,65 @@
+const MAX_SAMPLES = 50_000;
+
+function numeric(value) {
+  return typeof value === "bigint" ? Number(value) : value;
+}
+
+function limits(data, offset, pixels) {
+  const step = Math.max(1, Math.ceil(pixels / MAX_SAMPLES));
+  const sample = [];
+  for (let index = 0; index < pixels; index += step) {
+    const value = numeric(data[offset + index]);
+    if (Number.isFinite(value)) sample.push(value);
+  }
+  if (sample.length === 0) return [0, 1];
+  sample.sort((a, b) => a - b);
+  const low = sample[Math.floor((sample.length - 1) * 0.02)];
+  const high = sample[Math.ceil((sample.length - 1) * 0.98)];
+  return low === high ? [low - 0.5, high + 0.5] : [low, high];
+}
+
+function byte(value, [low, high]) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, Math.min(1, (value - low) / (high - low))) * 255);
+}
+
+export function rasterRgba(data, width, height, planes, maxSize = 2048) {
+  const pixels = width * height;
+  if (planes !== 1 && planes !== 3) throw new Error("rendering needs one or three bands");
+  const scale = Math.min(1, maxSize / Math.max(width, height));
+  const outWidth = Math.max(1, Math.round(width * scale));
+  const outHeight = Math.max(1, Math.round(height * scale));
+  const stretches = Array.from({ length: planes }, (_, plane) => limits(data, plane * pixels, pixels));
+  const rgba = new Uint8ClampedArray(outWidth * outHeight * 4);
+
+  for (let y = 0; y < outHeight; y += 1) {
+    const sourceY = Math.min(height - 1, Math.floor(y / scale));
+    for (let x = 0; x < outWidth; x += 1) {
+      const sourceX = Math.min(width - 1, Math.floor(x / scale));
+      const sourcePixel = sourceY * width + sourceX;
+      const target = (y * outWidth + x) * 4;
+      if (planes === 1) {
+        const value = byte(numeric(data[sourcePixel]), stretches[0]);
+        rgba[target] = value;
+        rgba[target + 1] = value;
+        rgba[target + 2] = value;
+      } else {
+        for (let channel = 0; channel < 3; channel += 1) {
+          rgba[target + channel] = byte(
+            numeric(data[channel * pixels + sourcePixel]),
+            stretches[channel],
+          );
+        }
+      }
+      rgba[target + 3] = 255;
+    }
+  }
+  return { rgba, width: outWidth, height: outHeight, stretches };
+}
+
+export function affineCorners(transform, width, height) {
+  const [a, b, c, d, e, f] = transform;
+  return [[0, 0], [width, 0], [width, height], [0, height]].map(
+    ([column, row]) => [a * column + b * row + c, d * column + e * row + f],
+  );
+}

package/playground/rumi-mark.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-2 -2 104 104" role="img" aria-label="rumi">
+  <style>
+    polygon { stroke: #aeb2b6; stroke-opacity: .72; stroke-width: 1.35; stroke-linejoin: round; fill: #474a50; animation: lit 6s step-end infinite; }
+    .nw { --on: #7457ff; animation-delay: 0s }
+    .ne { --on: #ffd54a; animation-delay: 1.5s }
+    .se { --on: #91f2bc; animation-delay: 3s }
+    .sw { --on: #ff7a4f; animation-delay: 4.5s }
+    @keyframes lit { 0% { fill: var(--on) } 25%, 100% { fill: #474a50 } }
+    @media (prefers-reduced-motion: reduce) { polygon { animation: none } }
+  </style>
+  <polygon class="nw" points="0,0 47,0 43,38 0,32"/>
+  <polygon class="ne" points="47,0 100,0 100,55 70,50 43,38"/>
+  <polygon class="se" points="70,50 100,55 100,100 58,100 50,72"/>
+  <polygon class="sw" points="0,32 43,38 70,50 50,72 58,100 0,100"/>
+</svg>

package/playground/server.mjs

@@ -0,0 +1,80 @@
+import { createReadStream } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const javascript = path.resolve(here, "..");
+let installedGeoZL;
+try {
+  installedGeoZL = path.dirname(fileURLToPath(import.meta.resolve("@asterisk-labs/geozl")));
+} catch {}
+const candidates = [
+  process.env.GEOZL_WASM_DIR,
+  installedGeoZL,
+  path.resolve(here, "../../../../geozl/core/build-wasm/wasm"),
+  path.resolve(here, "../../../extern/geozl/core/build-wasm/wasm"),
+].filter(Boolean);
+let geozl;
+for (const candidate of candidates) {
+  try {
+    await access(path.join(candidate, "geozl_api.js"));
+    geozl = candidate;
+    break;
+  } catch {}
+}
+if (!geozl) throw new Error("GeoZL WASM build not found; set GEOZL_WASM_DIR");
+
+const sampleFlag = process.argv.indexOf("--sample");
+const sample = sampleFlag >= 0 ? path.resolve(process.argv[sampleFlag + 1]) : undefined;
+const port = Number(process.env.PORT || 4321);
+
+function inside(root, requestPath) {
+  const file = path.resolve(root, requestPath);
+  return file === root || file.startsWith(`${root}${path.sep}`) ? file : undefined;
+}
+
+function target(url) {
+  if (url === "/sample.rumi" && sample) return sample;
+  if (url.startsWith("/rumi/")) return inside(javascript, url.slice(6));
+  if (url.startsWith("/geozl/")) return inside(geozl, url.slice(7));
+  return inside(here, url === "/" ? "index.html" : url.slice(1));
+}
+
+http.createServer(async (request, response) => {
+  try {
+    const file = target(new URL(request.url, "http://localhost").pathname);
+    if (!file) return void response.writeHead(404).end("not found");
+    const info = await stat(file);
+    const match = /^bytes=(\d+)-(\d+)$/.exec(request.headers.range ?? "");
+    const extension = path.extname(file);
+    const type = extension === ".wasm" ? "application/wasm"
+      : extension === ".js" || extension === ".mjs" ? "text/javascript"
+      : extension === ".css" ? "text/css"
+      : extension === ".svg" ? "image/svg+xml"
+      : extension === ".html" ? "text/html; charset=utf-8"
+      : "application/octet-stream";
+    const headers = { "Accept-Ranges": "bytes", "Access-Control-Allow-Origin": "*", "Content-Type": type };
+    if (match) {
+      const start = Number(match[1]);
+      const end = Number(match[2]);
+      if (start > end || end >= info.size) {
+        return void response.writeHead(416, { "Content-Range": `bytes */${info.size}` }).end();
+      }
+      response.writeHead(206, {
+        ...headers,
+        "Content-Length": end - start + 1,
+        "Content-Range": `bytes ${start}-${end}/${info.size}`,
+      });
+      createReadStream(file, { start, end }).pipe(response);
+      return;
+    }
+    response.writeHead(200, { ...headers, "Content-Length": info.size });
+    createReadStream(file).pipe(response);
+  } catch (error) {
+    response.writeHead(404).end(error.message ?? String(error));
+  }
+}).listen(port, "127.0.0.1", () => {
+  console.log(`Rumi playground: http://127.0.0.1:${port}/`);
+});