ldr 0.6.0 → 0.8.0

package/README.md

@@ -102,7 +102,7 @@ Light the scene (or set `scene.environment`) as you would for any `MeshStandardM
 | `resolveModel(name)` | – | Resolves an external reference to a `Doc`, such as a model loaded separately. Return `null` to treat it as a part. |
 | `maxDepth` | `64` | Submodel nesting limit (cycle guard). |
 
-MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part instances (`embedded: true`) and override library parts of the same name.
+MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part instances (`embedded: true`) and override library parts of the same name. `loadModel` asks the parts CDN for them by a hash of their definition (`embeddedKeys`), so a CDN built with `--embedded <model dir>` serves the embedded parts of those models (the demo CDN carries the ones in its 1,773 catalog models).
 
 **Packs and rendering**
 
@@ -143,6 +143,15 @@ MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part
 
 `setStep` doesn't rebuild anything: it compacts instance buffers, and culling is step-aware (a stud covered only by a later step's part stays visible). `stats` reflect the shown step.
 
+**Building instructions.** `parseModel(text, name, { callouts: true })` (or `loadModel(url, { callouts: true })`) sequences a
+submodel placed N times in one step like a booklet: the first copy is built step by step (its instances get `mult = N`, the "xN"),
+the other copies appear finished at the end of that step. `planStepViews(instances, pack.header.parts, stepOf, stepCount)` plans a
+camera per step (`view(step)` → `{ dir, target, radius, minVis, meanVis, below, isolate }`, LDraw space): the booklet view (30° up,
+45° round) while it shows the new parts at least half visible on average, otherwise the best of 24 views from above (or from below for
+parts added underneath), preferring front three-quarter views and small turns (thresholds from Agrawala et al., SIGGRAPH 2003).
+`isolate` is set while a sub-assembly is being built: show it on its own with `setStep(step, isolateMask(instances, view.isolate))`.
+Visibility is measured on part bounding boxes, so it needs no GPU and also runs in Node.
+
 ### `ldr/node` (Node / Bun only)
 
 Everything above, plus:
@@ -202,7 +211,7 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 
 - **Transparency:** transparent colours render opaque.
 - **Opt-in pack features:** conditional lines need packs built with `cond`. Printed parts show their images only from `textures` packs (the embedded PNGs dominate the pack size); default packs draw the FALLBACK geometry.
-- **ROTSTEP** is reported (`stepViews`, `instance.view`), not applied. Rotating the camera per step is up to your app.
+- **ROTSTEP** is reported (`stepViews`, `instance.view`), not applied; `planStepViews` takes a `fixed(step)` override if you want to honour it.
 - **Packs are static:** they hold only the parts they were built for. A model that uses parts missing from the pack lists them in `stats.missing`.
 - **Occlusion culling:** beyond hidden studs and undersides there is no occlusion culling (bricks enclosed by other bricks are still drawn). Frustum culling and LOD apply per spatial cluster.
 - **LOD and edges:** edge LOD drops sub-pixel edge segments and hides edges where bricks are a fraction of a pixel, which visibly lightens far-away views drawn with edges (up to 4.7% of pixels on Datsville overviews). Set `lodEdgeMinPx: 0, lodEdgePx: 0` to keep every edge (much slower on large models), or `lod: false` to turn LOD off entirely.
@@ -212,4 +221,4 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 - **Code:** MIT © Evan Bacon.
 - **LDraw parts:** packs you build contain geometry from the **LDraw.org Parts Library**, which is licensed **CC BY 2.0** (newer files CC BY 4.0, per file header). If you ship packs, credit "LDraw.org Parts Library (CC BY 2.0)" in your app. See <https://www.ldraw.org/legal-info>.
 - **Datsville:** the benchmark model is by [mjhorvath/Datsville](https://github.com/mjhorvath/Datsville) (CC BY-SA 4.0). It is used for benchmarking only and is not redistributed.
-- **Trademarks:** LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project. LDraw™ is a trademark of the Estate of James Jessiman.
+- **Trademarks:** LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project; ldr is not affiliated with the LEGO Group. LDraw™ is a trademark of the Estate of James Jessiman.

package/dist/cdn.d.ts

@@ -24,6 +24,7 @@ export interface LoadedModel extends LdrObject {
 /**
  * One call from an `.ldr` / `.mpd` URL (or text) to a three.js object: fetches the model, fetches just the parts it uses from the
  * parts CDN and builds an instanced `LdrObject`. No LDraw library or parts pack needed.
- * Limits (v1): parts defined inside the model (MPD-embedded parts) and loose geometry in model files are skipped (listed in `stats.missing`).
+ * MPD-embedded parts are fetched by content key (`emb/<hash>.dat`, see embedded.ts): a CDN built with `--embedded` serves the ones in
+ * known models. Embedded parts the CDN lacks, and loose geometry in model files, are skipped (listed in `stats.missing`).
  */
 export declare function loadModel(source: string, o?: LoadModelOptions): Promise<LoadedModel>;

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/cli.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/cli.ts
 import fs4 from "node:fs";
 import zlib from "node:zlib";
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/build-pack.ts
 import fs3 from "node:fs";
 import path3 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/resolver.ts
 import fs from "node:fs";
 import path from "node:path";
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/spec.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/spec.ts
 var norm = (s) => s.trim().toLowerCase().replace(/\\/g, "/").replace(/\/+/g, "/");
 function parseColor(tok) {
   if (/^0x/i.test(tok))
@@ -469,6 +469,7 @@ function transformTexMap(map, m) {
   const x = (q) => [m[3] * q[0] + m[4] * q[1] + m[5] * q[2] + m[0], m[6] * q[0] + m[7] * q[1] + m[8] * q[2] + m[1], m[9] * q[0] + m[10] * q[1] + m[11] * q[2] + m[2]];
   return { ...map, p1: x(map.p1), p2: x(map.p2), p3: x(map.p3) };
 }
+var STUB_OVERRIDES = { "32531.dat": "32531a.dat" };
 function mul(a, b) {
   const [ax, ay, az, a0, a1, a2, a3, a4, a5, a6, a7, a8] = a, [bx, by, bz, b0, b1, b2, b3, b4, b5, b6, b7, b8] = b;
   return [
@@ -704,12 +705,15 @@ function fileStepViews(f) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/model.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/model.ts
+var CALLOUT_END = 999999;
+var stepKey = (steps) => steps.map((x) => String(x).padStart(6, "0")).join(".") + "~";
 function flatten(doc, opts = {}) {
   const out = [];
   const maxDepth = opts.maxDepth ?? 64;
-  const loose = opts.looseGeometry !== false, tx = !!opts.textures;
+  const loose = opts.looseGeometry !== false, tx = !!opts.textures, co = !!opts.callouts;
   const src = new Map;
+  let subs = 0;
   const lazy = (f, k) => {
     const key = f.name + "#" + k;
     let fn = src.get(key);
@@ -720,16 +724,44 @@ function flatten(doc, opts = {}) {
     }
     return fn;
   };
-  const walk = (d, fname, m, color, path, stepPath, depth, texIn) => {
+  const walk = (d, fname, m, color, path, stepPath, depth, texIn, fixed = null, subPath = [], subMats = []) => {
     const f = d.files.get(fname);
     if (!f || depth > maxDepth)
       return;
     let s = 0;
+    const subId = depth > 0 ? ++subs : 0;
+    const sp0 = co && subId ? [...subPath, subId] : subPath;
+    const sm0 = co && subId ? [...subMats, m] : subMats;
+    const groups = co && !fixed ? new Map : null;
+    let ordStep = -1, ord = 0;
+    const sub = (sd, file, mm, col, sp, lt) => {
+      if (ordStep !== s) {
+        ordStep = s;
+        ord = 0;
+      }
+      const g = groups?.get(s + "|" + file);
+      if (g) {
+        g.n++;
+        return walk(sd, sd === d ? file : sd.main, mm, col, path + "/" + file, [...sp, CALLOUT_END], depth + 1, lt, [...sp, CALLOUT_END], sp0, sm0);
+      }
+      const spo = [...sp, ord++], from = out.length;
+      walk(sd, sd === d ? file : sd.main, mm, col, path + "/" + file, spo, depth + 1, lt, fixed, sp0, sm0);
+      groups?.set(s + "|" + file, { n: 1, from, to: out.length });
+    };
     const views = fileStepViews(f);
     const ls = loose ? looseSteps(f) : [];
     let li = 0;
     const emit = (part, col, mm, sp, k, embedded, tex) => {
+      if (fixed)
+        sp = fixed;
       const i = { part, color: col, m: mm, step: sp[0], steps: sp, localStep: k, path };
+      if (subId) {
+        i.sub = subId;
+        if (co) {
+          i.subPath = sp0;
+          i.subMats = sm0;
+        }
+      }
       if (embedded)
         i.embedded = true;
       if (tex) {
@@ -775,7 +807,7 @@ function flatten(doc, opts = {}) {
       const lt = tex && local ? transformTexMap(tex, local) : null;
       if (d.files.has(c.file)) {
         if (fileKind(d, c.file) === "model") {
-          walk(d, c.file, mm, col, path + "/" + c.file, sp, depth + 1, lt);
+          sub(d, c.file, mm, col, sp, lt);
           continue;
         }
         emit(c.file, col, mm, sp, s, true, lt);
@@ -783,12 +815,18 @@ function flatten(doc, opts = {}) {
       }
       const ext = opts.resolveModel?.(c.file);
       if (ext) {
-        walk(ext, ext.main, mm, col, path + "/" + c.file, sp, depth + 1, lt);
+        sub(ext, c.file, mm, col, sp, lt);
         continue;
       }
       emit(c.file, col, mm, sp, s, false, lt);
     }
     flushLoose(Infinity);
+    if (groups) {
+      for (const g of groups.values())
+        if (g.n > 1)
+          for (let j = g.from;j < g.to; j++)
+            out[j].mult ??= g.n;
+    }
   };
   if (fileKind(doc, doc.main) === "part") {
     const f = doc.files.get(doc.main);
@@ -803,7 +841,7 @@ function parseModel(text, name = "main.ldr", opts) {
   return flatten(parse(text, name, { geometryText: true }), opts);
 }
 function sequenceSteps(insts) {
-  const key = (i) => i.steps.map((x) => String(x).padStart(6, "0")).join(".");
+  const key = (i) => stepKey(i.steps);
   const uniq = [...new Set(insts.map(key))].sort();
   const rank = new Map(uniq.map((k, j) => [k, j]));
   const stepOf = new Int32Array(insts.length);
@@ -826,7 +864,7 @@ function parseLDConfig(text) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/resolver.ts
 var TOP_STUD_RE = /^(stud|studa|stud2|stud2a|stud6|stud6a|stud10|stud15|stud2s|stud2s2|stud-logo\d*|stud2-logo\d*)\.dat$/i;
 var UNDER_STUD_RE = /^(stud3|stud3a|stud4.*|stud12|stud16.*|stud18a)\.dat$/i;
 var norm2 = (ref) => ref.trim().replace(/\\/g, "/").toLowerCase();
@@ -896,7 +934,7 @@ class Library {
     return key;
   }
   resolve(ref) {
-    const n = norm2(ref);
+    const n0 = norm2(ref), n = STUB_OVERRIDES[n0] ?? n0;
     if (this.virtual.size && this.virtual.has(n))
       return "mpd/" + n;
     for (const pre of ["parts/", "p/", "models/"])
@@ -1096,11 +1134,11 @@ function collectDeps(lib, refs) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/compile.ts
 import fs2 from "node:fs";
 import path2 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/lod.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/lod.ts
 import { MeshoptSimplifier, MeshoptEncoder } from "meshoptimizer";
 await Promise.all([MeshoptSimplifier.ready, MeshoptEncoder.ready]);
 function reorderMesh(P, N, C, I) {
@@ -1292,7 +1330,7 @@ function lodChain(P, C, I) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/compile.ts
 function loadColors(root) {
   const map = new Map;
   for (const l of fs2.readFileSync(path2.join(root, "LDConfig.ldr"), "latin1").split(/\r?\n/)) {
@@ -1875,7 +1913,7 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
   return Buffer.concat([head, ...chunks.map((c) => new Uint8Array(c.buffer, c.byteOffset, c.byteLength))]);
 }
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/node/build-pack.ts
 function buildPack(o) {
   const lib = new Library(o.ldrawRoot);
   const refs = new Map;
@@ -1938,7 +1976,7 @@ function buildPack(o) {
   return { data: encodePack(parts, kinds, comp.opts.weld, extra, { texture, lod: o.lod !== false, reorder: !!o.reorder }), parts: parts.size, studKinds: kinds.size, missing: [...missing], ...warnings.length ? { warnings } : {} };
 }
 
-// ../../../../../../../tmp/ldr-build-NB5kkP/src/cli.ts
+// ../../../../../../../tmp/ldr-build-eZnTdy/src/cli.ts
 var HELP = `ldr pack — build a parts pack for the ldr three.js renderer
 
 Usage:

package/dist/embedded.d.ts

@@ -0,0 +1,2 @@
+/** CDN name for each embedded part in `names` (normalized file names inside `text`): `emb/<hash>.dat`. */
+export declare function embeddedKeys(text: string, names: Iterable<string>, fallback?: string): Map<string, string>;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { parse, parseColor, isDirectColor, mul, I as IDENTITY, norm, smoothNormals, parseTexMap, texmapUV, texmapTriangleUV, transformTexMap, resolveTexture, fileKind, looseSteps, looseSource, looseFile, loosePartName, texWrapper, invert, hash32, colorToken, rotStepMatrix, stepViewMatrix, fileStepViews } from "./spec.js";
 export type { M as Matrix12, Doc, LFile, Cmd, RotStep, BufExchg, TexMap, TexMapCmd, TexMapMethod, TexAnno, DataBlock, PartMesh, FileKind, StepView } from "./spec.js";
-export { flatten, parseModel, sequenceSteps, parseLDConfig } from "./model.js";
+export { flatten, parseModel, sequenceSteps, stepKey, parseLDConfig, CALLOUT_END } from "./model.js";
+export { planStepViews, isolateMask, viewDir, instanceBoxes, MIN_VIS, REORIENT } from "./instructions.js";
+export type { StepCameraView, StepCameraOptions, Vec3 } from "./instructions.js";
 export type { PartInstance, FlattenOptions, LDrawColor } from "./model.js";
 export { loadPack, decodePack, buildLdrScene, makeMaterial, createInstancedEdges, computeCulling, cullCore, forEachStud, conditionalLines, createInstancedConditionalEdges, conditionalLineVisible, warmPackGeometry } from "./render.js";
 export { precomputeCull, sceneInstances } from "./cull.js";
@@ -10,3 +12,4 @@ export type { LdrObject, LdrObjectOptions, LdrStats, ColorSource } from "./scene
 export { decompressPack } from "./pack-io.js";
 export { loadModel, loadParts, loadPartsIndex, mergePacks, prepareModel, DEFAULT_PARTS_CDN } from "./cdn.js";
 export type { LoadModelOptions, LoadedModel, LoadPartsOptions, PartsCdnIndex, PrepareOptions, PreparedModel } from "./cdn.js";
+export { embeddedKeys } from "./embedded.js";