@driftengine/capture 4.12.0 → 4.13.0

package/README.md

@@ -3,7 +3,7 @@
 A video to a playable scene, on the player's own device — no service, no account, and a runtime
 that never fetches.
 
-**72,960 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
+**73,103 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
 `scripts/fixtures/size/capture-only.ts`. Optional: nothing in `@driftengine/core` imports it.
 
 ## What is here so far

package/dist/gaussians/parameters.d.ts

@@ -31,5 +31,16 @@ export declare function clear(gradients: GaussianGradients, count: number): void
  * what the refinement grows the busiest of.
  */
 export declare function chain(cloud: Cloud, gradients: GaussianGradients): void;
-/** The fitted cloud as a capture: single precision, cut to what it holds. */
+/**
+ * The fitted cloud as a capture: single precision, cut to what it holds, and its colour as display
+ * values.
+ *
+ * **Encoded, because `SplatSource.colors` is a display value** — what every trained capture stores,
+ * since training fits photographs as they look — and the splat shader decodes it after the
+ * view-dependent term. The fit runs in linear light against decoded frames, so its colour goes out
+ * through the sRGB encode, which the shader's decode undoes exactly. The l=1 band is carried
+ * through the encode's slope at that colour, the first-order step: what it gives up is a sheen as
+ * large as the colour itself, which comes back a little off. What would make it wrong is a fit
+ * run in display values, which this one is not.
+ */
 export declare function harvest(cloud: Cloud): SplatSource;

package/dist/gaussians/parameters.js

@@ -145,21 +145,53 @@ export function chain(cloud, gradients) {
         }
     }
 }
-/** The fitted cloud as a capture: single precision, cut to what it holds. */
+/**
+ * The fitted cloud as a capture: single precision, cut to what it holds, and its colour as display
+ * values.
+ *
+ * **Encoded, because `SplatSource.colors` is a display value** — what every trained capture stores,
+ * since training fits photographs as they look — and the splat shader decodes it after the
+ * view-dependent term. The fit runs in linear light against decoded frames, so its colour goes out
+ * through the sRGB encode, which the shader's decode undoes exactly. The l=1 band is carried
+ * through the encode's slope at that colour, the first-order step: what it gives up is a sheen as
+ * large as the colour itself, which comes back a little off. What would make it wrong is a fit
+ * run in display values, which this one is not.
+ */
 export function harvest(cloud) {
     const { count } = cloud;
+    const linear = cloud.colors.values;
+    const colors = new Float32Array(count * 3);
+    for (let i = 0; i < count * 3; i += 1)
+        colors[i] = encode(Math.max(0, linear[i]));
     const source = {
         count,
         positions: Float32Array.from(cloud.positions.values.subarray(0, count * 3)),
         scales: Float32Array.from(cloud.scales.subarray(0, count * 3)),
         rotations: Float32Array.from(cloud.rotations.values.subarray(0, count * 4)),
-        colors: Float32Array.from(cloud.colors.values.subarray(0, count * 3)),
+        colors,
         opacities: Float32Array.from(cloud.opacities.subarray(0, count)),
     };
     if (cloud.sh1 === null)
         return source;
-    return {
-        ...source,
-        sh1: Float32Array.from(cloud.sh1.values.subarray(0, count * SH1_COEFFICIENTS)),
-    };
+    const band = cloud.sh1.values;
+    const sh1 = new Float32Array(count * SH1_COEFFICIENTS);
+    /* Interleaved by basis and then by channel, so coefficient `k` carries channel `k % 3`. */
+    for (let at = 0; at < count; at += 1) {
+        for (let k = 0; k < SH1_COEFFICIENTS; k += 1) {
+            const slope = encodeSlope(Math.max(0, linear[at * 3 + (k % 3)]));
+            sh1[at * SH1_COEFFICIENTS + k] = band[at * SH1_COEFFICIENTS + k] * slope;
+        }
+    }
+    return { ...source, sh1 };
+}
+/*
+ * The sRGB encode and its derivative, through the reproducible `exactExp` and `exactLog` the fit's
+ * other transforms use, so a capture fitted on two machines hands over the same colours.
+ */
+function encode(value) {
+    return value <= 0.0031308 ? value * 12.92 : 1.055 * exactExp(exactLog(value) / 2.4) - 0.055;
+}
+/** The encode's slope at `value`: 12.92 on its straight segment, and the curve's above it. */
+function encodeSlope(value) {
+    return value <= 0.0031308 ? 12.92 : (1.055 / 2.4) * exactExp(exactLog(value) * (1 / 2.4 - 1));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/capture",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "A video to a playable scene, on the player's device: the models it runs and the stages that use them",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,12 +27,12 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "4.12.0",
-    "@driftengine/drft": "4.12.0",
-    "@driftengine/nav": "4.12.0",
-    "@driftengine/physics": "4.12.0",
-    "@driftengine/splats": "4.12.0",
-    "@driftengine/texture": "4.12.0"
+    "@driftengine/core": "4.13.0",
+    "@driftengine/drft": "4.13.0",
+    "@driftengine/nav": "4.13.0",
+    "@driftengine/physics": "4.13.0",
+    "@driftengine/splats": "4.13.0",
+    "@driftengine/texture": "4.13.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/gaussians/parameters.ts

@@ -167,20 +167,53 @@ export function chain(cloud: Cloud, gradients: GaussianGradients): void {
   }
 }
 
-/** The fitted cloud as a capture: single precision, cut to what it holds. */
+/**
+ * The fitted cloud as a capture: single precision, cut to what it holds, and its colour as display
+ * values.
+ *
+ * **Encoded, because `SplatSource.colors` is a display value** — what every trained capture stores,
+ * since training fits photographs as they look — and the splat shader decodes it after the
+ * view-dependent term. The fit runs in linear light against decoded frames, so its colour goes out
+ * through the sRGB encode, which the shader's decode undoes exactly. The l=1 band is carried
+ * through the encode's slope at that colour, the first-order step: what it gives up is a sheen as
+ * large as the colour itself, which comes back a little off. What would make it wrong is a fit
+ * run in display values, which this one is not.
+ */
 export function harvest(cloud: Cloud): SplatSource {
   const { count } = cloud;
+  const linear = cloud.colors.values;
+  const colors = new Float32Array(count * 3);
+  for (let i = 0; i < count * 3; i += 1) colors[i] = encode(Math.max(0, linear[i] as number));
   const source: SplatSource = {
     count,
     positions: Float32Array.from(cloud.positions.values.subarray(0, count * 3)),
     scales: Float32Array.from(cloud.scales.subarray(0, count * 3)),
     rotations: Float32Array.from(cloud.rotations.values.subarray(0, count * 4)),
-    colors: Float32Array.from(cloud.colors.values.subarray(0, count * 3)),
+    colors,
     opacities: Float32Array.from(cloud.opacities.subarray(0, count)),
   };
   if (cloud.sh1 === null) return source;
-  return {
-    ...source,
-    sh1: Float32Array.from(cloud.sh1.values.subarray(0, count * SH1_COEFFICIENTS)),
-  };
+  const band = cloud.sh1.values;
+  const sh1 = new Float32Array(count * SH1_COEFFICIENTS);
+  /* Interleaved by basis and then by channel, so coefficient `k` carries channel `k % 3`. */
+  for (let at = 0; at < count; at += 1) {
+    for (let k = 0; k < SH1_COEFFICIENTS; k += 1) {
+      const slope = encodeSlope(Math.max(0, linear[at * 3 + (k % 3)] as number));
+      sh1[at * SH1_COEFFICIENTS + k] = (band[at * SH1_COEFFICIENTS + k] as number) * slope;
+    }
+  }
+  return { ...source, sh1 };
+}
+
+/*
+ * The sRGB encode and its derivative, through the reproducible `exactExp` and `exactLog` the fit's
+ * other transforms use, so a capture fitted on two machines hands over the same colours.
+ */
+function encode(value: number): number {
+  return value <= 0.0031308 ? value * 12.92 : 1.055 * exactExp(exactLog(value) / 2.4) - 0.055;
+}
+
+/** The encode's slope at `value`: 12.92 on its straight segment, and the curve's above it. */
+function encodeSlope(value: number): number {
+  return value <= 0.0031308 ? 12.92 : (1.055 / 2.4) * exactExp(exactLog(value) * (1 / 2.4 - 1));
 }