@bubo-squared/gyroview 0.1.0

package/dist/packages/core/src/domain/format/trailer/Trailer.js

@@ -0,0 +1,23 @@
+//#region ../../packages/core/src/domain/format/trailer/Trailer.ts
+/**
+* The table of contents of an Insta360 trailer: which records exist and where their payloads
+* lie. Pure data; reading payloads is the caller's job because some are megabytes large.
+*/
+var Trailer = class {
+	footer;
+	payloadStart;
+	byId;
+	constructor(footer, payloadStart, records) {
+		this.footer = footer;
+		this.payloadStart = payloadStart;
+		this.byId = new Map(records.map((record) => [record.id, record]));
+	}
+	get records() {
+		return [...this.byId.values()];
+	}
+	locationOf(id) {
+		return this.byId.get(id);
+	}
+};
+//#endregion
+export { Trailer };

package/dist/packages/core/src/domain/format/trailer/TrailerFooter.js

@@ -0,0 +1,27 @@
+import { GyroViewError } from "../../../shared/errors/GyroViewError.js";
+import "../constants.js";
+import { ByteReader } from "../../../shared/binary/ByteReader.js";
+//#region ../../packages/core/src/domain/format/trailer/TrailerFooter.ts
+/**
+* The fixed 72-byte block that closes an Insta360 file. Its presence identifies the format;
+* its size field tells where the trailer payload begins.
+*/
+var TrailerFooter = class TrailerFooter {
+	trailerSize;
+	version;
+	constructor(trailerSize, version) {
+		this.trailerSize = trailerSize;
+		this.version = version;
+	}
+	/**
+	* Parses exactly the last {@link TRAILER_FOOTER_SIZE} bytes of a file.
+	*/
+	static parse(bytes) {
+		if (bytes.byteLength !== 72) throw new GyroViewError("invalid-trailer", `footer must be 72 bytes, got ${bytes.byteLength}`);
+		const reader = new ByteReader(bytes);
+		if (reader.asciiAt(40, 32) !== "8db42d694ccc418790edff439fe026bf") throw new GyroViewError("invalid-trailer", "file does not end with the Insta360 magic");
+		return new TrailerFooter(reader.uint32LeAt(32), reader.uint32LeAt(36));
+	}
+};
+//#endregion
+export { TrailerFooter };

package/dist/packages/core/src/domain/format/trailer/locateRecords.js

@@ -0,0 +1,80 @@
+import { GyroViewError } from "../../../shared/errors/GyroViewError.js";
+import { RecordType } from "../constants.js";
+import { ByteRange } from "../../../shared/binary/ByteRange.js";
+import { RecordHeader } from "./RecordHeader.js";
+import { parseRecordIndex } from "./parseRecordIndex.js";
+//#region ../../packages/core/src/domain/format/trailer/locateRecords.ts
+/**
+* Finds every record payload. Newer firmware writes an index record before the footer and pads
+* records to aligned offsets; older firmware writes records back to back, which can only be
+* walked backwards from the footer. The header before the footer tells which case applies.
+*/
+function locateRecords(source, layout) {
+	return layout.lastHeader.id === RecordType.Index ? locateThroughIndex(source, layout) : locateByWalkingBackwards(source, layout);
+}
+async function locateThroughIndex(source, layout) {
+	const indexOffset = layout.fileSize - 72 - 6 - layout.lastHeader.payloadSize;
+	ensureNotBeforePayloadStart(indexOffset, layout.lastHeader, layout.payloadStart);
+	const indexRange = ByteRange.of(indexOffset, layout.lastHeader.payloadSize);
+	const records = parseRecordIndex(await source.read(indexRange), layout.payloadStart);
+	for (const record of records) ensureBeforeIndex(record, indexRange.offset);
+	return records;
+}
+/**
+* The index counts every offset from the payload start, so only a record's end can stray: past
+* the index, into the footer or beyond the file.
+*/
+function ensureBeforeIndex(record, indexStart) {
+	if (record.payload.end > indexStart) throw new GyroViewError("invalid-trailer", `record ${record.id} at ${record.payload.offset}+${record.payload.length} lies outside the trailer`);
+}
+async function locateByWalkingBackwards(source, layout) {
+	const records = [];
+	const chunks = new BackwardChunks(source, layout.payloadStart);
+	let recordEnd = layout.fileSize - 72;
+	while (recordEnd > layout.payloadStart) {
+		const header = RecordHeader.parse(await chunks.bytesEndingAt(recordEnd, 6));
+		const payloadOffset = recordEnd - 6 - header.payloadSize;
+		ensureNotBeforePayloadStart(payloadOffset, header, layout.payloadStart);
+		records.push({
+			id: header.id,
+			format: header.format,
+			payload: ByteRange.of(payloadOffset, header.payloadSize)
+		});
+		recordEnd = payloadOffset;
+	}
+	return records.toReversed();
+}
+/**
+* How much of the trailer one read of the backward walk takes: the headers of the small records
+* near the footer share one, and only a large payload (the gyro record) sends the walk past it.
+*/
+var WALK_CHUNK_SIZE = 65536;
+/**
+* Reads the trailer backwards a chunk at a time, so walking a bare trailer costs a round trip
+* per chunk rather than per record, each read being an HTTP request.
+*/
+var BackwardChunks = class {
+	source;
+	trailerStart;
+	chunkStart = 0;
+	chunk = /* @__PURE__ */ new Uint8Array();
+	constructor(source, trailerStart) {
+		this.source = source;
+		this.trailerStart = trailerStart;
+	}
+	async bytesEndingAt(end, length) {
+		const start = end - length;
+		if (start < this.trailerStart) throw new GyroViewError("invalid-trailer", `a record header at ${start} lies before the trailer`);
+		if (!(start >= this.chunkStart && end <= this.chunkStart + this.chunk.byteLength)) await this.readChunkEndingAt(end);
+		return this.chunk.subarray(start - this.chunkStart, end - this.chunkStart);
+	}
+	async readChunkEndingAt(end) {
+		this.chunkStart = Math.max(this.trailerStart, end - WALK_CHUNK_SIZE);
+		this.chunk = await this.source.read(ByteRange.of(this.chunkStart, end - this.chunkStart));
+	}
+};
+function ensureNotBeforePayloadStart(payloadOffset, header, payloadStart) {
+	if (payloadOffset < payloadStart) throw new GyroViewError("invalid-trailer", `record ${header.id} (${header.payloadSize} bytes) runs past the trailer start; records are not contiguous`);
+}
+//#endregion
+export { WALK_CHUNK_SIZE, locateRecords };

package/dist/packages/core/src/domain/format/trailer/parseRecordIndex.js

@@ -0,0 +1,28 @@
+import { GyroViewError } from "../../../shared/errors/GyroViewError.js";
+import { ByteReader } from "../../../shared/binary/ByteReader.js";
+import { ByteRange } from "../../../shared/binary/ByteRange.js";
+//#region ../../packages/core/src/domain/format/trailer/parseRecordIndex.ts
+/**
+* Parses the index record (id 0) into record locations. Slot offsets are relative to the
+* trailer payload start, so the caller supplies that absolute position.
+*/
+function parseRecordIndex(bytes, payloadStart) {
+	if (bytes.byteLength % 10 !== 0) throw new GyroViewError("invalid-trailer", `index size ${bytes.byteLength} is not a multiple of 10`);
+	const reader = new ByteReader(bytes);
+	const records = [];
+	for (let slotOffset = 0; slotOffset < bytes.byteLength; slotOffset += 10) {
+		const location = slotAt(reader, slotOffset, payloadStart);
+		if (location) records.push(location);
+	}
+	return records;
+}
+function slotAt(reader, slotOffset, payloadStart) {
+	const size = reader.uint32LeAt(slotOffset + 2);
+	return size === 0 ? void 0 : {
+		id: reader.uint8At(slotOffset + 0),
+		format: reader.uint8At(slotOffset + 1),
+		payload: ByteRange.of(payloadStart + reader.uint32LeAt(slotOffset + 6), size)
+	};
+}
+//#endregion
+export { parseRecordIndex };

package/dist/packages/core/src/domain/format/trailer/readTrailer.js

@@ -0,0 +1,32 @@
+import { GyroViewError } from "../../../shared/errors/GyroViewError.js";
+import { ByteReader } from "../../../shared/binary/ByteReader.js";
+import { ByteRange } from "../../../shared/binary/ByteRange.js";
+import { RecordHeader } from "./RecordHeader.js";
+import { locateRecords } from "./locateRecords.js";
+import { Trailer } from "./Trailer.js";
+import { TrailerFooter } from "./TrailerFooter.js";
+//#region ../../packages/core/src/domain/format/trailer/readTrailer.ts
+var TAIL_SIZE = 78;
+/**
+* Reads the trailer's table of contents with as few round trips as possible: one read for the
+* footer plus last header, then whatever locating the records needs. `fileSize` is passed in so
+* the caller can share one size lookup between several readers of the same source.
+*/
+async function readTrailer(source, fileSize) {
+	if (fileSize < TAIL_SIZE) throw new GyroViewError("invalid-trailer", `file of ${fileSize} bytes is too small to hold a trailer`);
+	const layout = parseLayout(await source.read(ByteRange.lastOf(fileSize, TAIL_SIZE)), fileSize);
+	return new Trailer(layout.footer, layout.payloadStart, await locateRecords(source, layout));
+}
+function parseLayout(tail, fileSize) {
+	const reader = new ByteReader(tail);
+	const footer = TrailerFooter.parse(reader.bytesAt(6, 72));
+	if (footer.trailerSize > fileSize) throw new GyroViewError("invalid-trailer", `trailer size ${footer.trailerSize} exceeds file size ${fileSize}`);
+	return {
+		fileSize,
+		payloadStart: fileSize - footer.trailerSize,
+		footer,
+		lastHeader: RecordHeader.parse(reader.bytesAt(0, 6))
+	};
+}
+//#endregion
+export { readTrailer };

package/dist/packages/core/src/domain/motion/exposure/ExposureRecord.js

@@ -0,0 +1,53 @@
+import { ensureIndexInRange, ensureInvariant } from "../../../shared/errors/GyroViewError.js";
+import { microseconds, seconds } from "../../../shared/units/time.js";
+//#region ../../packages/core/src/domain/motion/exposure/ExposureRecord.ts
+/**
+* Capture times and shutter durations of every frame the sensor produced, in order.
+*/
+var ExposureRecord = class ExposureRecord {
+	captureTimeStore;
+	shutterTimeStore;
+	constructor(captureTimeStore, shutterTimeStore) {
+		this.captureTimeStore = captureTimeStore;
+		this.shutterTimeStore = shutterTimeStore;
+		ensureInvariant(captureTimeStore.length === shutterTimeStore.length, "exposure record arrays disagree on the entry count");
+	}
+	get length() {
+		return this.captureTimeStore.length;
+	}
+	get captureTimes() {
+		return this.captureTimeStore;
+	}
+	get shutterTimes() {
+		return this.shutterTimeStore;
+	}
+	entryAt(index) {
+		ensureIndexInRange(index, this.length, "exposure entry");
+		return {
+			captureTime: microseconds(this.captureTimeStore[index] ?? 0),
+			shutterTime: seconds(this.shutterTimeStore[index] ?? 0)
+		};
+	}
+	/**
+	* Index of the first entry captured at or after `captureTime`, or the length when none is.
+	*/
+	indexAtOrAfter(captureTime) {
+		let low = 0;
+		let high = this.captureTimeStore.length;
+		while (low < high) {
+			const middle = low + high >>> 1;
+			if ((this.captureTimeStore[middle] ?? Infinity) < captureTime) low = middle + 1;
+			else high = middle;
+		}
+		return low;
+	}
+	/**
+	* The `count` entries starting at `start`, as their own record.
+	*/
+	slice(start, count) {
+		ensureInvariant(start >= 0 && count >= 0 && start + count <= this.length, "exposure slice out of range");
+		return new ExposureRecord(this.captureTimeStore.slice(start, start + count), this.shutterTimeStore.slice(start, start + count));
+	}
+};
+//#endregion
+export { ExposureRecord };

package/dist/packages/core/src/domain/motion/gyro/GyroTrack.js

@@ -0,0 +1,60 @@
+import { ensureIndexInRange, ensureInvariant } from "../../../shared/errors/GyroViewError.js";
+import { microseconds } from "../../../shared/units/time.js";
+//#region ../../packages/core/src/domain/motion/gyro/GyroTrack.ts
+/**
+* Structure-of-arrays storage for a whole recording's IMU samples (a 4-minute X5 clip has a
+* quarter of a million), with a per-sample view for callers that prefer objects. Its times never
+* go back: the orientation lookup searches them and the estimation windows measure them, so
+* recorded stamps come through {@link repairedTimeline}.
+*/
+var GyroTrack = class {
+	captureTimeStore;
+	accelerationStore;
+	angularVelocityStore;
+	constructor(captureTimeStore, accelerationStore, angularVelocityStore) {
+		this.captureTimeStore = captureTimeStore;
+		this.accelerationStore = accelerationStore;
+		this.angularVelocityStore = angularVelocityStore;
+		const expected = captureTimeStore.length * 3;
+		ensureInvariant(accelerationStore.length === expected && angularVelocityStore.length === expected, "gyro track arrays disagree on the sample count");
+		ensureInvariant(isNonDecreasing(captureTimeStore), "gyro sample times go back");
+	}
+	get length() {
+		return this.captureTimeStore.length;
+	}
+	get isEmpty() {
+		return this.captureTimeStore.length === 0;
+	}
+	get captureTimes() {
+		return this.captureTimeStore;
+	}
+	/**
+	* Mean spacing between consecutive samples, or undefined for fewer than two samples.
+	*/
+	get meanSampleInterval() {
+		if (this.length < 2) return void 0;
+		const span = (this.captureTimeStore[this.length - 1] ?? 0) - (this.captureTimeStore[0] ?? 0);
+		return microseconds(span / (this.length - 1));
+	}
+	sampleAt(index) {
+		ensureIndexInRange(index, this.length, "gyro sample");
+		const base = index * 3;
+		return {
+			captureTime: microseconds(this.captureTimeStore[index] ?? 0),
+			acceleration: this.vectorAt(this.accelerationStore, base),
+			angularVelocity: this.vectorAt(this.angularVelocityStore, base)
+		};
+	}
+	vectorAt(store, base) {
+		return [
+			store[base] ?? NaN,
+			store[base + 1] ?? NaN,
+			store[base + 2] ?? NaN
+		];
+	}
+};
+function isNonDecreasing(times) {
+	return times.every((time, index) => index === 0 || time >= (times[index - 1] ?? time));
+}
+//#endregion
+export { GyroTrack };

package/dist/packages/core/src/domain/motion/gyro/medianStep.js

@@ -0,0 +1,11 @@
+//#region ../../packages/core/src/domain/motion/gyro/medianStep.ts
+/**
+* The median spacing of consecutive stamps: a stray among them moves it by no more than one
+* place, so a few glitched or unset stamps do not decide it. Zero for fewer than two stamps.
+*/
+function medianStep(stamps) {
+	const sorted = stamps.subarray(1).map((stamp, index) => stamp - (stamps[index] ?? stamp)).toSorted();
+	return sorted[Math.floor(sorted.length / 2)] ?? 0;
+}
+//#endregion
+export { medianStep };

package/dist/packages/core/src/domain/motion/gyro/repairedTimeline.js

@@ -0,0 +1,101 @@
+import { medianStep } from "./medianStep.js";
+//#region ../../packages/core/src/domain/motion/gyro/repairedTimeline.ts
+/**
+* How far a stamp may stray from where its neighbours put it, in typical sample intervals,
+* before it is taken for a glitch: far beyond an IMU's jitter, far below what a flipped bit
+* leaves.
+*/
+var STRAY_INTERVALS = 50;
+/**
+* The least stray tolerance, in microseconds, for a record whose stamps barely move.
+*/
+var MIN_STRAY_TOLERANCE_US = 1e4;
+/**
+* A stretch of stamps in step this long is trusted: longer than any run of strays the repair
+* mends (a clock glitch, a flipped bit, a few uninitialised stamps), so strays never outvote it.
+*/
+var TRUSTED_STRETCH = 17;
+/**
+* Recorded stamps made fit to integrate over and to search. Stretches of stamps in step are
+* trusted when they are long (and the longest always is); every stamp outside them is placed on
+* the line from its nearest trusted neighbour, keeping its own time when that is near. A real gap
+* lies between two trusted stretches and stays. No stamp is then let go back.
+*/
+function repairedTimeline(recorded) {
+	const interval = typicalInterval(recorded);
+	const line = {
+		recorded,
+		interval,
+		tolerance: toleranceOf(interval)
+	};
+	const times = Float64Array.from(recorded);
+	placeOutsideTrusted(times, trustedStretches(steadyStretches(line)), line);
+	const mended = times.filter((time, index) => time !== recorded[index]).length;
+	for (let index = 1; index < times.length; index += 1) times[index] = Math.max(times[index] ?? 0, times[index - 1] ?? 0);
+	return {
+		times,
+		mended
+	};
+}
+function toleranceOf(interval) {
+	return Math.max(STRAY_INTERVALS * interval, MIN_STRAY_TOLERANCE_US);
+}
+/**
+* The median spacing of the first samples.
+*/
+function typicalInterval(times) {
+	return medianStep(times.subarray(0, 1025));
+}
+/**
+* The maximal runs of stamps each a step after the one before (not back, not far ahead).
+*/
+function steadyStretches({ recorded, tolerance }) {
+	const stretches = [];
+	let start = 0;
+	for (let index = 1; index <= recorded.length; index += 1) {
+		const step = (recorded[index] ?? -Infinity) - (recorded[index - 1] ?? 0);
+		if (step >= 0 && step <= tolerance) continue;
+		stretches.push({
+			start,
+			end: index
+		});
+		start = index;
+	}
+	return stretches;
+}
+function trustedStretches(stretches) {
+	let longest = 0;
+	for (const stretch of stretches) longest = Math.max(longest, lengthOf(stretch));
+	return stretches.filter((stretch) => {
+		const length = lengthOf(stretch);
+		return length >= TRUSTED_STRETCH || length === longest;
+	});
+}
+function lengthOf(stretch) {
+	return stretch.end - stretch.start;
+}
+/**
+* Each stamp between trusted stretches, or before the first or after the last, placed on the
+* line from the trusted stamp before it (or after it, ahead of the first stretch).
+*/
+function placeOutsideTrusted(times, trusted, line) {
+	const [first] = trusted;
+	if (!first) return;
+	for (let index = first.start - 1; index >= 0; index -= 1) times[index] = placed(index, (times[index + 1] ?? 0) - line.interval, line);
+	for (const [position, stretch] of trusted.entries()) placeAfter(times, {
+		start: stretch.end,
+		end: trusted[position + 1]?.start ?? times.length
+	}, line);
+}
+function placeAfter(times, untrusted, line) {
+	for (let index = untrusted.start; index < untrusted.end; index += 1) times[index] = placed(index, (times[index - 1] ?? 0) + line.interval, line);
+}
+/**
+* The stamp's own time when it is near where its neighbour puts it, that place otherwise.
+*/
+function placed(index, expected, line) {
+	const recorded = line.recorded[index] ?? expected;
+	return Math.abs(recorded - expected) <= line.tolerance ? recorded : expected;
+}
+//#endregion
+export { repairedTimeline };

package/dist/packages/core/src/domain/motion/imu/ImuFrame.js

@@ -0,0 +1,112 @@
+import { ensureInvariant } from "../../../shared/errors/GyroViewError.js";
+import { determinantOf, transformVector } from "../../../shared/math/Matrix3.js";
+//#region ../../packages/core/src/domain/motion/imu/ImuFrame.ts
+var AXIS_VECTORS = /* @__PURE__ */ new Map([
+	["x", [
+		1,
+		0,
+		0
+	]],
+	["y", [
+		0,
+		1,
+		0
+	]],
+	["z", [
+		0,
+		0,
+		1
+	]],
+	["-x", [
+		-1,
+		0,
+		0
+	]],
+	["-y", [
+		0,
+		-1,
+		0
+	]],
+	["-z", [
+		0,
+		0,
+		-1
+	]]
+]);
+function axisVector(axis) {
+	const vector = AXIS_VECTORS.get(axis);
+	ensureInvariant(vector !== void 0, `unknown IMU axis ${axis}`);
+	return vector;
+}
+function toBodyMatrixOf(bodyAxes) {
+	const [rowX, rowY, rowZ] = bodyAxes.map((axis) => axisVector(axis));
+	return [
+		...rowX,
+		...rowY,
+		...rowZ
+	];
+}
+/**
+* Only a proper rotation is a frame: a repeated axis is singular and a reflection would
+* integrate a mirrored world.
+*/
+function isProperRotation(bodyAxes) {
+	return determinantOf(toBodyMatrixOf(bodyAxes)) === 1;
+}
+/**
+* A frame measured on a recording of the camera it is for.
+*/
+function measuredImuFrame(name, bodyAxes) {
+	return {
+		...frameOf(name, bodyAxes),
+		isVerified: true
+	};
+}
+/**
+* A frame assumed until a recording proves it; it still needs a real file.
+*/
+function assumedImuFrame(name, bodyAxes) {
+	return {
+		...frameOf(name, bodyAxes),
+		isVerified: false
+	};
+}
+function frameOf(name, bodyAxes) {
+	ensureInvariant(isProperRotation(bodyAxes), `IMU axes ${bodyAxes.join(", ")} are not a rotation`);
+	return {
+		name,
+		toBody: toBodyMatrixOf(bodyAxes)
+	};
+}
+function toBodyFrame(frame, imuVector) {
+	return transformVector(frame.toBody, imuVector);
+}
+/**
+* Measured on two X5 recordings (firmware 1.7 and 1.11, ADR 0009): the IMU sits rotated a quarter
+* turn about the camera's lateral axis, so the body's down is the IMU's z and the body's forward
+* is the IMU's minus y. Chosen by the world-stillness ranking in
+* `tools/integration/src/measure/imuFrameRanking.test.ts`, which every other arrangement loses.
+*/
+var X5_IMU_FRAME = measuredImuFrame("X5", [
+	"x",
+	"z",
+	"-y"
+]);
+/**
+* Until a recording proves otherwise, the IMU is assumed aligned with the body.
+*/
+var ALIGNED_IMU_FRAME = assumedImuFrame("aligned (unverified)", [
+	"x",
+	"y",
+	"z"
+]);
+var IMU_FRAMES_BY_MODEL = [["Insta360 X5", X5_IMU_FRAME]];
+/**
+* The IMU frame for a recording, chosen from the camera model the file names. A starting point
+* the recording's own data can be checked against with the ranking test, never the last word.
+*/
+function imuFrameFor(hints) {
+	return IMU_FRAMES_BY_MODEL.find(([prefix]) => hints.model?.startsWith(prefix))?.[1] ?? ALIGNED_IMU_FRAME;
+}
+//#endregion
+export { ALIGNED_IMU_FRAME, X5_IMU_FRAME, assumedImuFrame, imuFrameFor, isProperRotation, toBodyFrame };

package/dist/packages/core/src/domain/motion/orientation/OrientationTrack.js

@@ -0,0 +1,146 @@
+import { ensureInvariant } from "../../../shared/errors/GyroViewError.js";
+import { seconds } from "../../../shared/units/time.js";
+import { ZERO_VECTOR3, addVectors, isFiniteVector, scaleVector, subtractVectors } from "../../../shared/math/Vector3.js";
+import { clamp } from "../../../shared/math/clamp.js";
+import { toBodyFrame } from "../imu/ImuFrame.js";
+import { estimateGyroBias, stillestWindow } from "./estimateGyroBias.js";
+import { IDENTITY_QUATERNION, multiplyQuaternions, normalizeQuaternion, quaternionFromRotationVector, slerpQuaternions } from "../../../shared/math/Quaternion.js";
+import { gravityCorrection, initialOrientation } from "./gravity.js";
+//#region ../../packages/core/src/domain/motion/orientation/OrientationTrack.ts
+var DEFAULT_GRAVITY_GAIN = .2;
+/**
+* Length of the stillest window the gyro bias is estimated from.
+*/
+var BIAS_WINDOW_SECONDS = .5;
+/**
+* Length of the opening window whose mean gravity levels the initial pose: half a second of
+* accelerometer readings averages out hand shake at the start.
+*/
+var LEVELLING_WINDOW_SECONDS = .5;
+var QUATERNION_COMPONENTS = 4;
+/**
+* Gaps longer than this between samples are integrated as if they were this long: a dropout
+* must not spin the estimate by a whole missing second.
+*/
+var MAX_STEP_SECONDS = .05;
+/**
+* The camera's orientation over the whole recording, body frame to world frame, one quaternion
+* per gyro sample. World: y down along gravity, z along the body's forward axis at the start.
+*/
+var OrientationTrack = class OrientationTrack {
+	videoTimes;
+	quaternions;
+	constructor(videoTimes, quaternions) {
+		this.videoTimes = videoTimes;
+		this.quaternions = quaternions;
+		ensureInvariant(quaternions.length === videoTimes.length * QUATERNION_COMPONENTS, "orientation track arrays disagree on the sample count");
+	}
+	/**
+	* Integrates the gyro, bias-corrected and pulled towards gravity, from an initial pose that
+	* levels the opening window's gravity.
+	*/
+	static integrate(parts) {
+		const { gyro, clock, frame } = parts;
+		const videoTimes = new Float64Array(gyro.length);
+		const quaternions = new Float32Array(gyro.length * QUATERNION_COMPONENTS);
+		if (gyro.isEmpty) return new OrientationTrack(videoTimes, quaternions);
+		const context = {
+			frame,
+			bias: estimateGyroBias(gyro, frame, stillestWindow(gyro, frame, seconds(BIAS_WINDOW_SECONDS))),
+			gravityGain: parts.options?.gravityGain ?? DEFAULT_GRAVITY_GAIN
+		};
+		videoTimes.set(sampleVideoTimes(gyro, clock));
+		let state = {
+			orientation: initialOrientation(gyro, frame, seconds(LEVELLING_WINDOW_SECONDS)),
+			time: seconds(videoTimes[0] ?? 0),
+			rate: ZERO_VECTOR3
+		};
+		for (let index = 0; index < gyro.length; index += 1) {
+			const time = seconds(videoTimes[index] ?? state.time);
+			state = stepTo(state, {
+				sample: finiteSample(gyro, index),
+				time
+			}, context);
+			quaternions.set(state.orientation, index * QUATERNION_COMPONENTS);
+		}
+		return new OrientationTrack(videoTimes, quaternions);
+	}
+	get length() {
+		return this.videoTimes.length;
+	}
+	/**
+	* The orientation at a video time, interpolated between samples and held at the ends.
+	*/
+	orientationAt(videoTime) {
+		if (this.length === 0) return IDENTITY_QUATERNION;
+		const after = this.firstIndexAfter(videoTime);
+		if (after === 0) return this.quaternionAt(0);
+		if (after >= this.length) return this.quaternionAt(this.length - 1);
+		const before = after - 1;
+		const span = (this.videoTimes[after] ?? 0) - (this.videoTimes[before] ?? 0);
+		const fraction = span > 0 ? (videoTime - (this.videoTimes[before] ?? 0)) / span : 0;
+		return slerpQuaternions(this.quaternionAt(before), this.quaternionAt(after), fraction);
+	}
+	quaternionAt(index) {
+		const base = index * QUATERNION_COMPONENTS;
+		const [x = 0, y = 0, z = 0, w = 1] = this.quaternions.subarray(base, base + QUATERNION_COMPONENTS);
+		return [
+			x,
+			y,
+			z,
+			w
+		];
+	}
+	firstIndexAfter(videoTime) {
+		let low = 0;
+		let high = this.length;
+		while (low < high) {
+			const middle = Math.floor((low + high) / 2);
+			if ((this.videoTimes[middle] ?? Infinity) <= videoTime) low = middle + 1;
+			else high = middle;
+		}
+		return low;
+	}
+};
+/**
+* The samples' video times, never going back as the track's capture times never do, so the
+* lookup's binary search holds.
+*/
+function sampleVideoTimes(gyro, clock) {
+	return Float64Array.from({ length: gyro.length }, (_unused, index) => clock.gyroVideoTimeOf(gyro.sampleAt(index).captureTime));
+}
+function finiteSample(gyro, index) {
+	const sample = gyro.sampleAt(index);
+	ensureInvariant(isFiniteVector(sample.acceleration) && isFiniteVector(sample.angularVelocity), `gyro sample ${index} is not finite`);
+	return sample;
+}
+/**
+* The state at the next sample: the body turned at the previous rate, pulled towards the gravity
+* this sample measures, for the time since the previous sample (clamped, see MAX_STEP_SECONDS).
+*/
+function stepTo(state, { sample, time }, context) {
+	const { frame, bias, gravityGain } = context;
+	const step = clamp(time - state.time, 0, MAX_STEP_SECONDS);
+	const correction = gravityCorrection(state.orientation, toBodyFrame(frame, sample.acceleration));
+	return {
+		orientation: advance(state.orientation, corrected(state.rate, correction, gravityGain), step),
+		time,
+		rate: subtractVectors(toBodyFrame(frame, sample.angularVelocity), bias)
+	};
+}
+/**
+* The gyro rate with the gravity pull added, radians per second in the body frame.
+*/
+function corrected(rate, correction, gain) {
+	return addVectors(rate, scaleVector(correction, gain));
+}
+/**
+* One integration step: the body turns at `rate` for `step` seconds. The rate is the one
+* measured at the start of the interval, so a turn beginning at a sample begins exactly there.
+*/
+function advance(orientation, rate, step) {
+	const turn = quaternionFromRotationVector(scaleVector(rate, step));
+	return normalizeQuaternion(multiplyQuaternions(orientation, turn));
+}
+//#endregion
+export { OrientationTrack };