@bubo-squared/gyroview 0.1.0

package/dist/packages/core/src/domain/format/layout/detectLensLayout.js

@@ -0,0 +1,122 @@
+import { GyroViewError } from "../../../shared/errors/GyroViewError.js";
+import { RecordingFileName } from "../naming/RecordingFileName.js";
+import { FULL_FRAME, LEFT_HALF, RIGHT_HALF } from "../../stitching/LensLayout.js";
+//#region ../../packages/core/src/domain/format/layout/detectLensLayout.ts
+var LENS_COUNT = 2;
+var PACKED_ASPECT_RATIO = 2;
+var ASPECT_TOLERANCE = .02;
+var BACK_LENS_RANK = 0;
+var UNNAMED_RANK = 1;
+var SCREEN_LENS_RANK = 2;
+/**
+* Decides how the lens images are stored from the tracks actually present, using the info
+* record only as a hint. See ADR 0004.
+*/
+function detectLensLayout(inputs, hints) {
+	const candidates = inputs.flatMap((input, inputIndex) => input.videoTracks.map(({ description }) => ({
+		input,
+		inputIndex,
+		track: description
+	})));
+	if (inputs.length === 1 && areTwoMatchingSquareTracks(candidates)) return multiTrack(candidates, hints);
+	if (inputs.length === LENS_COUNT && isOneSquareTrackPerInput(inputs, candidates)) return splitFiles(inputs, candidates);
+	const [only] = candidates;
+	if (only && candidates.length === 1 && isPacked(only.track)) return packed(only);
+	throw undecidable(inputs, candidates);
+}
+/**
+* Lens 0 is the back lens. Without a track-order hint the first track is assumed to be it, as
+* for the `_00_` file of a pair; when the hint says track 0 is stream 10 the tracks are swapped.
+*/
+function multiTrack(candidates, hints) {
+	const isSwapped = hints.trackOrder === "stream-10-first";
+	const ordered = isSwapped ? candidates.toReversed() : candidates;
+	const fileLayoutEvidence = hints.fileLayout === void 0 ? [] : [`info record file layout ${hints.fileLayout}`];
+	const trackOrderEvidence = hints.trackOrder === void 0 ? "no track order hint: lens 0 assumed to be track 0" : `info record track order ${hints.trackOrder}: lens 0 is track ${isSwapped ? 1 : 0}`;
+	return {
+		kind: "multi-track",
+		sources: ordered.map((candidate, lensIndex) => fullFrameSource(candidate, lensIndex)),
+		evidence: [
+			"one input with two video tracks",
+			...fileLayoutEvidence,
+			trackOrderEvidence
+		]
+	};
+}
+function splitFiles(inputs, candidates) {
+	const ordered = candidates.toSorted((left, right) => fileRank(left.input) - fileRank(right.input));
+	const names = inputs.map((input) => input.name ?? "?").join(", ");
+	return {
+		kind: "split-files",
+		sources: ordered.map((candidate, lensIndex) => fullFrameSource(candidate, lensIndex)),
+		evidence: [`two inputs with one video track each (${names})`, "lens 0 taken from the _00_ file when named"]
+	};
+}
+function packed(candidate) {
+	const { inputIndex, track } = candidate;
+	return {
+		kind: "packed",
+		sources: [{
+			lensIndex: 0,
+			inputIndex,
+			trackIndex: track.trackIndex,
+			region: LEFT_HALF
+		}, {
+			lensIndex: 1,
+			inputIndex,
+			trackIndex: track.trackIndex,
+			region: RIGHT_HALF
+		}],
+		evidence: [`single ${track.codedWidth}x${track.codedHeight} track with a 2:1 aspect ratio`]
+	};
+}
+function fullFrameSource(candidate, lensIndex) {
+	return {
+		lensIndex,
+		inputIndex: candidate.inputIndex,
+		trackIndex: candidate.track.trackIndex,
+		region: FULL_FRAME
+	};
+}
+/**
+* Lens tracks are square and, in one file, identical in size.
+*/
+function areTwoMatchingSquareTracks(candidates) {
+	const [first, second] = candidates;
+	return candidates.length === LENS_COUNT && first !== void 0 && second !== void 0 && isSquare(first.track) && first.track.codedWidth === second.track.codedWidth && first.track.codedHeight === second.track.codedHeight;
+}
+function isOneSquareTrackPerInput(inputs, candidates) {
+	return candidates.length === LENS_COUNT && inputs.every((input) => input.videoTracks.length === 1) && candidates.every((candidate) => isSquare(candidate.track));
+}
+function isSquare(track) {
+	return track.codedWidth === track.codedHeight;
+}
+function isPacked(track) {
+	return Math.abs(track.codedWidth / track.codedHeight - PACKED_ASPECT_RATIO) <= ASPECT_TOLERANCE;
+}
+/**
+* The back lens file (`_00_`) sorts first, the screen-side lens file (`_10_`) second; unnamed or
+* unconventionally named files keep their given order.
+*/
+function fileRank(input) {
+	const name = RecordingFileName.parse(input.name ?? "");
+	if (name?.isBackLens) return BACK_LENS_RANK;
+	return name?.isScreenLens ? SCREEN_LENS_RANK : UNNAMED_RANK;
+}
+function undecidable(inputs, candidates) {
+	const [only] = candidates;
+	if (inputs.length === 1 && candidates.length === 1 && only !== void 0 && isSquare(only.track)) return missingSecondFile(only.input);
+	const shape = candidates.map((candidate) => `${candidate.track.codedWidth}x${candidate.track.codedHeight}`).join(", ");
+	return new GyroViewError("unsupported-layout", `cannot map ${candidates.length} video track(s) [${shape}] in ${inputs.length} file(s) onto two lenses`);
+}
+/**
+* What to hand over besides a lone half: the file the name says holds the other lens, when the
+* name follows the camera's pattern.
+*/
+function missingSecondFile(input) {
+	const name = RecordingFileName.parse(input.name ?? "");
+	const other = name ? `the matching ${name.otherLensName()}` : "the other lens's file";
+	return new GyroViewError("missing-second-file", `this recording stores one lens per file; provide ${other} as the second source`);
+}
+//#endregion
+export { detectLensLayout };

package/dist/packages/core/src/domain/format/naming/RecordingFileName.js

@@ -0,0 +1,67 @@
+//#region ../../packages/core/src/domain/format/naming/RecordingFileName.ts
+/**
+* Insta360 file names follow `VID_20260814_132640_00_013.insv`: a prefix, the capture date and
+* time, a two-digit stream code and a sequence number. In the stream code the first digit names
+* the lens (0 the back lens, 1 the screen-side lens) and the second marks a proxy (0 the
+* recording itself, 1 its low-resolution LRV). Seen on the X5 samples (`VID_..._00_` with
+* `LRV_..._01_`) and documented by the community for the `_00_`/`_10_` pairs of older cameras.
+* The name is only ever a hint: whatever it suggests is verified against the file's contents.
+*/
+var FILE_NAME_PATTERN = /^(?<prefix>[A-Za-z]+(?:_[A-Za-z]+)*)_(?<stamp>\d{8}_\d{6})_(?<lens>\d)(?<proxy>\d)_(?<sequence>\d{3})\.(?<extension>[A-Za-z0-9]+)$/u;
+var BACK_LENS_DIGIT = 0;
+var SCREEN_LENS_DIGIT = 1;
+var RECORDING_DIGIT = 0;
+var PROXY_DIGIT = 1;
+/**
+* Value object over a camera file name; derives the name of the other lens's file the camera
+* writes beside it (see {@link otherLensName}).
+*/
+var RecordingFileName = class RecordingFileName {
+	parts;
+	constructor(parts) {
+		this.parts = parts;
+	}
+	/**
+	* Undefined for names that do not follow the camera's convention.
+	*/
+	static parse(fileName) {
+		const groups = FILE_NAME_PATTERN.exec(fileName)?.groups;
+		return groups ? new RecordingFileName(partsOf(groups)) : void 0;
+	}
+	get isBackLens() {
+		return this.parts.lensDigit === BACK_LENS_DIGIT;
+	}
+	get isScreenLens() {
+		return this.parts.lensDigit === SCREEN_LENS_DIGIT;
+	}
+	get isProxy() {
+		return this.parts.proxyDigit === PROXY_DIGIT;
+	}
+	/**
+	* The file holding the other lens of a split-file recording: `_00_` for `_10_` and back.
+	*/
+	otherLensName() {
+		const lensDigit = this.isBackLens ? SCREEN_LENS_DIGIT : BACK_LENS_DIGIT;
+		return new RecordingFileName({
+			...this.parts,
+			lensDigit,
+			proxyDigit: RECORDING_DIGIT
+		}).toString();
+	}
+	toString() {
+		const { prefix, captureStamp, lensDigit, proxyDigit, sequence, extension } = this.parts;
+		return `${prefix}_${captureStamp}_${lensDigit}${proxyDigit}_${sequence}.${extension}`;
+	}
+};
+function partsOf(groups) {
+	return {
+		prefix: groups["prefix"] ?? "",
+		captureStamp: groups["stamp"] ?? "",
+		lensDigit: Number(groups["lens"]),
+		proxyDigit: Number(groups["proxy"]),
+		sequence: groups["sequence"] ?? "",
+		extension: groups["extension"] ?? ""
+	};
+}
+//#endregion
+export { RecordingFileName };

package/dist/packages/core/src/domain/format/records/TrailerRecords.js

@@ -0,0 +1,83 @@
+import { ensureInvariant } from "../../../shared/errors/GyroViewError.js";
+import { RecordType } from "../constants.js";
+import { parseExposureRecord } from "./exposure/parseExposureRecord.js";
+import { GYRO_LAYOUT_PROBE_SIZE, parseGyroRecord, selectGyroSampleLayout } from "./gyro/parseGyroRecord.js";
+import { captureTimeOfStamp, firstFrameCaptureTime } from "../captureOrigin.js";
+import { ByteRange } from "../../../shared/binary/ByteRange.js";
+//#region ../../packages/core/src/domain/format/records/TrailerRecords.ts
+/**
+* The large records the trailer lists, read on demand through the source: the gyro record in the
+* sample layout the file actually uses, and the exposure record.
+*/
+var TrailerRecords = class {
+	source;
+	trailer;
+	info;
+	gyroLayoutPromise;
+	constructor(source, trailer, info) {
+		this.source = source;
+		this.trailer = trailer;
+		this.info = info;
+	}
+	/**
+	* Whether the trailer lists an exposure record, parsed or not.
+	*/
+	get listsExposure() {
+		return this.trailer.locationOf(RecordType.Exposure) !== void 0;
+	}
+	/**
+	* Undefined when the camera wrote no gyro record.
+	*/
+	async readGyro() {
+		const location = this.trailer.locationOf(RecordType.Gyro);
+		if (location === void 0) return void 0;
+		const [payload, layout] = await Promise.all([this.source.read(location.payload), this.gyroSampleLayout()]);
+		ensureInvariant(layout !== void 0, "a gyro record always yields or refuses a layout");
+		return parseGyroRecord(payload, layout);
+	}
+	/**
+	* Undefined when the camera wrote no exposure record, or a damaged one. Its stamps are in the
+	* gyro layout's unit, so a layout that cannot be told refuses it as it refuses the gyro record.
+	*/
+	async readExposure() {
+		const location = this.trailer.locationOf(RecordType.Exposure);
+		if (location === void 0) return void 0;
+		const [payload, layout] = await Promise.all([this.source.read(location.payload), this.gyroSampleLayout()]);
+		return parseExposureRecord(payload, (stamp) => captureTimeOfStamp(stamp, layout));
+	}
+	/**
+	* When the first frame was captured, which the info record stamps in the gyro layout's unit;
+	* undefined when it does not say.
+	*/
+	async firstFrameCaptureTime() {
+		return firstFrameCaptureTime(this.info, await this.gyroSampleLayout());
+	}
+	/**
+	* The gyro sample layout the file actually uses: from the info record's flag when present,
+	* otherwise inferred from the first bytes of the gyro record, which may refuse to tell.
+	* Undefined without a gyro record and without the flag.
+	*/
+	gyroSampleLayout() {
+		this.gyroLayoutPromise ??= this.selectGyroLayout();
+		return this.gyroLayoutPromise;
+	}
+	async selectGyroLayout() {
+		const hints = this.gyroLayoutHints();
+		if (hints.isRawGyro !== void 0) return selectGyroSampleLayout(hints, void 0);
+		const location = this.trailer.locationOf(RecordType.Gyro);
+		const head = location === void 0 ? void 0 : await this.readHeadOf(location);
+		return selectGyroSampleLayout(hints, head);
+	}
+	gyroLayoutHints() {
+		return {
+			isRawGyro: this.info.isRawGyro,
+			ranges: this.info.sensorRanges
+		};
+	}
+	readHeadOf(location) {
+		const length = Math.min(GYRO_LAYOUT_PROBE_SIZE, location.payload.length);
+		return this.source.read(ByteRange.of(location.payload.offset, length));
+	}
+};
+//#endregion
+export { TrailerRecords };

package/dist/packages/core/src/domain/format/records/exposure/parseExposureRecord.js

@@ -0,0 +1,48 @@
+import { hasErrorCode } from "../../../../shared/errors/GyroViewError.js";
+import { ByteReader } from "../../../../shared/binary/ByteReader.js";
+import { ExposureRecord } from "../../../motion/exposure/ExposureRecord.js";
+//#region ../../packages/core/src/domain/format/records/exposure/parseExposureRecord.ts
+/**
+* Longer than any exposure a camera takes for one frame, night-lapses included; a flipped bit in
+* a float64 shutter time lands far beyond, or at NaN.
+*/
+var MAX_PLAUSIBLE_SHUTTER_SECONDS = 60;
+/**
+* Decodes the exposure record into per-frame capture times, from stamps in the camera's unit
+* through `captureTimeOf`, and shutter times; bytes after the last whole entry are ignored.
+* Undefined when an entry cannot be a reading (a stamp past the safe integers or out of order, a
+* shutter time no camera takes, as a flipped bit leaves): entries belong to frames by their
+* position, so a damaged record is left out whole and frame timing falls back to its next source.
+*/
+function parseExposureRecord(payload, captureTimeOf) {
+	try {
+		return decodeEntries(payload, captureTimeOf);
+	} catch (error) {
+		if (hasErrorCode(error, "binary-unsafe-integer")) return void 0;
+		throw error;
+	}
+}
+function decodeEntries(payload, captureTimeOf) {
+	const count = Math.floor(payload.byteLength / 16);
+	const reader = new ByteReader(payload);
+	const captureTimes = new Float64Array(count);
+	const shutterTimes = new Float64Array(count);
+	for (let index = 0; index < count; index += 1) {
+		const offset = index * 16;
+		captureTimes[index] = captureTimeOf(reader.uint64LeAt(offset + 0));
+		shutterTimes[index] = reader.float64LeAt(offset + 8);
+	}
+	return isInOrder(captureTimes) && shutterTimes.every((time) => isPlausibleShutterTime(time)) ? new ExposureRecord(captureTimes, shutterTimes) : void 0;
+}
+/**
+* Capture times that go back betray a stray stamp, either way: a stamp moved forward makes the
+* next one go back.
+*/
+function isInOrder(captureTimes) {
+	return captureTimes.every((time, index) => index === 0 || time >= (captureTimes[index - 1] ?? time));
+}
+function isPlausibleShutterTime(time) {
+	return time >= 0 && time <= MAX_PLAUSIBLE_SHUTTER_SECONDS;
+}
+//#endregion
+export { parseExposureRecord };

package/dist/packages/core/src/domain/format/records/gyro/FloatGyroSampleLayout.js

@@ -0,0 +1,39 @@
+import { milliseconds, millisecondsToMicroseconds } from "../../../../shared/units/time.js";
+import "./gyroLayouts.js";
+//#region ../../packages/core/src/domain/format/records/gyro/FloatGyroSampleLayout.ts
+/**
+* 56-byte samples with float64 components, written by cameras before the raw layout.
+*/
+var FloatGyroSampleLayout = class {
+	name = "float";
+	sampleSize = 56;
+	/**
+	* A flipped exponent bit leaves a float64 far beyond any reading, or next to zero; a flipped
+	* fraction bit changes it by less than half.
+	*/
+	flipSteps = {
+		acceleration: [],
+		angularVelocity: []
+	};
+	captureTimeOf(stamp) {
+		return millisecondsToMicroseconds(milliseconds(stamp));
+	}
+	timestampAt(reader, offset) {
+		return this.captureTimeOf(reader.uint64LeAt(offset + 0));
+	}
+	accelerationAt(reader, offset) {
+		return this.vectorAt(reader, offset + 8);
+	}
+	angularVelocityAt(reader, offset) {
+		return this.vectorAt(reader, offset + 32);
+	}
+	vectorAt(reader, offset) {
+		return [
+			reader.float64LeAt(offset),
+			reader.float64LeAt(offset + 8),
+			reader.float64LeAt(offset + 16)
+		];
+	}
+};
+//#endregion
+export { FloatGyroSampleLayout };

package/dist/packages/core/src/domain/format/records/gyro/RawGyroSampleLayout.js

@@ -0,0 +1,55 @@
+import { degrees, degreesToRadians } from "../../../../shared/units/angle.js";
+import { microseconds } from "../../../../shared/units/time.js";
+import { DEFAULT_GYROSCOPE_RANGE_DPS, RAW_FULL_SCALE, RAW_HIGH_BIT_WEIGHTS, RAW_ZERO_POINT } from "./gyroLayouts.js";
+//#region ../../packages/core/src/domain/format/records/gyro/RawGyroSampleLayout.ts
+/**
+* Compact 20-byte samples written by X5-era firmware (`is_raw_gyro` = 1).
+*/
+var RawGyroSampleLayout = class {
+	name = "raw";
+	sampleSize = 20;
+	flipSteps;
+	accelerationScale;
+	angularVelocityScale;
+	constructor(ranges = {}) {
+		const accelerometerG = statedRange(ranges.accelerometerG, 16);
+		const gyroscopeDps = statedRange(ranges.gyroscopeDps, DEFAULT_GYROSCOPE_RANGE_DPS);
+		this.accelerationScale = accelerometerG / RAW_FULL_SCALE;
+		this.angularVelocityScale = degreesToRadians(degrees(gyroscopeDps)) / RAW_FULL_SCALE;
+		this.flipSteps = {
+			acceleration: RAW_HIGH_BIT_WEIGHTS.map((weight) => weight * this.accelerationScale),
+			angularVelocity: RAW_HIGH_BIT_WEIGHTS.map((weight) => weight * this.angularVelocityScale)
+		};
+	}
+	captureTimeOf(stamp) {
+		return microseconds(stamp);
+	}
+	timestampAt(reader, offset) {
+		return this.captureTimeOf(reader.uint64LeAt(offset + 0));
+	}
+	accelerationAt(reader, offset) {
+		return this.vectorAt(reader, offset + 8, this.accelerationScale);
+	}
+	angularVelocityAt(reader, offset) {
+		return this.vectorAt(reader, offset + 14, this.angularVelocityScale);
+	}
+	vectorAt(reader, offset, scale) {
+		return [
+			this.componentAt(reader, offset, scale),
+			this.componentAt(reader, offset + 2, scale),
+			this.componentAt(reader, offset + 4, scale)
+		];
+	}
+	componentAt(reader, offset, scale) {
+		return (reader.uint16LeAt(offset) - RAW_ZERO_POINT) * scale;
+	}
+};
+/**
+* The stated range, or the default where none is stated. A range of zero, as a flipped bit or a
+* field left unset writes, would scale every reading to nothing.
+*/
+function statedRange(range, fallback) {
+	return range !== void 0 && range > 0 ? range : fallback;
+}
+//#endregion
+export { RawGyroSampleLayout };

package/dist/packages/core/src/domain/format/records/gyro/SampleColumns.js

@@ -0,0 +1,82 @@
+import { GyroTrack } from "../../../motion/gyro/GyroTrack.js";
+//#region ../../packages/core/src/domain/format/records/gyro/SampleColumns.ts
+/**
+* How closely the neighbours must agree, and the reading put back meet them, in parts of the
+* step (a sixteenth): looser than real motion curves over one interval and the sensor's noise,
+* tighter than a shock or a vibration would match a bit's weight by chance.
+*/
+var STEP_PARTS_TOLERATED = 16;
+/**
+* The samples of a gyro record kept so far, in the columns a {@link GyroTrack} stores them in.
+*/
+var SampleColumns = class {
+	length = 0;
+	recordedTimes;
+	accelerations;
+	angularVelocities;
+	constructor(capacity) {
+		this.recordedTimes = new Float64Array(capacity);
+		this.accelerations = new Float32Array(capacity * 3);
+		this.angularVelocities = new Float32Array(capacity * 3);
+	}
+	push(sample) {
+		this.recordedTimes[this.length] = sample.captureTime;
+		this.accelerations.set(sample.acceleration, this.length * 3);
+		this.angularVelocities.set(sample.angularVelocity, this.length * 3);
+		this.length += 1;
+	}
+	/**
+	* Leaves out samples a flipped high bit moved: one component a bit's weight (one of `steps`)
+	* from where its agreeing neighbours put it. A shock or a vibration leaps too, but between
+	* neighbours that disagree, or by another amount. Compacts in place; each check reads only
+	* samples not yet moved over.
+	*/
+	dropFlippedBits(steps) {
+		let kept = 0;
+		for (let index = 0; index < this.length; index += 1) {
+			if (this.isFlippedAt(index, steps)) continue;
+			this.moveSample(index, kept);
+			kept += 1;
+		}
+		this.length = kept;
+	}
+	/**
+	* The stamps as recorded, to be mended before they make a track.
+	*/
+	captureTimes() {
+		return this.recordedTimes.subarray(0, this.length);
+	}
+	toTrack(captureTimes) {
+		const vectors = this.length * 3;
+		return new GyroTrack(captureTimes, this.accelerations.subarray(0, vectors), this.angularVelocities.subarray(0, vectors));
+	}
+	isFlippedAt(index, steps) {
+		return index > 0 && index < this.length - 1 && (hasFlippedComponent(this.accelerations, index, steps.acceleration) || hasFlippedComponent(this.angularVelocities, index, steps.angularVelocity));
+	}
+	moveSample(from, to) {
+		if (from === to) return;
+		this.recordedTimes[to] = this.recordedTimes[from] ?? 0;
+		for (const vectors of [this.accelerations, this.angularVelocities]) vectors.copyWithin(to * 3, from * 3, (from + 1) * 3);
+	}
+};
+function hasFlippedComponent(vectors, index, steps) {
+	for (let axis = 0; axis < 3; axis += 1) if (isFlippedComponent(vectors, index * 3 + axis, steps)) return true;
+	return false;
+}
+/**
+* The component at `offset` lies one of `steps` from where its agreeing neighbours put it. Plain
+* loops, no closures: this runs for every component of every sample of an hour-long record.
+*/
+function isFlippedComponent(vectors, offset, steps) {
+	const before = vectors[offset - 3] ?? 0;
+	const after = vectors[offset + 3] ?? 0;
+	const leap = Math.abs((vectors[offset] ?? 0) - (before + after) / 2);
+	const disagreement = Math.abs(before - after);
+	for (const step of steps) {
+		const tolerance = step / STEP_PARTS_TOLERATED;
+		if (disagreement <= tolerance && Math.abs(leap - step) <= tolerance) return true;
+	}
+	return false;
+}
+//#endregion
+export { SampleColumns };

package/dist/packages/core/src/domain/format/records/gyro/gyroLayouts.js

@@ -0,0 +1,12 @@
+//#region ../../packages/core/src/domain/format/records/gyro/gyroLayouts.ts
+var RAW_ZERO_POINT = 32768;
+var RAW_FULL_SCALE = 32768;
+/**
+* The weights of a raw component's two highest bits: a flip there moves a reading by its full
+* range or half of it, still within the plausible bounds. A flip lower down moves it too little
+* to matter.
+*/
+var RAW_HIGH_BIT_WEIGHTS = [RAW_FULL_SCALE, RAW_FULL_SCALE / 2];
+var DEFAULT_GYROSCOPE_RANGE_DPS = 2e3;
+//#endregion
+export { DEFAULT_GYROSCOPE_RANGE_DPS, RAW_FULL_SCALE, RAW_HIGH_BIT_WEIGHTS, RAW_ZERO_POINT };

package/dist/packages/core/src/domain/format/records/gyro/parseGyroRecord.js

@@ -0,0 +1,129 @@
+import { GyroViewError, hasErrorCode } from "../../../../shared/errors/GyroViewError.js";
+import { ByteReader } from "../../../../shared/binary/ByteReader.js";
+import "./gyroLayouts.js";
+import { FloatGyroSampleLayout } from "./FloatGyroSampleLayout.js";
+import { RawGyroSampleLayout } from "./RawGyroSampleLayout.js";
+import { SampleColumns } from "./SampleColumns.js";
+import { medianStep } from "../../../motion/gyro/medianStep.js";
+import { repairedTimeline } from "../../../motion/gyro/repairedTimeline.js";
+//#region ../../packages/core/src/domain/format/records/gyro/parseGyroRecord.ts
+/**
+* Plausible spacing between consecutive samples when guessing the layout: 100 Hz to 10 kHz.
+*/
+var MIN_PLAUSIBLE_INTERVAL_US = 100;
+var MAX_PLAUSIBLE_INTERVAL_US = 1e4;
+/**
+* The samples the layout is told from when the info record does not say: enough that a few
+* uninitialised or glitched stamps at the start are outvoted, in one small read.
+*/
+var SAMPLES_TO_GUESS_FROM = 32;
+var MIN_SAMPLES_TO_GUESS_FROM = 2;
+/**
+* Readings past these are no motion a camera makes: the X5 declares a 32 g and a 2000 degrees a
+* second (35 rad/s) range. A flipped bit in a float64 reading lands far beyond them, or at NaN.
+*/
+var MAX_PLAUSIBLE_ACCELERATION_G = 64;
+var MAX_PLAUSIBLE_ANGULAR_VELOCITY_RAD_S = 100;
+/**
+* Enough leading bytes of a gyro record to tell its layout, in samples of the larger layout.
+*/
+var GYRO_LAYOUT_PROBE_SIZE = 56 * SAMPLES_TO_GUESS_FROM;
+/**
+* The sample layout of the gyro record: from the info record's flag when present, otherwise from
+* the timestamps the candidates decode in the record's first bytes (`head`). Undefined when
+* there is neither a flag nor a record to look at.
+*/
+function selectGyroSampleLayout(hints, head) {
+	const raw = new RawGyroSampleLayout(hints.ranges);
+	const float = new FloatGyroSampleLayout();
+	if (hints.isRawGyro !== void 0) return hints.isRawGyro ? raw : float;
+	if (head === void 0) return void 0;
+	const plausible = [raw, float].filter((layout) => hasPlausibleTimestamps(head, layout));
+	const [winner] = plausible;
+	if (winner && plausible.length === 1) return winner;
+	throw new GyroViewError("unsupported-gyro-record", `cannot tell the gyro sample layout from the first ${head.byteLength} bytes without the info record`);
+}
+/**
+* Decodes the gyro record payload into a {@link GyroTrack} with the given layout. Whole samples
+* only: a partial sample at the end is tolerated and reported, never rejected. So is a sample whose
+* bytes cannot be a reading (a stamp past the safe integers, a value no camera measures, a
+* component a flipped bit moved, a slot left all zero): each sample carries its own time, so the
+* others still count.
+* Stamps that stray from their neighbours are mended (see {@link repairedTimeline}).
+*/
+function parseGyroRecord(payload, layout) {
+	const count = Math.floor(payload.byteLength / layout.sampleSize);
+	const reader = new ByteReader(payload);
+	const columns = new SampleColumns(count);
+	for (let index = 0; index < count; index += 1) {
+		const sample = readableSampleAt(reader, layout, index * layout.sampleSize);
+		if (sample) columns.push(sample);
+	}
+	columns.dropFlippedBits(layout.flipSteps);
+	const timeline = repairedTimeline(columns.captureTimes());
+	return {
+		track: columns.toTrack(timeline.times),
+		layout: layout.name,
+		strayBytes: payload.byteLength % layout.sampleSize,
+		damagedSamples: count - columns.length,
+		mendedStamps: timeline.mended
+	};
+}
+function readableSampleAt(reader, layout, offset) {
+	try {
+		const captureTime = layout.timestampAt(reader, offset);
+		if (captureTime === 0 && isUnwritten(reader.bytesAt(offset, layout.sampleSize))) return void 0;
+		const sample = {
+			captureTime,
+			acceleration: layout.accelerationAt(reader, offset),
+			angularVelocity: layout.angularVelocityAt(reader, offset)
+		};
+		return isWithin(sample.acceleration, MAX_PLAUSIBLE_ACCELERATION_G) && isWithin(sample.angularVelocity, MAX_PLAUSIBLE_ANGULAR_VELOCITY_RAD_S) ? sample : void 0;
+	} catch (error) {
+		if (hasErrorCode(error, "binary-unsafe-integer")) return void 0;
+		throw error;
+	}
+}
+/**
+* A sample left all zero, as a camera leaves the first slots it never wrote: in the raw layout
+* it would read the negative full range on every axis, which no sensor measures.
+*/
+function isUnwritten(sample) {
+	return sample.every((byte) => byte === 0);
+}
+function isWithin(vector, bound) {
+	return vector.every((component) => Math.abs(component) <= bound);
+}
+/**
+* A layout fits when the stamps it decodes step by a plausible IMU interval: the median step,
+* so a few stamps left at zero or glitched at the start do not decide.
+*/
+function hasPlausibleTimestamps(payload, layout) {
+	const stamps = stampsOf(payload, layout);
+	if (stamps.length < MIN_SAMPLES_TO_GUESS_FROM) return false;
+	const median = medianStep(stamps);
+	return median >= MIN_PLAUSIBLE_INTERVAL_US && median <= MAX_PLAUSIBLE_INTERVAL_US;
+}
+/**
+* The stamps `layout` decodes from the leading samples; one that cannot be a stamp is skipped.
+*/
+function stampsOf(payload, layout) {
+	const reader = new ByteReader(payload);
+	const count = Math.floor(payload.byteLength / layout.sampleSize);
+	const stamps = [];
+	for (let index = 0; index < count; index += 1) {
+		const stamp = stampAt(reader, layout, index * layout.sampleSize);
+		if (stamp !== void 0) stamps.push(stamp);
+	}
+	return Float64Array.from(stamps);
+}
+function stampAt(reader, layout, offset) {
+	try {
+		return layout.timestampAt(reader, offset);
+	} catch (error) {
+		if (hasErrorCode(error, "binary-unsafe-integer")) return void 0;
+		throw error;
+	}
+}
+//#endregion
+export { GYRO_LAYOUT_PROBE_SIZE, parseGyroRecord, selectGyroSampleLayout };

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

@@ -0,0 +1,23 @@
+import { GyroViewError } from "../../../shared/errors/GyroViewError.js";
+import { ByteReader } from "../../../shared/binary/ByteReader.js";
+//#region ../../packages/core/src/domain/format/trailer/RecordHeader.ts
+/**
+* The 6-byte header that follows each record payload.
+*/
+var RecordHeader = class RecordHeader {
+	format;
+	id;
+	payloadSize;
+	constructor(format, id, payloadSize) {
+		this.format = format;
+		this.id = id;
+		this.payloadSize = payloadSize;
+	}
+	static parse(bytes) {
+		if (bytes.byteLength !== 6) throw new GyroViewError("invalid-trailer", `record header must be 6 bytes, got ${bytes.byteLength}`);
+		const reader = new ByteReader(bytes);
+		return new RecordHeader(reader.uint8At(0), reader.uint8At(1), reader.uint32LeAt(2));
+	}
+};
+//#endregion
+export { RecordHeader };