jspsych-tangram 0.0.1

package/src/core/engine/geometry/math.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure vector and polygon mathematical operations
+ * No game logic dependencies - just geometric math
+ */
+
+import type { Vec, Poly } from '@/core/domain/types';
+
+// ===== Constants =====
+
+export const EPS = 1e-6;
+
+// ===== Vector Operations =====
+
+export const vsub = (a: Vec, b: Vec): Vec => ({ x: a.x - b.x, y: a.y - b.y });
+export const vlen = (v: Vec) => Math.hypot(v.x, v.y);
+export const vscale = (v: Vec, s: number): Vec => ({ x: v.x * s, y: v.y * s });
+export const vadd = (a: Vec, b: Vec): Vec => ({ x: a.x + b.x, y: a.y + b.y });
+
+/** Squared distance between two points (faster than full distance) */
+export const dist2 = (a: Vec, b: Vec): number => {
+  const dx = a.x - b.x, dy = a.y - b.y;
+  return dx * dx + dy * dy;
+};
+
+/**
+ * Check if point p lies on the line segment from a to b (within epsilon tolerance)
+ */
+export function pointOnSegment(p: Vec, a: Vec, b: Vec, eps = 1e-9): boolean {
+  // collinear?
+  const cross = (b.y - a.y) * (p.x - a.x) - (b.x - a.x) * (p.y - a.y);
+  if (Math.abs(cross) > eps) return false;
+  // within bounding box?
+  const minX = Math.min(a.x, b.x) - eps, maxX = Math.max(a.x, b.x) + eps;
+  const minY = Math.min(a.y, b.y) - eps, maxY = Math.max(a.y, b.y) + eps;
+  return p.x >= minX && p.x <= maxX && p.y >= minY && p.y <= maxY;
+}
+
+/**
+ * Return an array of points subdividing the segment [a,b] into `n` equal parts (excluding `a`).
+ */
+export function subdivideSegment(a: Vec, b: Vec, n: number): Vec[] {
+  if (n <= 1) return [b];
+  const ab = vsub(b, a);
+  const step = 1 / n;
+  const pts: Vec[] = [];
+  for (let i = 1; i <= n; i++) pts.push(vadd(a, vscale(ab, step * i)));
+  return pts;
+}
+
+// ===== Polygon Operations =====
+
+/** Boundary-inclusive even–odd point-in-polygon test */
+export function pointInPolygon(pt: Vec, poly: Poly): boolean {
+  // 1) On-edge / on-vertex counts as inside
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const vertexJ = poly[j];
+    const vertexI = poly[i];
+    if (!vertexJ || !vertexI) continue;
+    if (pointOnSegment(pt, vertexJ, vertexI)) return true;
+  }
+
+  // 2) Standard even–odd ray casting (edges strictly above/below pivot)
+  // Using the common (yi > y) !== (yj > y) test avoids counting horizontal edges twice.
+  let inside = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const vertexI = poly[i];
+    const vertexJ = poly[j];
+    if (!vertexI || !vertexJ) continue;
+    const xi = vertexI.x, yi = vertexI.y;
+    const xj = vertexJ.x, yj = vertexJ.y;
+
+    const intersects = (yi > pt.y) !== (yj > pt.y)
+      && pt.x < ((xj - xi) * (pt.y - yi)) / (yj - yi + 1e-12) + xi;
+
+    if (intersects) inside = !inside;
+  }
+  return inside;
+}
+
+/** Project a polygon onto axis (nx, ny) and return min/max projection values */
+export function project(poly: Poly, nx: number, ny: number) {
+  let min = Infinity, max = -Infinity;
+  for (const p of poly) {
+    const s = p.x * nx + p.y * ny;
+    if (s < min) min = s;
+    if (s > max) max = s;
+  }
+  return { min, max };
+}
+
+/** Calculate axis-aligned bounding box for a polygon */
+export function polygonAABB(poly: Poly) {
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const pt of poly) {
+    if (pt.x < minX) minX = pt.x;
+    if (pt.y < minY) minY = pt.y;
+    if (pt.x > maxX) maxX = pt.x;
+    if (pt.y > maxY) maxY = pt.y;
+  }
+  return { minX, minY, maxX, maxY };
+}

package/src/core/engine/geometry/pieces.ts

@@ -0,0 +1,290 @@
+/**
+ * Game-specific piece geometry operations
+ * Includes: piece positioning, placement, grid snapping, and anchor generation
+ *
+ * Consolidated from: piece.ts, placement.ts, grid.ts, anchors.ts
+ */
+
+import type { Blueprint, Vec, Poly, Anchor } from "@/core/domain/types";
+import type { CircleLayout, SectorGeom } from "@/core/domain/layout";
+import { polysAABB } from "./bounds";
+import { pointInPolygon, dist2 } from "./math";
+import { CONFIG } from "@/core/config/config";
+
+const GRID_PX = CONFIG.layout.grid.stepPx;
+
+// ===== Piece Positioning (from piece.ts) =====
+
+/** Translate blueprint polys to world coords for a given top-left (TL). */
+export function piecePolysAt(
+  bp: Blueprint,
+  bb: { min: { x: number; y: number } },
+  tl: { x: number; y: number }
+) {
+  const ox = tl.x - bb.min.x;
+  const oy = tl.y - bb.min.y;
+  const polys = ("shape" in bp && bp.shape) ? bp.shape : [];
+  return polys.map(poly => poly.map(p => ({ x: p.x + ox, y: p.y + oy })));
+}
+
+/** Build support offsets: each vertex relative to the AABB center. */
+export function computeSupportOffsets(
+  bp: Blueprint,
+  bb: { min: { x: number; y: number }; width: number; height: number }
+) {
+  const cx = bb.min.x + bb.width / 2;
+  const cy = bb.min.y + bb.height / 2;
+
+  const polys = ("shape" in bp && bp.shape && bp.shape.length)
+    ? bp.shape
+    : [[
+        { x: bb.min.x,           y: bb.min.y },
+        { x: bb.min.x + bb.width,  y: bb.min.y },
+        { x: bb.min.x + bb.width,  y: bb.min.y + bb.height },
+        { x: bb.min.x,           y: bb.min.y + bb.height },
+      ]];
+
+  const offs: Vec[] = [];
+  for (const poly of polys) for (const v of poly) offs.push({ x: v.x - cx, y: v.y - cy });
+  return offs;
+}
+
+/** Clamp using directional vertex support → exact contact with the ring. */
+export function clampTopLeftBySupport(
+  tlx: number,
+  tly: number,
+  d: {
+    aabb: { width: number; height: number };
+    support: { x: number; y: number }[];
+  },
+  layout: CircleLayout,
+  target: "workspace" | "silhouette",
+  pointerInsideCenter: boolean
+) {
+  const cx0 = tlx + d.aabb.width / 2;
+  const cy0 = tly + d.aabb.height / 2;
+
+  const vx = cx0 - layout.cx;
+  const vy = cy0 - layout.cy;
+  const r  = Math.hypot(vx, vy);
+  if (r === 0) return { x: tlx, y: tly };
+
+  const ux = vx / r, uy = vy / r;
+
+  let h_out = -Infinity, h_in = -Infinity;
+  for (const o of d.support) {
+    const outProj = o.x * ux + o.y * uy;
+    if (outProj > h_out) h_out = outProj;
+    const inProj = -(o.x * ux + o.y * uy);
+    if (inProj > h_in) h_in = inProj;
+  }
+
+  if (target === "workspace") {
+    const [rIn, rOut] = layout.bands.workspace;
+    const minR = pointerInsideCenter ? 0 : (rIn + h_in);
+    const maxR = rOut - h_out;
+    const rClamped = Math.min(Math.max(r, minR), maxR);
+    if (Math.abs(rClamped - r) < 1e-6) return { x: tlx, y: tly };
+    const newCx = layout.cx + rClamped * ux;
+    const newCy = layout.cy + rClamped * uy;
+    return { x: newCx - d.aabb.width / 2, y: newCy - d.aabb.height / 2 };
+  } else {
+    const rOut = layout.bands.silhouette[1];
+    const maxR = rOut - h_out;
+    if (r <= maxR) return { x: tlx, y: tly };
+    const newCx = layout.cx + maxR * ux;
+    const newCy = layout.cy + maxR * uy;
+    return { x: newCx - d.aabb.width / 2, y: newCy - d.aabb.height / 2 };
+  }
+}
+
+// ===== Placement (from placement.ts) =====
+
+/** gcd for positive integers */
+function igcd(a: number, b: number) {
+  a = Math.round(Math.abs(a)); b = Math.round(Math.abs(b));
+  while (b) [a, b] = [b, a % b];
+  return a || 1;
+}
+
+/** Infer the base lattice unit in raw silhouette coordinates. */
+export function inferUnitFromPolys(polys: Poly[]): number {
+  let g = 0;
+  for (const poly of polys) {
+    for (let i = 0; i < poly.length; i++) {
+      const a = poly[i], b = poly[(i + 1) % poly.length];
+      if (!a || !b) continue;
+      const dx = Math.round(Math.abs(b.x - a.x));
+      const dy = Math.round(Math.abs(b.y - a.y));
+      if (dx) g = g ? igcd(g, dx) : dx;
+      if (dy) g = g ? igcd(g, dy) : dy;
+    }
+  }
+  return g || 1;
+}
+
+/**
+ * Place polys using scale S, re-centered, and translation snapped to GRID_PX; returns polys.
+ * The center is snapped to the grid so the lattice points under the silhouette stay invariant.
+ */
+export function placeSilhouetteGridAlignedAsPolys(
+  polys: Poly[],
+  S: number,
+  rectCenter: { cx: number; cy: number }
+): Poly[] {
+  if (!polys || polys.length === 0) return [];
+  const a = polysAABB(polys);
+  const cx0 = (a.min.x + a.max.x) / 2;
+  const cy0 = (a.min.y + a.max.y) / 2;
+  const cx = Math.round(rectCenter.cx / GRID_PX) * GRID_PX;
+  const cy = Math.round(rectCenter.cy / GRID_PX) * GRID_PX;
+  const tx = cx - S * cx0;
+  const ty = cy - S * cy0;
+  const stx = Math.round(tx / GRID_PX) * GRID_PX;
+  const sty = Math.round(ty / GRID_PX) * GRID_PX;
+  return polys.map(poly => poly.map(p => ({ x: S * p.x + stx, y: S * p.y + sty })));
+}
+
+// ===== Grid Operations (from grid.ts) =====
+
+export function nearestGridNode(p: Vec): Vec {
+  return { x: Math.round(p.x / GRID_PX) * GRID_PX, y: Math.round(p.y / GRID_PX) * GRID_PX };
+}
+
+/** Generate grid nodes inside an AABB. */
+export function gridNodesInAABB(min: Vec, max: Vec): Vec[] {
+  const out: Vec[] = [];
+  const x0 = Math.ceil(min.x / GRID_PX) * GRID_PX;
+  const y0 = Math.ceil(min.y / GRID_PX) * GRID_PX;
+  for (let y = y0; y <= max.y; y += GRID_PX) {
+    for (let x = x0; x <= max.x; x += GRID_PX) out.push({ x, y });
+  }
+  return out;
+}
+
+/** Keep nodes in a band (and optional sector wedge). */
+export function filterNodesToBandAndSector(
+  nodes: Vec[],
+  layout: CircleLayout,
+  band: "workspace" | "silhouette",
+  sector?: SectorGeom
+): Vec[] {
+  const [rIn, rOut] = layout.bands[band];
+  const out: Vec[] = [];
+  for (const n of nodes) {
+    const dx = n.x - layout.cx, dy = n.y - layout.cy;
+    const r = Math.hypot(dx, dy);
+    if (r < rIn || r > rOut) continue;
+
+    if (sector) {
+      let theta = Math.atan2(dy, dx);
+      if (layout.mode === "circle") {
+        if (theta < -Math.PI / 2) theta += 2 * Math.PI;
+      } else {
+        if (theta < Math.PI) theta += 2 * Math.PI;
+      }
+      if (theta < sector.start || theta >= sector.end) continue;
+    }
+    out.push(n);
+  }
+  return out;
+}
+
+/** Keep nodes that lie inside any of the polygons. */
+export function filterNodesInPolys(
+  nodes: Vec[],
+  polys: Poly[],
+  pointInPolyFn: (pt: Vec, poly: Poly) => boolean = pointInPolygon
+): Vec[] {
+  const out: Vec[] = [];
+  node: for (const n of nodes) {
+    for (const poly of polys) {
+      if (pointInPolyFn(n, poly)) { out.push(n); continue node; }
+    }
+  }
+  return out;
+}
+
+// ===== Anchor Operations (from anchors.ts) =====
+
+/**
+ * Find the nearest anchor that "accepts" a piece signature (kind/compositeSignature).
+ * Returns null if none within the optional radius.
+ */
+export function nearestAcceptingAnchor(
+  anchors: Anchor[] | undefined,
+  point: Vec,
+  accepts: { kind?: string; compositeSignature?: string },
+  withinPx: number = Infinity
+): { anchor: Anchor; d2: number } | null {
+  if (!anchors || !anchors.length) return null;
+
+  const { kind, compositeSignature } = accepts;
+  const r2 = withinPx === Infinity ? Infinity : withinPx * withinPx;
+
+  let best: { anchor: Anchor; d2: number } | null = null;
+  for (const a of anchors) {
+    const ok = a.accepts.some(acc =>
+      (acc.kind === undefined || acc.kind === kind) &&
+      (acc.compositeSignature === undefined || acc.compositeSignature === compositeSignature)
+    );
+    if (!ok) continue;
+
+    const d2val = dist2(point, a.position);
+    if (d2val <= r2 && (!best || d2val < best.d2)) {
+      best = { anchor: a, d2: d2val };
+    }
+  }
+  return best;
+}
+
+/** True if `point` is within `withinPx` of the given anchor. */
+export function withinAnchor(anchor: Anchor, point: Vec, withinPx: number): boolean {
+  const r2 = withinPx * withinPx;
+  return dist2(point, anchor.position) <= r2;
+}
+
+// Node-grid helpers for anchor generation
+export function workspaceNodes(layout: CircleLayout, sector: SectorGeom): Vec[] {
+  const pad = 6;
+  const min = { x: layout.cx - layout.outerR, y: layout.cy - layout.outerR - pad };
+  const max = { x: layout.cx + layout.outerR, y: layout.cy + layout.outerR + pad };
+  const nodes = gridNodesInAABB(min, max);
+  return filterNodesToBandAndSector(nodes, layout, "workspace", sector);
+}
+
+export function silhouetteNodes(layout: CircleLayout, sector: SectorGeom, fittedMask: Poly[]): Vec[] {
+  const pad = 6;
+  const min = { x: layout.cx - layout.outerR, y: layout.cy - layout.outerR - pad };
+  const max = { x: layout.cx + layout.outerR, y: layout.cy + layout.outerR + pad };
+  const nodes = gridNodesInAABB(min, max);
+  const banded = filterNodesToBandAndSector(nodes, layout, "silhouette", sector);
+  return filterNodesInPolys(banded, fittedMask);
+}
+
+export function silhouetteBandNodes(layout: CircleLayout, sector: SectorGeom): Vec[] {
+  const pad = 6;
+  const min = { x: layout.cx - layout.outerR, y: layout.cy - layout.outerR - pad };
+  const max = { x: layout.cx + layout.outerR, y: layout.cy + layout.outerR + pad };
+  const nodes = gridNodesInAABB(min, max);
+  return filterNodesToBandAndSector(nodes, layout, "silhouette", sector);
+}
+
+/** Generate anchor grid nodes for the inner ring (radius < innerR) */
+export function innerRingNodes(layout: CircleLayout): Vec[] {
+  const pad = 6;
+  const min = { x: layout.cx - layout.innerR, y: layout.cy - layout.innerR - pad };
+  const max = { x: layout.cx + layout.innerR, y: layout.cy + layout.innerR + pad };
+  const nodes = gridNodesInAABB(min, max);
+  // Filter to nodes within the inner circle
+  const out: Vec[] = [];
+  for (const n of nodes) {
+    const dx = n.x - layout.cx, dy = n.y - layout.cy;
+    const r = Math.hypot(dx, dy);
+    if (r < layout.innerR) out.push(n);
+  }
+  return out;
+}
+
+export const anchorsDiameterToPx = (anchorsDiag: number, gridPx: number = GRID_PX) =>
+  anchorsDiag * Math.SQRT2 * gridPx;

package/src/core/engine/geometry/polygons.ts

@@ -0,0 +1,43 @@
+/**
+ * Polygon-specific operations (subdivision, etc.)
+ * Uses pure math functions from math.ts
+ */
+
+import type { Poly, Vec } from "@/core/domain/types";
+import { vsub, vlen, subdivideSegment, EPS } from './math';
+
+/**
+ * "Half-edge" subdivision like the Python spec:
+ * - Axis-aligned legs split into steps of unit/2.
+ * - 45° diagonals split into steps of unit*sqrt(2)/2.
+ *
+ * Works for triangles/squares/parallelograms. Keeps polygon closed (no duplicate final vertex).
+ */
+export function subdivideForHalfEdges(poly: Poly, unit: number): Poly {
+  if (poly.length < 3) return poly.slice();
+  const diagStep = (unit * Math.SQRT2) / 2; // √2/2 * unit
+  const axisStep = unit / 2;
+
+  const out: Vec[] = [];
+  for (let i = 0; i < poly.length; i++) {
+    const a = poly[i];
+    const b = poly[(i + 1) % poly.length];
+    if (!a || !b) continue;
+    const seg = vsub(b, a);
+    const L = vlen(seg);
+    // detect 45° diagonal (|dx| == |dy| within eps)
+    const isDiag = Math.abs(Math.abs(seg.x) - Math.abs(seg.y)) < EPS && L > EPS;
+    const step = isDiag ? diagStep : axisStep;
+
+    // ensure an integer number of steps (round to nearest)
+    const n = Math.max(1, Math.round(L / step));
+    const pts = subdivideSegment(a, b, n);
+    if (i === 0) out.push(a);
+    // push all but the last vertex (to avoid duplicating the starting vertex at the end)
+    for (let k = 0; k < pts.length - (i === poly.length - 1 ? 1 : 0); k++) {
+      const pt = pts[k];
+      if (pt) out.push(pt);
+    }
+  }
+  return out;
+}