ldr 0.0.0-alpha.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Bacon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
 # ldr
 
-Lego Utilities
+High-performance LEGO® (LDraw) rendering for [three.js](https://threejs.org). Renders 100k-brick models at interactive frame rates by precompiling parts into a compact binary **parts pack** and drawing them with instancing, hidden-stud/tube culling, low-detail studs, single-sided faces and indexed edge lines.
+
+- Spec-compliant LDraw reader: `.ldr`, `.mpd` (submodels), `.dat`; BFC, `STEP`, `ROTSTEP`, `BUFEXCHG`, direct colours, `~Moved to` aliases.
+- `createLdrObject()` gives you a `THREE.Group` to drop into any scene, plus a build-steps API.
+- `ldr pack` CLI builds parts packs from your LDraw library (zstd/gzip compressed for serving).
+- ESM, TypeScript types, tree-shakeable (`sideEffects: false`); `three` is a peer dependency.
+
+## Install
+
+```bash
+bun add ldr three        # or: npm i ldr three
+```
+
+## Quickstart
+
+1. **Build a parts pack** for your model(s) (one-time, at build time):
+
+```bash
+bunx ldr pack --ldraw ./ldraw -o public/car.pack.zst models/car.ldr
+```
+
+2. **Render it:**
+
+```ts
+import * as THREE from "three";
+import { parseModel, loadPack, createLdrObject } from "ldr";
+
+const [text, pack] = await Promise.all([
+  fetch("/car.ldr").then((r) => r.text()),
+  loadPack("/car.pack.zst"),            // .zst / .gz / .br / raw .bin
+]);
+const model = createLdrObject(parseModel(text, "car.ldr"), pack, {
+  edges: true, cullStuds: true, cullUndersides: true, side: "front", material: "plastic",
+});
+scene.add(model.object);                 // +Y up, 1 unit = 1 LDU (scale option available)
+
+// build steps
+model.setStep(0);                        // show step 0 only … model.stepCount steps total
+model.setStep(null);                     // show everything
+```
+
+Add lights (or `scene.environment`) as for any `MeshStandardMaterial`/`MeshPhysicalMaterial`.
+
+## Getting parts
+
+The LDraw parts library is **not bundled** in this package. Download it from <https://library.ldraw.org> (`complete.zip`, ~90 MB unzipped to an `ldraw/` folder containing `LDConfig.ldr`, `parts/`, `p/`).
+The LDraw library is licensed **CC BY 2.0** — if you ship packs built from it, credit "LDraw.org Parts Library" (CC BY 2.0) in your app.
+
+Packs contain only the parts you ask for, so they're small: a 10k-brick Datsville section with 80 unique parts and the 100k section with 290 unique parts are 0.27 MB and 1.1 MB with zstd (1.3 / 3.3 MB gzip).
+
+```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]
+```
+
+Or from code (Node/Bun):
+
+```ts
+import { buildPack } from "ldr/node";
+const { data, parts, missing } = buildPack({ ldrawRoot: "./ldraw", models: ["car.ldr"], studs: "low" });
+await Bun.write("car.pack.bin", data);
+```
+
+The pack embeds the LDConfig colour table by default, so no extra colour file is needed at runtime.
+
+## API
+
+### `ldr` (browser-safe)
+
+| 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`. |
+| `parseModel(text, name?, opts?)` | `parse` + `flatten`. |
+| `sequenceSteps(instances)` | Global build-step index per instance (nested submodel steps sequenced). |
+| `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). |
+| `createLdrObject(instances, pack, options?) → LdrObject` | High-level three.js object. |
+| `createInstancedEdges(pos, instancedMesh, material?)` | Welded, indexed edge lines sharing an InstancedMesh's matrices (for custom batching). |
+| `conditionalLines(pack, entry, which?)` / `createInstancedConditionalEdges(cond, instancedMesh, material?)` | Type-5 conditional lines from a `--cond` pack (stride 12: p0, p1, c0, c1), drawn by a vertex shader only where the control points fall on the same side of the projected line. |
+| `makeTexturedMaterial(side, texture, wrapU?)` / `packTexture(pack, i)` / `texmapUV` / `texmapTriangleUV` | Printed / sticker parts from a `--textures` pack: a `!TEXMAP` UV material (image alpha blends over the part colour, untextured outside [0,1]) and the decoded embedded PNG. UV conventions follow LDView (v = 0 is the image's top row). |
+| `buildLdrScene`, `computeCulling`, `makeMaterial` | Low-level renderer used by the benchmarks. |
+
+`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()`.
+
+### `ldr/node` (Node/Bun only)
+
+Everything above, plus `buildPack(options)`, `Library` (filesystem LDraw resolver: `where`, `flatten`, `mesh`, `colors`), `Compiler`, `encodePack`, `writePack`.
+
+## Performance
+
+Measured with the benchmark harness in [`bench/`](https://github.com/EvanBacon/ldr/tree/main/bench) (Chrome, synced frame time while orbiting). Apple M4 Pro, native GL (Metal via ANGLE):
+
+| model | renderer | load | frame | tris/frame | draw calls |
+|---|---|---|---|---|---|
+| Datsville 100k bricks | three.js `LDrawLoader`-geometry instancing | 19.5 s | 105.7 ms (9 fps) | 142.7M | 290 |
+| Datsville 100k bricks | **ldr** (low studs, culling, single-sided) | **2.2 s** | **30.1 ms (33 fps)** | 59.1M | 506 |
+| Datsville 10k bricks | three.js instancing | 13.5 s | 45.9 ms | 60.5M | 80 |
+| Datsville 10k bricks | **ldr** (same) | **1.0 s** | **10.9 ms (92 fps)** | 21.0M | 131 |
+| 100k-brick grid | **ldr** + edges | 0.67 s | 15.7 ms (64 fps) | 4.0M | 24 |
+| 10k-brick grid | `LDrawLoader` | 6.6 s | 61.5 ms | 2.6M | 29,671 |
+| 10k-brick grid | **ldr** + edges | 0.15 s | 2.2 ms | 0.4M | 24 |
+
+**Demo app** (`demo/`, rAF fps on the M4 Pro with big-model defaults — shadows/AO/edges off above 50k bricks): Datsville 100k at **43.5 fps** (1.8 s load), full Datsville (392k bricks) at **9.9 fps**.
+
+Visual-diff studies show culling and single-sided faces are lossless (≤0.009% pixels); low-detail studs change only stud silhouettes. Stud culling hides ~39–51% of studs on real models.
+
+## 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.
+- `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`.
+
+LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project.
+
+## License
+
+MIT (code). Parts data you build from the LDraw library is CC BY 2.0 (LDraw.org).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};