ldr 0.5.1 → 0.6.0

package/dist/pack-io.d.ts

@@ -1,2 +1,11 @@
 /** 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>;
+/** A decoded parts pack. `buffer` is the raw (uncompressed) pack, used by `mergePacks`. */
+export type Pack = {
+    header: any;
+    arr: (r: any) => any;
+    bytes: number;
+    buffer?: ArrayBuffer;
+};
+/** Decode an uncompressed parts pack (4-byte LE header length, JSON header, then aligned typed-array payload). */
+export declare function decodePack(buf: ArrayBuffer): Pack;

package/dist/parts-cdn.d.ts

@@ -0,0 +1,64 @@
+import { type Pack } from "./pack-io.js";
+import { type PartInstance } from "./model.js";
+import { type CullResult } from "./cull.js";
+/** Default parts CDN (LDraw library parts, CC BY 2.0 / 4.0, compiled by ldr; hosted with the demo site). */
+export declare const DEFAULT_PARTS_CDN = "https://ldr-demo.vercel.app/cdn/v1/";
+export interface PartsCdnIndex {
+    format: string;
+    release?: string;
+    license?: string;
+    archives: string[];
+    bytes: number;
+    colors: Record<string, string>;
+    parts: Record<string, [number, number, number]>;
+}
+export interface LoadPartsOptions {
+    /** Base URL of the parts CDN (ending in /). Default `DEFAULT_PARTS_CDN`. */
+    cdn?: string;
+    /** Merge two byte ranges into one request when the gap between them is at most this many bytes. Default 16 KB. */
+    gap?: number;
+    /** Max parallel Range requests. Default 24 (HTTP/2 multiplexes them; browsers cap HTTP/1.1 at 6 per host themselves). */
+    concurrency?: number;
+    fetch?: typeof fetch;
+}
+/** Fetch (and cache) a parts CDN index. */
+export declare function loadPartsIndex(cdn?: string, f?: typeof fetch): Promise<PartsCdnIndex>;
+/** Merge several packs into one (parts and stud kinds; the first pack's definition wins on name clashes). */
+export declare function mergePacks(packs: Pack[], extra?: Record<string, unknown>): Pack;
+/**
+ * Fetch the given parts from a parts CDN and return them as one Pack (with the LDConfig colour table).
+ * Parts the CDN does not have are listed in `missing`.
+ */
+export declare function loadParts(names: Iterable<string>, o?: LoadPartsOptions): Promise<{
+    pack: Pack;
+    missing: string[];
+    requests: number;
+    bytes: number;
+}>;
+export interface PrepareOptions extends LoadPartsOptions {
+    /** Also compute stud/underside culling (for `createLdrObject`'s `precomputedCull`), using this `textures` setting (default true). */
+    cull?: boolean;
+    textures?: boolean;
+    /** Called with the flattened model as soon as it is parsed (before the parts are fetched). */
+    onParsed?: (insts: PartInstance[]) => void;
+    /** Treat `source` as LDraw text instead of a URL. */
+    text?: boolean;
+    /** File name used for the main model (MPD resolution). Default: last URL segment. */
+    name?: string;
+}
+export interface PreparedModel {
+    insts: PartInstance[];
+    pack: Pack;
+    missing: string[];
+    requests: number;
+    bytes: number;
+    timings: {
+        fetchModel: number;
+        parse: number;
+        parts: number;
+        cull?: number;
+    };
+    cull?: CullResult;
+}
+/** Everything in `loadModel` before three.js: fetch + parse the model, fetch + inflate + merge its parts. No DOM/three (runs in a Worker). */
+export declare function prepareModel(source: string, o?: PrepareOptions): Promise<PreparedModel>;

package/dist/render.d.ts

@@ -1,48 +1,36 @@
 import * as THREE from 'three';
-/** `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. */
+import { decodePack, type Pack } from './pack-io.js';
+export { decodePack, type Pack };
+/** `edges`: LDraw edge lines, welded + indexed and sharing each batch's instance matrices (`'idx'` is the same as `true`).
+ *  `cond`: draw type-5 conditional lines when the pack carries them (pack v2, built with `cond: true`) and edges are on. Default true.
+ *  `condStuds`: also draw them on stud batches (stud silhouettes). Default true. Uncertified (no BFC) parts are always double-sided. */
 export type LdrParams = {
-    pack: string;
+    cull?: CullResult;
     cullStuds: boolean;
     cullUnder: boolean;
-    edges: boolean | 'idx' | 'ss';
+    edges?: boolean | 'idx';
     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;
-    /** Compact vertex formats (int8 normals, uint8 colours). Default true. */
-    quant?: boolean;
     /** Distance LOD: spatial clusters per part, simplified meshes from `lod` packs, studs dropped and edges hidden once sub-pixel. Default true. */
     lod?: boolean;
     /** LOD: max screen-space error in pixels (default 0.5). */
     lodPx?: number;
     /** LOD: draw edge lines only where one stud (20 LDU) spans at least this many pixels (default 0.5; 0 = always). */
     lodEdgePx?: number;
-    /** LOD: drop sub-pixel studs (default true). */
-    lodStuds?: boolean;
-    /** LOD: use simplified meshes from `lod` packs (default true). */
-    lodMesh?: boolean;
+    /** LOD: draw only edge segments at least this many pixels long on screen (default 0.15; 0 = all). */
+    lodEdgeMinPx?: number;
+    /** LOD: skip upright parts' undersides while the camera is above their bottom faces and studs are < 4 px (default true). */
+    lodUnder?: boolean;
     /** Global build step per instance (same order as `insts`). Enables `setStep`: steps become instance-buffer compaction with
      *  step-aware culling instead of a rebuild. */
     steps?: ArrayLike<number>;
 };
-export type Inst = {
-    part: string;
-    color: string;
-    m: number[];
-};
-/** A decoded parts pack. `buffer` is the raw (uncompressed) pack, used by `mergePacks`. */
-export type Pack = {
-    header: any;
-    arr: (r: any) => any;
-    bytes: number;
-    buffer?: ArrayBuffer;
-};
+import { type Inst } from './cull.js';
+export type { Inst };
 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). */
@@ -64,23 +52,11 @@ export declare function conditionalLineVisible(cond: ArrayLike<number>, i: numbe
  *  `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;
-/** Culling result in flat arrays. Studs are enumerated in instance order, then each part's `studs` order (the order `forEachStud` visits). */
-export type CullResult = {
-    nStuds: number;
-    studHidden: Uint8Array;
-    studUp: Uint8Array;
-    underHidden: Uint8Array;
-    studsHidden: number;
-    /** With `steps`: the first build step at which each stud / underside is hidden (STEP_NEVER = never), for step-aware culling. */
-    studHideStep?: Int32Array;
-    underHideStep?: Int32Array;
-};
-/** `studHideStep` / `underHideStep` value for "never hidden". */
-export declare const STEP_NEVER = 2147483647;
-/** Visit every stud (instance order, then part stud order) with its world matrix `w` (scratch; copy to keep). */
-export declare function forEachStud(insts: Inst[], H: any, fn: (j: number, inst: number, w: Float64Array, kind: string, color: string, stud: number) => void): void;
-/** `steps` (optional, per instance): also compute when each stud / underside becomes hidden as the model is built step by step. */
-export declare function cullCore(insts: Inst[], H: any, steps?: ArrayLike<number>): CullResult;
+/** InstancedMesh.computeBoundingSphere() (three r151-r186), ported to a loop over the instance array: same arithmetic, same result
+ *  bit for bit, without a Matrix4 copy + Sphere clone per instance (1.8M studs on Datsville 100k). */
+export declare function instancedBoundingSphere(im: THREE.InstancedMesh): THREE.Sphere;
+import { forEachStud, cullCore, STEP_NEVER, type CullResult } from './cull.js';
+export { forEachStud, cullCore, STEP_NEVER, type CullResult };
 /** Object-shaped culling result (one entry per stud with its world matrix). Kept for API compatibility; `buildLdrScene` uses `cullCore`. */
 export declare function computeCulling(insts: Inst[], H: any): {
     studs: {
@@ -98,7 +74,6 @@ export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, c
     setSide: (front: boolean) => void;
     setEdges: (v: boolean) => void;
     setCond: (v: boolean) => void;
-    swapStuds: (alt: any) => () => void;
     setLod: (on: boolean) => void;
     setStep: (s: number | null) => {
         studsTotal: number;
@@ -109,3 +84,8 @@ export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, c
     box: THREE.Box3;
     texturesReady: Promise<void>;
 };
+/**
+ * Builds (and caches on the pack) the shared BufferGeometries `buildLdrScene` will use, in time slices of about `sliceMs` that yield
+ * to the event loop, until done or `stop()` returns true. Lets the main thread do this useful work while the load worker culls.
+ */
+export declare function warmPackGeometry(pack: Pack, stop?: () => boolean, sliceMs?: number): Promise<void>;

package/dist/scene.d.ts

@@ -1,9 +1,12 @@
 import * as THREE from "three";
 import { type Pack } from "./render.js";
+import { type CullResult } from "./cull.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 {
+    /** Culling computed ahead (e.g. by `prepareModel({ cull: true })` in a worker) for these same instances and `textures` setting. */
+    precomputedCull?: CullResult;
     /** 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).
@@ -36,12 +39,18 @@ export interface LdrObjectOptions {
     /** Distance LOD, re-selected for each camera you render with. Default true. Batches are split into spatial clusters (so off-screen
      *  ones are frustum-culled); each cluster draws the coarsest simplified mesh (from `lod` packs, the `buildPack` default) whose error
      *  stays under `lodPx`, drops studs whose 12-LDU disc is under `lodPx`, and hides edge lines where a stud spans under `lodEdgePx`.
-     *  Datsville 100k on an M4 Pro: 22 -> 6.3 ms per frame (57 -> 9.7 ms with edges); <=1.6% of pixels differ, mostly stud moire. */
+     *  Datsville 100k on an M4 Pro: 22 -> 4.3 ms per frame (57 -> 6.2 ms with edges); <=1.5% of pixels differ without edges, mostly stud moire. */
     lod?: boolean;
     /** LOD: max screen-space error in pixels. Default 0.5. */
     lodPx?: number;
     /** LOD: draw edge / conditional lines only where one stud (20 LDU) spans at least this many pixels. Default 0.5; 0 = always. */
     lodEdgePx?: number;
+    /** LOD: draw only the edge segments at least this many pixels long on screen (a part's edges are sorted longest first). Default 0.15;
+     *  0 = every segment. Shorter segments still darken a pixel each, so far views drawn with edges get lighter as this grows. */
+    lodEdgeMinPx?: number;
+    /** LOD: skip undersides that can't be seen: while the camera is behind every bottom face of a cluster's (same-orientation) parts and
+     *  studs are under 4 px, or where the body is drawn as its closed bounding box. Default true. */
+    lodUnder?: boolean;
 }
 export interface LdrStats {
     instances: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldr",
-  "version": "0.5.1",
+  "version": "0.6.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",
@@ -49,7 +49,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun scripts/build.ts && tsc -p tsconfig.build.json && bun scripts/postbuild.ts && node scripts/check-dist.mjs",
+    "build": "rm -rf dist && bun scripts/gen-worker.ts && bun scripts/build.ts && tsc -p tsconfig.build.json && bun scripts/postbuild.ts && node scripts/check-dist.mjs",
     "test": "bun test",
     "prepublishOnly": "bun run build && bun test"
   },