@bvdmitri/gyroview 0.9.0-cutaway.3 → 0.9.0-cutaway.4

package/CHANGELOG.md

@@ -23,6 +23,13 @@ Added (ADR 0046, each row is turned for the time its sensor read it):
   longer skews the top and bottom of the picture against its middle. Other cameras turn whole
   until their sensors' row order is measured.
 
+Added (ADR 0047, the smooth mode keeps the horizon level and looks ahead for its heading):
+
+- A fifth stabilization mode, `smooth` (`stabilization="smooth"`, `setStabilization('smooth')`,
+  the Stabilization menu): the horizon level as in `horizon`, the view facing the camera's heading
+  smoothed over a second either way in the recording, so turns are followed without lag and the
+  heading's shake is gone. `STABILIZATION_MODES` lists it between `horizon` and `follow`.
+
 Fixed:
 
 - A clip trimmed in the Insta360 app is stabilized with the gyro of its own frames. The app keeps

package/dist/index.d.ts

@@ -300,6 +300,7 @@ export declare const STABILIZATION_MODES: readonly [
 	"off",
 	"lock",
 	"horizon",
+	"smooth",
 	"follow"
 ];
 export type StabilizationMode = (typeof STABILIZATION_MODES)[number];
@@ -1106,7 +1107,7 @@ export declare class GyroViewElement extends TypedEventElement implements LiveSe
 	 */
 	stopMotionLook(): void;
 	/**
-	 * Stabilizes the picture in `mode` (`off`, `lock`, `horizon`, `follow`); any other value,
+	 * Stabilizes the picture in `mode` (`off`, `lock`, `horizon`, `smooth`, `follow`); any other value,
 	 * an unset one included, is refused.
 	 */
 	setStabilization(mode: StabilizationMode): void;

package/dist/packages/core/src/application/stabilization/StabilizingFrameSink.js

@@ -1,6 +1,6 @@
 import { rotationIntoBody } from "../../domain/motion/mounting/Mounting.js";
 import { rowCorrectionsAt } from "../../domain/motion/rollingShutter/RollingShutter.js";
-import { OffStabilization } from "../../domain/motion/stabilization/stabilizers.js";
+import { OffStabilization, stabilizerFor } from "../../domain/motion/stabilization/stabilizers.js";
 //#region ../../packages/core/src/application/stabilization/StabilizingFrameSink.ts
 /**
 * Use case: before every presentation, looks up the camera's orientation at the frame's
@@ -16,6 +16,13 @@ var StabilizingFrameSink = class {
 	setStabilizer(stabilizer) {
 		this.stabilizer = stabilizer;
 	}
+	/**
+	* Stabilizes in `mode`, its strategy built over the recording's orientations, which the smooth
+	* mode looks ahead in.
+	*/
+	setStabilizationMode(mode) {
+		this.stabilizer = stabilizerFor(mode, this.parts.motion.orientations);
+	}
 	present(presentation) {
 		const time = this.exposureTimeOf(presentation);
 		const { orientations, mounting } = this.parts.motion;

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

@@ -72,6 +72,15 @@ var OrientationTrack = class OrientationTrack {
 		return this.videoTimes.length;
 	}
 	/**
+	* The video times of the first and the last sample; undefined for an empty track.
+	*/
+	get span() {
+		return this.length === 0 ? void 0 : {
+			start: seconds(this.videoTimes[0] ?? 0),
+			end: seconds(this.videoTimes[this.length - 1] ?? 0)
+		};
+	}
+	/**
 	* The orientation at a video time, interpolated between samples and held at the ends.
 	*/
 	orientationAt(videoTime) {

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

@@ -0,0 +1,109 @@
+import { radians } from "../../../shared/units/angle.js";
+import { seconds } from "../../../shared/units/time.js";
+import { rotateVector } from "../../../shared/math/Quaternion.js";
+//#region ../../packages/core/src/domain/motion/stabilization/SmoothedHeading.ts
+/**
+* The step of the grid the heading is smoothed on: far finer than any turn the smoothing keeps.
+*/
+var GRID_STEP_SECONDS = .01;
+/**
+* The Gaussian's reach, in standard deviations: what lies further weighs under one percent of
+* one percent.
+*/
+var KERNEL_REACH = 3;
+/**
+* The camera's heading over a whole recording, smoothed both ways in time, so a steady turn is
+* followed without lag and a quick shake is averaged away.
+*
+* @remarks
+* The heading is the twist about the vertical horizon reads, `atan2(m13 - m31, m11 + m33)` of
+* the orientation's matrix, but averaged as that vector rather than as an angle. The vector's
+* length is how well the heading is defined: twice the cosine of half the camera's tilt from
+* upright, nothing where it has turned half over about a horizontal axis. Averaged as vectors,
+* the moments a skydiver's camera tumbles through that count for little, where an angle would
+* swing through a half turn at random and, unwrapped, leave a whole turn too many. Near the ends
+* the Gaussian is cut off and its weights taken in proportion.
+*/
+var SmoothedHeading = class SmoothedHeading {
+	start;
+	sines;
+	cosines;
+	constructor(start, sines, cosines) {
+		this.start = start;
+		this.sines = sines;
+		this.cosines = cosines;
+	}
+	/**
+	* Smooths the heading of the track's orientations with a Gaussian of standard deviation
+	* `spread`; undefined for an empty track.
+	*/
+	static of(track, spread) {
+		const span = track.span;
+		if (!span) return void 0;
+		const count = Math.max(1, Math.floor((span.end - span.start) / GRID_STEP_SECONDS) + 1);
+		const sines = new Float64Array(count);
+		const cosines = new Float64Array(count);
+		for (let index = 0; index < count; index += 1) {
+			const [sine, cosine] = headingVectorOf(track.orientationAt(seconds(span.start + index * GRID_STEP_SECONDS)));
+			sines[index] = sine;
+			cosines[index] = cosine;
+		}
+		const samples = spread / GRID_STEP_SECONDS;
+		return new SmoothedHeading(span.start, gaussianOf(sines, samples), gaussianOf(cosines, samples));
+	}
+	/**
+	* The smoothed heading at a video time, interpolated on the grid and held at its ends.
+	*/
+	at(time) {
+		const position = (time - this.start) / GRID_STEP_SECONDS;
+		const last = this.sines.length - 1;
+		const below = Math.min(Math.max(Math.floor(position), 0), last);
+		const above = Math.min(below + 1, last);
+		const fraction = Math.min(Math.max(position - below, 0), 1);
+		const between = (values) => {
+			const low = values[below] ?? 0;
+			return low + ((values[above] ?? low) - low) * fraction;
+		};
+		return radians(Math.atan2(between(this.sines), between(this.cosines)));
+	}
+};
+/**
+* The twist about the vertical as a vector, its length how well the twist is defined.
+*/
+function headingVectorOf(orientation) {
+	const [xx, , xz] = rotateVector(orientation, [
+		1,
+		0,
+		0
+	]);
+	const [zx, , zz] = rotateVector(orientation, [
+		0,
+		0,
+		1
+	]);
+	return [zx - xz, xx + zz];
+}
+/**
+* The values smoothed by a Gaussian of `spread` samples, cut off at its reach and renormalized
+* where the ends cut it shorter.
+*/
+function gaussianOf(values, spread) {
+	const reach = Math.ceil(spread * KERNEL_REACH);
+	const weights = Float64Array.from({ length: reach + 1 }, (_, offset) => Math.exp(-(offset * offset) / (2 * spread * spread)));
+	const smoothed = new Float64Array(values.length);
+	for (let index = 0; index < values.length; index += 1) {
+		let sum = 0;
+		let weightSum = 0;
+		const from = Math.max(0, index - reach);
+		const to = Math.min(values.length - 1, index + reach);
+		for (let other = from; other <= to; other += 1) {
+			const weight = weights[Math.abs(other - index)] ?? 0;
+			sum += weight * (values[other] ?? 0);
+			weightSum += weight;
+		}
+		smoothed[index] = sum / weightSum;
+	}
+	return smoothed;
+}
+//#endregion
+export { SmoothedHeading };

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

@@ -3,6 +3,7 @@ var STABILIZATION_MODES = [
 	"off",
 	"lock",
 	"horizon",
+	"smooth",
 	"follow"
 ];
 /**

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

@@ -3,6 +3,7 @@ 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";
+import { SmoothedHeading } from "./SmoothedHeading.js";
 //#region ../../packages/core/src/domain/motion/stabilization/stabilizers.ts
 /**
 * The picture moves with the camera, as recorded.
@@ -29,6 +30,26 @@ var HorizonStabilization = class {
 		return multiplyMatrices(quaternionToMatrix(conjugateQuaternion(orientation)), quaternionToMatrix(heading));
 	}
 };
+/**
+* How far either way in time the smooth mode's heading is averaged: the standard deviation of its
+* Gaussian. A head's shake, a few hertz, is gone; a turn of a few seconds is kept.
+*/
+var SMOOTH_HEADING_SPREAD_SECONDS = 1;
+/**
+* The horizon stays level and the view faces the camera's heading smoothed both ways in time
+* over the whole recording: turns are followed without lag, shake in the heading is gone.
+* Stateless: the smoothing is done once, when the strategy is built.
+*/
+var SmoothStabilization = class {
+	heading;
+	constructor(heading) {
+		this.heading = heading;
+	}
+	nextRotation(orientation, videoTime) {
+		const facing = quaternionFromAxisAngle(WORLD_DOWN, this.heading.at(videoTime));
+		return multiplyMatrices(quaternionToMatrix(conjugateQuaternion(orientation)), quaternionToMatrix(facing));
+	}
+};
 var DEFAULT_FOLLOW_OPTIONS = {
 	timeConstant: seconds(1.5),
 	maxContinuousGap: seconds(1)
@@ -64,13 +85,18 @@ var STABILIZERS = {
 	off: () => new OffStabilization(),
 	lock: () => new LockStabilization(),
 	horizon: () => new HorizonStabilization(),
+	smooth: (orientations) => {
+		const heading = orientations && SmoothedHeading.of(orientations, seconds(SMOOTH_HEADING_SPREAD_SECONDS));
+		return heading ? new SmoothStabilization(heading) : new HorizonStabilization();
+	},
 	follow: () => new FollowStabilization()
 };
 /**
-* A fresh strategy for the mode; stateful ones start from nothing.
+* A fresh strategy for the mode; stateful ones start from nothing. The smooth mode looks ahead in
+* the recording's `orientations`; without them it is horizon.
 */
-function stabilizerFor(mode) {
-	return STABILIZERS[mode]();
+function stabilizerFor(mode, orientations) {
+	return STABILIZERS[mode](orientations);
 }
 /**
 * The camera's heading: the twist of its orientation about the world's vertical axis (the
@@ -83,4 +109,4 @@ function headingOf(orientation) {
 	return radians(2 * Math.atan2(y, w));
 }
 //#endregion
-export { FollowStabilization, HorizonStabilization, LockStabilization, OffStabilization, stabilizerFor };
+export { FollowStabilization, HorizonStabilization, LockStabilization, OffStabilization, SmoothStabilization, stabilizerFor };

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

@@ -1,7 +1,6 @@
 import { messageOf } from "../../../core/src/shared/errors/GyroViewError.js";
 import { milliseconds, seconds } from "../../../core/src/shared/units/time.js";
 import { UPRIGHT_MOUNTING } from "../../../core/src/domain/motion/mounting/Mounting.js";
-import { stabilizerFor } from "../../../core/src/domain/motion/stabilization/stabilizers.js";
 import { buildStitchingSetup } from "../../../core/src/domain/stitching/StitchingSetup.js";
 import { StabilizingFrameSink } from "../../../core/src/application/stabilization/StabilizingFrameSink.js";
 import { GainMatchingFrameSink } from "../../../core/src/application/gainMatching/GainMatchingFrameSink.js";
@@ -87,7 +86,7 @@ function drawingFor(parts, disposables) {
 function pictureSettingsOf(drawing, session) {
 	return {
 		setStabilization: (mode) => {
-			drawing.stabilizing?.setStabilizer(stabilizerFor(mode));
+			drawing.stabilizing?.setStabilizationMode(mode);
 			session.redraw();
 		},
 		setQuality: (quality) => {

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

@@ -2,7 +2,6 @@ import { ensureInvariant, messageOf } from "../../../core/src/shared/errors/Gyro
 import { seconds } from "../../../core/src/shared/units/time.js";
 import { UPRIGHT_MOUNTING } from "../../../core/src/domain/motion/mounting/Mounting.js";
 import "../../../core/src/domain/motion/stabilization/Stabilizer.js";
-import { stabilizerFor } from "../../../core/src/domain/motion/stabilization/stabilizers.js";
 import "../../../core/src/domain/view/PictureQuality.js";
 import { RenditionSpan, renditionSizeOf } from "../../../core/src/domain/rendition/RenditionSpan.js";
 import { GainMatchingFrameSink } from "../../../core/src/application/gainMatching/GainMatchingFrameSink.js";
@@ -92,7 +91,7 @@ var RenditionRun = class {
 	sinksOver(request) {
 		const { opened } = this.parts;
 		const { sink, stabilizing } = sinkOver(this.renderer, opened);
-		stabilizing?.setStabilizer(stabilizerFor(request.stabilization ?? "lock"));
+		stabilizing?.setStabilizationMode(request.stabilization ?? "lock");
 		const mounting = opened.motion?.mounting ?? UPRIGHT_MOUNTING;
 		const lenses = stitchingSetupOf(opened).lenses;
 		const matching = new GainMatchingFrameSink(sink, this.renderer, referenceLensOf(lenses, mounting));

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

@@ -39,6 +39,7 @@ var STABILIZATION_ICONS = {
 	off: fromTwentyUnitGrid("<path d=\"M2 11l2.5-3 3 4.5 3-6 3 5 2-2.5L18 11\"/>"),
 	lock: fromTwentyUnitGrid("<rect x=\"4.5\" y=\"9\" width=\"11\" height=\"8\" rx=\"1.5\"/><path d=\"M7 9V6.5a3 3 0 016 0V9\"/>"),
 	horizon: fromTwentyUnitGrid("<circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M3 10h14M8 13h4\"/>"),
+	smooth: fromTwentyUnitGrid("<circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M3 10h14\"/><path d=\"M6 13.5c1.5-1 2.5-1 4 0s2.5 1 4 0\"/>"),
 	follow: fromTwentyUnitGrid("<path d=\"M3 15c3.5 0 4-9 8.5-9 2 0 3 1 4.5 1\"/><path d=\"M14 4.5L16.5 7 14 9.5\"/>")
 };
 /**

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

@@ -33,12 +33,14 @@ var DEFAULT_MESSAGES = frozenMessages({
 		off: "Off",
 		lock: "Lock",
 		horizon: "Horizon",
+		smooth: "Smooth",
 		follow: "Follow"
 	},
 	stabilizationModeDescriptions: {
 		off: "Footage as the camera moved",
 		lock: "Orientation fixed to the world",
 		horizon: "Level horizon, follows heading",
+		smooth: "Level horizon, heading smoothed",
 		follow: "Follows turns, smooths out shake"
 	},
 	viewModes: {

package/dist/packages/player/src/element/GyroViewElement.js

@@ -239,7 +239,7 @@ var GyroViewElement = class extends TypedEventElement {
 		this.player.stopMotionLook();
 	}
 	/**
-	* Stabilizes the picture in `mode` (`off`, `lock`, `horizon`, `follow`); any other value,
+	* Stabilizes the picture in `mode` (`off`, `lock`, `horizon`, `smooth`, `follow`); any other value,
 	* an unset one included, is refused.
 	*/
 	setStabilization(mode) {