minidraco 0.4.0 → 0.5.0

package/README.md

@@ -43,16 +43,17 @@ Median across an 18-model corpus vs [draco.js](https://github.com/mrdoob/draco.j
 [draco3d](https://www.npmjs.com/package/draco3d) wasm decoder (full results in
 [BENCH.md](https://github.com/verekia/minidraco/blob/main/BENCH.md)):
 
-| benchmark                                     | vs draco.js     | vs draco3d wasm |
-| --------------------------------------------- | --------------- | --------------- |
-| single-threaded decode — bun (JSC)            | 🟢 1.23× faster | 🟢 1.32× faster |
-| single-threaded decode — Chrome (V8)          | 🟢 1.26× faster | 🟢 1.06× faster |
-| `GLTFLoader.parse`, worker pool — Chrome (V8) | 🟢 1.46× faster | 🔴 1.05× slower |
-
-Faster than draco.js across the corpus, ahead of the wasm decoder single-threaded, and
-competitive in a real `GLTFLoader.parse` with the main thread left free.
-
-🟢 There's no `draco_decoder.wasm` to fetch and compile before the first decode, so minidraco (and draco.js) often beat the wasm decoder on first load (not reflected on the benchmark).
+| benchmark                                          | vs draco.js     | vs draco3d wasm |
+| -------------------------------------------------- | --------------- | --------------- |
+| single-threaded decode — bun (JSC)                 | 🟢 1.27× faster | 🟢 1.38× faster |
+| single-threaded decode — Chrome (V8)               | 🟢 1.29× faster | 🟢 1.11× faster |
+| `GLTFLoader.parse`, warm worker pool — Chrome (V8) | 🟢 1.62× faster | ⚪ even         |
+| `GLTFLoader.parse`, cold first load — Chrome (V8)  | 🟢 1.31× faster | ⚪ even         |
+
+Faster than draco.js across the corpus, ahead of the wasm decoder single-threaded, and even with
+it in a real `GLTFLoader.parse` with the main thread left free — both warm and on the first load
+of a session, where minidraco's worker pool is still JIT-warming while the wasm decoder is
+fetching and compiling its module (no `draco_decoder.wasm` to host or download here).
 
 ## Download size
 

package/dist/index.js

@@ -1264,6 +1264,8 @@ var MetadataDecoder = class {
 var ANS_P8_PRECISION = 256;
 var ANS_L_BASE = 4096;
 var ANS_IO_BASE = 256;
+var COARSE_STREAM_FACTOR = 8;
+var COARSE_BUCKET_BITS = 8;
 function memGetLe16(buf, offset) {
   return buf[offset] | buf[offset + 1] << 8;
 }
@@ -1341,6 +1343,13 @@ var RAnsDecoder = class {
   lutTable;
   probTable;
   cumProbTable;
+  // Short-stream mode (see ransBuildLookUpTable): no full-precision lut; a
+  // 256-entry bucket table narrows each lookup to a symbol range that a short
+  // cumProb scan finishes. cumProbTable then carries one extra trailing entry
+  // (== ransPrecision) so the scan needs no bounds check.
+  coarse;
+  bucketShift;
+  bucketTable;
   buf;
   bufOffset;
   // First valid byte of this decoder's slice within buf (absolute offsets,
@@ -1355,6 +1364,9 @@ var RAnsDecoder = class {
     this.lutTable = null;
     this.probTable = null;
     this.cumProbTable = null;
+    this.coarse = false;
+    this.bucketShift = 0;
+    this.bucketTable = null;
     this.buf = null;
     this.bufOffset = 0;
     this.bufStart = 0;
@@ -1414,6 +1426,10 @@ var RAnsDecoder = class {
       tablePool.push(this.cumProbTable);
       this.cumProbTable = null;
     }
+    if (this.bucketTable !== null) {
+      tablePool.push(this.bucketTable);
+      this.bucketTable = null;
+    }
     return this.state === this.lRansBase;
   }
   ransRead() {
@@ -1427,7 +1443,14 @@ var RAnsDecoder = class {
     }
     const quo = state >>> this.ransPrecisionBits;
     const rem = state & this.ransPrecisionMask;
-    const symbol = this.lutTable[rem];
+    let symbol;
+    if (this.coarse) {
+      const cumProbTable = this.cumProbTable;
+      symbol = this.bucketTable[rem >> this.bucketShift];
+      while (cumProbTable[symbol + 1] <= rem) symbol++;
+    } else {
+      symbol = this.lutTable[rem];
+    }
     this.state = quo * this.probTable[symbol] + rem - this.cumProbTable[symbol];
     this.bufOffset = bufOffset;
     return symbol;
@@ -1439,6 +1462,10 @@ var RAnsDecoder = class {
   // once here so each loop body stays monomorphic on its concrete type. The
   // three bodies are intentionally identical copies.
   decodeSymbols(out, count) {
+    if (this.coarse) {
+      this._decodeSymbolsCoarse(out, count);
+      return;
+    }
     const lutTable = this.lutTable;
     if (lutTable instanceof Uint8Array) {
       this._decodeSymbolsU8(out, count, lutTable);
@@ -1492,6 +1519,33 @@ var RAnsDecoder = class {
     this.state = state;
     this.bufOffset = bufOffset;
   }
+  // Short-stream loop: bucket table + cumProb scan instead of the full lut.
+  // Same state arithmetic as the lut loops, so the output is identical.
+  _decodeSymbolsCoarse(out, count) {
+    const buf = this.buf;
+    const lRansBase = this.lRansBase;
+    const ransPrecisionBits = this.ransPrecisionBits;
+    const ransPrecisionMask = this.ransPrecisionMask;
+    const probTable = this.probTable;
+    const cumProbTable = this.cumProbTable;
+    const bucketTable = this.bucketTable;
+    const bucketShift = this.bucketShift;
+    let state = this.state;
+    let bufOffset = this.bufOffset;
+    const bufStart = this.bufStart;
+    for (let i = 0; i < count; ++i) {
+      while (state < lRansBase && bufOffset > bufStart) {
+        state = state << 8 | buf[--bufOffset];
+      }
+      const rem = state & ransPrecisionMask;
+      let symbol = bucketTable[rem >> bucketShift];
+      while (cumProbTable[symbol + 1] <= rem) symbol++;
+      out[i] = symbol;
+      state = (state >>> ransPrecisionBits) * probTable[symbol] + rem - cumProbTable[symbol];
+    }
+    this.state = state;
+    this.bufOffset = bufOffset;
+  }
   _decodeSymbolsU32(out, count, lutTable) {
     const buf = this.buf;
     const lRansBase = this.lRansBase;
@@ -1514,23 +1568,62 @@ var RAnsDecoder = class {
     this.state = state;
     this.bufOffset = bufOffset;
   }
-  // Builds the ransPrecision-entry lookup table. Returns false on bad input data.
-  ransBuildLookUpTable(tokenProbs, numSymbols) {
-    const LutArray = numSymbols <= 256 ? Uint8Array : numSymbols <= 65536 ? Uint16Array : Uint32Array;
-    const lutTable = acquirePooled(LutArray, this.ransPrecision);
+  // Builds the decoding tables. Returns false on bad input data.
+  //
+  // expectedCount is how many symbols the caller will decode from this stream.
+  // The full lut has ransPrecision (>= 4096) entries, and a primitive-heavy
+  // file builds thousands of them to decode a few dozen symbols each -- on such
+  // files the table builds cost more than the decodes. Short streams therefore
+  // get a coarse 256-entry bucket table (symbol at the start of each
+  // precision/256-wide bucket) and finish each lookup with a scan of the
+  // cumulative probabilities; long streams keep the exact lut, whose per-symbol
+  // cost is lower.
+  ransBuildLookUpTable(tokenProbs, numSymbols, expectedCount = 2147483647) {
+    const ransPrecision = this.ransPrecision;
+    const coarse = numSymbols <= 65535 && expectedCount * COARSE_STREAM_FACTOR < ransPrecision;
+    this.coarse = coarse;
     const probTable = acquirePooled(Uint32Array, numSymbols);
-    const cumProbTable = acquirePooled(Uint32Array, numSymbols);
-    this.lutTable = lutTable;
+    const cumProbTable = acquirePooled(Uint32Array, numSymbols + 1);
     this.probTable = probTable;
     this.cumProbTable = cumProbTable;
     let cumProb = 0;
+    if (coarse) {
+      this.lutTable = null;
+      for (let i = 0; i < numSymbols; ++i) {
+        const prob = tokenProbs[i];
+        probTable[i] = prob;
+        cumProbTable[i] = cumProb;
+        cumProb += prob;
+        if (cumProb > ransPrecision) {
+          return false;
+        }
+      }
+      if (cumProb !== ransPrecision) {
+        return false;
+      }
+      cumProbTable[numSymbols] = ransPrecision;
+      const bucketShift = this.ransPrecisionBits - COARSE_BUCKET_BITS;
+      const bucketTable = acquirePooled(Uint16Array, 1 << COARSE_BUCKET_BITS);
+      this.bucketShift = bucketShift;
+      this.bucketTable = bucketTable;
+      let symbol = 0;
+      for (let b = 0; b < 1 << COARSE_BUCKET_BITS; ++b) {
+        const rem = b << bucketShift;
+        while (cumProbTable[symbol + 1] <= rem) symbol++;
+        bucketTable[b] = symbol;
+      }
+      return true;
+    }
+    const LutArray = numSymbols <= 256 ? Uint8Array : numSymbols <= 65536 ? Uint16Array : Uint32Array;
+    const lutTable = acquirePooled(LutArray, ransPrecision);
+    this.lutTable = lutTable;
     let actProb = 0;
     for (let i = 0; i < numSymbols; ++i) {
       const prob = tokenProbs[i];
       probTable[i] = prob;
       cumProbTable[i] = cumProb;
       cumProb += prob;
-      if (cumProb > this.ransPrecision) {
+      if (cumProb > ransPrecision) {
         return false;
       }
       if (prob < 32) {
@@ -1542,9 +1635,10 @@ var RAnsDecoder = class {
       }
       actProb = cumProb;
     }
-    if (cumProb !== this.ransPrecision) {
+    if (cumProb !== ransPrecision) {
       return false;
     }
+    cumProbTable[numSymbols] = ransPrecision;
     return true;
   }
 };
@@ -1993,14 +2087,18 @@ var PointCloudDecoder = class _PointCloudDecoder {
     for (let i2 = 0; i2 < decoders.length; i2++) {
       decoders[i2].collectPendingSymbolStreams(pending);
     }
+    const paired = pending.filter((stream) => !stream.ans.coarse);
     let i = 0;
-    for (; i + 1 < pending.length; i += 2) {
-      const a = pending[i];
-      const b = pending[i + 1];
+    for (; i + 1 < paired.length; i += 2) {
+      const a = paired[i];
+      const b = paired[i + 1];
       ransDecodeSymbolsPair(a.ans, a.out, a.count, b.ans, b.out, b.count);
     }
-    if (i < pending.length) {
-      pending[i].ans.decodeSymbols(pending[i].out, pending[i].count);
+    if (i < paired.length) {
+      paired[i].ans.decodeSymbols(paired[i].out, paired[i].count);
+    }
+    for (const stream of pending) {
+      if (stream.ans.coarse) stream.ans.decodeSymbols(stream.out, stream.count);
     }
     for (let k = 0; k < decoders.length; k++) {
       if (!decoders[k].decodeAttributesFinish()) {
@@ -2570,8 +2668,10 @@ var RAnsSymbolDecoder = class {
   get numSymbols() {
     return this.numSymbols_;
   }
-  // Initialize the decoder and decode the probability table.
-  create(buffer) {
+  // Initialize the decoder and decode the probability table. expectedCount is
+  // the number of symbols the caller will decode (lets short streams skip the
+  // full lookup table; see RAnsDecoder.ransBuildLookUpTable).
+  create(buffer, expectedCount = 2147483647) {
     if (buffer.bitstreamVersion === 0) {
       return false;
     }
@@ -2612,7 +2712,7 @@ var RAnsSymbolDecoder = class {
       }
     }
     buffer.advance(pos - startPos);
-    if (!this.ans_.ransBuildLookUpTable(this.probabilityTable_, this.numSymbols_)) {
+    if (!this.ans_.ransBuildLookUpTable(this.probabilityTable_, this.numSymbols_, expectedCount)) {
       return false;
     }
     return true;
@@ -2654,7 +2754,7 @@ function decodeSymbols(numValues, numComponents, srcBuffer, outValues) {
 }
 function decodeTaggedSymbols(numValues, numComponents, srcBuffer, outValues) {
   const tagDecoder = new RAnsSymbolDecoder(5);
-  if (!tagDecoder.create(srcBuffer)) {
+  if (!tagDecoder.create(srcBuffer, Math.ceil(numValues / numComponents))) {
     return false;
   }
   if (!tagDecoder.startDecoding(srcBuffer)) {
@@ -2719,7 +2819,7 @@ function parseRawSymbolStream(numValues, srcBuffer) {
     return null;
   }
   const decoder = new RAnsSymbolDecoder(maxBitLength);
-  if (!decoder.create(srcBuffer)) {
+  if (!decoder.create(srcBuffer, numValues)) {
     return null;
   }
   if (numValues > 0 && decoder.numSymbols === 0) {
@@ -2732,7 +2832,7 @@ function parseRawSymbolStream(numValues, srcBuffer) {
 }
 function decodeRawSymbolsInternal(uniqueSymbolsBitLength, numValues, srcBuffer, outValues) {
   const decoder = new RAnsSymbolDecoder(uniqueSymbolsBitLength);
-  if (!decoder.create(srcBuffer)) {
+  if (!decoder.create(srcBuffer, numValues)) {
     return false;
   }
   if (numValues > 0 && decoder.numSymbols === 0) {
@@ -4234,11 +4334,16 @@ var PredictionSchemeDeltaDecoder = class extends PredictionSchemeDecoder {
     return true;
   }
   computeOriginalValues(inCorr, outData, size, numComponents, entryToPointIdMap) {
-    this._transform.init(numComponents);
+    const transform = this._transform;
+    transform.init(numComponents);
+    if (transform.computeOriginalValuesDelta) {
+      transform.computeOriginalValuesDelta(inCorr, outData, size, numComponents);
+      return true;
+    }
     const zeroVals = new Int32Array(numComponents);
-    this._transform.computeOriginalValue(zeroVals, 0, inCorr, 0, outData, 0);
+    transform.computeOriginalValue(zeroVals, 0, inCorr, 0, outData, 0);
     for (let i = numComponents; i < size; i += numComponents) {
-      this._transform.computeOriginalValue(outData, i - numComponents, inCorr, i, outData, i);
+      transform.computeOriginalValue(outData, i - numComponents, inCorr, i, outData, i);
     }
     return true;
   }
@@ -4779,7 +4884,6 @@ var AttributeTransform = class {
 // src/decoder/attributes/AttributeOctahedronTransform.ts
 var AttributeOctahedronTransform = class extends AttributeTransform {
   _quantizationBits;
-  _tmpVec;
   constructor() {
     super();
     this._quantizationBits = -1;
@@ -4811,15 +4915,30 @@ var AttributeOctahedronTransform = class extends AttributeTransform {
     const srcI32 = new Int32Array(srcAddr.buffer, srcAddr.byteOffset, numPoints * 2);
     const dstAddr = targetAttribute.getAddress(0);
     const dstF32 = new Float32Array(dstAddr.buffer, dstAddr.byteOffset, numPoints * 3);
-    const outVec = this._tmpVec || (this._tmpVec = new Float32Array(3));
+    const fround = Math.fround;
+    const scale = toolBox._dequantizationScale;
     let si = 0;
     let di = 0;
     for (let i = 0; i < numPoints; i++) {
-      toolBox.quantizedOctahedralCoordsToUnitVector(srcI32[si], srcI32[si + 1], outVec);
+      let y = fround(fround(fround(srcI32[si]) * scale) - 1);
+      let z = fround(fround(fround(srcI32[si + 1]) * scale) - 1);
       si += 2;
-      dstF32[di] = outVec[0];
-      dstF32[di + 1] = outVec[1];
-      dstF32[di + 2] = outVec[2];
+      const x = fround(fround(1 - Math.abs(y)) - Math.abs(z));
+      let xOffset = -x;
+      if (xOffset < 0) xOffset = 0;
+      y = fround(y + (y < 0 ? xOffset : -xOffset));
+      z = fround(z + (z < 0 ? xOffset : -xOffset));
+      const normSquared = fround(fround(fround(x * x) + fround(y * y)) + fround(z * z));
+      if (normSquared < 1e-6) {
+        dstF32[di] = 0;
+        dstF32[di + 1] = 0;
+        dstF32[di + 2] = 0;
+      } else {
+        const d = fround(1 / fround(Math.sqrt(normSquared)));
+        dstF32[di] = fround(x * d);
+        dstF32[di + 1] = fround(y * d);
+        dstF32[di + 2] = fround(z * d);
+      }
       di += 3;
     }
     return true;
@@ -4989,6 +5108,140 @@ var PredictionSchemeNormalOctahedronCanonicalizedDecodingTransform = class exten
     outOrigVals[outOffset] = origS + center;
     outOrigVals[outOffset + 1] = origT + center;
   }
+  // Fused delta loop for PredictionSchemeDeltaDecoder: the whole
+  // value[i] = original(value[i-1], corr[i]) chain in one call, with the
+  // toolbox fields hoisted to locals and the previous output carried in
+  // locals. This is the hot path for PREDICTION_DIFFERENCE normals (one call
+  // per value through the interface was ~8% of decode time on the bundles).
+  // The arithmetic is computeOriginalValue above verbatim -- keep them in
+  // sync; only the plumbing differs.
+  computeOriginalValuesDelta(inCorr, outData, size, numComponents) {
+    const toolBox = this._octahedronToolBox;
+    const center = toolBox._centerValue;
+    const maxQuantizedValue = toolBox._maxQuantizedValue;
+    let prevS = 0;
+    let prevT = 0;
+    for (let i = 0; i < size; i += numComponents) {
+      const corrS = inCorr[i];
+      const corrT = inCorr[i + 1];
+      let predS = prevS - center;
+      let predT = prevT - center;
+      const predIsInDiamond = Math.abs(predS) + Math.abs(predT) <= center;
+      if (!predIsInDiamond) {
+        let signS = 0;
+        let signT = 0;
+        if (predS >= 0 && predT >= 0) {
+          signS = 1;
+          signT = 1;
+        } else if (predS <= 0 && predT <= 0) {
+          signS = -1;
+          signT = -1;
+        } else {
+          signS = predS > 0 ? 1 : -1;
+          signT = predT > 0 ? 1 : -1;
+        }
+        const cornerPointS = signS * center;
+        const cornerPointT = signT * center;
+        let us = predS * 2 - cornerPointS | 0;
+        let ut = predT * 2 - cornerPointT | 0;
+        if (signS * signT >= 0) {
+          const temp = us;
+          us = -ut;
+          ut = -temp;
+        } else {
+          const temp = us;
+          us = ut;
+          ut = temp;
+        }
+        predS = (us + cornerPointS) / 2 | 0;
+        predT = (ut + cornerPointT) / 2 | 0;
+      }
+      const predIsInBottomLeft = predS === 0 && predT === 0 || predS < 0 && predT <= 0;
+      let rotationCount = 0;
+      if (predS === 0) {
+        if (predT > 0) rotationCount = 3;
+        else if (predT < 0) rotationCount = 1;
+      } else if (predS > 0) {
+        if (predT >= 0) rotationCount = 2;
+        else rotationCount = 1;
+      } else {
+        if (predT > 0) rotationCount = 3;
+      }
+      if (!predIsInBottomLeft) {
+        const s = predS, t = predT;
+        switch (rotationCount) {
+          case 1:
+            predS = t;
+            predT = -s | 0;
+            break;
+          case 2:
+            predS = -s | 0;
+            predT = -t | 0;
+            break;
+          case 3:
+            predS = -t | 0;
+            predT = s;
+            break;
+        }
+      }
+      let origS = predS + corrS | 0;
+      if (origS > center) origS -= maxQuantizedValue;
+      else if (origS < -center) origS += maxQuantizedValue;
+      let origT = predT + corrT | 0;
+      if (origT > center) origT -= maxQuantizedValue;
+      else if (origT < -center) origT += maxQuantizedValue;
+      if (!predIsInBottomLeft) {
+        const s = origS, t = origT;
+        switch (4 - rotationCount & 3) {
+          case 1:
+            origS = t;
+            origT = -s | 0;
+            break;
+          case 2:
+            origS = -s | 0;
+            origT = -t | 0;
+            break;
+          case 3:
+            origS = -t | 0;
+            origT = s;
+            break;
+        }
+      }
+      if (!predIsInDiamond) {
+        let signS = 0;
+        let signT = 0;
+        if (origS >= 0 && origT >= 0) {
+          signS = 1;
+          signT = 1;
+        } else if (origS <= 0 && origT <= 0) {
+          signS = -1;
+          signT = -1;
+        } else {
+          signS = origS > 0 ? 1 : -1;
+          signT = origT > 0 ? 1 : -1;
+        }
+        const cornerPointS = signS * center;
+        const cornerPointT = signT * center;
+        let us = origS * 2 - cornerPointS | 0;
+        let ut = origT * 2 - cornerPointT | 0;
+        if (signS * signT >= 0) {
+          const temp = us;
+          us = -ut;
+          ut = -temp;
+        } else {
+          const temp = us;
+          us = ut;
+          ut = temp;
+        }
+        origS = (us + cornerPointS) / 2 | 0;
+        origT = (ut + cornerPointT) / 2 | 0;
+      }
+      prevS = origS + center | 0;
+      prevT = origT + center | 0;
+      outData[i] = prevS;
+      outData[i + 1] = prevT;
+    }
+  }
 };
 
 // src/decoder/compression/attributes/prediction_schemes/PredictionSchemeNormalOctahedronDecodingTransform.ts
@@ -7223,7 +7476,7 @@ var MeshEdgebreakerTraversalValenceDecoder = class extends MeshEdgebreakerTraver
           return false;
         }
         const decoder = new RAnsSymbolDecoder(maxBitLength);
-        if (!decoder.create(outBuffer)) {
+        if (!decoder.create(outBuffer, numSymbols)) {
           return false;
         }
         if (decoder.numSymbols === 0) {
@@ -7239,37 +7492,38 @@ var MeshEdgebreakerTraversalValenceDecoder = class extends MeshEdgebreakerTraver
         this._contextCounters[i] = 0;
       }
     }
-    const allU8 = pending.every((entry) => entry.decoder.ans_.lutTable instanceof Uint8Array);
+    const lockstep = pending.filter((entry) => entry.decoder.ans_.lutTable instanceof Uint8Array);
     let p = 0;
-    if (allU8) {
-      while (pending.length - p >= 3) {
-        const a = pending[p];
-        const b = pending[p + 1];
-        const c = pending[p + 2];
-        ransDecodeSymbolsTrioU8(
-          a.decoder.ans_,
-          a.out,
-          a.count,
-          b.decoder.ans_,
-          b.out,
-          b.count,
-          c.decoder.ans_,
-          c.out,
-          c.count
-        );
-        p += 3;
-      }
-      if (pending.length - p === 2) {
-        const a = pending[p];
-        const b = pending[p + 1];
-        ransDecodeSymbolsPairU8(a.decoder.ans_, a.out, a.count, b.decoder.ans_, b.out, b.count);
-        p += 2;
-      }
+    while (lockstep.length - p >= 3) {
+      const a = lockstep[p];
+      const b = lockstep[p + 1];
+      const c = lockstep[p + 2];
+      ransDecodeSymbolsTrioU8(
+        a.decoder.ans_,
+        a.out,
+        a.count,
+        b.decoder.ans_,
+        b.out,
+        b.count,
+        c.decoder.ans_,
+        c.out,
+        c.count
+      );
+      p += 3;
     }
-    for (; p < pending.length; ++p) {
-      pending[p].decoder.ans_.decodeSymbols(pending[p].out, pending[p].count);
+    if (lockstep.length - p === 2) {
+      const a = lockstep[p];
+      const b = lockstep[p + 1];
+      ransDecodeSymbolsPairU8(a.decoder.ans_, a.out, a.count, b.decoder.ans_, b.out, b.count);
+      p += 2;
+    }
+    for (; p < lockstep.length; ++p) {
+      lockstep[p].decoder.ans_.decodeSymbols(lockstep[p].out, lockstep[p].count);
     }
     for (const entry of pending) {
+      if (!(entry.decoder.ans_.lutTable instanceof Uint8Array)) {
+        entry.decoder.ans_.decodeSymbols(entry.out, entry.count);
+      }
       entry.decoder.endDecoding();
     }
     return true;