minidraco 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# minidraco
+
+A fast, pure-TypeScript [Draco](https://google.github.io/draco/) mesh decoder with a drop-in
+`DRACOLoader` replacement for [Three.js](https://threejs.org/) — no wasm files to host, no
+external decoder to fetch and compile, and a built-in worker pool so decoding never blocks the
+main thread.
+
+minidraco started as a TypeScript port of [mrdoob/draco.js](https://github.com/mrdoob/draco.js)
+(MIT), then restructured and optimized (rANS table pooling, seam-list corner tables, allocation
+elimination in the entropy decoders, specialized attribute extraction) to close the gap with the
+official [draco3d](https://www.npmjs.com/package/draco3d) wasm decoder.
+
+## Usage
+
+```ts
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
+import { MiniDRACOLoader } from 'minidraco/three'
+
+const gltfLoader = new GLTFLoader()
+gltfLoader.setDRACOLoader(new MiniDRACOLoader())
+gltfLoader.load('model.glb', gltf => scene.add(gltf.scene))
+```
+
+`MiniDRACOLoader` is API-compatible with `THREE.DRACOLoader` (`setDecoderPath` and friends are
+no-ops). Decoding runs in a pool of module workers (default 4, `setWorkerLimit(n)` to change,
+`0` to force synchronous main-thread decoding). If workers can't be spawned (SSR, exotic
+bundlers), it falls back to synchronous decoding automatically.
+
+Or decode a raw Draco bitstream without Three.js:
+
+```ts
+import { decodeDracoMesh } from 'minidraco'
+
+const mesh = decodeDracoMesh(new Uint8Array(bytes))
+```
+
+## Feature support
+
+- Triangular meshes: edgebreaker (standard + valence) and sequential encodings, all bitstream
+  prediction schemes (delta, parallelogram, multi-parallelogram, constrained multi-parallelogram,
+  portable tex-coords, geometric octahedron normals)
+- Quantized, integer, and octahedron-normal attributes
+- Custom / generic attributes (glTF `_*` semantics), skinning attributes (`JOINTS_0` /
+  `WEIGHTS_0`), vertex colors, multiple UV sets
+- Output is verified bit-identical to the official wasm decoder (≤ 1 ulp on dequantized floats)
+  in the test suite, on both real production GLBs and Draco's own test corpus
+- Point clouds are not supported (glTF `KHR_draco_mesh_compression` only ever contains meshes)
+
+## Performance
+
+Decoding the three production bundle GLBs in `example/public/models` (Apple Silicon, medians;
+`bun run bench` for the harness). Raw single-threaded decode, bun/JSC:
+
+| file (points / faces)                | minidraco | draco.js | draco3d wasm |
+| ------------------------------------ | --------- | -------- | ------------ |
+| canine (1.1k / 0.5k)                 | 0.6 ms    | 0.6 ms   | 0.4 ms       |
+| player (5.1k / 2.5k)                 | 1.9 ms    | 1.7 ms   | 1.2 ms       |
+| static (291k / 221k, 488 primitives) | **50 ms** | 55 ms    | 51 ms        |
+
+In the browser the worker pool changes the story for real scenes — wall-clock
+`GLTFLoader.parse` of the 488-primitive static bundle (Chromium, warm loaders, `/bench` page of
+the example):
+
+| decoder                  | static bundle | main thread |
+| ------------------------ | ------------- | ----------- |
+| minidraco (4 workers)    | ~51 ms        | free        |
+| draco.js (main thread)   | ~72 ms        | blocked     |
+| draco3d wasm (4 workers) | ~23 ms        | free        |
+
+And unlike the wasm decoder there is nothing to host or fetch: the first decode doesn't pay the
+~50–70 ms wasm download + compile + worker bootstrap, which typically makes minidraco the fastest
+option for the first model on screen.
+
+## Download size
+
+What the browser actually downloads per decoder (minified with esbuild, `three` external since
+it's shared; gzip -9 / brotli -q 11):
+
+| payload                                               | plain  | gzip    | brotli  |
+| ----------------------------------------------------- | ------ | ------- | ------- |
+| minidraco — `minidraco/three` in the app bundle       | 102 KB | 26.6 KB | 23.1 KB |
+| minidraco — `worker.js` chunk (fetched on 1st decode) | 99 KB  | 25.5 KB | 22.1 KB |
+| draco.js — loader + decoder in the app bundle         | 96 KB  | 24.8 KB | 21.5 KB |
+| draco3d — `draco_wasm_wrapper.js` (runtime fetch)     | 78 KB  | 13.1 KB | 11.0 KB |
+| draco3d — `draco_decoder.wasm` (runtime fetch)        | 279 KB | 86.1 KB | 64.6 KB |
+
+Totals over the wire (brotli): **minidraco ~45 KB** (23 KB in the app bundle + 22 KB worker
+chunk, or just 23 KB with `setWorkerLimit(0)`), **draco.js ~22 KB**, **draco3d wasm ~76 KB** —
+and the wasm files are separate runtime fetches you must host, on the critical path of the first
+decode, while the JS decoders ship inside your existing bundle chunks.
+
+## Monorepo
+
+- `library/` — the `minidraco` package
+- `example/` — Next.js + React Three Fiber demo (model/decoder switcher, per-mesh filter,
+  animation playback, in-browser benchmark at `/bench`)
+
+```sh
+bun install
+bun dev        # library watch build + example dev server
+bun run all    # format check, lint, typecheck, warden, tests
+bun run bench  # decoder comparison benchmark (bun)
+```
+
+The test suite decodes every Draco primitive of the bundle GLBs with minidraco and the official
+draco3d wasm decoder and compares indices and every attribute value, plus 13 raw `.drc` fixtures
+from Draco's test corpus covering the encodings the bundles don't hit.
+
+## License
+
+MIT — includes code derived from [mrdoob/draco.js](https://github.com/mrdoob/draco.js) (MIT),
+implementing Google's [Draco](https://github.com/google/draco) bitstream (Apache-2.0).

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+declare class BitDecoder {
+    _bitBuffer: Uint8Array | null;
+    _bitOffset: number;
+    _byteLength: number;
+    constructor();
+    reset(uint8Array: Uint8Array, byteLength: number): void;
+    bitsDecoded(): number;
+    getBits(nbits: number): number | undefined;
+}
+declare class DecoderBuffer {
+    _data: Uint8Array | null;
+    _dataView: DataView | null;
+    _dataSize: number;
+    _pos: number;
+    _bitDecoder: BitDecoder;
+    _bitMode: boolean;
+    _bitstreamVersion: number;
+    constructor();
+    init(data: ArrayBuffer | Uint8Array | ArrayLike<number>, dataSize?: number, version?: number): void;
+    decodeUint8(): number | undefined;
+    decodeInt8(): number | undefined;
+    decodeUint16(): number | undefined;
+    decodeUint32(): number | undefined;
+    decodeInt32(): number | undefined;
+    decodeFloat32(): number | undefined;
+    decodeUint64(): number | undefined;
+    decodeBytes(size: number): Uint8Array | undefined;
+    startBitDecoding(decodeSize: boolean): number | undefined;
+    endBitDecoding(): void;
+    decodeLeastSignificantBits32(nbits: number): number | undefined;
+    decodeVarintUint32(): number | undefined;
+    decodeVarintUint64(): number | undefined;
+    advance(bytes: number): void;
+    get bitstreamVersion(): number;
+    set bitstreamVersion(v: number);
+    get data(): Uint8Array;
+    get dataHead(): Uint8Array;
+    get remainingSize(): number;
+    get decodedSize(): number;
+    get bitDecoderActive(): boolean;
+}
+
+declare class DataBuffer {
+    _data: Uint8Array;
+    constructor();
+    update(data: Uint8Array | ArrayBufferView | ArrayBuffer | null | undefined, size: number, offset?: number): boolean;
+    resize(newSize: number): void;
+    write(bytePos: number, inArray: Uint8Array | ArrayBufferView | ArrayBuffer, dataSize: number): void;
+    get data(): Uint8Array;
+    get dataSize(): number;
+    _resize(newSize: number): void;
+}
+
+declare const Type: {
+    readonly INVALID: -1;
+    readonly POSITION: 0;
+    readonly NORMAL: 1;
+    readonly COLOR: 2;
+    readonly TEX_COORD: 3;
+    readonly GENERIC: 4;
+    readonly NAMED_ATTRIBUTES_COUNT: 5;
+};
+declare class GeometryAttribute {
+    _buffer: DataBuffer | null;
+    _numComponents: number;
+    _dataType: number;
+    _normalized: boolean;
+    _byteStride: number;
+    _byteOffset: number;
+    _attributeType: number;
+    _uniqueId: number;
+    constructor();
+    init(attributeType: number, buffer: DataBuffer | null, numComponents: number, dataType: number, normalized: boolean, byteStride: number, byteOffset: number): void;
+    getAddress(attIndex: number): Uint8Array;
+    copyFrom(srcAtt: GeometryAttribute): boolean;
+    resetBuffer(buffer: DataBuffer, byteStride: number, byteOffset: number): void;
+    get attributeType(): number;
+    get dataType(): number;
+    get numComponents(): number;
+    get buffer(): DataBuffer | null;
+    get byteStride(): number;
+    get byteOffset(): number;
+    get uniqueId(): number;
+    set uniqueId(id: number);
+}
+
+declare class AttributeTransformData {
+    _transformType: number;
+    _buffer: DataBuffer;
+    constructor();
+    get transformType(): number;
+    set transformType(type: number);
+    setParameterValue(byteOffset: number, value: number, type: string): void;
+    appendParameterValue(value: number, type: string): void;
+    _typeSize(type: string): number;
+}
+
+type ExtractTypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
+declare class PointAttribute extends GeometryAttribute {
+    _identityMapping: boolean;
+    _numUniqueEntries: number;
+    _indicesMap: number[] | Uint32Array;
+    _attributeBuffer: DataBuffer | null;
+    _attributeTransformData: AttributeTransformData | null;
+    _cachedFloat32View?: Float32Array;
+    _cachedFloat32Buffer?: ArrayBufferLike;
+    _cachedInt32View?: Int32Array;
+    _cachedInt32Buffer?: ArrayBufferLike;
+    _cachedUint32View?: Uint32Array;
+    _cachedUint32Buffer?: ArrayBufferLike;
+    _cachedUint16View?: Uint16Array;
+    _cachedUint16Buffer?: ArrayBufferLike;
+    _cachedInt16View?: Int16Array;
+    _cachedInt16Buffer?: ArrayBufferLike;
+    _cachedUint8View?: Uint8Array;
+    _cachedUint8Buffer?: ArrayBufferLike;
+    _cachedInt8View?: Int8Array;
+    _cachedInt8Buffer?: ArrayBufferLike;
+    _cachedFloat64View?: Float64Array;
+    _cachedFloat64Buffer?: ArrayBufferLike;
+    _cachedDataView?: DataView;
+    _cachedDVBuffer?: ArrayBufferLike;
+    constructor(geometryAttribute?: GeometryAttribute);
+    init(attributeType: number, numComponents: number, dataType: number, normalized: boolean, numAttributeValues: number): void;
+    reset(numAttributeValues: number): boolean;
+    get size(): number;
+    mappedIndex(pointIndex: number): number;
+    get isMappingIdentity(): boolean;
+    get indicesMapSize(): number;
+    get indicesMap(): number[] | Uint32Array;
+    setIdentityMapping(): void;
+    setExplicitMapping(numPoints: number): void;
+    setExplicitMappingUnfilled(numPoints: number): void;
+    setAttributeTransformData(transformData: AttributeTransformData): void;
+    convertValue(attIndex: number, outVal: number[] | Int32Array | Uint32Array | Float32Array | Float64Array): void;
+    extractTo<C extends new (length: number) => ExtractTypedArray>(OutputTypedArray: C, numPoints: number): InstanceType<C>;
+    copyFrom(srcAtt: PointAttribute): void;
+}
+
+declare class PointCloud {
+    num_points_: number;
+    attributes_: (PointAttribute | null)[];
+    named_attribute_index_: number[][];
+    constructor();
+    numNamedAttributes(type: number): number;
+    getNamedAttributeId(type: number, i?: number): number;
+    getNamedAttribute(type: number, i?: number): PointAttribute | null;
+    getAttributeByUniqueId(uniqueId: number): PointAttribute | null;
+    getAttributeIdByUniqueId(uniqueId: number): number;
+    numAttributes(): number;
+    attribute(attId: number): PointAttribute;
+    addAttribute(pa: PointAttribute): number;
+    setAttribute(attId: number, pa: PointAttribute): void;
+    numPoints(): number;
+    setNumPoints(num: number): void;
+}
+
+declare class Mesh extends PointCloud {
+    faces_: Int32Array;
+    numFaces_: number;
+    attribute_data_: {
+        elementType: number;
+    }[];
+    constructor();
+    _ensureFaceCapacity(numFaces: number): void;
+    addFace(face: ArrayLike<number>): void;
+    setNumFaces(numFaces: number): void;
+    numFaces(): number;
+    face(faceId: number): number[];
+    setAttribute(attId: number, pa: PointAttribute): void;
+}
+
+declare class DracoOptions {
+    _globalOptions: Map<string, unknown>;
+    _attributeOptions: Map<number, Map<string, unknown>>;
+    constructor();
+    getGlobalBool(name: string, defaultVal: boolean): boolean;
+    findAttributeOptions(attKey: number): Map<string, unknown> | null;
+    getAttributeBool(attKey: number, name: string, defaultVal: boolean): boolean;
+}
+
+declare class DecoderOptions extends DracoOptions {
+    constructor();
+}
+
+declare class Decoder {
+    options_: DecoderOptions;
+    constructor();
+    static getEncodedGeometryType(inBuffer: DecoderBuffer): number;
+    decodeMeshFromBuffer(inBuffer: DecoderBuffer): {
+        mesh: Mesh | null;
+        ok: boolean;
+        message: string;
+    };
+    decodeBufferToMesh(inBuffer: DecoderBuffer, outGeometry: Mesh): {
+        ok: boolean;
+        message: string;
+    };
+    options(): DecoderOptions;
+}
+
+declare const DataType: {
+    readonly INVALID: 0;
+    readonly INT8: 1;
+    readonly UINT8: 2;
+    readonly INT16: 3;
+    readonly UINT16: 4;
+    readonly INT32: 5;
+    readonly UINT32: 6;
+    readonly INT64: 7;
+    readonly UINT64: 8;
+    readonly FLOAT32: 9;
+    readonly FLOAT64: 10;
+    readonly BOOL: 11;
+    readonly TYPES_COUNT: 12;
+};
+type DataType = (typeof DataType)[keyof typeof DataType];
+
+declare const EncodedGeometryType: {
+    readonly INVALID_GEOMETRY_TYPE: -1;
+    readonly POINT_CLOUD: 0;
+    readonly TRIANGULAR_MESH: 1;
+    readonly NUM_ENCODED_GEOMETRY_TYPES: 2;
+};
+type EncodedGeometryType = (typeof EncodedGeometryType)[keyof typeof EncodedGeometryType];
+
+declare const decodeDracoMesh: (data: Uint8Array) => Mesh;
+
+export { DataType, Decoder, DecoderBuffer, EncodedGeometryType, Type as GeometryAttributeType, Mesh, PointAttribute, decodeDracoMesh };