@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/kinds/openings.ts

@@ -0,0 +1,141 @@
+// Windows and doors as one mesh each: a reveal (surround in the wall's colour, so the glass reads
+// set back by `depth`), stone sill and lintel, sash frame with glazing bars, or a panelled door
+// leaf. The wall mass behind stays whole (no boolean cut): half the triangles, no T-junctions.
+// Authored with the face at x = 0 looking +X, then turned to the requested side.
+//   LOD0: everything · LOD1: no glazing bars / door panels · LOD2: glass or leaf only.
+
+import { type Lod, type Mesh, merge, place, Ts23dError, type Vec3 } from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { box } from '../primitives/index.ts';
+import { mass } from './mass.ts';
+
+export type OpeningSide = 'front' | 'back' | 'left' | 'right';
+
+export interface OpeningOptions {
+  readonly kind: 'window' | 'door';
+  /** Clear opening, metres (UK sash ≈ 0.9 × 1.6; door ≈ 0.9 × 2.1). */
+  readonly width: number;
+  readonly height: number;
+  /** Bottom centre of the opening ON the wall face. */
+  readonly at: Vec3;
+  /** Which way the wall faces (front = +X, left = +Y). */
+  readonly facing: OpeningSide;
+  readonly glass: Vec3;
+  /** Sash frame / door leaf colour. */
+  readonly frame: Vec3;
+  /** Reveal (surround) colour: the wall's, so the opening reads recessed. */
+  readonly wall: Vec3;
+  readonly wallStrip?: StripId;
+  /** Sill + lintel colour (dressed stone). */
+  readonly trim?: Vec3;
+  /** Reveal depth, metres. Default 0.12 (half a brick). */
+  readonly depth?: number;
+  /** Reveal band width either side. Default 0.1. */
+  readonly surround?: number;
+  /** Glazing panes [across, up]: 2-over-2 sash = [2, 2]. Default window [2, 2]. */
+  readonly panes?: readonly [number, number];
+  readonly sill?: boolean;
+  readonly lintel?: boolean;
+}
+
+const YAW: Record<OpeningSide, number> = {
+  front: 0,
+  left: Math.PI / 2,
+  back: Math.PI,
+  right: -Math.PI / 2,
+};
+
+/** Base-centred box flush on the wall face (x = 0), back face omitted (it is against the wall). */
+const onWall = (size: Vec3, y: number, z: number, color: Vec3, strip?: StripId): Mesh =>
+  box({ size, at: [size[0] / 2, y, z], color, omit: ['back'], ...(strip ? { strip } : {}) });
+
+export function opening(o: OpeningOptions, lod: Lod = 0): Mesh {
+  const { width: w, height: h } = o;
+  if (!(w > 0.2 && h > 0.2 && Number.isFinite(w) && Number.isFinite(h)))
+    throw new Ts23dError('T3D_RECIPE_INVALID', {
+      cause: `${o.kind} opening is ${w} × ${h} m`,
+      fix: 'give a clear width and height > 0.2 m (sash ≈ 0.9 × 1.6, door ≈ 0.9 × 2.1)',
+    });
+  const r = o.depth ?? 0.12;
+  const s = o.surround ?? 0.1;
+  const trim = o.trim ?? [0.78, 0.75, 0.68];
+  const door = o.kind === 'door';
+  const parts: Mesh[] = [];
+  // The infill: glass flush on the wall, or the door leaf a little proud of it.
+  parts.push(
+    door
+      ? onWall([0.05, w, h], 0, 0, o.frame, 'wood')
+      : onWall([0.02, w, h], 0, 0, o.glass, 'glass'),
+  );
+  if (lod < 2) {
+    const lintel = o.lintel ?? true;
+    // Reveal masonry in true-scale courses aligned with the wall's (courses start at world z 0).
+    const reveal = (size: Vec3, y: number, z: number): Mesh =>
+      mass(
+        {
+          size,
+          at: [size[0] / 2, y, z],
+          color: o.wall,
+          strip: o.wallStrip ?? 'plain',
+          courseOrigin: -o.at[2],
+          omit: ['back'],
+        },
+        lod,
+      );
+    for (const side of [-1, 1]) parts.push(reveal([r, s, h], side * (w / 2 + s / 2), 0));
+    if (lintel) parts.push(onWall([r + 0.03, w + 2 * s + 0.2, 0.22], 0, h, trim, 'stone'));
+    else parts.push(reveal([r, w + 2 * s, s], 0, h));
+    if (!door && (o.sill ?? true))
+      parts.push(onWall([r + 0.07, w + 2 * s + 0.12, 0.07], 0, -0.07, trim, 'stone'));
+    if (!door) parts.push(...sash(o, w, h, lod));
+    else if (lod === 0) parts.push(...panels(o, w, h));
+  }
+  return place(merge(parts), { yaw: YAW[o.facing], at: o.at });
+}
+
+/** Sash frame round the glass; glazing bars at LOD0. */
+function sash(o: OpeningOptions, w: number, h: number, lod: Lod): Mesh[] {
+  const f = 0.06;
+  const d = 0.05;
+  const out = [
+    onWall([d, f, h], -(w / 2 - f / 2), 0, o.frame),
+    onWall([d, f, h], w / 2 - f / 2, 0, o.frame),
+    onWall([d, w - 2 * f, f], 0, 0, o.frame),
+    onWall([d, w - 2 * f, f], 0, h - f, o.frame),
+  ];
+  if (lod > 0) return out;
+  const [across, up] = o.panes ?? [2, 2];
+  const bar = 0.03;
+  for (let i = 1; i < across; i++)
+    out.push(
+      onWall([d * 0.8, bar, h - 2 * f], -w / 2 + f + ((w - 2 * f) * i) / across, f, o.frame),
+    );
+  for (let j = 1; j < up; j++)
+    out.push(onWall([d * 0.8, w - 2 * f, bar], 0, f + ((h - 2 * f) * j) / up - bar / 2, o.frame));
+  return out;
+}
+
+/** Four raised fielded panels on a door leaf (LOD0). */
+function panels(o: OpeningOptions, w: number, h: number): Mesh[] {
+  const out: Mesh[] = [];
+  const pw = (w - 0.36) / 2;
+  const tone: Vec3 = [o.frame[0] * 0.85, o.frame[1] * 0.85, o.frame[2] * 0.85];
+  for (const y of [-1, 1])
+    for (const [z0, ph] of [
+      [0.15, h * 0.38],
+      [0.15 + h * 0.38 + 0.15, h - 0.45 - h * 0.38],
+    ] as const)
+      out.push(
+        box({
+          size: [0.02, pw, ph],
+          at: [0.06, y * (pw / 2 + 0.06), z0],
+          color: tone,
+          omit: ['back'],
+        }),
+      );
+  // Knob on the lock side.
+  out.push(
+    box({ size: [0.06, 0.06, 0.06], at: [0.08, w / 2 - 0.12, h * 0.48], color: [0.7, 0.6, 0.3] }),
+  );
+  return out;
+}

package/src/kinds/planned.ts

@@ -0,0 +1,12 @@
+// Kinds with a fixed entry point and no body yet. Each is a library of builders recipes call;
+// the roadmap slice that builds it is named in the error.
+
+import { type BuildContext, notImplemented } from '../core/index.ts';
+
+/** Stylised creature from a skeleton + SDF flesh (Spore-like). Realistic ones go via /neural. M4. */
+export function creature(
+  _ctx: BuildContext,
+  _o: { skeleton: 'biped' | 'quadruped' | 'bird'; height: number },
+): void {
+  notImplemented('creature (SDF-skinned skeleton)', 'docs/idea/07-what-fits.md');
+}

package/src/kinds/roof-chimney.ts

@@ -0,0 +1,100 @@
+// A chimney stack for `roofMesh`: brick shaft from the wall plate (hidden in the attic, so it
+// always meets the roof) to a set height above where it leaves the slope, with an oversailing
+// cap course (LOD0/1) and clay pots (LOD0). Building-regs rule of thumb: ≥ 0.9 m above the
+// highest point where it passes through the roof.
+
+import { type Lod, type Mesh, MeshBuilder, merge, type Vec3 } from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { box, lathe } from '../primitives/index.ts';
+import { emitFace } from './faces.ts';
+
+export interface RoofChimney {
+  /** Centre offset from the roof's `at`, world X/Y metres. */
+  readonly at: readonly [number, number];
+  /** Stack width (X) and depth (Y). Default [0.9, 0.6]. */
+  readonly size?: readonly [number, number];
+  /** Height above the highest roof point it touches. Default 0.9. */
+  readonly height?: number;
+  readonly color: Vec3;
+  readonly strip?: StripId;
+  /** Clay pots on top (LOD0). Default: one per 0.4 m of width. */
+  readonly pots?: number;
+  readonly potColor?: Vec3;
+}
+
+export function chimney(
+  c: RoofChimney,
+  heightAt: (x: number, y: number) => number,
+  at: Vec3,
+  lod: Lod,
+): Mesh {
+  const [w, d] = c.size ?? [0.9, 0.6];
+  const cx = at[0] + c.at[0];
+  const cy = at[1] + c.at[1];
+  const corners: [number, number][] = [
+    [cx - w / 2, cy - d / 2],
+    [cx + w / 2, cy - d / 2],
+    [cx + w / 2, cy + d / 2],
+    [cx - w / 2, cy + d / 2],
+  ];
+  const exit = Math.max(...corners.map(([x, y]) => heightAt(x, y)));
+  const top = exit + (c.height ?? 0.9);
+  const z0 = at[2];
+  const strip = c.strip ?? 'brick';
+  const b = new MeshBuilder();
+  corners.forEach(([x0, y0], i) => {
+    const [x1, y1] = corners[(i + 1) % 4] ?? [x0, y0];
+    emitFace(b, {
+      points: [
+        [x0, y0, z0],
+        [x1, y1, z0],
+        [x1, y1, top],
+        [x0, y0, top],
+      ],
+      normal: [y1 - y0, -(x1 - x0), 0],
+      up: [0, 0, 1],
+      vOrigin: [0, 0, z0],
+      color: c.color,
+      strip,
+      banded: lod < 2,
+    });
+  });
+  emitFace(b, {
+    points: corners.map(([x, y]) => [x, y, top] as Vec3),
+    normal: [0, 0, 1],
+    up: [0, 1, 0],
+    vOrigin: [cx, cy, top],
+    color: c.color,
+    strip: 'plain',
+    banded: false,
+  });
+  const parts = [b.build()];
+  if (lod < 2) {
+    const k = 0.06;
+    const cap: Vec3 = [c.color[0] * 0.85, c.color[1] * 0.85, c.color[2] * 0.85];
+    parts.push(box({ size: [w + 2 * k, d + 2 * k, 0.1], at: [cx, cy, top - 0.22], color: cap }));
+    parts.push(box({ size: [w + k, d + k, 0.07], at: [cx, cy, top - 0.07], color: cap }));
+  }
+  if (lod === 0) {
+    const n = c.pots ?? Math.max(1, Math.round(w / 0.4));
+    const pot = c.potColor ?? [0.62, 0.32, 0.2];
+    for (let i = 0; i < n; i++) {
+      const x = cx - w / 2 + (w * (i + 0.5)) / n;
+      parts.push(
+        lathe({
+          profile: [
+            [0.13, 0],
+            [0.1, 0.36],
+            [0.125, 0.4],
+            [0.125, 0.46],
+          ],
+          segments: 8,
+          caps: true,
+          at: [x, cy, top - 0.02],
+          color: pot,
+        }),
+      );
+    }
+  }
+  return merge(parts);
+}

package/src/kinds/roof-shape.ts

@@ -0,0 +1,230 @@
+// Roof geometry as maths, no mesh: every pitched roof here is convex, so its surface is the LOWER
+// ENVELOPE (min) of a few planes over a plan outline. Gable = 2 planes, hip/pyramid = 4, gambrel =
+// 4, mansard = 8, shed = 1. Facets are the plan cells where one plane is lowest; ridges and hips
+// fall out as the creases between them. Local frame: `a` along the ridge, `b` across it, z up from
+// the wall plate; the roof UNDERSIDE passes through the top outer edge of every wall.
+
+import { Ts23dError, type Vec2, type Vec3 } from '../core/index.ts';
+import type { StripId } from '../material/index.ts';
+import { area2, clipPoly } from './faces.ts';
+
+export type RoofType = 'gable' | 'hip' | 'pyramid' | 'mansard' | 'gambrel' | 'shed';
+export type RoofSide = 'front' | 'back' | 'left' | 'right';
+
+export interface RoofOptions {
+  readonly type: RoofType;
+  /** Wall-line width (X) and depth (Y) of the mass the roof sits on, metres. */
+  readonly footprint: readonly [number, number];
+  /** Main slope, degrees (the lower, steep slope of a mansard or gambrel). */
+  readonly pitchDeg: number;
+  /** Centre of the footprint at wall-plate height (top of the walls). */
+  readonly at: Vec3;
+  readonly color: Vec3;
+  /** Roofing strip, laid in true-scale courses down the slope. Default 'slate'. */
+  readonly strip?: StripId;
+  /** Eave overhang past the walls, metres. Default 0.35. */
+  readonly overhang?: number;
+  /** Gable-end (rake) overhang; default = overhang. Hipped roofs ignore it. */
+  readonly rake?: number;
+  /** Slab thickness perpendicular to the slope (rafter + battens + slate). Default 0.18. */
+  readonly thickness?: number;
+  /** Ridge direction; default along the longer side. */
+  readonly ridge?: 'x' | 'y';
+  /** Shed only: the side the single slope falls toward. Default 'front' (+X). */
+  readonly low?: RoofSide;
+  /** Mansard / gambrel upper slope, degrees. Default 20 (mansard), 30 (gambrel). */
+  readonly upperPitchDeg?: number;
+  /** Mansard / gambrel: share of the half-span the lower slope covers in plan. Default 0.3 / 0.45. */
+  readonly knee?: number;
+}
+
+export interface Plane {
+  /** z = c + ga·a + gb·b (local, relative to the wall plate). */
+  readonly c: number;
+  readonly ga: number;
+  readonly gb: number;
+}
+
+export interface RoofShape {
+  readonly L: number;
+  readonly D: number;
+  /** Underside planes and the matching top planes (offset by the perpendicular thickness). */
+  readonly under: readonly Plane[];
+  readonly top: readonly Plane[];
+  /** Plan outline at the eaves (CCW, local a/b). */
+  readonly outline: readonly Vec2[];
+  /** Local unit axes in world XY: a → ex, b → ey (ex × ey = +Z). */
+  readonly ex: Vec2;
+  readonly ey: Vec2;
+  readonly thickness: number;
+}
+
+const RAD = Math.PI / 180;
+const FRAMES: Record<RoofSide, [Vec2, Vec2]> = {
+  // Frame whose −b side faces the named world side.
+  front: [
+    [0, 1],
+    [-1, 0],
+  ],
+  back: [
+    [0, -1],
+    [1, 0],
+  ],
+  left: [
+    [-1, 0],
+    [0, -1],
+  ],
+  right: [
+    [1, 0],
+    [0, 1],
+  ],
+};
+
+const bad = (cause: string, fix: string): Ts23dError =>
+  new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+
+export function validateRoof(o: RoofOptions): void {
+  const [w, d] = o.footprint;
+  if (!(w > 0 && d > 0 && Number.isFinite(w) && Number.isFinite(d)))
+    throw bad(
+      `roof footprint is [${w}, ${d}]`,
+      'pass the wall-line [width X, depth Y] in metres, both > 0',
+    );
+  const maxPitch = o.type === 'mansard' || o.type === 'gambrel' ? 85 : 75;
+  if (!(o.pitchDeg >= 3 && o.pitchDeg <= maxPitch))
+    throw bad(
+      `${o.type} roof pitchDeg is ${o.pitchDeg}`,
+      `use 3–${maxPitch}° (slate ≥ 20°, tile 30–45°, sheet metal ≥ 3°); for a flat roof use a box`,
+    );
+  const t = o.thickness ?? 0.18;
+  if (!(t > 0 && t < 1))
+    throw bad(`roof thickness is ${t}`, 'use 0.1–0.3 m (rafter + battens + slate)');
+  const ov = o.overhang ?? 0.35;
+  if (!(ov >= 0 && ov < 3) || !((o.rake ?? ov) >= 0))
+    throw bad(`roof overhang is ${ov}`, 'use 0–1.5 m past the wall line (0 for a party wall)');
+  if (o.type === 'mansard' || o.type === 'gambrel') {
+    const up = o.upperPitchDeg ?? (o.type === 'mansard' ? 20 : 30);
+    if (!(up > 0 && up < o.pitchDeg))
+      throw bad(
+        `${o.type} upperPitchDeg ${up} is not below pitchDeg ${o.pitchDeg}`,
+        'the upper slope must be shallower than the lower one (mansard 70°/20°, gambrel 60°/30°)',
+      );
+    const k = o.knee ?? 0.3;
+    if (!(k > 0 && k < 1))
+      throw bad(`${o.type} knee is ${k}`, 'use a fraction 0.15–0.6 of the half-span');
+  }
+}
+
+/** Planes of the roof UNDERSIDE for a type, in the local frame. */
+function underPlanes(o: RoofOptions, L: number, D: number): Plane[] {
+  const tp = Math.tan(o.pitchDeg * RAD);
+  const side = (s: number, c = 0, k = s): Plane[] => [
+    { c: c + D * k, ga: 0, gb: -s },
+    { c: c + D * k, ga: 0, gb: s },
+  ];
+  const ends = (s: number, c = 0, k = s): Plane[] => [
+    { c: c + L * k, ga: -s, gb: 0 },
+    { c: c + L * k, ga: s, gb: 0 },
+  ];
+  switch (o.type) {
+    case 'gable':
+      return side(tp);
+    case 'shed':
+      return [{ c: D * tp, ga: 0, gb: tp }];
+    case 'hip':
+      return [...side(tp), ...ends(tp)];
+    case 'pyramid': {
+      const h = Math.min(L, D) * tp;
+      return [...side(h / D), ...ends(h / L)];
+    }
+    case 'gambrel':
+    case 'mansard': {
+      const t2 = Math.tan((o.upperPitchDeg ?? (o.type === 'mansard' ? 20 : 30)) * RAD);
+      const r = (o.knee ?? (o.type === 'mansard' ? 0.3 : 0.45)) * Math.min(L, D);
+      // Upper plane: z = r·tp + (D − r − |b|)·t2 → c = r·tp + (D − r)·t2 with slope t2.
+      const upper = (half: number): number => r * tp + (half - r) * t2 - half * t2;
+      const lower = [...side(tp), ...(o.type === 'mansard' ? ends(tp) : [])];
+      const top = [
+        ...side(t2, upper(D), t2),
+        ...(o.type === 'mansard' ? ends(t2, upper(L), t2) : []),
+      ];
+      return [...lower, ...top];
+    }
+  }
+}
+
+export function roofShape(o: RoofOptions): RoofShape {
+  validateRoof(o);
+  const [w, d] = o.footprint;
+  const ridge = o.ridge ?? (w >= d ? 'x' : 'y');
+  const low: RoofSide = o.type === 'shed' ? (o.low ?? 'front') : ridge === 'x' ? 'right' : 'front';
+  const [ex, ey] = FRAMES[low];
+  const L = (Math.abs(ex[0]) > 0.5 ? w : d) / 2;
+  const D = (Math.abs(ex[0]) > 0.5 ? d : w) / 2;
+  const ov = o.overhang ?? 0.35;
+  const t = o.thickness ?? 0.18;
+  const under = underPlanes(o, L, D);
+  const top = under.map((p) => ({ ...p, c: p.c + t * Math.hypot(1, p.ga, p.gb) }));
+  const hipped = o.type === 'hip' || o.type === 'pyramid' || o.type === 'mansard';
+  const A = hipped ? 4 * (L + D + ov) : L + (o.rake ?? ov);
+  const B = D + ov;
+  // Eave height: the steepest-falling b-plane at the eave line; every plane must stay above it.
+  const g0 = under[0] ?? { c: 0, ga: 0, gb: 1 };
+  const zEave = -ov * Math.hypot(g0.ga, g0.gb);
+  let outline: Vec2[] = [
+    [-A, -B],
+    [A, -B],
+    [A, B],
+    [-A, B],
+  ];
+  for (const p of under) outline = clipPoly(outline, (q) => zEave - zAt(p, q));
+  return { L, D, under, top, outline, ex, ey, thickness: t };
+}
+
+export const zAt = (p: Plane, q: Vec2): number => p.c + p.ga * q[0] + p.gb * q[1];
+
+/** Envelope height (min of planes) at a local plan point. */
+export const envelope = (planes: readonly Plane[], q: Vec2): number =>
+  Math.min(...planes.map((p) => zAt(p, q)));
+
+/** The plan cell of each plane on the envelope (empty cells dropped), with its plane. */
+export function facets(planes: readonly Plane[], outline: readonly Vec2[]): [Plane, Vec2[]][] {
+  const out: [Plane, Vec2[]][] = [];
+  planes.forEach((p, i) => {
+    let cell: Vec2[] = [...outline];
+    planes.forEach((q, j) => {
+      if (j !== i && cell.length >= 3) cell = clipPoly(cell, (r) => zAt(p, r) - zAt(q, r));
+    });
+    if (cell.length >= 3 && Math.abs(area2(cell)) > 1e-6) out.push([p, cell]);
+  });
+  return out;
+}
+
+/** Local plan → world XY offset (add `at`). */
+export const toWorld = (s: RoofShape, q: Vec2, z: number, at: Vec3): Vec3 => [
+  at[0] + s.ex[0] * q[0] + s.ey[0] * q[1],
+  at[1] + s.ex[1] * q[0] + s.ey[1] * q[1],
+  at[2] + z,
+];
+
+/** World XY → local plan. */
+export const toLocal = (s: RoofShape, x: number, y: number, at: Vec3): Vec2 => {
+  const dx = x - at[0];
+  const dy = y - at[1];
+  return [dx * s.ex[0] + dy * s.ex[1], dx * s.ey[0] + dy * s.ey[1]];
+};
+
+/** World z of the roof's top surface at world (x, y) — chimneys, dormers, aerials sit on this. */
+export function roofHeightAt(o: RoofOptions, x: number, y: number): number {
+  const s = roofShape(o);
+  return o.at[2] + envelope(s.top, toLocal(s, x, y, o.at));
+}
+
+/** World z of the highest point of the roof surface (ridge or apex), slab included. */
+export function ridgeHeight(o: RoofOptions): number {
+  const s = roofShape(o);
+  let z = -Infinity;
+  for (const [p, cell] of facets(s.top, s.outline))
+    for (const q of cell) z = Math.max(z, zAt(p, q));
+  return o.at[2] + z;
+}