@johnhenry/math-sample 0.0.0-stage → 0.1.0

package/src/svg.ts

@@ -0,0 +1,124 @@
+import { formatTick, niceTicks, tickStep } from "./ticks.ts";
+import { toScreenX, toScreenY, type Viewport } from "./viewport.ts";
+
+/** Anything with parallel `x` / `y` arrays, e.g. {@link Samples}. `NaN` in `y` breaks the path. */
+export interface XY {
+  x: ArrayLike<number>;
+  y: ArrayLike<number>;
+}
+
+export interface PathOptions {
+  /** Decimal places for screen coordinates. Default 2. */
+  digits?: number;
+}
+
+/**
+ * SVG path data (`d` attribute) for a sampled curve, mapped through the
+ * viewport to a `width` x `height` screen box. Each run of finite rows is one
+ * `M ... L ...` subpath, so gaps stay gaps. Empty input gives `""`.
+ */
+export function samplesToSvgPath(
+  samples: XY,
+  viewport: Viewport,
+  width: number,
+  height: number,
+  options: PathOptions = {},
+): string {
+  const digits = options.digits ?? 2;
+  const parts: string[] = [];
+  let pen = false;
+  const n = Math.min(samples.x.length, samples.y.length);
+  for (let i = 0; i < n; i++) {
+    const y = samples.y[i];
+    const x = samples.x[i];
+    if (!Number.isFinite(y) || !Number.isFinite(x)) {
+      pen = false;
+      continue;
+    }
+    const sx = toScreenX(x, viewport, width).toFixed(digits);
+    const sy = toScreenY(y, viewport, height).toFixed(digits);
+    parts.push(`${pen ? "L" : "M"}${sx} ${sy}`);
+    pen = true;
+  }
+  return parts.join(" ");
+}
+
+/** Escape a value for use inside a double-quoted SVG attribute, so a caller-supplied colour cannot break out of it. */
+function attr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export interface AxesOptions {
+  /** Approximate tick count per axis. Default 6. */
+  targetTickCount?: number;
+  /** Axis and tick colour. Default `#888`. */
+  stroke?: string;
+  /** Label colour. Default `#222`. */
+  labelFill?: string;
+  /** Label size in px. Default 11. */
+  fontSize?: number;
+}
+
+/**
+ * SVG elements (`<line>` and `<text>` with inline attributes, no stylesheet)
+ * for x/y axes with ticks and labels. An axis sits at data zero when that is
+ * on screen and otherwise hugs the nearest edge, labels flipping inward so
+ * they never clip. The origin is labelled once. Returns `""` for a
+ * degenerate viewport.
+ */
+export function axesToSvg(viewport: Viewport, width: number, height: number, options: AxesOptions = {}): string {
+  const { xMin, xMax, yMin, yMax } = viewport;
+  if (!(xMax > xMin) || !(yMax > yMin)) return "";
+  const stroke = attr(options.stroke ?? "#888");
+  const fill = attr(options.labelFill ?? "#222");
+  const fontSize = options.fontSize !== undefined && Number.isFinite(options.fontSize) ? options.fontSize : 11;
+  const count = options.targetTickCount ?? 6;
+  const half = 4;
+  const font = `font-size="${fontSize}" font-family="system-ui, sans-serif"`;
+
+  const xAxisAtBottom = yMin > 0;
+  const xAxisAtTop = yMax < 0;
+  const axisY = xAxisAtBottom ? height : xAxisAtTop ? 0 : toScreenY(0, viewport, height);
+  const yAxisAtRight = xMax < 0;
+  const yAxisAtLeft = xMin > 0;
+  const axisX = yAxisAtRight ? width : yAxisAtLeft ? 0 : toScreenX(0, viewport, width);
+
+  const out: string[] = [
+    `<line x1="0" y1="${axisY}" x2="${width}" y2="${axisY}" stroke="${stroke}" stroke-width="1" />`,
+    `<line x1="${axisX}" y1="0" x2="${axisX}" y2="${height}" stroke="${stroke}" stroke-width="1" />`,
+  ];
+
+  const xStep = tickStep(xMin, xMax, count);
+  const labelBelow = !xAxisAtBottom;
+  for (const v of niceTicks(xMin, xMax, count)) {
+    const sx = toScreenX(v, viewport, width);
+    out.push(
+      `<line x1="${sx.toFixed(2)}" y1="${(axisY - half).toFixed(2)}" x2="${sx.toFixed(2)}" y2="${(axisY + half).toFixed(2)}" stroke="${stroke}" stroke-width="1" />`,
+    );
+    if (v !== 0) {
+      const ty = axisY + (labelBelow ? half + 2 : -(half + 2));
+      out.push(
+        `<text x="${sx.toFixed(2)}" y="${ty.toFixed(2)}" fill="${fill}" ${font} text-anchor="middle" dominant-baseline="${labelBelow ? "hanging" : "auto"}">${formatTick(v, xStep)}</text>`,
+      );
+    }
+  }
+
+  const yStep = tickStep(yMin, yMax, count);
+  const labelLeft = !yAxisAtLeft;
+  for (const v of niceTicks(yMin, yMax, count)) {
+    const sy = toScreenY(v, viewport, height);
+    out.push(
+      `<line x1="${(axisX - half).toFixed(2)}" y1="${sy.toFixed(2)}" x2="${(axisX + half).toFixed(2)}" y2="${sy.toFixed(2)}" stroke="${stroke}" stroke-width="1" />`,
+    );
+    const tx = axisX + (labelLeft ? -(half + 4) : half + 4);
+    out.push(
+      `<text x="${tx.toFixed(2)}" y="${sy.toFixed(2)}" fill="${fill}" ${font} text-anchor="${labelLeft ? "end" : "start"}" dominant-baseline="middle">${formatTick(v, yStep)}</text>`,
+    );
+  }
+  return out.join("\n");
+}
+
+/** Wrap SVG `content` in a standalone `<svg>` document of the given size. */
+export function svgDocument(width: number, height: number, content: string): string {
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">\n${content}\n</svg>`;
+}

package/src/ticks.ts

@@ -0,0 +1,46 @@
+/**
+ * The step "nice numbers" tick generation uses for `[min, max]`: the value of
+ * 1, 2, 5 or 10 times a power of ten at or just above `(max - min) / targetCount`
+ * (rounded up, so there are never more than about `targetCount` ticks).
+ * Returns `NaN` for a degenerate range.
+ */
+export function tickStep(min: number, max: number, targetCount = 6): number {
+  if (!(max > min) || !Number.isFinite(max - min) || !(targetCount >= 1)) return Number.NaN;
+  const roughStep = (max - min) / targetCount;
+  const magnitude = 10 ** Math.floor(Math.log10(roughStep));
+  const residual = roughStep / magnitude;
+  const nice = residual > 5 ? 10 : residual > 2 ? 5 : residual > 1 ? 2 : 1;
+  return nice * magnitude;
+}
+
+/**
+ * Round tick values inside `[min, max]`, about `targetCount` of them (default
+ * 6). Ticks are integer multiples of the step, rounded to the step's own
+ * decimal places, so `0.1 * 3` reads `0.3` and not `0.30000000000000004`.
+ * Returns `[]` for a degenerate or non-finite range.
+ */
+export function niceTicks(min: number, max: number, targetCount = 6): number[] {
+  const step = tickStep(min, max, targetCount);
+  if (!Number.isFinite(step) || step < 1e-20) return []; // below this, fixed-point rounding would collapse every tick to 0
+  const decimals = decimalsOf(step);
+  const first = Math.ceil(min / step - 1e-9);
+  const last = Math.floor(max / step + 1e-9);
+  const ticks: number[] = [];
+  for (let i = first; i <= last; i++) ticks.push(roundTo(i * step, decimals));
+  return ticks;
+}
+
+/** A tick label with as many decimals as `step` needs, so a run of labels reads uniformly (`3.0, 3.5, 4.0`). */
+export function formatTick(value: number, step: number): string {
+  if (value === 0) return "0";
+  return value.toFixed(decimalsOf(step));
+}
+
+function decimalsOf(step: number): number {
+  return Math.min(20, Math.max(0, -Math.floor(Math.log10(step) + 1e-9)));
+}
+
+function roundTo(value: number, decimals: number): number {
+  const r = Number(value.toFixed(decimals));
+  return r === 0 ? 0 : r; // fold -0 into 0
+}

package/src/viewport.ts

@@ -0,0 +1,150 @@
+/** A rectangle of data space: the part of the plane a plot currently shows. */
+export interface Viewport {
+  xMin: number;
+  xMax: number;
+  yMin: number;
+  yMax: number;
+}
+
+/** Data x to a screen coordinate in `[0, width]` (left to right). */
+export function toScreenX(x: number, viewport: Viewport, width: number): number {
+  return ((x - viewport.xMin) / (viewport.xMax - viewport.xMin)) * width;
+}
+
+/** Data y to a screen coordinate in `[0, height]` (screen y grows downward, so this flips). */
+export function toScreenY(y: number, viewport: Viewport, height: number): number {
+  return height - ((y - viewport.yMin) / (viewport.yMax - viewport.yMin)) * height;
+}
+
+/** Inverse of {@link toScreenX}. */
+export function toDataX(sx: number, viewport: Viewport, width: number): number {
+  return viewport.xMin + (sx / width) * (viewport.xMax - viewport.xMin);
+}
+
+/** Inverse of {@link toScreenY}. */
+export function toDataY(sy: number, viewport: Viewport, height: number): number {
+  return viewport.yMin + ((height - sy) / height) * (viewport.yMax - viewport.yMin);
+}
+
+/**
+ * The viewport of the given data-space span in which data point
+ * (`anchorX`, `anchorY`) sits under screen point (`sx`, `sy`). Panning,
+ * wheel-zoom and pinch-zoom all reduce to this: panning keeps the span and
+ * moves the anchor's screen position; zooming keeps the anchor's screen
+ * position and changes the span.
+ */
+export function viewportFromAnchor(
+  anchorX: number,
+  anchorY: number,
+  sx: number,
+  sy: number,
+  spanX: number,
+  spanY: number,
+  width: number,
+  height: number,
+): Viewport {
+  const xMin = anchorX - (sx / width) * spanX;
+  const yMin = anchorY - ((height - sy) / height) * spanY;
+  return { xMin, xMax: xMin + spanX, yMin, yMax: yMin + spanY };
+}
+
+/**
+ * Pan by a pointer drag of (`dxPx`, `dyPx`) screen pixels: the content follows
+ * the pointer, so dragging right moves the window left and dragging down moves
+ * it up. Pixels are whatever unit `width`/`height` use (CSS px or device px,
+ * as long as they agree).
+ */
+export function panViewport(viewport: Viewport, dxPx: number, dyPx: number, width: number, height: number): Viewport {
+  const dx = (dxPx / width) * (viewport.xMax - viewport.xMin);
+  const dy = (dyPx / height) * (viewport.yMax - viewport.yMin);
+  return {
+    xMin: viewport.xMin - dx,
+    xMax: viewport.xMax - dx,
+    yMin: viewport.yMin + dy,
+    yMax: viewport.yMax + dy,
+  };
+}
+
+/**
+ * Scale both spans by `factor` (below 1 zooms in, above 1 zooms out) while
+ * keeping the data point under screen point (`sx`, `sy`) fixed there.
+ */
+export function zoomViewport(
+  viewport: Viewport,
+  factor: number,
+  sx: number,
+  sy: number,
+  width: number,
+  height: number,
+): Viewport {
+  const ax = toDataX(sx, viewport, width);
+  const ay = toDataY(sy, viewport, height);
+  return viewportFromAnchor(
+    ax,
+    ay,
+    sx,
+    sy,
+    (viewport.xMax - viewport.xMin) * factor,
+    (viewport.yMax - viewport.yMin) * factor,
+    width,
+    height,
+  );
+}
+
+/** Wheel step: scrolling down (`deltaY > 0`) zooms out (factor above 1), up zooms in. Feed to {@link zoomViewport}. */
+export function wheelZoomFactor(deltaY: number, step = 1.1): number {
+  return deltaY > 0 ? step : 1 / step;
+}
+
+/** Pinch span factor: fingers moving apart zoom in (factor below 1). Feed to {@link zoomViewport}. */
+export function pinchZoomFactor(startDistancePx: number, currentDistancePx: number): number {
+  return startDistancePx / currentDistancePx;
+}
+
+/**
+ * The viewport that bounds the finite `(x, y)` points, grown by `padding` (a
+ * fraction of each span, default 0.05). A degenerate extent (one point, or a
+ * constant) is widened to a span of 2 so the result is always drawable.
+ * Non-finite values (gaps) are ignored. With no finite points, returns `[-1, 1]^2`.
+ */
+export function fitViewport(x: ArrayLike<number>, y: ArrayLike<number>, padding = 0.05): Viewport {
+  let xMin = Number.POSITIVE_INFINITY;
+  let xMax = Number.NEGATIVE_INFINITY;
+  let yMin = Number.POSITIVE_INFINITY;
+  let yMax = Number.NEGATIVE_INFINITY;
+  const n = Math.min(x.length, y.length);
+  for (let i = 0; i < n; i++) {
+    const px = x[i];
+    const py = y[i];
+    if (!Number.isFinite(px) || !Number.isFinite(py)) continue;
+    if (px < xMin) xMin = px;
+    if (px > xMax) xMax = px;
+    if (py < yMin) yMin = py;
+    if (py > yMax) yMax = py;
+  }
+  if (xMin > xMax) return { xMin: -1, xMax: 1, yMin: -1, yMax: 1 };
+  const pad = (lo: number, hi: number): [number, number] => {
+    if (hi === lo) return [lo - 1, hi + 1];
+    const p = (hi - lo) * padding;
+    return [lo - p, hi + p];
+  };
+  const [x0, x1] = pad(xMin, xMax);
+  const [y0, y1] = pad(yMin, yMax);
+  return { xMin: x0, xMax: x1, yMin: y0, yMax: y1 };
+}
+
+/**
+ * Canvas backing-store size for a CSS-pixel box at a device pixel ratio:
+ * set `canvas.width/height` to `width`/`height` and `ctx.scale(scale, scale)`,
+ * then draw in CSS pixels. A non-finite or non-positive `dpr` is treated as 1.
+ * Sample against the CSS size (or the backing size) consistently; the
+ * viewport maths is unit-agnostic.
+ */
+export function backingStoreSize(
+  cssWidth: number,
+  cssHeight: number,
+  dpr: number,
+): { width: number; height: number; scale: number } {
+  const scale = Number.isFinite(dpr) && dpr > 0 ? dpr : 1;
+  return { width: Math.round(cssWidth * scale), height: Math.round(cssHeight * scale), scale };
+}