3draft 0.0.0-stage → 26.11.1013

package/src/order.js

@@ -0,0 +1,94 @@
+// Back-to-front painting order, Newell-Sancha style.
+//
+// Faces that overlap on screen are ordered by plane tests: face A can be painted
+// after face B when A lies wholly on the eye side of B's plane, or when B lies
+// wholly behind A's plane. The resulting "paint this first" relations are then
+// sorted topologically. Centroid depth only breaks ties, and orders faces that
+// cannot be compared (intersecting solids, cycles) as well as before.
+
+import { dot, sub } from './vec.js';
+
+const PLANE_EPS = 1e-6; // plane test tolerance, world units
+const PX = 0.01; // overlaps thinner than this are treated as touching
+
+// Do two convex screen polygons overlap by more than a sliver? (separating axis test)
+const overlaps = (a, b) => {
+  for (const poly of [a, b]) {
+    for (let i = 0; i < poly.length; i++) {
+      const p = poly[i];
+      const q = poly[(i + 1) % poly.length];
+      const nx = q.y - p.y;
+      const ny = p.x - q.x;
+      const length = Math.hypot(nx, ny);
+      if (!length) continue;
+      let minA = Infinity;
+      let maxA = -Infinity;
+      let minB = Infinity;
+      let maxB = -Infinity;
+      for (const v of a) {
+        const d = (v.x * nx + v.y * ny) / length;
+        if (d < minA) minA = d;
+        if (d > maxA) maxA = d;
+      }
+      for (const v of b) {
+        const d = (v.x * nx + v.y * ny) / length;
+        if (d < minB) minB = d;
+        if (d > maxB) maxB = d;
+      }
+      if (maxA <= minB + PX || maxB <= minA + PX) return false;
+    }
+  }
+  return true;
+};
+
+// Signed distances of points to a face's plane, positive on the eye side.
+const distances = (points, face) => points.map((v) => dot(face.n, sub(v, face.p)) * face.eye);
+
+/**
+ * Items need: { i, world, screen, n, p, eye, depth }
+ *   world  face points in world space      screen  the same, projected { x, y }
+ *   n, p   unit normal and a point on it   eye     +1 if the face faces the camera, else -1
+ *   depth  mean depth, used for ties       i       face index, used for ties
+ */
+export const paintOrder = (items) => {
+  const count = items.length;
+  const after = items.map(() => []);
+  const waiting = new Array(count).fill(0);
+  const link = (first, second) => {
+    after[first].push(second);
+    waiting[second] += 1;
+  };
+
+  for (let i = 0; i < count; i++) {
+    for (let j = i + 1; j < count; j++) {
+      const A = items[i];
+      const B = items[j];
+      if (!overlaps(A.screen, B.screen)) continue;
+      const a = distances(A.world, B); // A against B's plane
+      const b = distances(B.world, A); // B against A's plane
+      const aAfterB = a.every((d) => d >= -PLANE_EPS) || b.every((d) => d <= PLANE_EPS);
+      const bAfterA = b.every((d) => d >= -PLANE_EPS) || a.every((d) => d <= PLANE_EPS);
+      if (aAfterB && !bAfterA) link(j, i);
+      else if (bAfterA && !aAfterB) link(i, j);
+    }
+  }
+
+  const farther = (x, y) =>
+    items[x].depth > items[y].depth || (items[x].depth === items[y].depth && items[x].i < items[y].i);
+  const done = new Array(count).fill(false);
+  const out = [];
+  while (out.length < count) {
+    let best = -1;
+    for (let k = 0; k < count; k++) {
+      if (!done[k] && waiting[k] === 0 && (best < 0 || farther(k, best))) best = k;
+    }
+    if (best < 0) {
+      // a cycle: take the farthest face that is left
+      for (let k = 0; k < count; k++) if (!done[k] && (best < 0 || farther(k, best))) best = k;
+    }
+    done[best] = true;
+    out.push(items[best]);
+    for (const k of after[best]) waiting[k] -= 1;
+  }
+  return out;
+};

package/src/pick.js

@@ -0,0 +1,83 @@
+// Surface sensing: what is under a screen pixel, and a marker that lies on it.
+// Picking casts a real ray against the face geometry, so it is exact even where
+// the painter-sorted drawing is not.
+
+import { add, cross, dot, norm, scale, sub } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { ray } from './camera.js';
+
+const EPS = 1e-9;
+
+// Moller-Trumbore ray/triangle test. Distance along the ray, or null.
+const hitTriangle = (o, d, a, b, c) => {
+  const e1 = sub(b, a);
+  const e2 = sub(c, a);
+  const h = cross(d, e2);
+  const det = dot(e1, h);
+  if (Math.abs(det) < EPS) return null;
+  const inv = 1 / det;
+  const s = sub(o, a);
+  const u = inv * dot(s, h);
+  if (u < 0 || u > 1) return null;
+  const q = cross(s, e1);
+  const v = inv * dot(d, q);
+  if (v < 0 || u + v > 1) return null;
+  const t = inv * dot(e2, q);
+  return t > EPS ? t : null;
+};
+
+/**
+ * The nearest surface under panel pixel (x, y), or null.
+ * { face, distance, point, normal, front, color }
+ * `normal` is a unit vector facing the camera; `front` tells whether the face
+ * itself faces the camera (always true while `cull` is on). Faces are assumed
+ * convex and planar.
+ */
+export const pick = (mesh, cam, x, y, { cull = true } = {}) => {
+  const { origin, dir } = ray(cam, x, y);
+  let best = null;
+  mesh.faces.forEach((face, i) => {
+    const pts = face.v.map((k) => mesh.positions[k]);
+    const outward = norm(faceNormal(pts));
+    const front = dot(outward, dir) < 0;
+    if (cull && !front) return;
+    for (let j = 1; j < pts.length - 1; j++) {
+      const t = hitTriangle(origin, dir, pts[0], pts[j], pts[j + 1]);
+      if (t !== null && (!best || t < best.distance)) {
+        best = {
+          face: i,
+          distance: t,
+          point: add(origin, scale(dir, t)),
+          normal: front ? outward : scale(outward, -1),
+          front,
+          color: face.color,
+        };
+      }
+    }
+  });
+  return best;
+};
+
+/**
+ * A target cross lying flat on the picked surface (perpendicular to its
+ * normal): four arms with a gap in the middle and a ring, as 3D polylines.
+ * It is aligned to the first edge of the face, so it turns with the object.
+ * `radius` is the ring radius in world units.
+ */
+export const crosshair = (mesh, hit, radius = 0.1) => {
+  const [a, b] = mesh.faces[hit.face].v;
+  const t1 = norm(sub(mesh.positions[b], mesh.positions[a]));
+  const t2 = norm(cross(hit.normal, t1));
+  const at = (p, q) => add(hit.point, add(scale(t1, p * radius), scale(t2, q * radius)));
+  const ring = Array.from({ length: 33 }, (_, i) => {
+    const angle = (i / 32) * 2 * Math.PI;
+    return at(Math.cos(angle), Math.sin(angle));
+  });
+  return [
+    [at(-1.7, 0), at(-0.4, 0)],
+    [at(0.4, 0), at(1.7, 0)],
+    [at(0, -1.7), at(0, -0.4)],
+    [at(0, 0.4), at(0, 1.7)],
+    ring,
+  ];
+};

package/src/place.js

@@ -0,0 +1,23 @@
+// Putting things down on surfaces.
+
+import { add, cross, norm, scale, sub } from './vec.js';
+import { box } from './mesh.js';
+
+/**
+ * A square prism standing on the picked surface: its base lies on the surface,
+ * centered at the hit point, and it rises along the surface normal. Its sides
+ * line up with the first edge of the face. The height is `3 * base` unless given.
+ * Returns a new mesh; merge() it into the scene.
+ */
+export const standOn = (mesh, hit, { base = 0.15, height = 3 * base, color = '#c8c8c8' } = {}) => {
+  const [a, b] = mesh.faces[hit.face].v;
+  const ex = norm(sub(mesh.positions[b], mesh.positions[a]));
+  const ey = hit.normal;
+  const ez = cross(ex, ey);
+  return box({
+    size: [base, height, base],
+    at: add(hit.point, scale(ey, height / 2)),
+    axes: [ex, ey, ez],
+    color,
+  });
+};

package/src/svg.js

@@ -0,0 +1,119 @@
+// Flat SVG preview: points, edges, faces. No shading, no textures.
+// Faces are painted far to near (see order.js), back faces culled. The polygon stroke
+// is the edge layer, so hidden edges stay hidden. Output is deterministic.
+
+import { sub, dot, norm } from './vec.js';
+import { faceNormal } from './mesh.js';
+import { paintOrder } from './order.js';
+import { VIEW_ORDER, makeCamera, project } from './camera.js';
+
+const defaults = {
+  size: 400,
+  cull: true,
+  points: true,
+  stroke: '#1d1d1f',
+  pointColor: '#d6336c',
+  background: '#fafafa',
+};
+
+const num = (n) => String(Math.round(n * 100) / 100 + 0); // +0 turns -0 into 0
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+
+const panel = (mesh, view, o, x = 0, y = 0) => {
+  const cam = makeCamera(view, mesh, o.size, o.fit);
+  const name = esc(cam.name);
+  const proj = mesh.positions.map((p) => project(cam, p));
+  const items = [];
+
+  mesh.faces.forEach((face, i) => {
+    const world = face.v.map((k) => mesh.positions[k]);
+    const screen = face.v.map((k) => proj[k]);
+    if (screen.some((s) => s.depth <= 0.01)) return; // behind the camera
+    const dir = cam.ortho ? cam.f : sub(world[0], cam.eye);
+    const normal = faceNormal(world);
+    const facing = dot(normal, dir) < 0;
+    if (o.cull && !facing) return; // back face
+    items.push({
+      i,
+      vs: face.v,
+      world,
+      screen,
+      n: norm(normal),
+      p: world[0],
+      eye: facing ? 1 : -1,
+      color: face.color ?? '#c8c8c8',
+      depth: screen.reduce((s, p) => s + p.depth, 0) / screen.length,
+      pts: screen.map((p) => `${num(p.x)},${num(p.y)}`).join(' '),
+    });
+  });
+
+  const ordered = paintOrder(items); // far to near
+
+  // A point is drawn right after the nearest painted face that holds it, so
+  // faces painted later (closer to the camera) still cover it.
+  const last = new Map();
+  ordered.forEach((it, idx) => it.vs.forEach((k) => last.set(k, idx)));
+
+  const body = ordered.flatMap((it, idx) => {
+    const polygon =
+      `<polygon data-face="${it.i}" data-depth="${num(it.depth)}" points="${it.pts}" ` +
+      `fill="${it.color}" stroke="${o.stroke}" stroke-width="1.5" stroke-linejoin="round"/>`;
+    const dots = o.points
+      ? it.vs
+          .filter((k) => last.get(k) === idx)
+          .sort((a, b) => a - b)
+          .map(
+            (k) =>
+              `<circle data-v="${k}" cx="${num(proj[k].x)}" cy="${num(proj[k].y)}" r="3" fill="${o.pointColor}"/>`,
+          )
+      : [];
+    return [polygon, ...dots];
+  });
+
+  // 3D polylines (e.g. a surface cursor) drawn on top of everything else.
+  const marks = (o.marks ?? []).flatMap((m) =>
+    m.lines.flatMap((line) => {
+      const pts = line.map((p) => project(cam, p));
+      if (pts.some((p) => p.depth <= 0.01)) return [];
+      return [
+        `<polyline data-mark="${esc(m.name ?? 'mark')}" points="${pts.map((p) => `${num(p.x)},${num(p.y)}`).join(' ')}" ` +
+          `fill="none" stroke="${m.color ?? '#0b7285'}" stroke-width="${m.width ?? 2}" ` +
+          `stroke-linecap="round" stroke-linejoin="round"/>`,
+      ];
+    }),
+  );
+
+  return [
+    `<g data-view="${name}" transform="translate(${x} ${y})">`,
+    `<rect width="${o.size}" height="${o.size}" fill="${o.background}" stroke="#cfcfd4"/>`,
+    `<text x="10" y="20" font-family="monospace" font-size="13" fill="#555">${name}</text>`,
+    ...body,
+    ...marks,
+    '</g>',
+  ].join('\n');
+};
+
+const root = (w, h, body) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="${w}" height="${h}">\n${body}\n</svg>\n`;
+
+/**
+ * One standalone SVG for a single view: 'front' | 'side' | 'top' | 'persp',
+ * or a custom { dir, up, ortho, name? } spec.
+ */
+export const renderView = (mesh, view, opts = {}) => {
+  const o = { ...defaults, ...opts };
+  return root(o.size, o.size, panel(mesh, view, o));
+};
+
+/** The four views one after another: [{ name, svg }, ...]. */
+export const renderViews = (mesh, opts = {}) =>
+  VIEW_ORDER.map((name) => ({ name, svg: renderView(mesh, name, opts) }));
+
+/** All four views on one 2x2 sheet: front, side / top, persp. */
+export const renderSheet = (mesh, opts = {}) => {
+  const o = { ...defaults, ...opts };
+  const body = VIEW_ORDER.map((name, i) =>
+    panel(mesh, name, o, (i % 2) * o.size, Math.floor(i / 2) * o.size),
+  ).join('\n');
+  return root(o.size * 2, o.size * 2, body);
+};

package/src/vec.js

@@ -0,0 +1,16 @@
+// Tiny vec3 helpers on plain [x, y, z] arrays.
+
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a, b) => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+export const len = (a) => Math.hypot(a[0], a[1], a[2]);
+export const norm = (a) => {
+  const l = len(a);
+  return l ? scale(a, 1 / l) : [0, 0, 0];
+};

package/src/version.js

@@ -0,0 +1,8 @@
+// Versions are date based and stored as semver YY.M.DNNN (see scripts/bump.js).
+// This gives the readable form: '26.11.1001' -> '26.11.01.001'.
+
+export const displayVersion = (version) => {
+  const [yy, mm, p] = version.split('.').map(Number);
+  const pad = (n, w) => String(n).padStart(w, '0');
+  return `${pad(yy, 2)}.${pad(mm, 2)}.${pad(Math.floor(p / 1000), 2)}.${pad(p % 1000, 3)}`;
+};