@bubo-squared/gyroview 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 What changed for a page using the package, newest first. Until 1.0, a minor version may change
 the API.
 
+## 0.4.1 (2026-10-01)
+
+What a page may notice:
+
+- An Insta360 X4 Air recording is stabilized about the right axes: its IMU frame is measured
+  (ADR 0009) where it was assumed. The `ready` event's `imuFrame` is
+  `{ name: 'X4 Air', isVerified: true }` where it was the unverified aligned frame, and the load
+  no longer warns (`recording-degraded`) that the IMU frame has not been verified on a recording.
+- A camera is given a measured IMU frame only by its whole model name: a model whose name merely
+  begins with a measured camera's, such as a later "X5 Pro", gets the unverified frame and its
+  warning until a recording of it is measured.
+
+## 0.4.0 (2026-10-01)
+
+New:
+
+- Insta360 X6 recordings play. Their only calibration is a v6 string, now read as the Mei model
+  with more terms (ADR 0032); the X6's IMU frame and the radial scale its lenses want are
+  measured (ADR 0009, ADR 0023); and its 10-bit HLG video is shown as SDR, as Insta360 Studio
+  shows it (ADR 0033).
+- Each of the `ready` event's `tracks` has a `colour`: its primaries, transfer, matrix and range
+  as the track's bitstream says (`TrackColour`, with the types `ColourPrimaries`,
+  `TransferCharacteristics`, `MatrixCoefficients` and `ColourRange`).
+- `inspectRecording`'s calibration strings include `offsetV6`, and `calibrationVersion` may be
+  6, the v6 string's.
+
+What a page may notice:
+
+- A recording whose only calibration is a v6 string plays where it failed with
+  `no-calibration`.
+- Stabilization samples the gyro half way through each frame's shutter, no longer half a
+  readout later. An X5's stabilized picture shifts by that half readout (4 ms at 5.7K60, 10.6 ms
+  at 8K30), and a swinging camera's world holds stiller (ADR 0034).
+- A track whose colour the player cannot show as it should is drawn with a
+  `recording-degraded` warning: a PQ or linear-light transfer is drawn as recorded, SDR of wider
+  primaries than BT.709's is shown as BT.709, HLG of primaries other than BT.709's or BT.2020's
+  keeps its gamut.
+- The decoder is told the track's whole colour, not only its range (the range alone where the
+  browser's WebCodecs does not know one of its values).
+- Where a browser's decoder converts a track's colour through another matrix than the track's
+  own, as Safari's does with the X6's BT.2020, the picture is brought back to the track's.
+- Seeking again and again, or dragging the seek bar, no longer stops playback now and then with
+  `decode` ("the audio element failed (media error 3)"): the sound is handed to the browser in
+  whole segments, so a seek can no longer cut one in half.
+
 ## 0.3.1 (2026-09-30)
 
 New:

package/README.md

@@ -1,6 +1,6 @@
 # @bubo-squared/gyroview
 
-Play raw Insta360 `.insv` recordings (X3, X4, X5) in the browser. `<gyro-view>` reads the
+Play raw Insta360 `.insv` recordings (X3, X4, X5, X6) in the browser. `<gyro-view>` reads the
 camera's dual-fisheye file directly, over HTTP byte ranges or from a local file, decodes both
 lenses in hardware with WebCodecs, and stitches and gyro-stabilizes them on the GPU. No Insta360
 Studio export step.
@@ -45,10 +45,10 @@ A page without a bundler loads the standalone file, which has Three.js and media
 ```html
 <script
   type="module"
-  src="https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.3/dist/standalone.js"
+  src="https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.4/dist/standalone.js"
 ></script>
 <script type="module">
-  import { inspectRecording } from 'https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.3/dist/standalone.js';
+  import { inspectRecording } from 'https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.4/dist/standalone.js';
 </script>
 ```
 

package/dist/index.d.ts

@@ -42,6 +42,7 @@ declare const CalibrationVersion: {
 	readonly Legacy: 1;
 	readonly Polynomial: 2;
 	readonly Mei: 3;
+	readonly ExtendedMei: 6;
 };
 type CalibrationVersion = (typeof CalibrationVersion)[keyof typeof CalibrationVersion];
 type Milliseconds = Brand<number, "Milliseconds">;
@@ -67,6 +68,7 @@ interface CalibrationStrings {
 	readonly offset: string | undefined;
 	readonly offsetV2: string | undefined;
 	readonly offsetV3: string | undefined;
+	readonly offsetV6: string | undefined;
 }
 /**
  * Everything the player learns from the info record. Absent fields are `undefined`; nothing here
@@ -225,6 +227,39 @@ export interface RecordingInspection {
 	readonly gyro: GyroSummary | UnreadableGyro | undefined;
 	readonly exposure: ExposureReport | undefined;
 }
+declare const COLOUR_PRIMARIES: readonly [
+	"bt709",
+	"bt470bg",
+	"smpte170m",
+	"bt2020",
+	"smpte432"
+];
+declare const TRANSFER_CHARACTERISTICS: readonly [
+	"bt709",
+	"smpte170m",
+	"iec61966-2-1",
+	"linear",
+	"pq",
+	"hlg"
+];
+declare const MATRIX_COEFFICIENTS: readonly [
+	"rgb",
+	"bt709",
+	"bt470bg",
+	"smpte170m",
+	"bt2020-ncl"
+];
+type Unspecified = "unspecified";
+export type ColourPrimaries = (typeof COLOUR_PRIMARIES)[number] | Unspecified;
+export type TransferCharacteristics = (typeof TRANSFER_CHARACTERISTICS)[number] | Unspecified;
+export type MatrixCoefficients = (typeof MATRIX_COEFFICIENTS)[number] | Unspecified;
+export type ColourRange = "full" | "limited" | Unspecified;
+export interface TrackColour {
+	readonly primaries: ColourPrimaries;
+	readonly transfer: TransferCharacteristics;
+	readonly matrix: MatrixCoefficients;
+	readonly range: ColourRange;
+}
 interface VideoTrackDescription {
 	readonly trackIndex: number;
 	readonly codedWidth: number;
@@ -233,6 +268,7 @@ interface VideoTrackDescription {
 	 * WebCodecs codec string, for example `hvc1.1.6.L153.B0` or `avc1.640033`.
 	 */
 	readonly codec: string;
+	readonly colour: TrackColour;
 }
 export type StabilizationMode = "off" | "lock" | "horizon" | "follow";
 export declare const STABILIZATION_MODES: readonly StabilizationMode[];

package/dist/packages/adapters/mediabunny/src/MediabunnyAudioPackager.js

@@ -1,4 +1,4 @@
-import { GyroViewError } from "../../../core/src/shared/errors/GyroViewError.js";
+import { GyroViewError, ensureInvariant } from "../../../core/src/shared/errors/GyroViewError.js";
 import "../../../core/src/index.js";
 import { SegmentChannel } from "./SegmentChannel.js";
 import { EncodedAudioPacketSource, EncodedPacket, Mp4OutputFormat, NullTarget, Output } from "mediabunny";
@@ -9,10 +9,9 @@ import { EncodedAudioPacketSource, EncodedPacket, Mp4OutputFormat, NullTarget, O
 */
 var FRAGMENT_DURATION_SECONDS = 1;
 /**
-* Segments (each fragment is two: `moof` and `mdat`) that may wait for the consumer before
-* re-packaging pauses.
+* Media segments that may wait for the consumer before re-packaging pauses.
 */
-var SEGMENTS_AHEAD = 4;
+var SEGMENTS_AHEAD = 2;
 /**
 * The codec strings of the audio the cameras record, AAC (`mp4a.40.2` for AAC-LC), and mediabunny's
 * name for it. Other codecs are not re-packaged: the picture then plays on a silent clock.
@@ -21,10 +20,10 @@ var AAC_CODEC_STRING_PREFIX = "mp4a.40.";
 var AAC = "aac";
 /**
 * AudioPackager over mediabunny: the samples re-packaged, unchanged, into fragmented MP4.
-* Segments are taken from the muxer's box callbacks rather than from its byte stream: that
-* yields whole `ftyp`/`moov`/`moof`/`mdat` boxes and leaves out the `mfra` index the muxer
-* appends at the end, which Media Source Extensions do not accept. Fragmented output keeps the
-* track's own timestamps, so segments started mid-track land at their true time.
+* Segments are assembled from the muxer's box callbacks rather than taken from its byte stream:
+* that yields whole segments and leaves out the `mfra` index the muxer appends at the end, which
+* Media Source Extensions do not accept. Fragmented output keeps the track's own timestamps, so
+* segments started mid-track land at their true time.
 */
 var MediabunnyAudioPackager = class {
 	segmentsOf(samples, configuration) {
@@ -112,18 +111,53 @@ function decoderConfigOf(configuration) {
 		...configuration.description && { description: configuration.description }
 	};
 }
+/**
+* The muxer's boxes handed on as whole segments: the initialization segment (`ftyp` and `moov`)
+* and each media segment (`moof` and its `mdat`). A consumer that stops between two segments, as
+* a seek does, then never leaves a source buffer's parser inside one, where Chromium reads the
+* next segments' bytes as the samples of the `moof` it holds and fails to decode them.
+*/
 function fragmentedMp4Into(channel) {
-	const forward = (data) => {
-		channel.push(new Uint8Array(data));
-	};
+	const segment = new SegmentAssembly(channel);
 	return new Mp4OutputFormat({
 		fastStart: "fragmented",
 		minimumFragmentDuration: FRAGMENT_DURATION_SECONDS,
-		onFtyp: forward,
-		onMoov: forward,
-		onMoof: forward,
-		onMdat: forward
+		onFtyp: (data) => {
+			segment.begin(data);
+		},
+		onMoov: (data) => {
+			segment.end(data);
+		},
+		onMoof: (data) => {
+			segment.begin(data);
+		},
+		onMdat: (data) => {
+			segment.end(data);
+		}
 	});
 }
+/**
+* A segment's first box held until the box that ends it arrives, then both pushed as one.
+*/
+var SegmentAssembly = class {
+	channel;
+	opening;
+	constructor(channel) {
+		this.channel = channel;
+	}
+	begin(box) {
+		ensureInvariant(this.opening === void 0, "a segment began before the last one ended");
+		this.opening = new Uint8Array(box);
+	}
+	end(box) {
+		const { opening } = this;
+		ensureInvariant(opening !== void 0, "a segment ended that never began");
+		const whole = new Uint8Array(opening.byteLength + box.byteLength);
+		whole.set(opening);
+		whole.set(box, opening.byteLength);
+		this.opening = void 0;
+		this.channel.push(whole);
+	}
+};
 //#endregion
 export { MediabunnyAudioPackager };

package/dist/packages/adapters/mediabunny/src/MediabunnyCodecReader.js

@@ -1,6 +1,7 @@
 import { GyroViewError, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
 import "../../../core/src/index.js";
 import { audioConfigurationOf, videoConfigurationOf } from "./decoderConfigurations.js";
+import { trackColourOf } from "./trackColour.js";
 import { ALL_FORMATS, BufferSource, Input } from "mediabunny";
 //#region ../../packages/adapters/mediabunny/src/MediabunnyCodecReader.ts
 /**
@@ -39,7 +40,8 @@ async function videoCodecOf(track, trackIndex) {
 		trackIndex,
 		codedWidth,
 		codedHeight,
-		codec: config.codec
+		codec: config.codec,
+		colour: trackColourOf(config.colorSpace)
 	};
 	return {
 		trackId: track.id,

package/dist/packages/adapters/mediabunny/src/decoderConfigurations.js

@@ -2,7 +2,7 @@ import { copyOfBytes } from "./bufferSources.js";
 //#region ../../packages/adapters/mediabunny/src/decoderConfigurations.ts
 /**
 * A WebCodecs video decoder configuration in the core's terms; the coded size comes from the
-* track where the configuration leaves it out.
+* track where the configuration leaves it out, the colour from the track's description.
 */
 function videoConfigurationOf(config, description) {
 	return {
@@ -10,7 +10,7 @@ function videoConfigurationOf(config, description) {
 		codedWidth: config.codedWidth ?? description.codedWidth,
 		codedHeight: config.codedHeight ?? description.codedHeight,
 		description: config.description === void 0 ? void 0 : copyOfBytes(config.description),
-		isFullRange: config.colorSpace?.fullRange ?? void 0
+		colour: description.colour
 	};
 }
 /**

package/dist/packages/adapters/mediabunny/src/trackColour.js

@@ -0,0 +1,21 @@
+import { COLOUR_PRIMARIES, MATRIX_COEFFICIENTS, TRANSFER_CHARACTERISTICS, namedOrUnspecified } from "../../../core/src/domain/colour/TrackColour.js";
+import "../../../core/src/index.js";
+//#region ../../packages/adapters/mediabunny/src/trackColour.ts
+/**
+* A track's colour in the core's terms, from the colour space mediabunny reads off its sample
+* entry or, without a `colr` box, its SPS: a value the core does not name is unspecified.
+*/
+function trackColourOf(colorSpace) {
+	return {
+		primaries: namedOrUnspecified(COLOUR_PRIMARIES, colorSpace?.primaries),
+		transfer: namedOrUnspecified(TRANSFER_CHARACTERISTICS, colorSpace?.transfer),
+		matrix: namedOrUnspecified(MATRIX_COEFFICIENTS, colorSpace?.matrix),
+		range: rangeOf(colorSpace?.fullRange)
+	};
+}
+function rangeOf(fullRange) {
+	if (fullRange === true) return "full";
+	return fullRange === false ? "limited" : "unspecified";
+}
+//#endregion
+export { trackColourOf };

package/dist/packages/adapters/mse-audio/src/SourceBufferFeeder.js

@@ -73,7 +73,7 @@ var SourceBufferFeeder = class {
 	async feed(from, stop) {
 		try {
 			await this.settlePendingAppend();
-			if (this.hasAllAudioFrom(from)) return;
+			if (stop.wasStopped || this.hasElementFailed() || this.hasAllAudioFrom(from)) return;
 			await this.feedFrom(this.startOf(from), stop);
 		} catch (error) {
 			this.failureValue ??= asGyroViewError(error, "decode", "feeding the audio buffer failed");
@@ -106,11 +106,15 @@ var SourceBufferFeeder = class {
 	}
 	/**
 	* Appends segments as the playhead needs them. True when the track ended, false when stopped.
+	* A run stops only between two whole segments (the port's promise) and never cancels an
+	* append, so the source buffer's parser is always at a segment's start when the next run
+	* appends its initialization segment.
 	*/
 	async pump(segments, stop) {
 		let next = await this.nextWhenNeeded(segments, stop);
 		while (next !== STOPPED) {
 			if (next.done === true) return true;
+			if (this.hasElementFailed()) return false;
 			this.evictBehind();
 			await this.append(next.value);
 			next = await this.nextWhenNeeded(segments, stop);
@@ -162,6 +166,13 @@ var SourceBufferFeeder = class {
 		}
 		if (await outcome === "error") throw new GyroViewError("decode", "the audio buffer could not parse a segment");
 	}
+	/**
+	* The element failed: every append now throws, and the element's own error says why, not the
+	* feeder's.
+	*/
+	hasElementFailed() {
+		return this.parts.element.error !== null;
+	}
 	async settlePendingAppend() {
 		if (this.parts.sourceBuffer.updating) await nextOfEvents(this.parts.sourceBuffer, ["updateend"]);
 	}

package/dist/packages/adapters/three/src/ThreeFrameRenderer.js

@@ -5,6 +5,7 @@ import { aspectOf } from "../../../core/src/domain/view/screenLayout.js";
 import { DEFAULT_FRAMING } from "../../../core/src/domain/view/Framing.js";
 import { viewModeRulesFor } from "../../../core/src/domain/view/viewModes.js";
 import "../../../core/src/index.js";
+import { MatrixCorrections } from "./matrixCorrections.js";
 import { SAMPLING_STRATEGIES } from "./samplingStrategies.js";
 import { applyLensGain, applyPicture, applyShaderSampling, applyStabilization, createRendererUniforms } from "./rendererUniforms.js";
 import { createFullscreenTriangle } from "./fullscreenPass.js";
@@ -127,6 +128,7 @@ var ThreeFrameRenderer = class {
 			const frame = frames[index];
 			if (frame) texture.setFrame(frame.handle);
 		}
+		this.parts.matrixCorrections.follow(frames.map((frame) => frame.handle));
 		this.hasFrames = true;
 		this.render();
 	}
@@ -250,6 +252,7 @@ function assembleParts(renderer, setup, pictures) {
 		materials,
 		textures,
 		uniforms,
+		matrixCorrections: new MatrixCorrections(setup.lenses, uniforms.uLensMatrixCorrection),
 		lensCount: setup.lenses.length,
 		seamProof
 	};

package/dist/packages/adapters/three/src/conversionUniforms.js

@@ -0,0 +1,61 @@
+import { IDENTITY_MATRIX3 } from "../../../core/src/shared/math/Matrix3.js";
+import { BT709_LUMINANCE, HLG_OETF } from "../../../core/src/domain/colour/DisplayConversion.js";
+import "../../../core/src/index.js";
+import { toThreeMatrix } from "./threeMatrix.js";
+import { glslFloat } from "./glslLiterals.js";
+import { Vector4 } from "three";
+//#region ../../packages/adapters/three/src/conversionUniforms.ts
+/**
+* The kinds of conversion as the shader tells them apart; it shows any kind but HLG's as
+* recorded.
+*/
+var CONVERSION_AS_RECORDED = 0;
+var CONVERSION_HLG_TO_SDR_BT709 = 1;
+/**
+* The constants `displayConversion.glsl` refers to: HLG's kind, BT.2100 HLG's constants and
+* BT.709's luminance, from the core.
+*/
+var CONVERSION_DEFINES = [
+	["CONVERSION_HLG_TO_SDR_BT709", CONVERSION_HLG_TO_SDR_BT709],
+	["HLG_A", glslFloat(HLG_OETF.a)],
+	["HLG_B", glslFloat(HLG_OETF.b)],
+	["HLG_C", glslFloat(HLG_OETF.c)],
+	["HLG_SEGMENT_JOIN", glslFloat(HLG_OETF.segmentJoin)],
+	["HLG_SQUARE_SEGMENT_DIVISOR", glslFloat(HLG_OETF.squareSegmentDivisor)],
+	["HLG_LOG_SEGMENT_DIVISOR", glslFloat(HLG_OETF.logSegmentDivisor)],
+	["BT709_LUMINANCE_RED", glslFloat(BT709_LUMINANCE[0])],
+	["BT709_LUMINANCE_GREEN", glslFloat(BT709_LUMINANCE[1])],
+	["BT709_LUMINANCE_BLUE", glslFloat(BT709_LUMINANCE[2])]
+];
+function conversionUniforms(lenses) {
+	const slots = lenses.map((lens) => conversionSlotOf(lens.displayConversion));
+	return {
+		uLensConversion: { value: slots.map((slot) => slot.kind) },
+		uLensMatrixCorrection: { value: lenses.map(() => toThreeMatrix(IDENTITY_MATRIX3)) },
+		uLensGamut: { value: slots.map((slot) => slot.gamut) },
+		uLensTone: { value: slots.map((slot) => slot.tone) }
+	};
+}
+/**
+* Exhaustive over the conversion kinds: a new kind does not compile until it is packed. What a
+* kind does not use stays neutral: the identity gamut, a tone of zeros.
+*/
+function conversionSlotOf(conversion) {
+	switch (conversion.kind) {
+		case "as-recorded": return {
+			kind: CONVERSION_AS_RECORDED,
+			gamut: toThreeMatrix(IDENTITY_MATRIX3),
+			tone: new Vector4()
+		};
+		case "hlg-to-sdr-bt709": {
+			const { exposure, kneeStart, ceiling, exponent } = conversion.tone;
+			return {
+				kind: CONVERSION_HLG_TO_SDR_BT709,
+				gamut: toThreeMatrix(conversion.gamut),
+				tone: new Vector4(exposure, kneeStart, ceiling, exponent)
+			};
+		}
+	}
+}
+//#endregion
+export { CONVERSION_DEFINES, conversionUniforms };

package/dist/packages/adapters/three/src/glslLiterals.js

@@ -0,0 +1,10 @@
+//#region ../../packages/adapters/three/src/glslLiterals.ts
+/**
+* A number as a GLSL float literal, with its decimal point: three.js writes a define's number as
+* JavaScript prints it, so 3 would be an int, and GLSL ES 3.00 converts no int to a float.
+*/
+function glslFloat(value) {
+	return Number.isSafeInteger(value) ? value.toFixed(1) : String(value);
+}
+//#endregion
+export { glslFloat };

package/dist/packages/adapters/three/src/matrixCorrections.js

@@ -0,0 +1,35 @@
+import { MATRIX_COEFFICIENTS, namedOrUnspecified } from "../../../core/src/domain/colour/TrackColour.js";
+import { matrixCorrectionOf } from "../../../core/src/domain/colour/matrixCorrection.js";
+import "../../../core/src/index.js";
+import { toThreeMatrix } from "./threeMatrix.js";
+//#region ../../packages/adapters/three/src/matrixCorrections.ts
+/**
+* Follows the matrix each lens's frames name, and brings their texels back to the matrix the
+* track was recorded with where the two differ (ADR 0033): WebKit's decoders convert Y′CbCr with
+* BT.709 whatever a stream says, and name BT.709 on the frames they make.
+*/
+var MatrixCorrections = class {
+	lenses;
+	uniform;
+	named;
+	constructor(lenses, uniform) {
+		this.lenses = lenses;
+		this.uniform = uniform;
+		this.named = Array.from({ length: lenses.length });
+	}
+	/**
+	* Updates a lens's correction when its frames name another matrix than before.
+	*/
+	follow(frames) {
+		for (const [index, lens] of this.lenses.entries()) {
+			const frame = frames[lens.frameSlot];
+			if (!frame) continue;
+			const named = namedOrUnspecified(MATRIX_COEFFICIENTS, frame.colorSpace.matrix);
+			if (named === this.named[index]) continue;
+			this.named[index] = named;
+			this.uniform.value[index] = toThreeMatrix(matrixCorrectionOf(lens.displayConversion.matrix, named));
+		}
+	}
+};
+//#endregion
+export { MatrixCorrections };

package/dist/packages/adapters/three/src/rendererUniforms.js

@@ -1,7 +1,10 @@
 import { ensureIndexInRange, ensureInvariant } from "../../../core/src/shared/errors/GyroViewError.js";
+import { MEI_TERM_CAPACITY } from "../../../core/src/domain/optics/MeiDistortion.js";
 import { IDENTITY_MATRIX3 } from "../../../core/src/shared/math/Matrix3.js";
 import { aspectOfArea, planeHalfExtentOf } from "../../../core/src/domain/view/rectilinear.js";
 import "../../../core/src/index.js";
+import { toThreeMatrix } from "./threeMatrix.js";
+import { CONVERSION_DEFINES, conversionUniforms } from "./conversionUniforms.js";
 import "./samplingStrategies.js";
 import { Matrix3, Vector2, Vector3, Vector4 } from "three";
 var LENS_MEI = 0;
@@ -14,6 +17,10 @@ var SHADER_DEFINES = Object.fromEntries([
 	["MAX_LENSES", 2],
 	["LENS_MEI", LENS_MEI],
 	["LENS_RADIAL_POLYNOMIAL", LENS_RADIAL_POLYNOMIAL],
+	["MEI_RADIAL_TERMS", MEI_TERM_CAPACITY.radial],
+	["MEI_TANGENTIAL_ORDERS", MEI_TERM_CAPACITY.tangential],
+	["MEI_THIN_PRISM_ORDERS", MEI_TERM_CAPACITY.thinPrism],
+	...CONVERSION_DEFINES,
 	["SAMPLING_BILINEAR", 0],
 	["SAMPLING_TRILINEAR", 1],
 	["SAMPLING_SUPERSAMPLED", 2]
@@ -24,6 +31,7 @@ function createRendererUniforms(setup, textures) {
 		...viewUniforms(setup),
 		...projectionUniforms(lenses),
 		...samplingUniforms(lenses),
+		...conversionUniforms(lenses),
 		uTexture0: { value: textures[0] ?? null },
 		uTexture1: { value: textures[1] ?? null }
 	};
@@ -47,12 +55,18 @@ function projectionUniforms(lenses) {
 		uLensPrincipalPoint: { value: lenses.map((lens) => toVector2(lens.projection.principalPoint)) },
 		uLensFocal: { value: slots.map((slot) => slot.focal) },
 		uLensXi: { value: slots.map((slot) => slot.xi) },
-		uLensRadial: { value: slots.map((slot) => slot.radial) },
-		uLensTangential: { value: slots.map((slot) => slot.tangential) },
+		uLensRadial: { value: slots.flatMap((slot) => slot.radial) },
+		uLensTangential: { value: slots.flatMap((slot) => slot.tangential) },
+		uLensThinPrism: { value: slots.flatMap((slot) => slot.thinPrism) },
 		uLensPolynomial: { value: slots.map((slot) => slot.polynomial) },
 		uLensHalfFov: { value: lenses.map((lens) => lens.halfFieldOfView) }
 	};
 }
+var NO_MEI_DISTORTION = {
+	radial: [],
+	tangential: [],
+	thinPrism: []
+};
 /**
 * Exhaustive over the projection kinds: a new kind does not compile until it is packed.
 */
@@ -62,20 +76,33 @@ function slotOf(projection) {
 			kind: LENS_MEI,
 			focal: new Vector2(...projection.focal),
 			xi: projection.xi,
-			radial: new Vector3(...projection.radial),
-			tangential: new Vector2(...projection.tangential),
+			...meiTermSlots(projection.distortion),
 			polynomial: new Vector4()
 		};
 		case "radial-polynomial": return {
 			kind: LENS_RADIAL_POLYNOMIAL,
 			focal: new Vector2(),
 			xi: 0,
-			radial: new Vector3(),
-			tangential: new Vector2(),
+			...meiTermSlots(NO_MEI_DISTORTION),
 			polynomial: new Vector4(...projection.coefficients)
 		};
 	}
 }
+function meiTermSlots(distortion) {
+	return {
+		radial: fittedToCapacity(distortion.radial, MEI_TERM_CAPACITY.radial, () => 0),
+		tangential: fittedToCapacity(distortion.tangential.map((pair) => new Vector2(pair.p1, pair.p2)), MEI_TERM_CAPACITY.tangential, () => new Vector2()),
+		thinPrism: fittedToCapacity(distortion.thinPrism.map((term) => new Vector2(term.x, term.y)), MEI_TERM_CAPACITY.thinPrism, () => new Vector2())
+	};
+}
+/**
+* The terms in the room the shader holds for their family, the rest of it zero; more terms than
+* it holds are a defect of the model that made them.
+*/
+function fittedToCapacity(terms, capacity, zero) {
+	ensureInvariant(terms.length <= capacity, `a Mei lens has ${terms.length} terms of a family the shader holds ${capacity} of`);
+	return Array.from({ length: capacity }, (_unused, index) => terms[index] ?? zero());
+}
 function samplingUniforms(lenses) {
 	return {
 		uLensWindow: { value: lenses.map((lens) => new Vector4(lens.window.x, lens.window.y, lens.window.width, lens.window.height)) },
@@ -136,12 +163,6 @@ function valuesOf(picture, viewportAspect) {
 function toVector4(area) {
 	return new Vector4(area.x, area.y, area.width, area.height);
 }
-/**
-* Row-major core matrix into a three matrix, whose `set` takes rows too.
-*/
-function toThreeMatrix(m) {
-	return new Matrix3().set(...m);
-}
 function toVector2(point) {
 	return new Vector2(point.x, point.y);
 }

package/dist/packages/adapters/three/src/shaderPrograms.js

@@ -1,4 +1,5 @@
 import analysis_frag_default from "./shaders/analysis.frag.js";
+import displayConversion_default from "./shaders/displayConversion.js";
 import equirectangularRays_default from "./shaders/equirectangularRays.js";
 import fixedJoin_default from "./shaders/fixedJoin.js";
 import header_default from "./shaders/header.js";
@@ -14,8 +15,9 @@ import stitch_frag_default from "./shaders/stitch.frag.js";
 * The fragment programs, each the GLSL chunks it is made of in the order they must appear: a
 * chunk comes after every chunk whose declarations it uses. The only place that order is known.
 */
+var LENS_TEXELS = [lensTextures_default, displayConversion_default];
 var LENS_PROJECTION = [
-	lensTextures_default,
+	...LENS_TEXELS,
 	lensModels_default,
 	lensSampling_default
 ];
@@ -48,7 +50,7 @@ function pictureProgramsWith(seamJoin) {
 		"lens-tiles": [
 			header_default,
 			screenAreas_default,
-			lensTextures_default,
+			...LENS_TEXELS,
 			rawLenses_frag_default
 		]
 	};

package/dist/packages/adapters/three/src/shaders/analysis.frag.js

@@ -1,4 +1,4 @@
 //#region ../../packages/adapters/three/src/shaders/analysis.frag.glsl?raw
-var analysis_frag_default = "in vec2 vNdc;\nout vec4 outColor;\n\n// One row per lens: what that lens sees along the seam ring, the circle of directions halfway\n// through the blend band around lens 0's optical axis, sampled around the ring along x. Rows\n// share their directions, so their means differ by exposure (and parallax), not by content.\n// Alpha marks the texels a lens actually images.\nvoid main() {\n  int lens = int(floor((vNdc.y + 1.0) * 0.5 * float(MAX_LENSES)));\n  float phi = (vNdc.x + 1.0) * PI;\n  float ring = 0.5 * (uFeather.x + uFeather.y);\n  vec3 inLensZero = vec3(sin(ring) * cos(phi), sin(ring) * sin(phi), cos(ring));\n  // The lens rotations take body directions into each lens; the transpose goes back.\n  vec3 dirBody = transpose(uLensRotation[0]) * inLensZero;\n  if (lens >= uLensCount) {\n    outColor = vec4(0.0);\n    return;\n  }\n  LensSample seen = sampleLensWith(lens, dirBody, SAMPLING_BILINEAR);\n  outColor = seen.isImaged ? vec4(seen.color, 1.0) : vec4(0.0);\n}\n";
+var analysis_frag_default = "in vec2 vNdc;\nout vec4 outColor;\n\n// One row per lens: what that lens sees along the seam ring, the circle of directions halfway\n// through the blend band around lens 0's optical axis, sampled around the ring along x. Rows\n// share their directions, so their means differ by exposure (and parallax), not by content:\n// exposure signals, in which it is a factor (ADR 0033). Alpha marks the texels a lens images.\nvoid main() {\n  int lens = int(floor((vNdc.y + 1.0) * 0.5 * float(MAX_LENSES)));\n  float phi = (vNdc.x + 1.0) * PI;\n  float ring = 0.5 * (uFeather.x + uFeather.y);\n  vec3 inLensZero = vec3(sin(ring) * cos(phi), sin(ring) * sin(phi), cos(ring));\n  // The lens rotations take body directions into each lens; the transpose goes back.\n  vec3 dirBody = transpose(uLensRotation[0]) * inLensZero;\n  if (lens >= uLensCount) {\n    outColor = vec4(0.0);\n    return;\n  }\n  LensSample seen = sampleLensWith(lens, dirBody, SAMPLING_BILINEAR);\n  outColor = seen.isImaged ? vec4(seen.signal, 1.0) : vec4(0.0);\n}\n";
 //#endregion
 export { analysis_frag_default as default };

package/dist/packages/adapters/three/src/shaders/displayConversion.js

@@ -0,0 +1,4 @@
+//#region ../../packages/adapters/three/src/shaders/displayConversion.glsl?raw
+var displayConversion_default = "// How lens i's texels are brought to the SDR BT.709 display, as the core's exposureSignalOf and\n// shownOf (ADR 0033): the browser's upload has applied the track's matrix and range; the\n// transfer and primaries are this chunk's. Shown as recorded, or HLG converted to scene light,\n// into BT.709 and toned; gain matching scales the exposure signal between the two (ADR 0012).\nuniform int uLensConversion[MAX_LENSES];\n// R′G′B′ through the matrix a frame names back to the track's own (matrixCorrectionOf).\nuniform mat3 uLensMatrixCorrection[MAX_LENSES];\nuniform mat3 uLensGamut[MAX_LENSES];\n// Exposure, roll-off start, roll-off ceiling, display encoding power.\nuniform vec4 uLensTone[MAX_LENSES];\n\nstruct ToneCurve {\n  float exposure;\n  float kneeStart;\n  float ceiling;\n  float exponent;\n};\n\nToneCurve toneOf(int i) {\n  vec4 tone = uLensTone[i];\n  return ToneCurve(tone.x, tone.y, tone.z, tone.w);\n}\n\nfloat hlgInverseOetf(float signal) {\n  return signal <= HLG_SEGMENT_JOIN\n    ? signal * signal / HLG_SQUARE_SEGMENT_DIVISOR\n    : (exp((signal - HLG_C) / HLG_A) + HLG_B) / HLG_LOG_SEGMENT_DIVISOR;\n}\n\nconst vec3 BT709_LUMINANCE = vec3(BT709_LUMINANCE_RED, BT709_LUMINANCE_GREEN, BT709_LUMINANCE_BLUE);\n\nfloat rolledOff(float luminance, ToneCurve tone) {\n  float over = luminance - tone.kneeStart;\n  return over <= 0.0\n    ? luminance\n    : tone.kneeStart + over / (1.0 + over / (tone.ceiling - tone.kneeStart));\n}\n\n// The signal exposed back to light, its luminance rolled off with every channel scaled alike,\n// and encoded for the display.\nvec3 tonedFrom(vec3 signal, ToneCurve tone) {\n  vec3 light = tone.exposure * pow(signal, vec3(tone.exponent));\n  float luminance = dot(light, BT709_LUMINANCE);\n  float scale = luminance > 0.0 ? rolledOff(luminance, tone) / luminance : 1.0;\n  return min(pow(light * scale, vec3(1.0 / tone.exponent)), vec3(1.0));\n}\n\nbool isHlg(int i) {\n  return uLensConversion[i] == CONVERSION_HLG_TO_SDR_BT709;\n}\n\n// Lens i's texel where its exposure is a factor; as recorded for any kind but HLG.\nvec3 exposureSignalOf(int i, vec3 texel) {\n  vec3 recorded = uLensMatrixCorrection[i] * texel;\n  if (!isHlg(i)) return recorded;\n  // A corrected texel may fall just below black, which the square segment would make light.\n  recorded = max(recorded, 0.0);\n  vec3 scene = vec3(\n    hlgInverseOetf(recorded.r),\n    hlgInverseOetf(recorded.g),\n    hlgInverseOetf(recorded.b)\n  );\n  vec3 light = max(uLensGamut[i] * scene, 0.0);\n  return pow(light, vec3(1.0 / toneOf(i).exponent));\n}\n\n// An exposure signal of lens i as the display shows it; as recorded for any kind but HLG.\nvec3 shownOf(int i, vec3 signal) {\n  if (!isHlg(i)) return signal;\n  return tonedFrom(signal, toneOf(i));\n}\n\nvec3 toDisplay(int i, vec3 texel) {\n  return shownOf(i, exposureSignalOf(i, texel));\n}\n";
+//#endregion
+export { displayConversion_default as default };

package/dist/packages/adapters/three/src/shaders/lensModels.js

@@ -1,4 +1,4 @@
 //#region ../../packages/adapters/three/src/shaders/lensModels.glsl?raw
-var lensModels_default = "// The depth is positive for every direction inside a lens's field; directions behind it are\n// projected too, for the footprint's derivatives, and must not divide by zero.\nconst float MIN_DEPTH = 1e-3;\n\n// Canvas pixel of a unit direction in the lens frame under the unified (Mei) model: project onto\n// the unit sphere, then from xi behind its centre onto the image plane, distort, scale.\nvec2 projectMei(vec3 d, float xi, vec2 focal, vec2 principalPoint, vec3 radial, vec2 tangential) {\n  float depth = max(d.z + xi, MIN_DEPTH);\n  vec2 m = d.xy / depth;\n  float r2 = dot(m, m);\n  float radialFactor = 1.0 + radial.x * r2 + radial.y * r2 * r2 + radial.z * r2 * r2 * r2;\n  vec2 tangentialTerm = vec2(\n    2.0 * tangential.x * m.x * m.y + tangential.y * (r2 + 2.0 * m.x * m.x),\n    tangential.x * (r2 + 2.0 * m.y * m.y) + 2.0 * tangential.y * m.x * m.y\n  );\n  return focal * (radialFactor * m + tangentialTerm) + principalPoint;\n}\n\n// Canvas pixel of a unit direction under a radial polynomial in the angle from the optical axis.\nvec2 projectRadialPolynomial(vec3 d, float theta, vec4 c, vec2 principalPoint) {\n  float radius = theta * (c.x + theta * (c.y + theta * (c.z + theta * c.w)));\n  float lateral = length(d.xy);\n  vec2 unit = lateral > 0.0 ? d.xy / lateral : vec2(0.0);\n  return principalPoint + radius * unit;\n}\n";
+var lensModels_default = "// The depth is positive for every direction inside a lens's field; directions behind it are\n// projected too, for the footprint's derivatives, and must not divide by zero.\nconst float MIN_DEPTH = 1e-3;\n\nuniform vec2 uLensPrincipalPoint[MAX_LENSES];\nuniform vec2 uLensFocal[MAX_LENSES];\nuniform float uLensXi[MAX_LENSES];\n// Each Mei lens's distortion as the core's MeiDistortion holds it, lens after lens, as many terms\n// per lens as each family holds room for, by increasing order: radial terms k1, k2, ... of r²,\n// Brown's tangential pairs (p1, p2) scaled by r^(2j), and thin-prism shifts scaled by r^(2j + 2).\n// The orders a lens does not fill are zero.\nuniform float uLensRadial[MAX_LENSES * MEI_RADIAL_TERMS];\nuniform vec2 uLensTangential[MAX_LENSES * MEI_TANGENTIAL_ORDERS];\nuniform vec2 uLensThinPrism[MAX_LENSES * MEI_THIN_PRISM_ORDERS];\nuniform vec4 uLensPolynomial[MAX_LENSES];\n\n// c0 + c1 r² + c2 r⁴ + ... of each of lens i's families, by Horner's rule, as the core's seriesIn.\nfloat radialSeries(int i, float r2) {\n  float sum = 0.0;\n  for (int j = MEI_RADIAL_TERMS - 1; j >= 0; j--) {\n    sum = sum * r2 + uLensRadial[i * MEI_RADIAL_TERMS + j];\n  }\n  return sum;\n}\n\nvec2 tangentialSeries(int i, float r2) {\n  vec2 sum = vec2(0.0);\n  for (int j = MEI_TANGENTIAL_ORDERS - 1; j >= 0; j--) {\n    sum = sum * r2 + uLensTangential[i * MEI_TANGENTIAL_ORDERS + j];\n  }\n  return sum;\n}\n\nvec2 thinPrismSeries(int i, float r2) {\n  vec2 sum = vec2(0.0);\n  for (int j = MEI_THIN_PRISM_ORDERS - 1; j >= 0; j--) {\n    sum = sum * r2 + uLensThinPrism[i * MEI_THIN_PRISM_ORDERS + j];\n  }\n  return sum;\n}\n\n// A normalised image-plane point distorted by lens i, as the core's distortMei.\nvec2 distortMei(int i, vec2 m) {\n  float r2 = dot(m, m);\n  float radialFactor = 1.0 + r2 * radialSeries(i, r2);\n  vec2 decentering = tangentialSeries(i, r2);\n  vec2 tangentialTerm = vec2(\n    2.0 * decentering.x * m.x * m.y + decentering.y * (r2 + 2.0 * m.x * m.x),\n    decentering.x * (r2 + 2.0 * m.y * m.y) + 2.0 * decentering.y * m.x * m.y\n  );\n  return radialFactor * m + tangentialTerm + r2 * thinPrismSeries(i, r2);\n}\n\n// Canvas pixel of a unit direction in lens i's frame under the unified (Mei) model: project onto\n// the unit sphere, then from xi behind its centre onto the image plane, distort, scale.\nvec2 projectMei(int i, vec3 d) {\n  float depth = max(d.z + uLensXi[i], MIN_DEPTH);\n  return uLensFocal[i] * distortMei(i, d.xy / depth) + uLensPrincipalPoint[i];\n}\n\n// Canvas pixel of a unit direction under lens i's radial polynomial in the angle from its axis.\nvec2 projectRadialPolynomial(int i, vec3 d, float theta) {\n  vec4 c = uLensPolynomial[i];\n  float radius = theta * (c.x + theta * (c.y + theta * (c.z + theta * c.w)));\n  float lateral = length(d.xy);\n  vec2 unit = lateral > 0.0 ? d.xy / lateral : vec2(0.0);\n  return uLensPrincipalPoint[i] + radius * unit;\n}\n";
 //#endregion
 export { lensModels_default as default };

package/dist/packages/adapters/three/src/shaders/lensSampling.js

@@ -1,4 +1,4 @@
 //#region ../../packages/adapters/three/src/shaders/lensSampling.glsl?raw
-var lensSampling_default = "// How a body direction becomes a texel of one lens, for the stitch and the seam meters: the\n// calibration as uniforms, and the sampling through each lens model. Needs lensTextures.glsl.\nuniform vec2 uFeather;\nuniform mat3 uLensRotation[MAX_LENSES];\nuniform int uLensKind[MAX_LENSES];\nuniform vec2 uLensPrincipalPoint[MAX_LENSES];\nuniform vec2 uLensFocal[MAX_LENSES];\nuniform float uLensXi[MAX_LENSES];\nuniform vec3 uLensRadial[MAX_LENSES];\nuniform vec2 uLensTangential[MAX_LENSES];\nuniform vec4 uLensPolynomial[MAX_LENSES];\nuniform float uLensHalfFov[MAX_LENSES];\nuniform vec4 uLensWindow[MAX_LENSES];\n\nstruct LensSample {\n  bool isImaged;\n  // Angle from the lens's optical axis.\n  float theta;\n  vec3 color;\n};\n\n// Where lens i images direction d on its calibration canvas; the principal point, and not\n// known, for a kind of lens this shader does not know.\nvec2 canvasPixel(int i, vec3 d, float theta, out bool isKnown) {\n  isKnown = true;\n  if (uLensKind[i] == LENS_MEI) {\n    return projectMei(\n      d,\n      uLensXi[i],\n      uLensFocal[i],\n      uLensPrincipalPoint[i],\n      uLensRadial[i],\n      uLensTangential[i]\n    );\n  }\n  if (uLensKind[i] == LENS_RADIAL_POLYNOMIAL) {\n    return projectRadialPolynomial(d, theta, uLensPolynomial[i], uLensPrincipalPoint[i]);\n  }\n  isKnown = false;\n  return uLensPrincipalPoint[i];\n}\n\n// What lens i shows in a body direction, read as `sampling` says, if it images it at all:\n// outside its field, or beyond the window the frame shows, nothing. The footprint is taken in\n// every fragment before the gates, so its derivatives are defined.\nLensSample sampleLensWith(int i, vec3 dirBody, int sampling) {\n  vec3 d = uLensRotation[i] * dirBody;\n  // atan keeps its precision near the axis where acos loses it.\n  float theta = atan(length(d.xy), d.z);\n  bool isKnown;\n  vec2 pixel = canvasPixel(i, d, theta, isKnown);\n  vec2 windowUv = (pixel - uLensWindow[i].xy) / uLensWindow[i].zw;\n  Footprint footprint = footprintOf(i, windowUv);\n  bool isInWindow =\n    all(greaterThanEqual(windowUv, vec2(0.0))) && all(lessThanEqual(windowUv, vec2(1.0)));\n  LensSample result;\n  result.theta = theta;\n  result.isImaged = isKnown && theta < uLensHalfFov[i] && isInWindow;\n  result.color = result.isImaged ? sampleLens(uLensTexture[i], footprint, sampling).rgb : vec3(0.0);\n  return result;\n}\n\n// What lens i shows in a body direction, read as the picture is.\nLensSample sampleLensAt(int i, vec3 dirBody) {\n  return sampleLensWith(i, dirBody, uSampling);\n}\n";
+var lensSampling_default = "// How a body direction becomes a texel of one lens, for the stitch and the seam meters: the\n// pose and field as uniforms, and the sampling through each lens model, the texel as its\n// exposure signal. Needs lensTextures.glsl, displayConversion.glsl and lensModels.glsl.\nuniform vec2 uFeather;\nuniform mat3 uLensRotation[MAX_LENSES];\nuniform int uLensKind[MAX_LENSES];\nuniform float uLensHalfFov[MAX_LENSES];\nuniform vec4 uLensWindow[MAX_LENSES];\n\nstruct LensSample {\n  bool isImaged;\n  // Angle from the lens's optical axis.\n  float theta;\n  // The texel where the lens's exposure is a factor (displayConversion.glsl).\n  vec3 signal;\n};\n\n// Where lens i images direction d on its calibration canvas; the principal point, and not\n// known, for a kind of lens this shader does not know.\nvec2 canvasPixel(int i, vec3 d, float theta, out bool isKnown) {\n  isKnown = true;\n  if (uLensKind[i] == LENS_MEI) {\n    return projectMei(i, d);\n  }\n  if (uLensKind[i] == LENS_RADIAL_POLYNOMIAL) {\n    return projectRadialPolynomial(i, d, theta);\n  }\n  isKnown = false;\n  return uLensPrincipalPoint[i];\n}\n\n// What lens i shows in a body direction, read as `sampling` says, if it images it at all:\n// outside its field, or beyond the window the frame shows, nothing. The footprint is taken in\n// every fragment before the gates, so its derivatives are defined.\nLensSample sampleLensWith(int i, vec3 dirBody, int sampling) {\n  vec3 d = uLensRotation[i] * dirBody;\n  // atan keeps its precision near the axis where acos loses it.\n  float theta = atan(length(d.xy), d.z);\n  bool isKnown;\n  vec2 pixel = canvasPixel(i, d, theta, isKnown);\n  vec2 windowUv = (pixel - uLensWindow[i].xy) / uLensWindow[i].zw;\n  Footprint footprint = footprintOf(i, windowUv);\n  bool isInWindow =\n    all(greaterThanEqual(windowUv, vec2(0.0))) && all(lessThanEqual(windowUv, vec2(1.0)));\n  LensSample result;\n  result.theta = theta;\n  result.isImaged = isKnown && theta < uLensHalfFov[i] && isInWindow;\n  result.signal = result.isImaged\n    ? exposureSignalOf(i, sampleLens(uLensTexture[i], footprint, sampling).rgb)\n    : vec3(0.0);\n  return result;\n}\n\n// What lens i shows in a body direction, read as the picture is.\nLensSample sampleLensAt(int i, vec3 dirBody) {\n  return sampleLensWith(i, dirBody, uSampling);\n}\n";
 //#endregion
 export { lensSampling_default as default };