ldr 0.0.0-alpha.1 → 0.3.0

package/dist/node/library.d.ts

@@ -0,0 +1,42 @@
+import { type Doc, type PartMesh, type Instance } from "../spec.js";
+export declare class Library {
+    root: string;
+    unofficialRoot?: string | undefined;
+    cache: Map<string, Doc | null>;
+    meshCache: Map<string, PartMesh>;
+    /** Optional second root for unofficial parts (e.g. Unofficial/ next to the official tree). */
+    constructor(root: string, unofficialRoot?: string | undefined);
+    /**
+     * Resolve a part/prim/model by LDraw search order (case-insensitive):
+     * parts/, p/, models/, then parts/s (subparts). If `unofficial/` exists under root
+     * (or `unofficialRoot` is set), those trees are tried after the official ones.
+     * Follows `~Moved to` aliases to the canonical file.
+     */
+    where(name: string, _seen?: Set<string>): {
+        kind: "part" | "prim" | "model";
+        doc: Doc;
+        aliasOf?: string;
+    } | null;
+    private lookup;
+    /** Case-insensitive path resolve (library files are lowercase; callers may pass any case). */
+    private resolveFile;
+    colors(): Map<number, {
+        name: string;
+        hex: string;
+        edge: string;
+        alpha: number;
+    }>;
+    /** Flattened triangle mesh: positions + color code per tri (16 = inherit); edges as line segments.
+     *  `cond` stores type-5 lines as 12 floats each: endpoint0, endpoint1, control0, control1.
+     *  Default = what a renderer without !TEXMAP support draws (`0 !:` geometry skipped, FALLBACK geometry drawn).
+     *  `{ texmap: true }` = TEXMAP-aware geometry (START..FALLBACK incl. `0 !:` lines, FALLBACK..END skipped) plus `uv` / `texture`. */
+    mesh(name: string, opts?: {
+        texmap?: boolean;
+    }): PartMesh;
+    /** Texture PNG bytes for a !TEXMAP name: an MPD `!DATA` block in `doc` first, then the LDraw search path with a
+     *  `textures/` prefix (parts/, p/, models/, official then unofficial), then without it. Case-insensitive. */
+    texture(name: string, doc?: Doc): Uint8Array | null;
+    private emit;
+    /** Flatten a model into part instances. 24 handled at render (edge color). Alias parts resolve to canonical names. */
+    flatten(doc: Doc): Instance[];
+}

package/dist/node/resolver.d.ts

@@ -0,0 +1,33 @@
+export declare const TOP_STUD_RE: RegExp;
+export declare const UNDER_STUD_RE: RegExp;
+export declare const norm: (ref: any) => any;
+export declare const threeName: (ref: any) => any;
+export declare function parseType1(line: any): {
+    color: any;
+    m: any;
+    name: any;
+} | null;
+export declare function xf(m: any, p: any): any[];
+export declare function compose(a: any, b: any): any[];
+export declare const IDENT: number[];
+export declare class Library {
+    #private;
+    root: string;
+    index: Map<string, string>;
+    text: Map<string, string>;
+    stats: Map<string, any>;
+    constructor(root: string);
+    resolve(ref: any): string | null;
+    read(key: string): string;
+    isPart(key: any): any;
+    fileStats(key: any): any;
+}
+export declare function splitModel(text: any, fallbackName?: string): {
+    files: Map<string, string>;
+    main: string | null;
+    data: Map<string, string>;
+};
+export declare function flatten(model: any, lib: any, onInstance: any): {
+    missing: Map<any, any>;
+};
+export declare function collectDeps(lib: any, refs: any): Map<any, any>;

package/dist/pack-io.d.ts

@@ -0,0 +1,2 @@
+/** Detect gzip / zstd magic and return raw pack bytes (an ArrayBuffer you can hand to `decodePack`). */
+export declare function decompressPack(data: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;

package/dist/render.d.ts

@@ -0,0 +1,69 @@
+import * as THREE from 'three';
+/** `cond`: draw type-5 conditional lines when the pack carries them (pack v2, built with `cond: true`); 'idx' edges only. Default true.
+ *  `condStuds`: also draw them on stud batches (stud silhouettes). Default true. */
+export type LdrParams = {
+    pack: string;
+    cullStuds: boolean;
+    cullUnder: boolean;
+    edges: boolean | 'idx' | 'ss';
+    side: 'double' | 'front';
+    uncertDouble?: boolean;
+    cond?: boolean;
+    condStuds?: boolean;
+    /** Draw textured (!TEXMAP) parts with their PNGs when the pack carries them (pack v2 "tex", `ldr pack --textures`). Default true. */
+    tex?: boolean;
+};
+export type Inst = {
+    part: string;
+    color: string;
+    m: number[];
+};
+export type Pack = {
+    header: any;
+    arr: (r: any) => any;
+    bytes: number;
+};
+export declare function loadPack(url: string): Promise<Pack>;
+/** Decode an uncompressed parts pack (4-byte LE header length, JSON header, then aligned typed-array payload). */
+export declare function decodePack(buf: ArrayBuffer): Pack;
+export declare function makeMaterial(side: THREE.Side): THREE.MeshStandardMaterial;
+/** Material for textured (!TEXMAP) triangles: the LDraw colour as base, the PNG blended over it by its alpha (LDraw spec),
+ *  and no texture outside the projection's [0,1] range. `map` should have flipY = false (v = 0 is the image's top row). */
+export declare function makeTexturedMaterial(side: THREE.Side, map: THREE.Texture, wrapU?: boolean): THREE.MeshStandardMaterial;
+/** Decode a pack's embedded PNG into a texture (async; the texture fills in when decoded). Needs `createImageBitmap` (browsers, workers). */
+export declare function packTexture(pack: Pack, i: number): {
+    texture: THREE.Texture;
+    ready: Promise<void>;
+};
+/** Edge lines for an InstancedMesh: welds + indexes `pos` (line-segment endpoints, part space) and shares the mesh's instanceMatrix buffer, so edges cost one extra draw and no extra per-instance memory. Keep `geometry.instanceCount` in sync with `im.count`. */
+export declare function createInstancedEdges(pos: ArrayLike<number>, im: THREE.InstancedMesh, material?: THREE.Material): THREE.LineSegments;
+/** Expand a pack entry's conditional lines (pack v2 `condl` body / `condlu` underside) to part-space floats, stride 12:
+ *  p0, p1, control0, control1. `which` = 'all' (default; body then underside), 'body' or 'under'.
+ *  Returns null for v1 packs / parts without conditional lines. */
+export declare function conditionalLines(pack: Pack, entry: any, which?: 'all' | 'body' | 'under'): Float32Array | null;
+/** CPU mirror of the conditional-line vertex shader: true if the line p0-p1 is drawn for this model-view-projection matrix. */
+export declare function conditionalLineVisible(cond: ArrayLike<number>, i: number, mvp: THREE.Matrix4): boolean;
+/** Conditional (type-5) lines for an InstancedMesh, sharing its instanceMatrix buffer (one extra draw, no per-instance memory).
+ *  `cond` is part-space stride 12 (p0, p1, c0, c1), e.g. from `conditionalLines(pack, pack.header.parts[name])`.
+ *  GPU cost: 2 vertices x 13 floats per line (104 B/line), per part, not per instance. Keep `geometry.instanceCount` in sync with `im.count`. */
+export declare function createInstancedConditionalEdges(cond: ArrayLike<number>, im: THREE.InstancedMesh, material?: THREE.Material): THREE.LineSegments;
+export declare function computeCulling(insts: Inst[], H: any): {
+    studs: {
+        kind: string;
+        color: string;
+        w: number[];
+        hidden: boolean;
+    }[];
+    underHidden: boolean[];
+};
+export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, color: (c: string) => THREE.Color, mark: (k: string) => void): {
+    root: THREE.Group<THREE.Object3DEventMap>;
+    stats: any;
+    setCull: (studs: boolean, under: boolean) => void;
+    setSide: (front: boolean) => void;
+    setEdges: (v: boolean) => void;
+    setCond: (v: boolean) => void;
+    swapStuds: (alt: any) => () => void;
+    box: THREE.Box3;
+    texturesReady: Promise<void>;
+};

package/dist/scene.d.ts

@@ -0,0 +1,74 @@
+import * as THREE from "three";
+import { type Pack } from "./render.js";
+import type { PartInstance, LDrawColor } from "./model.js";
+export type ColorSource = Map<number, string | LDrawColor> | Record<number | string, string | LDrawColor> | ((code: number) => THREE.ColorRepresentation | undefined);
+export interface LdrObjectOptions {
+    /** Draw LDraw type-2 edge lines (indexed, sharing each part's instance matrices). Default true. */
+    edges?: boolean;
+    /** Draw type-5 conditional lines (silhouettes of curved surfaces) when the pack carries them (`ldr pack --cond`, pack v2).
+     *  Shares each part's instance matrices; follows `edges` on/off. Default true (no effect on packs without them). */
+    conditionalLines?: boolean;
+    /** Also draw conditional lines on studs (stud silhouettes). Default true. Round 17 (M4 Pro, Datsville 100k): stud lines are
+     *  ~37% of conditional-line vertex work; turning them off saves ~3.7 ms/frame. Only read when the object is built. */
+    conditionalStudLines?: boolean;
+    /** Draw textured parts (printed / sticker parts using !TEXMAP) with their images when the pack carries them (`ldr pack --textures`).
+     *  Default true; false draws the parts' FALLBACK geometry like a pack without textures. Only read when the object is built. */
+    textures?: boolean;
+    /** Hide studs fully covered by a part above. Default true. */
+    cullStuds?: boolean;
+    /** Hide undersides (tubes) sitting fully on studs below. Default true. */
+    cullUndersides?: boolean;
+    /** 'front' = single-sided BFC faces (fast); 'double' = render both sides. Uncertified parts are always double-sided. Default 'front'. */
+    side?: "front" | "double";
+    /** 'plastic' = MeshPhysicalMaterial with clearcoat; 'standard' = MeshStandardMaterial (cheapest, used by the benchmarks). Default 'plastic'. */
+    material?: "plastic" | "standard";
+    /** Colour table override. Defaults to the `colors` table embedded in the pack by `ldr pack`. */
+    colors?: ColorSource;
+    /** Colour for unknown codes. Default #A0A5A9. */
+    fallbackColor?: THREE.ColorRepresentation;
+    /** Keep native LDraw space (-Y up, 1 unit = 1 LDU). Default false: the object is rotated to +Y up. */
+    ldrawSpace?: boolean;
+    /** Uniform scale applied to the object (e.g. 0.4 for millimetres, 0.01 for ~metres-ish). Default 1 (LDU). */
+    scale?: number;
+    /** Initial step (inclusive, 0-based global sequence from `sequenceSteps`). Default: show all. */
+    step?: number;
+}
+export interface LdrStats {
+    instances: number;
+    drawn: number;
+    missing: string[];
+    studsTotal: number;
+    studsHidden: number;
+    undersTotal: number;
+    undersHidden: number;
+    buildMs: number;
+    /** Conditional-line batches (draw calls) created; 0 for packs without conditional lines. */
+    condBatches?: number;
+    /** Textured batches (one per part x texture) and distinct textures; 0 for packs without textures. */
+    texBatches?: number;
+    textures?: number;
+}
+export interface LdrObject {
+    /** Add this to your scene. */
+    object: THREE.Group;
+    stats: LdrStats;
+    /** Number of build steps (nested submodel steps are sequenced). */
+    stepCount: number;
+    /** Show instances up to and including `step` (null = all). Rebuilds batches; culling is recomputed for the partial model. */
+    setStep(step: number | null): void;
+    setEdges(on: boolean): void;
+    /** Resolves when the pack's textures (if any) are decoded and ready to render. Replaced by a new promise after `setStep`. */
+    texturesReady: Promise<void>;
+    /** Toggle conditional lines (only visible while edges are on). */
+    setConditionalLines(on: boolean): void;
+    setCulling(studs: boolean, undersides: boolean): void;
+    setSide(side: "front" | "double"): void;
+    /** Bounding box in the object's parent space. */
+    getBox(target?: THREE.Box3): THREE.Box3;
+    dispose(): void;
+}
+/**
+ * Build a three.js object for a flattened model using a parts pack.
+ * Instances whose part is not in the pack are skipped and listed in `stats.missing`.
+ */
+export declare function createLdrObject(instances: PartInstance[], pack: Pack, options?: LdrObjectOptions): LdrObject;

package/dist/spec.d.ts

@@ -0,0 +1,149 @@
+export type M = number[];
+export type RotStep = {
+    x: number;
+    y: number;
+    z: number;
+    mode: "REL" | "ABS" | "ADD" | "END";
+};
+export type BufExchg = {
+    op: "STORE" | "RETRIEVE";
+    buf: string;
+};
+/** TEXMAP projection (LDraw !TEXMAP extension). Points are in the coordinates of the file containing the START/NEXT. */
+export type TexMapMethod = "PLANAR" | "CYLINDRICAL" | "SPHERICAL";
+export interface TexMap {
+    method: TexMapMethod;
+    p1: number[];
+    p2: number[];
+    p3: number[];
+    /** CYLINDRICAL: angular extent (degrees); SPHERICAL: horizontal extent (degrees). */
+    a?: number;
+    /** SPHERICAL: vertical extent (degrees). */
+    b?: number;
+    /** PNG name as written (resolve via `textures/<name>` then `<name>`, or an MPD `!DATA` block). */
+    texture: string;
+    glossmap?: string;
+    /** true for `!TEXMAP NEXT` (applies to the next type 1-5 line only). */
+    next?: boolean;
+}
+export type TexMapCmd = {
+    op: "START" | "NEXT" | "FALLBACK" | "END";
+    map?: TexMap;
+};
+/** Texture-mapping annotations on geometry (type 1-5) commands:
+ *  `tex` = texture in effect for TEXMAP-aware renderers (START..FALLBACK or NEXT); `fallback` = line sits between
+ *  FALLBACK and END, so TEXMAP-aware renderers skip it and everyone else draws it. */
+export interface TexAnno {
+    tex?: TexMap;
+    fallback?: boolean;
+}
+export type Cmd = ({
+    t: 0;
+    text: string;
+    meta?: string;
+    bfc?: string;
+    step?: boolean;
+    rotstep?: RotStep;
+    bufexchg?: BufExchg;
+    /** `0 !TEXMAP ...` */
+    texmap?: TexMapCmd;
+    /** `0 !: <line>`: textured-only geometry, ignored by renderers without TEXMAP support (parsed here for those that have it). */
+    geom?: Cmd;
+} & TexAnno) | ({
+    t: 1;
+    color: number;
+    m: M;
+    file: string;
+} & TexAnno) | ({
+    t: 2 | 5;
+    color: number;
+    p: number[];
+} & TexAnno) | ({
+    t: 3 | 4;
+    color: number;
+    p: number[];
+} & TexAnno);
+export interface LFile {
+    name: string;
+    cmds: Cmd[];
+    movedTo?: string; /** Every TEXMAP START/NEXT in this file, in order. */
+    texmaps?: TexMap[];
+}
+/** An MPD `0 !DATA` block (base64-decoded), e.g. an embedded PNG texture. */
+export interface DataBlock {
+    name: string;
+    bytes: Uint8Array; /** "image/png" when the bytes carry the PNG signature. */
+    mime?: string;
+}
+export interface Doc {
+    main: string;
+    files: Map<string, LFile>; /** MPD `!DATA` blocks keyed by normalized name. */
+    data?: Map<string, DataBlock>;
+}
+export declare const norm: (s: string) => string;
+/** Parse LDraw color token: decimal code, or direct color 0x2RRGGBB (and related 0xN…… forms). */
+export declare function parseColor(tok: string): number;
+/** Parse the tail of `0 !TEXMAP START|NEXT <method> <params> <png> [GLOSSMAP <png>]`. Returns null when malformed. */
+export declare function parseTexMap(tail: string, next?: boolean): TexMap | null;
+export declare function parse(src: string, name?: string): Doc;
+/** Find an embedded texture in a parsed MPD: tries `name`, then without / with a `textures/` prefix (case-insensitive). */
+export declare function resolveTexture(doc: Doc, name: string): DataBlock | null;
+/**
+ * Texture coordinates of point `p` (same space as the map's points) per the LDraw !TEXMAP spec, with the sign and orientation
+ * conventions of LDView (the reference renderer the library's textured parts are checked against; the spec leaves them open).
+ * v = 0 is the image's top row for all three methods.
+ * PLANAR: u = distance from plane P1 (through p1, normal p1->p2) / |p2 - p1|, v likewise along p1->p3 (p1 = top-left corner).
+ * CYLINDRICAL: p1 bottom centre, p2 top centre, p3 on the bottom rim under the texture's centre. u = 0.5 + angle / a, the angle
+ *   from p3's radial direction, right-handed about p1->p2; v = distance below the top plane / |p2 - p1| (0 at the top, 1 at the bottom;
+ *   LDView 4.6 "cylindrical TEXMAP right side up").
+ * SPHERICAL: p1 centre, p2 = texture centre on the sphere, p3 fixes plane P1 (the texture's horizontal bisector). Its normal
+ *   n = -((p1 - p2) x (p3 - p2)) is "north". u = 0.5 + longitude / a (angle within P1 from p1->p2, right-handed about n);
+ *   v = 0.5 + latitude / b with latitude negative toward n, so north maps to the image's top. (LDView measures latitude after
+ *   rotating the point to longitude 0, i.e. equirectangular, rather than the literal "projected to plane P2"; the official
+ *   globe textures 61287p01..p04 are drawn for that.)
+ * `inside` is false when (u, v) falls outside [0, 1] (the spec leaves those points untextured: base colour shows).
+ * Use `texmapTriangleUV` for triangles: it unwraps angles across the seam and handles points on the axis / poles like LDView.
+ */
+export declare function texmapUV(map: TexMap, p: number[]): {
+    u: number;
+    v: number;
+    inside: boolean;
+};
+/** (u, v) for the 3 corners of a triangle, flat [u0, v0, u1, v1, u2, v2]. Angular u is unwrapped relative to the first corner
+ *  (so a triangle across the seam of a 360-degree map stays continuous); corners on the axis (cylindrical) or at a pole
+ *  (spherical) take the average u of the other corners. */
+export declare function texmapTriangleUV(map: TexMap, pts: number[][]): number[];
+/** Transform a TexMap's points by an LDraw matrix (e.g. into part space when the START lives in a subfile). */
+export declare function transformTexMap(map: TexMap, m: M): TexMap;
+export declare function mul(a: M, b: M): M;
+export declare const I: M;
+/** True if color is an LDraw direct color (0x2RRGGBB etc.), not a palette CODE. */
+export declare const isDirectColor: (c: number) => boolean;
+export interface PartMesh {
+    name: string;
+    pos: Float32Array;
+    col: Uint32Array;
+    edges: Float32Array;
+    cond: Float32Array;
+    nrm: Float32Array;
+    /** Only with `mesh(name, { texmap: true })`: per-vertex (u, v) from the active !TEXMAP (NaN where untextured). */
+    uv?: Float32Array;
+    /** Only with texmap: per-triangle index into `textures` (-1 = untextured). */
+    texture?: Int32Array;
+    textures?: string[];
+}
+export interface Instance {
+    part: string;
+    color: number;
+    m: M;
+    step: number;
+    localStep: number;
+    steps: number[];
+    path: string;
+    missing: boolean;
+    aliasOf?: string;
+}
+/** Smooth normals that respect LDraw semantics: faces sharing an edge are smoothed together unless the
+ *  edge is a type-2 line (hard). Conditional (type-5) lines force smooth; unmarked edges smooth only below creaseDeg.
+ *  `cond` may be stride-6 (legacy endpoints only) or stride-12 (endpoints + 2 control points). */
+export declare function smoothNormals(pos: number[], edges: number[], cond: number[], creaseDeg?: number): Float32Array;

package/package.json

@@ -1,52 +1,72 @@
 {
   "name": "ldr",
-  "version": "0.0.0-alpha.1",
-  "description": "LDraw",
-  "files": [
-    "lib"
-  ],
-  "homepage": "https://github.com/evanbacon/ldr#readme",
+  "version": "0.3.0",
+  "description": "High-performance LEGO (LDraw) rendering for three.js: instanced parts packs, hidden stud/tube culling, low-detail studs, indexed edges, build steps.",
+  "license": "MIT",
+  "author": "Evan Bacon",
+  "type": "module",
+  "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/evanbacon/ldr.git"
-  },
-  "bugs": {
-    "url": "https://github.com/evanbacon/ldr/issues"
-  },
-  "main": "lib/index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "lint": "eslint .",
-    "prettier": "eslint . --fix"
-  },
-  "directories": {
-    "example": "examples",
-    "lib": "lib"
+    "url": "git+https://github.com/EvanBacon/ldr.git",
+    "directory": "packages/ldr"
   },
+  "homepage": "https://github.com/EvanBacon/ldr#readme",
+  "bugs": "https://github.com/EvanBacon/ldr/issues",
   "keywords": [
     "lego",
-    "three.js",
-    "graphics",
-    "opengl",
-    "gl",
-    "arkit",
-    "ldraw"
+    "ldraw",
+    "three",
+    "threejs",
+    "webgl",
+    "instancing",
+    "renderer",
+    "mpd",
+    "ldr",
+    "bricks",
+    "3d"
   ],
-  "author": "Evan Bacon",
-  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "ldr": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target browser --format esm --external three --external fzstd && bun build src/node/index.ts src/cli.ts --outdir dist --root src --target node --format esm --external three --external fzstd && tsc -p tsconfig.build.json && bun scripts/postbuild.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
   "dependencies": {
-    "three": "0.88.0"
+    "fzstd": "^0.1.1"
   },
   "peerDependencies": {
-    "three": "0.88.0"
+    "three": ">=0.160.0"
   },
   "devDependencies": {
-    "babel-jest": "^23.0.1",
-    "eslint": "^4.19.1",
-    "flow-bin": "^0.26.0",
-    "jest": "^23.1.0",
-    "prettier": "^1.13.5"
+    "@types/bun": "latest",
+    "@types/node": "^26.6.5",
+    "@types/three": "^0.180.0",
+    "three": "^0.186.1",
+    "typescript": "^5.9.0"
   },
-  "eslintConfig": {
+  "engines": {
+    "node": ">=18"
   }
 }

package/lib/index.js

@@ -1 +0,0 @@
-export default {};