@bubo-squared/gyroview 0.1.0

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

@@ -0,0 +1,64 @@
+import { microsecondsToSeconds, seconds, secondsToMicroseconds } from "../../../shared/units/time.js";
+import { ZERO_VECTOR3, addVectors, magnitudeOf, scaleVector } from "../../../shared/math/Vector3.js";
+import { toBodyFrame } from "../imu/ImuFrame.js";
+//#region ../../packages/core/src/domain/motion/orientation/estimateGyroBias.ts
+/**
+* A window whose mean rate exceeds this (radians per second, about one degree per second) is
+* motion, not bias: gyro offsets are a fraction of a degree per second.
+*/
+var MAX_BIAS_RATE = .02;
+/**
+* Spacing assumed for a track too short to measure its own.
+*/
+var FALLBACK_INTERVAL = secondsToMicroseconds(seconds(1));
+/**
+* The window of `length` seconds in which the gyro reports the least motion: where the camera
+* rested, or at least moved least.
+*/
+function stillestWindow(gyro, frame, length) {
+	const interval = microsecondsToSeconds(gyro.meanSampleInterval ?? FALLBACK_INTERVAL);
+	const size = Math.max(1, Math.min(gyro.length, Math.round(length / interval)));
+	const magnitudes = Float64Array.from({ length: gyro.length }, (_unused, index) => magnitudeOf(toBodyFrame(frame, gyro.sampleAt(index).angularVelocity)));
+	let windowSum = 0;
+	for (let index = 0; index < size; index += 1) windowSum += magnitudes[index] ?? 0;
+	let best = {
+		start: 0,
+		sum: windowSum
+	};
+	for (let start = 1; start + size <= gyro.length; start += 1) {
+		windowSum += (magnitudes[start + size - 1] ?? 0) - (magnitudes[start - 1] ?? 0);
+		if (windowSum < best.sum) best = {
+			start,
+			sum: windowSum
+		};
+	}
+	return {
+		start: best.start,
+		end: best.start + size
+	};
+}
+/**
+* The mean of one vector quantity over a window of samples, in the body frame.
+*/
+function meanOverWindow({ gyro, frame }, window, quantity) {
+	let sum = ZERO_VECTOR3;
+	for (let index = window.start; index < window.end; index += 1) {
+		const measured = quantity(gyro.sampleAt(index));
+		sum = addVectors(sum, toBodyFrame(frame, measured));
+	}
+	return scaleVector(sum, 1 / Math.max(window.end - window.start, 1));
+}
+/**
+* The gyro's constant offset, taken as its mean reading over the stillest window. A camera
+* that never rests (mounted on a moving boat) gets no bias correction rather than having its
+* slowest real motion subtracted.
+*/
+function estimateGyroBias(gyro, frame, window) {
+	const mean = meanOverWindow({
+		gyro,
+		frame
+	}, window, (sample) => sample.angularVelocity);
+	return magnitudeOf(mean) <= MAX_BIAS_RATE ? mean : ZERO_VECTOR3;
+}
+//#endregion
+export { estimateGyroBias, meanOverWindow, stillestWindow };

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

@@ -0,0 +1,97 @@
+import { radians } from "../../../shared/units/angle.js";
+import { secondsToMicroseconds } from "../../../shared/units/time.js";
+import { crossProduct, dotProduct, magnitudeOf, scaleVector } from "../../../shared/math/Vector3.js";
+import { meanOverWindow } from "./estimateGyroBias.js";
+import { IDENTITY_QUATERNION, conjugateQuaternion, quaternionFromAxisAngle, rotateVector } from "../../../shared/math/Quaternion.js";
+//#region ../../packages/core/src/domain/motion/orientation/gravity.ts
+/**
+* Gravity points down; the world frame's y axis is down, like the body frame's at rest.
+*/
+var WORLD_DOWN = [
+	0,
+	1,
+	0
+];
+/**
+* Accelerometer magnitudes outside this band (in g) mean the camera is accelerating, so the
+* reading does not tell where down is.
+*/
+var MIN_RESTING_G = .9;
+var MAX_RESTING_G = 1.1;
+/**
+* Where gravity points in the body frame according to one accelerometer sample, or undefined
+* while the camera accelerates. The accelerometer measures the reaction to gravity, hence the
+* sign flip.
+*/
+function measuredGravity(accelerationInBody) {
+	const magnitude = magnitudeOf(accelerationInBody);
+	return magnitude >= MIN_RESTING_G && magnitude <= MAX_RESTING_G ? scaleVector(accelerationInBody, -1 / magnitude) : void 0;
+}
+/**
+* Mahony's error term: the rotation, in the body frame, that would swing the estimated gravity
+* onto the measured one. Zero while the camera accelerates.
+*/
+function gravityCorrection(orientation, accelerationInBody) {
+	const measured = measuredGravity(accelerationInBody);
+	if (!measured) return [
+		0,
+		0,
+		0
+	];
+	const estimated = rotateVector(conjugateQuaternion(orientation), WORLD_DOWN);
+	return crossProduct(measured, estimated);
+}
+/**
+* The samples within the first `length` seconds of the track, at least the first one.
+*/
+function openingWindow(gyro, length) {
+	if (gyro.isEmpty) return {
+		start: 0,
+		end: 0
+	};
+	const first = gyro.sampleAt(0).captureTime;
+	const span = secondsToMicroseconds(length);
+	let end = 1;
+	while (end < gyro.length && gyro.sampleAt(end).captureTime - first <= span) end += 1;
+	return {
+		start: 0,
+		end
+	};
+}
+/**
+* The pose at the start: the gravity measured over the opening window turned onto world down,
+* with no yaw, so the world's forward is the body's forward at the start. Identity when the
+* camera accelerates in that window; the gravity pull levels the estimate over the next seconds.
+*/
+function initialOrientation(gyro, frame, window) {
+	if (gyro.isEmpty) return IDENTITY_QUATERNION;
+	const opening = openingWindow(gyro, window);
+	const gravity = measuredGravity(meanOverWindow({
+		gyro,
+		frame
+	}, opening, (sample) => sample.acceleration));
+	return gravity ? rotationBetween(gravity, WORLD_DOWN) : IDENTITY_QUATERNION;
+}
+/**
+* The shortest rotation taking unit vector `from` onto unit vector `to`.
+*/
+function rotationBetween(from, to) {
+	const axis = crossProduct(from, to);
+	const dot = dotProduct(from, to);
+	const sine = magnitudeOf(axis);
+	if (sine > 0) return quaternionFromAxisAngle(axis, radians(Math.atan2(sine, dot)));
+	return dot > 0 ? IDENTITY_QUATERNION : quaternionFromAxisAngle(anyPerpendicular(from), radians(Math.PI));
+}
+function anyPerpendicular(v) {
+	return Math.abs(v[0]) < Math.abs(v[2]) ? [
+		0,
+		-v[2],
+		v[1]
+	] : [
+		-v[1],
+		v[0],
+		0
+	];
+}
+//#endregion
+export { WORLD_DOWN, gravityCorrection, initialOrientation };

package/dist/packages/core/src/domain/motion/stabilization/Stabilizer.js

@@ -0,0 +1,13 @@
+//#region ../../packages/core/src/domain/motion/stabilization/Stabilizer.ts
+var STABILIZATION_MODES = [
+	"off",
+	"lock",
+	"horizon",
+	"follow"
+];
+/**
+* The world stays put: the most useful default for a camera carried around.
+*/
+var DEFAULT_STABILIZATION_MODE = "lock";
+//#endregion
+export { DEFAULT_STABILIZATION_MODE, STABILIZATION_MODES };

package/dist/packages/core/src/domain/motion/stabilization/stabilizers.js

@@ -0,0 +1,86 @@
+import { radians } from "../../../shared/units/angle.js";
+import { seconds } from "../../../shared/units/time.js";
+import { IDENTITY_MATRIX3, multiplyMatrices } from "../../../shared/math/Matrix3.js";
+import { conjugateQuaternion, quaternionFromAxisAngle, quaternionToMatrix, slerpQuaternions } from "../../../shared/math/Quaternion.js";
+import { WORLD_DOWN } from "../orientation/gravity.js";
+//#region ../../packages/core/src/domain/motion/stabilization/stabilizers.ts
+/**
+* The picture moves with the camera, as recorded.
+*/
+var OffStabilization = class {
+	nextRotation() {
+		return IDENTITY_MATRIX3;
+	}
+};
+/**
+* The view is fixed to the world: camera motion disappears entirely.
+*/
+var LockStabilization = class {
+	nextRotation(orientation) {
+		return quaternionToMatrix(conjugateQuaternion(orientation));
+	}
+};
+/**
+* The horizon stays level but the view turns with the camera's heading.
+*/
+var HorizonStabilization = class {
+	nextRotation(orientation) {
+		const heading = quaternionFromAxisAngle(WORLD_DOWN, headingOf(orientation));
+		return multiplyMatrices(quaternionToMatrix(conjugateQuaternion(orientation)), quaternionToMatrix(heading));
+	}
+};
+var DEFAULT_FOLLOW_OPTIONS = {
+	timeConstant: seconds(1.5),
+	maxContinuousGap: seconds(1)
+};
+/**
+* The view follows the camera's direction smoothly, removing shake but not intended motion.
+*/
+var FollowStabilization = class {
+	options;
+	smoothed;
+	previousTime;
+	constructor(options = DEFAULT_FOLLOW_OPTIONS) {
+		this.options = options;
+	}
+	nextRotation(orientation, videoTime) {
+		this.smoothed = this.follow(orientation, videoTime);
+		this.previousTime = videoTime;
+		return multiplyMatrices(quaternionToMatrix(conjugateQuaternion(orientation)), quaternionToMatrix(this.smoothed));
+	}
+	/**
+	* A seek (a jump either way beyond the continuous gap) restarts on the camera; a small step
+	* back (frame jitter) holds; ordinary forward time low-passes towards the camera.
+	*/
+	follow(orientation, videoTime) {
+		const gap = this.previousTime === void 0 ? Infinity : videoTime - this.previousTime;
+		if (!this.smoothed || Math.abs(gap) > this.options.maxContinuousGap) return orientation;
+		if (gap <= 0) return this.smoothed;
+		const weight = 1 - Math.exp(-gap / this.options.timeConstant);
+		return slerpQuaternions(this.smoothed, orientation, weight);
+	}
+};
+var STABILIZERS = {
+	off: () => new OffStabilization(),
+	lock: () => new LockStabilization(),
+	horizon: () => new HorizonStabilization(),
+	follow: () => new FollowStabilization()
+};
+/**
+* A fresh strategy for the mode; stateful ones start from nothing.
+*/
+function stabilizerFor(mode) {
+	return STABILIZERS[mode]();
+}
+/**
+* The camera's heading: the twist of its orientation about the world's vertical axis (the
+* swing-twist decomposition). Unlike the yaw of the forward axis, it stays continuous when the
+* camera points straight up or down; it is undefined only for an exact half turn about a
+* horizontal axis, where it reads zero.
+*/
+function headingOf(orientation) {
+	const [, y, , w] = orientation;
+	return radians(2 * Math.atan2(y, w));
+}
+//#endregion
+export { FollowStabilization, HorizonStabilization, LockStabilization, OffStabilization, stabilizerFor };

package/dist/packages/core/src/domain/motion/timing/CaptureClock.js

@@ -0,0 +1,41 @@
+import { microseconds, microsecondsToSeconds, milliseconds, millisecondsToSeconds, seconds, secondsToMicroseconds } from "../../../shared/units/time.js";
+//#region ../../packages/core/src/domain/motion/timing/CaptureClock.ts
+/**
+* Relates the camera's capture clock (microseconds, shared by gyro samples and exposure entries)
+* to video time (seconds on the video track, where the first encoded frame shows at
+* `firstFrameVideoTime`). Gyro samples are stamped a little later than the frames they belong
+* to; that gyro offset is subtracted for them.
+*/
+var CaptureClock = class CaptureClock {
+	firstFrameCaptureTime;
+	gyroOffset;
+	firstFrameVideoTime;
+	constructor(firstFrameCaptureTime, gyroOffset = milliseconds(0), firstFrameVideoTime = seconds(0)) {
+		this.firstFrameCaptureTime = firstFrameCaptureTime;
+		this.gyroOffset = gyroOffset;
+		this.firstFrameVideoTime = firstFrameVideoTime;
+	}
+	/**
+	* The same clock for a track whose first frame shows at `videoTime`, so frame times and the
+	* orientation share the time base of the frames the decoder delivers.
+	*/
+	withFirstFrameAt(videoTime) {
+		return new CaptureClock(this.firstFrameCaptureTime, this.gyroOffset, videoTime);
+	}
+	videoTimeOf(captureTime) {
+		const sinceFirstFrame = microseconds(captureTime - this.firstFrameCaptureTime);
+		return seconds(this.firstFrameVideoTime + microsecondsToSeconds(sinceFirstFrame));
+	}
+	gyroVideoTimeOf(captureTime) {
+		return seconds(this.videoTimeOf(captureTime) - millisecondsToSeconds(this.gyroOffset));
+	}
+	/**
+	* Inverse of {@link videoTimeOf}, rounded to whole microseconds like the camera's clock.
+	*/
+	captureTimeOf(videoTime) {
+		const sinceFirstFrame = secondsToMicroseconds(seconds(videoTime - this.firstFrameVideoTime));
+		return microseconds(Math.round(this.firstFrameCaptureTime + sinceFirstFrame));
+	}
+};
+//#endregion
+export { CaptureClock };

package/dist/packages/core/src/domain/motion/timing/FrameTimes.js

@@ -0,0 +1,92 @@
+import { ensureIndexInRange, ensureInvariant } from "../../../shared/errors/GyroViewError.js";
+import { microseconds, seconds } from "../../../shared/units/time.js";
+import { clamp } from "../../../shared/math/clamp.js";
+//#region ../../packages/core/src/domain/motion/timing/FrameTimes.ts
+/**
+* A presentation time this small a part of a frame before its frame's still finds that frame:
+* decoders round timestamps to whole microseconds, a sixty-thousandth of a frame at 60 fps.
+*/
+var GRID_TOLERANCE_FRAMES = .01;
+/**
+* Capture timing of every encoded frame, in frame order.
+*/
+var FrameTimes = class FrameTimes {
+	readoutTime;
+	clock;
+	captureTimes;
+	shutterTimes;
+	frameDuration;
+	constructor(parts) {
+		ensureInvariant(parts.shutterTimes === void 0 || parts.shutterTimes.length === parts.captureTimes.length, "frame time arrays disagree on the frame count");
+		this.clock = parts.clock;
+		this.captureTimes = parts.captureTimes;
+		this.shutterTimes = parts.shutterTimes;
+		this.readoutTime = parts.readoutTime ?? seconds(0);
+		this.frameDuration = parts.frameDuration;
+	}
+	/**
+	* Frame times from a source that knows when frames were captured but not for how long.
+	*/
+	static withoutShutterTimes(parts) {
+		return new FrameTimes({
+			...parts,
+			shutterTimes: void 0
+		});
+	}
+	get frameCount() {
+		return this.captureTimes.length;
+	}
+	frameAt(index) {
+		ensureIndexInRange(index, this.frameCount, "frame");
+		const captureTime = microseconds(this.captureTimes[index] ?? 0);
+		const shutter = this.shutterTimes?.[index];
+		const shutterTime = shutter === void 0 ? void 0 : seconds(shutter);
+		const videoTime = this.clock.videoTimeOf(captureTime);
+		return {
+			index,
+			captureTime,
+			videoTime,
+			shutterTime,
+			midExposureVideoTime: seconds(videoTime + (shutterTime ?? 0) / 2 + this.readoutTime / 2)
+		};
+	}
+	/**
+	* When to sample the orientation for the frame shown at `videoTime`; undefined when there are
+	* no frames.
+	*/
+	midExposureAt(videoTime) {
+		const index = this.frameIndexAt(videoTime);
+		return index === void 0 ? void 0 : this.frameAt(index).midExposureVideoTime;
+	}
+	/**
+	* Index of the frame the track presents at `videoTime`, clamped to the first and last frame;
+	* undefined when there are no frames. Found by its place on the track's frame grid, which
+	* neither the camera clock's drift against the track nor timestamps rounded to microseconds
+	* move; by capture time only when the track gives no frame spacing.
+	*/
+	frameIndexAt(videoTime) {
+		if (this.frameCount === 0) return void 0;
+		const index = this.frameDuration === void 0 ? this.lastCapturedAt(videoTime) : this.onFrameGrid(videoTime, this.frameDuration);
+		return clamp(index, 0, this.frameCount - 1);
+	}
+	onFrameGrid(videoTime, frameDuration) {
+		const framesIn = (videoTime - this.clock.firstFrameVideoTime) / frameDuration;
+		return Math.floor(framesIn + GRID_TOLERANCE_FRAMES);
+	}
+	/**
+	* The last frame captured at or before `videoTime`.
+	*/
+	lastCapturedAt(videoTime) {
+		const target = this.clock.captureTimeOf(videoTime);
+		let low = 0;
+		let high = this.frameCount - 1;
+		while (low < high) {
+			const middle = Math.ceil((low + high) / 2);
+			if ((this.captureTimes[middle] ?? Infinity) <= target) low = middle;
+			else high = middle - 1;
+		}
+		return low;
+	}
+};
+//#endregion
+export { FrameTimes };

package/dist/packages/core/src/domain/motion/timing/frameTimeSources.js

@@ -0,0 +1,61 @@
+import { seconds } from "../../../shared/units/time.js";
+import { FrameTimes } from "./FrameTimes.js";
+//#region ../../packages/core/src/domain/motion/timing/frameTimeSources.ts
+/**
+* Preferred source: the exposure record holds one entry per captured frame; entries before the
+* first encoded frame are pre-roll and are skipped.
+*/
+function fromExposureRecord(context) {
+	const { exposureRecord, clock, frameCount } = context;
+	if (!exposureRecord) return void 0;
+	const start = exposureRecord.indexAtOrAfter(clock.firstFrameCaptureTime);
+	if (exposureRecord.length - start < frameCount) return void 0;
+	const frames = exposureRecord.slice(start, frameCount);
+	return new FrameTimes({
+		clock,
+		captureTimes: Float64Array.from(frames.captureTimes),
+		shutterTimes: Float64Array.from(frames.shutterTimes),
+		readoutTime: context.readoutTime,
+		frameDuration: context.frameDuration
+	});
+}
+/**
+* The video track's own presentation timestamps, which the clock relates to capture time from
+* where the track's first frame shows.
+*/
+function fromTrackTimestamps(context) {
+	const { trackTimestamps, clock, frameCount } = context;
+	if (!trackTimestamps || trackTimestamps.length < frameCount) return void 0;
+	const captureTimes = Float64Array.from(trackTimestamps.slice(0, frameCount), (timestamp) => clock.captureTimeOf(timestamp));
+	return FrameTimes.withoutShutterTimes({
+		clock,
+		captureTimes,
+		readoutTime: context.readoutTime,
+		frameDuration: context.frameDuration
+	});
+}
+/**
+* Last resort: frames spaced evenly at the nominal frame rate from the first frame's capture
+* time. Exact enough for playback, too coarse for tight stabilization sync.
+*/
+function fromNominalRate(context) {
+	const { frameRate, clock, frameCount } = context;
+	if (frameRate === void 0 || frameRate <= 0) return void 0;
+	const captureTimes = Float64Array.from({ length: frameCount }, (_unused, index) => clock.captureTimeOf(seconds(clock.firstFrameVideoTime + index / frameRate)));
+	return FrameTimes.withoutShutterTimes({
+		clock,
+		captureTimes,
+		readoutTime: context.readoutTime,
+		frameDuration: context.frameDuration
+	});
+}
+/**
+* Each source by its name; a record, so a new name cannot be left without its source.
+*/
+var FRAME_TIME_SOURCES = {
+	"exposure-record": fromExposureRecord,
+	"track-timestamps": fromTrackTimestamps,
+	nominal: fromNominalRate
+};
+//#endregion
+export { FRAME_TIME_SOURCES };

package/dist/packages/core/src/domain/motion/timing/resolveFrameTimes.js

@@ -0,0 +1,68 @@
+import { FRAME_TIME_SOURCES } from "./frameTimeSources.js";
+//#region ../../packages/core/src/domain/motion/timing/resolveFrameTimes.ts
+var EXPOSURE_FIRST = [
+	"exposure-record",
+	"track-timestamps",
+	"nominal"
+];
+var TRACK_TIMESTAMPS_FIRST = [
+	"track-timestamps",
+	"exposure-record",
+	"nominal"
+];
+/**
+* Tries the frame time sources in the order the camera suggests, falling back gracefully and
+* saying which source won. Undefined when none can say (not even a nominal frame rate):
+* frame times are optional, the picture still plays at the track's pace.
+*/
+function resolveFrameTimes(context, preferred) {
+	const warnings = [];
+	for (const source of orderFor(preferred)) {
+		const frameTimes = FRAME_TIME_SOURCES[source](context);
+		if (frameTimes) return {
+			frameTimes,
+			source,
+			warnings
+		};
+		warnings.push(`${source} unavailable`);
+	}
+}
+/**
+* Resolves what it can without the track's timestamps, which are costly to read, and asks for
+* them when the answer depends on them: their source comes, in the camera's order, before any
+* source that answers without them.
+*/
+function planFrameTimes(context, preferred) {
+	const warnings = [];
+	for (const source of orderFor(preferred)) {
+		if (source === "track-timestamps") return {
+			needsTrackTimestamps: true,
+			resolveWith: (trackTimestamps) => resolveFrameTimes({
+				...context,
+				trackTimestamps
+			}, preferred)
+		};
+		const frameTimes = FRAME_TIME_SOURCES[source]({
+			...context,
+			trackTimestamps: void 0
+		});
+		if (frameTimes) return {
+			needsTrackTimestamps: false,
+			resolved: {
+				frameTimes,
+				source,
+				warnings
+			}
+		};
+		warnings.push(`${source} unavailable`);
+	}
+	return {
+		needsTrackTimestamps: false,
+		resolved: void 0
+	};
+}
+function orderFor(preferred) {
+	return preferred === "track-timestamps" ? TRACK_TIMESTAMPS_FIRST : EXPOSURE_FIRST;
+}
+//#endregion
+export { planFrameTimes, resolveFrameTimes };

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

@@ -0,0 +1,39 @@
+import { pixelAtRadius, toPolar } from "./lensGeometry.js";
+import { HALF_FIELD_OF_VIEW } from "./opticsConstants.js";
+//#region ../../packages/core/src/domain/optics/EquidistantModel.ts
+/**
+* Ideal equidistant fisheye (`r = f * theta`) implied by the legacy `offset` string, which stores
+* only a radius and the centre per lens. The reading Insta360's own stitch agrees with on the
+* far field (ADR 0023), so the default; directions past the field edge are refused.
+*/
+var EquidistantModel = class {
+	parameters;
+	kind = "equidistant";
+	halfFieldOfView = HALF_FIELD_OF_VIEW;
+	principalPoint;
+	constructor(parameters) {
+		this.parameters = parameters;
+		this.principalPoint = parameters.principalPoint;
+	}
+	get projection() {
+		return {
+			kind: "radial-polynomial",
+			principalPoint: this.principalPoint,
+			coefficients: [
+				this.pixelsPerRadian,
+				0,
+				0,
+				0
+			]
+		};
+	}
+	project(direction) {
+		const { theta, radialUnit } = toPolar(direction);
+		return theta > this.halfFieldOfView ? void 0 : pixelAtRadius(this.principalPoint, this.pixelsPerRadian * theta, radialUnit);
+	}
+	get pixelsPerRadian() {
+		return this.parameters.edgeRadius / this.parameters.radiusAngle;
+	}
+};
+//#endregion
+export { EquidistantModel };

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

@@ -0,0 +1,45 @@
+import { HALF_FIELD_OF_VIEW } from "./opticsConstants.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.
+*/
+var MeiModel = class {
+	parameters;
+	kind = "mei";
+	halfFieldOfView = HALF_FIELD_OF_VIEW;
+	principalPoint;
+	constructor(parameters) {
+		this.parameters = parameters;
+		this.principalPoint = parameters.principalPoint;
+	}
+	get projection() {
+		return {
+			kind: "mei",
+			...this.parameters
+		};
+	}
+	project(direction) {
+		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);
+		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/PolynomialModel.js

@@ -0,0 +1,44 @@
+import { pixelAtRadius, toPolar } from "./lensGeometry.js";
+import { HALF_FIELD_OF_VIEW } from "./opticsConstants.js";
+//#region ../../packages/core/src/domain/optics/PolynomialModel.ts
+/**
+* Polynomial fisheye model of `offset_v2`. Insta360 does not document the normalisation; on the
+* X5 lenses, evaluating the polynomial in radians and scaling it so that the field edge maps to
+* `edgeRadius` reproduces the MEI model within 9 px, so that is the working interpretation until
+* a recording that carries only `offset_v2` can confirm it.
+*/
+var PolynomialModel = class {
+	parameters;
+	kind = "polynomial";
+	halfFieldOfView = HALF_FIELD_OF_VIEW;
+	principalPoint;
+	scale;
+	constructor(parameters) {
+		this.parameters = parameters;
+		this.principalPoint = parameters.principalPoint;
+		this.scale = parameters.edgeRadius / this.polynomial(this.halfFieldOfView);
+	}
+	get projection() {
+		const [c1, c2, c3, c4] = this.parameters.coefficients;
+		return {
+			kind: "radial-polynomial",
+			principalPoint: this.principalPoint,
+			coefficients: [
+				c1 * this.scale,
+				c2 * this.scale,
+				c3 * this.scale,
+				c4 * this.scale
+			]
+		};
+	}
+	project(direction) {
+		const { theta, radialUnit } = toPolar(direction);
+		return theta > this.halfFieldOfView ? void 0 : pixelAtRadius(this.principalPoint, this.scale * this.polynomial(theta), radialUnit);
+	}
+	polynomial(theta) {
+		const [c1, c2, c3, c4] = this.parameters.coefficients;
+		return theta * (c1 + theta * (c2 + theta * (c3 + theta * c4)));
+	}
+};
+//#endregion
+export { PolynomialModel };