ldr 0.3.0 → 0.4.0

package/dist/node/library.d.ts

@@ -1,9 +1,15 @@
+import { type FlattenOptions } from "../model.js";
 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>;
+    /** Files registered from flattened documents (MPD files and synthetic parts), searched before the library (MPD spec: a document's
+     *  files win over library files of the same name). The latest `flatten` wins; replacing or shadowing an entry clears the mesh cache. */
+    embedded: Map<string, Doc>;
+    /** Register `name` as a part whose source is file `file` of `doc` (or a parsed synthetic source). */
+    register(name: string, doc: Doc, file?: string): void;
     /** Optional second root for unofficial parts (e.g. Unofficial/ next to the official tree). */
     constructor(root: string, unofficialRoot?: string | undefined);
     /**
@@ -37,6 +43,8 @@ export declare class Library {
      *  `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[];
+    /** Flatten a model into part instances (see `flatten` in the browser entry for the rules; `models/` library files are walked
+     *  as submodels). 24 handled at render (edge color). Alias parts resolve to canonical names. MPD files and synthetic parts
+     *  (loose model geometry, model-level !TEXMAP wrappers) are registered so `mesh(inst.part)` / `mesh(inst.texPart)` find them. */
+    flatten(doc: Doc, opts?: FlattenOptions): Instance[];
 }

package/dist/node/resolver.d.ts

@@ -1,3 +1,5 @@
+import { type Doc } from '../spec.js';
+import { type FlattenOptions, type PartInstance } from '../model.js';
 export declare const TOP_STUD_RE: RegExp;
 export declare const UNDER_STUD_RE: RegExp;
 export declare const norm: (ref: any) => any;
@@ -17,6 +19,11 @@ export declare class Library {
     text: Map<string, string>;
     stats: Map<string, any>;
     constructor(root: string);
+    /** Document files registered by `flatten` (MPD files, synthetic parts): name -> key `mpd/<name>`. Searched first (MPD spec:
+     *  a document's files win over library files). First registration wins; a different text for the same name goes to `conflicts`. */
+    virtual: Map<string, string>;
+    conflicts: Set<string>;
+    addVirtual(name: string, text: string): string;
     resolve(ref: any): string | null;
     read(key: string): string;
     isPart(key: any): any;
@@ -27,7 +34,27 @@ export declare function splitModel(text: any, fallbackName?: string): {
     main: string | null;
     data: Map<string, string>;
 };
-export declare function flatten(model: any, lib: any, onInstance: any): {
+/** Parse the files of a `splitModel` result into a document (same parser as the browser path). */
+export declare function modelDoc(model: {
+    files: Map<string, string>;
+    main: string | null;
+}): Doc;
+export type ResolvedInstance = {
+    part: string;
+    ref: string;
+    color: string;
+    m: number[];
+    texPart?: string;
+    texRef?: string;
+    inst: PartInstance;
+};
+/**
+ * Flatten a `splitModel` result to library-resolved instances (`part` = library key, `ref` = name as referenced). Same walk as the
+ * browser `flatten` (shared code): MPD-embedded parts and synthetic parts (a model file's own geometry; with `textures`, parts wrapped
+ * by a model-level !TEXMAP) are registered on `lib` as virtual files (`mpd/<name>`) so the Compiler compiles them; every file of the
+ * document is registered, so MPD files also win over library files referenced from parts (MPD spec).
+ */
+export declare function flatten(model: any, lib: Library, onInstance: (i: ResolvedInstance) => void, opts?: FlattenOptions): {
     missing: Map<any, any>;
 };
 export declare function collectDeps(lib: any, refs: any): Map<any, any>;

package/dist/render.d.ts

@@ -1,5 +1,5 @@
 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.
+/** `cond`: draw type-5 conditional lines when the pack carries them (pack v2, built with `cond: true`); with 'idx' or legacy `true` edges. Default true.
  *  `condStuds`: also draw them on stud batches (stud silhouettes). Default true. */
 export type LdrParams = {
     pack: string;

package/dist/scene.d.ts

@@ -1,6 +1,7 @@
 import * as THREE from "three";
 import { type Pack } from "./render.js";
 import type { PartInstance, LDrawColor } from "./model.js";
+import type { StepView } from "./spec.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. */
@@ -54,6 +55,9 @@ export interface LdrObject {
     stats: LdrStats;
     /** Number of build steps (nested submodel steps are sequenced). */
     stepCount: number;
+    /** Per build step, the view rotation set by MLCad `0 ROTSTEP` (null = default view). Get the 3x3 (LDraw space, row-major) with
+     *  `stepViewMatrix(view, yourDefaultView)`; in three.js terms rotate the model by it inside the object's -Y-up flip. */
+    stepViews: (StepView | null)[];
     /** 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;

package/dist/spec.d.ts

@@ -57,17 +57,23 @@ export type Cmd = ({
 } & TexAnno) | ({
     t: 2 | 5;
     color: number;
-    p: number[];
+    p: number[]; /** source line, only with `parse(..., { geometryText: true })` (then `p` is empty) */
+    src?: string;
 } & TexAnno) | ({
     t: 3 | 4;
     color: number;
     p: number[];
+    src?: string;
 } & TexAnno);
 export interface LFile {
     name: string;
     cmds: Cmd[];
     movedTo?: string; /** Every TEXMAP START/NEXT in this file, in order. */
     texmaps?: TexMap[];
+    /** File type from the header (`0 !LDRAW_ORG <type>`, or legacy `0 LDRAW_ORG` / `0 Unofficial <type>` / `0 Official LCAD <type>`), lowercased
+     *  with any `unofficial_` prefix removed, e.g. "part", "subpart", "primitive", "shortcut", "model". Only header lines before the file's
+     *  first type 1-5 line count, and only known types are recorded. */
+    org?: string;
 }
 /** An MPD `0 !DATA` block (base64-decoded), e.g. an embedded PNG texture. */
 export interface DataBlock {
@@ -85,7 +91,12 @@ export declare const norm: (s: string) => string;
 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;
+/** `geometryText`: keep type 2-5 lines as their source text (`src`) with empty `p` instead of parsing their numbers (for tools that
+ *  only walk references and pass geometry through as text, e.g. the node pack builder; ~3x faster on geometry-heavy files). */
+export interface ParseOptions {
+    geometryText?: boolean;
+}
+export declare function parse(src: string, name?: string, popts?: ParseOptions): 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;
 /**
@@ -132,6 +143,7 @@ export interface PartMesh {
     texture?: Int32Array;
     textures?: string[];
 }
+/** A placed part from `Library.flatten` (same fields as `PartInstance`, plus library resolution). */
 export interface Instance {
     part: string;
     color: number;
@@ -142,8 +154,77 @@ export interface Instance {
     path: string;
     missing: boolean;
     aliasOf?: string;
+    embedded?: boolean;
+    source?: (() => string) & {
+        file?: LFile;
+        step?: number;
+    };
+    texPart?: string;
+    texSource?: string;
+    view?: StepView;
 }
 /** 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;
+export type FileKind = "part" | "model";
+/**
+ * Is a file of an MPD document a part (render its geometry as one unit) or a model (walk its type-1 lines into instances)?
+ * The MPD spec (ldraw.org article 47) makes no distinction, so this follows the file headers, then the content:
+ * 1. A header type decides (`0 !LDRAW_ORG <type>`, legacy `0 LDRAW_ORG`, `0 Unofficial <type>`, `0 Official LCAD <type>`;
+ *    an `Unofficial_` prefix is ignored): Part, Subpart, Primitive, 8_Primitive, 48_Primitive, Shortcut, Helper -> part;
+ *    Model, Submodel, Configuration -> model.
+ * 2. Without a header, the main (first) file is a model, and any other file is a part iff it has its own geometry
+ *    (a type 2-5 line, or a `0 !:` TEXMAP geometry line) or references a subpart / low-res primitive (`s/`, `8/`, `48/`).
+ *    Everything else (only type-1 references) is a model, as before.
+ * Files not in the document are library files (parts). A model's own type 2-5 lines are rendered too, as synthetic
+ * parts (see `looseSource`).
+ */
+export declare function fileKind(doc: Doc, name: string): FileKind;
+/** Local steps (as counted by `flatten`) in which a file has its own type 2-5 lines or `0 !:` geometry, ascending. */
+export declare function looseSteps(f: LFile): number[];
+/** LDraw colour token for a colour code: decimal, or `0x2RRGGBB` for direct colours. */
+export declare const colorToken: (c: number) => string;
+/** Name of the synthetic part holding a model file's own geometry in local step `step`: `<file>#<step>`. */
+export declare const loosePartName: (file: string, step: number) => string;
+/**
+ * The synthetic part for a model file's own type 2-5 lines in local step `step`, as a file: every `0 BFC` line of the file
+ * (winding / certification state, in order), the step's `!TEXMAP` and `0 !:` lines, and the step's type 2-5 lines. Type-1 lines
+ * are dropped (they are instances), together with a `!TEXMAP NEXT` that applied to one. Commands are shared with `f`.
+ */
+export declare function looseFile(f: LFile, step: number): LFile;
+/** LDraw source text of `looseFile(f, step)`. */
+export declare function looseSource(f: LFile, step: number): string;
+/** FNV-1a 32-bit, hex. */
+export declare function hash32(s: string): string;
+/** Inverse of an affine LDraw matrix, or null when singular. */
+export declare function invert(m: M): M | null;
+/**
+ * Synthetic part for a part reference wrapped by a model-level `!TEXMAP` (the map is defined in the model, not in the part file).
+ * `map` must already be in the part's own coordinates. The wrapper is a certified file that applies the map to the part, so
+ * TEXMAP-aware compilers texture it exactly as if the START were written in the part, and plain compilers produce the part itself.
+ * Name: `<part>#tex-<hash of the source>` (identical maps on the same part share one synthetic part).
+ */
+export declare function texWrapper(part: string, map: TexMap): {
+    name: string;
+    source: string;
+};
+/** View rotation for a build step from MLCad `0 ROTSTEP` (MLCad LDraw command extensions 2.0, §6.1).
+ *  `abs` false: view = <default view matrix> x `m`; true: view = `m`. `m` is 3x3 row-major. `rotstep` is the command that set it. */
+export interface StepView {
+    abs: boolean;
+    m: number[];
+    rotstep: RotStep;
+}
+/** ROTSTEP rotation matrix for angles in degrees, MLCad 2.0 §6.1.5 (= Rx * Ry * Rz), 3x3 row-major [a b c d e f g h i]. */
+export declare function rotStepMatrix(x: number, y: number, z: number): number[];
+/** The view matrix for a step (3x3 row-major): REL/ADD-from-default = `defaultView` x m, ABS = m, no ROTSTEP / END = `defaultView`. */
+export declare function stepViewMatrix(view: StepView | null | undefined, defaultView?: number[]): number[];
+/**
+ * View per local step of a file (index = step number as counted by `flatten`; null = default view). MLCad semantics: STEP and
+ * ROTSTEP both end a step; a ROTSTEP sets the view of the step it ends (MLCad 2.0 §6.1: "drawing stops after executing the
+ * command"; put a plain STEP right before it to show the rotation on its own) and of every later step until the next ROTSTEP.
+ * REL: default x R; ADD: current x R (from the default view if none); ABS: R; END: back to the default view. Each file starts
+ * at the default view (submodel steps are viewed on their own, as LPub3D does).
+ */
+export declare function fileStepViews(f: LFile): (StepView | null)[];

package/package.json

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