ldr 0.3.0 → 0.4.0

package/README.md

@@ -52,7 +52,7 @@ Packs contain only the parts you ask for, so they're small: a 10k-brick Datsvill
 
 ```bash
 ldr pack --ldraw <dir> -o <out.bin|.zst|.gz> [model.ldr ...] [--part 3001.dat ...] [--all-parts]
-         [--studs low|full] [--prims full|low] [--no-weld] [--no-colors] [--cond] [--textures]
+         [--studs low|full] [--prims full|low] [--no-weld] [--no-colors] [--cond] [--textures] [--no-loose-geometry]
 ```
 
 Or from code (Node/Bun):
@@ -72,9 +72,10 @@ The pack embeds the LDConfig colour table by default, so no extra colour file is
 | export | description |
 |---|---|
 | `parse(text, name?) → Doc` | Parse LDraw text into files/commands (MPD-aware). |
-| `flatten(doc, { resolveModel? }) → PartInstance[]` | Expand submodels into placed parts with `color`, 12-number matrix `m`, `step`, nested `steps`, `path`. |
+| `flatten(doc, { resolveModel?, looseGeometry?, textures? }) → PartInstance[]` | Expand submodels into placed parts with `color`, 12-number matrix `m`, `step`, nested `steps`, `path`. MPD-embedded parts (e.g. Studio/OMR unofficial parts) are emitted as parts (`embedded: true`, see `fileKind`); a model file's own type 2-5 lines become synthetic parts `<file>#<step>` (`looseGeometry`, default `true`); with `textures: true`, parts wrapped by a model-level `!TEXMAP` get `texPart` (a synthetic textured part, `texWrapper`). Instances carry their step's ROTSTEP `view`. |
 | `parseModel(text, name?, opts?)` | `parse` + `flatten`. |
-| `sequenceSteps(instances)` | Global build-step index per instance (nested submodel steps sequenced). |
+| `sequenceSteps(instances)` | Global build-step index per instance (nested submodel steps sequenced), plus `views`: the ROTSTEP view per global step. |
+| `fileKind(doc, name)` / `looseSource` / `loosePartName` / `texWrapper` / `fileStepViews` / `rotStepMatrix` / `stepViewMatrix` | Spec helpers: part vs model rule for MPD files (header type; else own geometry), the text of a model's loose geometry per step, model-level TEXMAP wrapper parts, ROTSTEP views (MLCad: `REL`/`ADD`/`ABS`/`END`, ROTSTEP ends the step). |
 | `parseLDConfig(text)` | `!COLOUR` table → `Map<code, {name, hex, edge, alpha}>`. |
 | `loadPack(url) → Promise<Pack>` | Fetch + decompress (by extension) + decode a pack. |
 | `decompressPack(bytes)` / `decodePack(buffer)` | Same, from bytes you already have (zstd/gzip auto-detected). |
@@ -86,7 +87,7 @@ The pack embeds the LDConfig colour table by default, so no extra colour file is
 
 `LdrObjectOptions`: `edges` (default `true`), `cullStuds` (`true`), `cullUndersides` (`true`), `side` (`"front"` \| `"double"`, default `"front"`), `material` (`"plastic"` \| `"standard"`), `colors` (Map / record / function override), `fallbackColor`, `ldrawSpace` (keep -Y up), `scale`, `step`, `conditionalLines` (default `true`; only has an effect with packs built with `--cond`), `conditionalStudLines` (default `true`; `false` skips stud silhouettes, ~half the conditional-line GPU cost but most of their visible effect on stud-heavy scenes), `textures` (default `true`; only has an effect with packs built with `--textures`; `object.texturesReady` resolves when images are decoded).
 
-`LdrObject`: `object`, `stats` (`instances`, `drawn`, `missing[]`, `studsHidden/Total`, `undersHidden/Total`, `buildMs`), `stepCount`, `setStep(n | null)`, `setEdges(on)`, `setCulling(studs, undersides)`, `setSide(side)`, `getBox()`, `dispose()`.
+`LdrObject`: `object`, `stats` (`instances`, `drawn`, `missing[]`, `studsHidden/Total`, `undersHidden/Total`, `buildMs`), `stepCount`, `stepViews` (ROTSTEP view per step, or `null`), `setStep(n | null)`, `setEdges(on)`, `setCulling(studs, undersides)`, `setSide(side)`, `getBox()`, `dispose()`.
 
 ### `ldr/node` (Node/Bun only)
 
@@ -112,7 +113,8 @@ Visual-diff studies show culling and single-sided faces are lossless (≤0.009%
 
 ## Notes & limitations
 
-- Transparent colours render opaque. Conditional (type-5) lines are drawn only from packs built with `--cond` (pack v2, opt-in: +8–14% zstd size on Datsville); default packs carry type-2 edges only. Printed parts show their `!TEXMAP` images only from packs built with `--textures` (pack v2, opt-in; the PNGs dominate the size); default packs draw the parts' FALLBACK geometry. Model-level `!TEXMAP` around a part reference (rather than inside the part file) and textured parts embedded in an MPD are not rendered yet.
+- Transparent colours render opaque. Conditional (type-5) lines are drawn only from packs built with `--cond` (pack v2, opt-in: +8–14% zstd size on Datsville); default packs carry type-2 edges only. Printed parts show their `!TEXMAP` images only from packs built with `--textures` (pack v2, opt-in; the PNGs dominate the size); default packs draw the parts' FALLBACK geometry. Model-level `!TEXMAP` around part references renders from `--textures` packs (one synthetic part per distinct map). Parts embedded in an MPD (unofficial/custom parts, stickers) render as parts and override library parts of the same name; geometry drawn directly in a model file is packed as synthetic parts (`--no-loose-geometry` to skip it).
+- ROTSTEP is reported (`stepViews`, `instance.view`), not applied: rotating the camera per step is up to the app.
 - `setStep` rebuilds batches (fast for instruction-sized models; culling is recomputed for the partial build).
 - Coordinates: LDraw units (1 stud = 20 LDU); the object is rotated to +Y up unless `ldrawSpace: true`.