@bubo-squared/gyroview 0.3.0 → 0.4.0

package/dist/packages/core/src/domain/optics/MeiModel.js

@@ -1,9 +1,10 @@
 import { HALF_FIELD_OF_VIEW } from "./opticsConstants.js";
+import { distortMei, ensureWithinTermCapacity } from "./MeiDistortion.js";
 //#region ../../packages/core/src/domain/optics/MeiModel.ts
 /**
-* Unified (Mei) omnidirectional camera model with radial-tangential distortion, as stored in
-* `offset_v3`. A direction is projected onto the unit sphere, then from a point `xi` behind the
-* sphere centre onto the normalised image plane, then distorted and scaled.
+* Unified (Mei) omnidirectional camera model with radial, tangential and thin-prism distortion,
+* as stored in `offset_v3` and `offset_v6`. A direction is projected onto the unit sphere, then from a point
+* `xi` behind the sphere centre onto the normalised image plane, then distorted and scaled.
 */
 var MeiModel = class {
 	parameters;
@@ -12,6 +13,7 @@ var MeiModel = class {
 	principalPoint;
 	constructor(parameters) {
 		this.parameters = parameters;
+		ensureWithinTermCapacity(parameters.distortion);
 		this.principalPoint = parameters.principalPoint;
 	}
 	get projection() {
@@ -24,22 +26,12 @@ var MeiModel = class {
 		const [x, y, z] = direction;
 		const depth = z + this.parameters.xi;
 		if (depth <= 0 || Math.atan2(Math.hypot(x, y), z) > this.halfFieldOfView) return void 0;
-		const normalised = [x / depth, y / depth];
-		const [distortedX, distortedY] = this.distort(normalised);
+		const [distortedX, distortedY] = distortMei(this.parameters.distortion, [x / depth, y / depth]);
 		return {
 			x: this.parameters.focal[0] * distortedX + this.principalPoint.x,
 			y: this.parameters.focal[1] * distortedY + this.principalPoint.y
 		};
 	}
-	distort([mx, my]) {
-		const [k1, k2, k3] = this.parameters.radial;
-		const [p1, p2] = this.parameters.tangential;
-		const r2 = mx * mx + my * my;
-		const radial = 1 + k1 * r2 + k2 * r2 * r2 + k3 * r2 * r2 * r2;
-		const tangentialX = 2 * p1 * mx * my + p2 * (r2 + 2 * mx * mx);
-		const tangentialY = p1 * (r2 + 2 * my * my) + 2 * p2 * mx * my;
-		return [radial * mx + tangentialX, radial * my + tangentialY];
-	}
 };
 //#endregion
 export { MeiModel };

package/dist/packages/core/src/domain/optics/scaledProjection.js

@@ -0,0 +1,30 @@
+//#region ../../packages/core/src/domain/optics/scaledProjection.ts
+/**
+* The projection with every image radius multiplied by `scale` about the principal point: the
+* Mei model's focal lengths, or the radial polynomial's coefficients. Exact at a scale of 1.
+*/
+function scaledProjection(projection, scale) {
+	switch (projection.kind) {
+		case "mei": {
+			const [fx, fy] = projection.focal;
+			return {
+				...projection,
+				focal: [fx * scale, fy * scale]
+			};
+		}
+		case "radial-polynomial": {
+			const [c1, c2, c3, c4] = projection.coefficients;
+			return {
+				...projection,
+				coefficients: [
+					c1 * scale,
+					c2 * scale,
+					c3 * scale,
+					c4 * scale
+				]
+			};
+		}
+	}
+}
+//#endregion
+export { scaledProjection };

package/dist/packages/core/src/domain/stitching/StitchingSetup.js

@@ -1,7 +1,8 @@
 import { degrees, degreesToRadians } from "../../shared/units/angle.js";
-import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+import { GyroViewError, ensureInvariant } from "../../shared/errors/GyroViewError.js";
 import { lensRotation } from "../optics/lensPose.js";
 import { SEAM_RING_ANGLE } from "./seamRing.js";
+import { scaledProjection } from "../optics/scaledProjection.js";
 //#region ../../packages/core/src/domain/stitching/StitchingSetup.ts
 /**
 * Two 200-degree lenses overlap between 80 and 100 degrees from their axes; the blend spans 5
@@ -33,23 +34,31 @@ function buildStitchingSetup(inputs) {
 	const { calibration, layout } = inputs;
 	if (calibration.lenses.length !== layout.sources.length) throw new GyroViewError("unsupported-layout", `the calibration describes ${calibration.lenses.length} lenses but the layout has ${layout.sources.length}`);
 	const frames = lensFrameOrder(layout);
+	ensureInvariant(inputs.displayConversions.length === frames.length, `${inputs.displayConversions.length} display conversions for ${frames.length} frame sources`);
 	return {
 		lenses: layout.sources.map((source) => {
 			const lens = lensOf(calibration, source.lensIndex);
+			const frameSlot = frames.findIndex((key) => isSameSource(key, source));
 			return {
 				lensIndex: source.lensIndex,
-				frameSlot: frames.findIndex((key) => isSameSource(key, source)),
+				frameSlot,
 				region: source.region,
 				window: canvasWindowOf(calibration, lens),
 				rotation: lensRotation(lens),
-				projection: lens.model.projection,
-				halfFieldOfView: lens.model.halfFieldOfView
+				projection: scaledProjection(lens.model.projection, calibration.radialScale),
+				halfFieldOfView: lens.model.halfFieldOfView,
+				displayConversion: conversionAt(inputs.displayConversions, frameSlot)
 			};
 		}),
 		frameSlotCount: frames.length,
 		feather: DEFAULT_FEATHER
 	};
 }
+function conversionAt(conversions, frameSlot) {
+	const conversion = conversions[frameSlot];
+	ensureInvariant(conversion !== void 0, `no display conversion for frame slot ${frameSlot}`);
+	return conversion;
+}
 function isSameSource(key, source) {
 	return key.inputIndex === source.inputIndex && key.trackIndex === source.trackIndex;
 }

package/dist/packages/core/src/index.js

@@ -1,7 +1,7 @@
 import { degrees } from "./shared/units/angle.js";
-import "./domain/optics/EquidistantModel.js";
 import "./domain/format/calibration/CalibrationVersion.js";
-import { GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf } from "./shared/errors/GyroViewError.js";
+import { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf } from "./shared/errors/GyroViewError.js";
+import { MEI_TERM_CAPACITY } from "./domain/optics/MeiDistortion.js";
 import { lazy } from "./shared/lazy.js";
 import { microseconds, microsecondsToSeconds, milliseconds, seconds, secondsToMicroseconds } from "./shared/units/time.js";
 import "./domain/motion/exposure/ExposureRecord.js";
@@ -48,8 +48,12 @@ import "./domain/stitching/seamMismatch.js";
 import "./domain/stitching/seamDisparity.js";
 import "./domain/stitching/seamDisparityField.js";
 import "./domain/stitching/seamJoin.js";
+import { COLOUR_PRIMARIES, MATRIX_COEFFICIENTS, TRANSFER_CHARACTERISTICS, namedOrUnspecified } from "./domain/colour/TrackColour.js";
+import { BT709_LUMINANCE, HLG_OETF, displayConversionsOf } from "./domain/colour/DisplayConversion.js";
+import { matrixCorrectionOf } from "./domain/colour/matrixCorrection.js";
 import { keysOf } from "./shared/keysOf.js";
 import { Outbox } from "./shared/events/Outbox.js";
+import "./shared/index.js";
 import { Ending, ITERATION_END } from "./shared/async/iteration.js";
 import { SourceByteStream } from "./application/download/SourceByteStream.js";
 import { startFileDownload } from "./application/download/startFileDownload.js";
@@ -64,4 +68,4 @@ import { WallClock } from "./application/playback/WallClock.js";
 import { isFlowing } from "./domain/playback/PlayerState.js";
 import { TypedEmitter } from "./shared/events/TypedEmitter.js";
 import { PlaybackSession } from "./application/playback/PlaybackSession.js";
-export { ByteRange, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, Ending, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, IDENTITY_MATRIX3, ITERATION_END, Outbox, PICTURE_QUALITIES, PlaybackSession, RecordingBuffer, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, SourceByteStream, StabilizingFrameSink, TypedEmitter, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, clampView, degrees, detectLensLayout, downloadPolicyFor, ensureIndexInRange, ensureInvariant, fileNameOfUrl, hasErrorCode, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, isSameView, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, messageOf, microseconds, microsecondsToSeconds, milliseconds, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, readSampleTable, seconds, secondsToMicroseconds, stabilizerFor, startFileDownload, timeRecording, viewModeRulesFor, zoomStepsForPinch };
+export { BT709_LUMINANCE, ByteRange, COLOUR_PRIMARIES, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, Ending, GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, HLG_OETF, IDENTITY_MATRIX3, ITERATION_END, MATRIX_COEFFICIENTS, MEI_TERM_CAPACITY, Outbox, PICTURE_QUALITIES, PlaybackSession, RecordingBuffer, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, SourceByteStream, StabilizingFrameSink, TRANSFER_CHARACTERISTICS, TypedEmitter, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, clampView, degrees, detectLensLayout, displayConversionsOf, downloadPolicyFor, ensureIndexInRange, ensureInvariant, fileNameOfUrl, hasErrorCode, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, isSameView, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, matrixCorrectionOf, messageOf, microseconds, microsecondsToSeconds, milliseconds, namedOrUnspecified, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, readSampleTable, seconds, secondsToMicroseconds, stabilizerFor, startFileDownload, timeRecording, viewModeRulesFor, zoomStepsForPinch };

package/dist/packages/core/src/shared/errors/GyroViewError.js

@@ -1,6 +1,6 @@
 //#region ../../packages/core/src/shared/errors/GyroViewError.ts
 /**
-* Stable machine-readable failure categories. Embedders switch on these; messages are for humans.
+* Stable machine-readable failure codes. Embedders switch on these; messages are for humans.
 */
 var GYRO_VIEW_ERROR_CODES = [
 	"binary-out-of-bounds",
@@ -30,17 +30,69 @@ var GYRO_VIEW_ERROR_CODES = [
 	"unsupported-container",
 	"unsupported-gyro-record",
 	"unsupported-info-format",
-	"unsupported-layout"
+	"unsupported-layout",
+	"webcodecs-unavailable"
 ];
+/**
+* Whose side a failure is on, for embedders that handle failures by kind: the browser cannot
+* decode or draw the recording, the file is not one the player can play, its bytes could not be
+* read, the page misused the API, or the player failed in a way it did not expect.
+*/
+var GYRO_VIEW_ERROR_CATEGORIES = [
+	"browser",
+	"recording",
+	"source",
+	"usage",
+	"internal"
+];
+/**
+* A record, so a new code cannot be added without its category.
+*/
+var CATEGORY_OF_CODE = {
+	"binary-out-of-bounds": "recording",
+	"binary-unsafe-integer": "recording",
+	"codec-unsupported": "browser",
+	cors: "source",
+	decode: "browser",
+	"embed-destroyed": "usage",
+	"index-out-of-range": "internal",
+	"invalid-argument": "usage",
+	"invalid-byte-range": "recording",
+	"invalid-calibration": "recording",
+	"invalid-protobuf": "recording",
+	"invalid-trailer": "recording",
+	"invariant-violation": "internal",
+	"missing-second-file": "recording",
+	"no-calibration": "recording",
+	"no-info-record": "recording",
+	"no-key-frame": "recording",
+	"playback-blocked": "browser",
+	"range-unsupported": "source",
+	"render-unavailable": "browser",
+	"source-changed": "source",
+	"source-truncated": "source",
+	"source-unreadable": "source",
+	"unsupported-calibration": "recording",
+	"unsupported-container": "recording",
+	"unsupported-gyro-record": "recording",
+	"unsupported-info-format": "recording",
+	"unsupported-layout": "recording",
+	"webcodecs-unavailable": "browser"
+};
 function isGyroViewErrorCode(value) {
 	return typeof value === "string" && GYRO_VIEW_ERROR_CODES.includes(value);
 }
 var GyroViewError = class extends Error {
 	code;
+	/**
+	* Its own property rather than a getter, so a serialized or logged copy of the error keeps it.
+	*/
+	category;
 	constructor(code, message, options) {
 		super(message, options);
 		this.code = code;
 		this.name = "GyroViewError";
+		this.category = CATEGORY_OF_CODE[code];
 	}
 };
 /**
@@ -79,4 +131,4 @@ function ensureIndexInRange(index, length, subject) {
 	if (!Number.isSafeInteger(index) || index < 0 || index >= length) throw new GyroViewError("index-out-of-range", `${subject} index ${index} is outside 0..${length - 1}`);
 }
 //#endregion
-export { GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf };
+export { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf };

package/dist/packages/core/src/shared/index.js

@@ -0,0 +1,11 @@
+import { degrees } from "./units/angle.js";
+import { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf } from "./errors/GyroViewError.js";
+import { lazy } from "./lazy.js";
+import { microseconds, microsecondsToSeconds, milliseconds, seconds, secondsToMicroseconds } from "./units/time.js";
+import "./math/Vector3.js";
+import { clamp } from "./math/clamp.js";
+import { IDENTITY_MATRIX3 } from "./math/Matrix3.js";
+import "./math/Quaternion.js";
+import { keysOf } from "./keysOf.js";
+import { Outbox } from "./events/Outbox.js";
+export { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, IDENTITY_MATRIX3, Outbox, asGyroViewError, clamp, degrees, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, keysOf, lazy, messageOf, microseconds, microsecondsToSeconds, milliseconds, seconds, secondsToMicroseconds };

package/dist/packages/core/src/shared/mapRecord.js

@@ -0,0 +1,11 @@
+//#region ../../packages/core/src/shared/mapRecord.ts
+/**
+* A record with each value of `every` turned by `map`, under the same keys: a table declared once
+* becomes a record of what it describes, and the record's type keeps every key of the table.
+*/
+function mapRecord(every, map) {
+	const entries = Object.entries(every).map(([key, value]) => [key, map(value, key)]);
+	return Object.fromEntries(entries);
+}
+//#endregion
+export { mapRecord };

package/dist/packages/core/src/shared/protobuf/ProtobufMessage.js

@@ -1,24 +1,10 @@
 import { GyroViewError } from "../errors/GyroViewError.js";
 import { ByteReader } from "../binary/ByteReader.js";
 import { decodeUtf8 } from "../text/utf8.js";
+import { WireType } from "./wireFormat.js";
 //#region ../../packages/core/src/shared/protobuf/ProtobufMessage.ts
-/**
-* Protocol Buffers wire types this decoder understands. Groups (3, 4) are obsolete and rejected.
-*/
-var WireType = {
-	Varint: 0,
-	Fixed64: 1,
-	LengthDelimited: 2,
-	Fixed32: 5
-};
-var FIELD_NUMBER_SHIFT = 3;
-var WIRE_TYPE_MASK = 7;
-var VARINT_PAYLOAD_BITS = 7n;
-var VARINT_PAYLOAD_MASK = 127n;
-var VARINT_CONTINUATION_BIT = 128;
-var FIXED64_SIZE = 8;
-var FIXED32_SIZE = 4;
-var MAX_VARINT_BYTES = 10;
+var VARINT_SHIFT = BigInt(7);
+var VARINT_MASK = BigInt(127);
 var MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
 /**
 * A schema-less view of one encoded protobuf message: fields are looked up by number and unknown
@@ -93,8 +79,8 @@ var Cursor = class {
 	}
 	readField() {
 		const key = this.readVarint();
-		const number = Number(key >> BigInt(FIELD_NUMBER_SHIFT));
-		const wireType = Number(key & BigInt(WIRE_TYPE_MASK));
+		const number = Number(key >> BigInt(3));
+		const wireType = Number(key & BigInt(7));
 		return {
 			number,
 			value: this.readValue(wireType, number)
@@ -108,11 +94,11 @@ var Cursor = class {
 			};
 			case WireType.Fixed64: return {
 				kind: "fixed64",
-				bytes: this.readBytes(FIXED64_SIZE)
+				bytes: this.readBytes(8)
 			};
 			case WireType.Fixed32: return {
 				kind: "fixed32",
-				bytes: this.readBytes(FIXED32_SIZE)
+				bytes: this.readBytes(4)
 			};
 			case WireType.LengthDelimited: return {
 				kind: "bytes",
@@ -124,13 +110,13 @@ var Cursor = class {
 	readVarint() {
 		let result = 0n;
 		let shift = 0n;
-		for (let consumed = 0; consumed < MAX_VARINT_BYTES; consumed += 1) {
+		for (let consumed = 0; consumed < 10; consumed += 1) {
 			const byte = this.readByte();
-			result |= (BigInt(byte) & VARINT_PAYLOAD_MASK) << shift;
-			if ((byte & VARINT_CONTINUATION_BIT) === 0) return result;
-			shift += VARINT_PAYLOAD_BITS;
+			result |= (BigInt(byte) & VARINT_MASK) << shift;
+			if ((byte & 128) === 0) return result;
+			shift += VARINT_SHIFT;
 		}
-		throw new GyroViewError("invalid-protobuf", `varint longer than ${MAX_VARINT_BYTES} bytes at byte ${this.position}`);
+		throw new GyroViewError("invalid-protobuf", `varint longer than 10 bytes at byte ${this.position}`);
 	}
 	readLength() {
 		const length = this.readVarint();

package/dist/packages/core/src/shared/protobuf/wireFormat.js

@@ -0,0 +1,16 @@
+//#region ../../packages/core/src/shared/protobuf/wireFormat.ts
+/**
+* The Protocol Buffers wire format (protobuf encoding spec, "Message Structure"): the wire types
+* a field key names and how keys and varints are laid out. The decoder and the fixtures' encoder
+* share it, so that the two cannot disagree on a byte.
+*
+* The wire types the info record uses; groups (3, 4) are obsolete, and the decoder rejects them.
+*/
+var WireType = {
+	Varint: 0,
+	Fixed64: 1,
+	LengthDelimited: 2,
+	Fixed32: 5
+};
+//#endregion
+export { WireType };

package/dist/packages/player/src/composition/buildPipeline.js

@@ -122,7 +122,8 @@ function wallClock(warning) {
 function stitchingSetupOf(opened) {
 	return buildStitchingSetup({
 		calibration: opened.calibration,
-		layout: opened.layout
+		layout: opened.layout,
+		displayConversions: opened.displayConversions
 	});
 }
 function sinkOver(renderer, opened) {

package/dist/packages/player/src/composition/openInputs.js

@@ -3,6 +3,7 @@ import { seconds } from "../../../core/src/shared/units/time.js";
 import { timeRecording } from "../../../core/src/application/recording/timeRecording.js";
 import { detectLensLayout } from "../../../core/src/domain/format/layout/detectLensLayout.js";
 import { lensFrameOrder } from "../../../core/src/domain/stitching/StitchingSetup.js";
+import { displayConversionsOf } from "../../../core/src/domain/colour/DisplayConversion.js";
 import { startFileDownload } from "../../../core/src/application/download/startFileDownload.js";
 import { downloadPolicyFor } from "../../../core/src/domain/download/DownloadPolicy.js";
 import { RecordingBuffer } from "../../../core/src/application/download/RecordingBuffer.js";
@@ -77,18 +78,20 @@ function calibrationOf(recording) {
 function assemble(parts, packager, disposables) {
 	const { read, files, layout, frameSources, calibration, timing } = parts;
 	const duration = seconds(Math.min(...files.map((file) => file.duration)));
+	const display = displayConversionsOf(frameSources.map((source) => source.description.colour));
 	const [sound] = files.flatMap((file) => file.audioTracks);
 	return {
 		recording: read.recording,
 		layout,
 		frameSources,
 		calibration,
+		displayConversions: display.conversions,
 		duration,
 		frameTimes: timing.frameTimes,
 		motion: timing.motion,
 		soundSegments: sound && (() => packager.segmentsOf(sound.samples, sound.configuration)),
 		metadata: metadataOf(parts, duration, sound !== void 0),
-		warnings: timing.warnings,
+		warnings: [...timing.warnings, ...display.warnings],
 		readAhead: () => {
 			for (const file of files) file.download.startReadingAhead();
 		},

package/dist/packages/player/src/controls/messages.js

@@ -78,7 +78,8 @@ var DEFAULT_MESSAGES = {
 		"unsupported-container": UNREADABLE,
 		"unsupported-gyro-record": UNREADABLE,
 		"unsupported-info-format": UNREADABLE,
-		"unsupported-layout": UNREADABLE
+		"unsupported-layout": UNREADABLE,
+		"webcodecs-unavailable": UNSUPPORTED_BROWSER
 	}
 };
 /**