ldr 0.2.0 → 0.3.0

package/dist/node/library.d.ts

@@ -27,8 +27,15 @@ export declare class Library {
         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 (for future conditional-line rendering). */
-    mesh(name: string): PartMesh;
+     *  `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

@@ -25,6 +25,7 @@ export declare class Library {
 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>;

package/dist/render.d.ts

@@ -1,4 +1,6 @@
 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;
@@ -6,6 +8,10 @@ export type LdrParams = {
     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;
@@ -21,8 +27,26 @@ 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;
@@ -38,6 +62,8 @@ export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, c
     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

@@ -5,6 +5,15 @@ export type ColorSource = Map<number, string | LDrawColor> | Record<number | str
 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. */
@@ -33,6 +42,11 @@ export interface LdrStats {
     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. */
@@ -43,6 +57,10 @@ export interface LdrObject {
     /** 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. */

package/dist/spec.d.ts

@@ -9,7 +9,35 @@ export type BufExchg = {
     op: "STORE" | "RETRIEVE";
     buf: string;
 };
-export type Cmd = {
+/** 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;
@@ -17,33 +45,76 @@ export type Cmd = {
     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;
+    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>;
+    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. */
@@ -55,6 +126,11 @@ export interface PartMesh {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldr",
-  "version": "0.2.0",
+  "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",