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

package/CHANGELOG.md

@@ -16,6 +16,13 @@ Added (ADR 0045, a recording is rendered frame by frame at the pace its consumer
   a multiple of four, or a span that holds no frame, is refused with `invalid-argument`. Its types,
   `Rendition` and `RenditionOptions`, are exported.
 
+Added (ADR 0046, each row is turned for the time its sensor read it):
+
+- An Insta360 ONE R recording has each row of its lenses turned by the camera's turn between the
+  frame's time and the time its sensor read that row, in every stabilization mode: a fast turn no
+  longer skews the top and bottom of the picture against its middle. Other cameras turn whole
+  until their sensors' row order is measured.
+
 Fixed:
 
 - A clip trimmed in the Insta360 app is stabilized with the gyro of its own frames. The app keeps
@@ -24,6 +31,9 @@ Fixed:
   the clip begins.
 - The two files of a split-lens clip trimmed in the Insta360 app (`VID_..._00_002-trim.insv`) are
   found as a pair: the name's suffix after the sequence number is kept for the other lens's file.
+- An Insta360 ONE R recording is stabilized in its own IMU frame. Its info record names it
+  "Insta360 OneR", which no entry matched, so it was stabilized under the aligned guess and lock
+  turned its picture more than leaving it alone; `ONE_R_IMU_FRAME` is measured (ADR 0009).
 
 ## 0.8.1 (2026-10-08)
 

package/dist/packages/adapters/three/src/ThreeFrameRenderer.js

@@ -9,6 +9,7 @@ import { SAMPLING_STRATEGIES } from "./samplingStrategies.js";
 import { applyLensGain, applyPicture, applyShaderSampling, applyStabilization } from "./rendererUniforms.js";
 import { SeamMeterPass } from "./seamMeter/SeamMeterPass.js";
 import { PLAYER_PICTURES, compileAgain, openRendererParts } from "./rendererParts.js";
+import { applyRowCorrections } from "./rowCorrections.js";
 import { scissorBoxOf } from "./scissorBox.js";
 //#region ../../packages/adapters/three/src/ThreeFrameRenderer.ts
 /**
@@ -97,6 +98,14 @@ var ThreeFrameRenderer = class {
 		this.ensureLive();
 		applyStabilization(this.parts.uniforms, rotation);
 	}
+	/**
+	* Turns each lens row by its rolling-shutter correction, or every row with the frame. Does not
+	* redraw by itself, as {@link setStabilization} does not.
+	*/
+	setRowCorrections(corrections) {
+		this.ensureLive();
+		applyRowCorrections(this.parts.uniforms, corrections);
+	}
 	present(presentation) {
 		this.ensureLive();
 		const { frames } = presentation.pair;

package/dist/packages/adapters/three/src/rendererUniforms.js

@@ -18,6 +18,7 @@ var SHADER_DEFINES = Object.fromEntries([
 	["MEI_RADIAL_TERMS", MEI_TERM_CAPACITY.radial],
 	["MEI_TANGENTIAL_ORDERS", MEI_TERM_CAPACITY.tangential],
 	["MEI_THIN_PRISM_ORDERS", MEI_TERM_CAPACITY.thinPrism],
+	["ROW_CORRECTIONS", 9],
 	...CONVERSION_DEFINES,
 	["SAMPLING_BILINEAR", 0],
 	["SAMPLING_TRILINEAR", 1],
@@ -39,6 +40,8 @@ function viewUniforms(setup) {
 		uLensCount: { value: setup.lenses.length },
 		uViewRotation: { value: new Matrix3() },
 		uStabilization: { value: new Matrix3() },
+		uRowCorrected: { value: false },
+		uRowCorrection: { value: Array.from({ length: 9 }, () => new Matrix3()) },
 		uPlaneHalfExtent: { value: 1 },
 		uPictureAspect: { value: 1 },
 		uScreenArea: { value: Array.from({ length: 2 }, () => new Vector4(0, 0, 1, 1)) },

package/dist/packages/adapters/three/src/rowCorrections.js

@@ -0,0 +1,18 @@
+import { ensureInvariant } from "../../../core/src/shared/errors/GyroViewError.js";
+import { toThreeMatrix } from "./threeMatrix.js";
+//#region ../../packages/adapters/three/src/rowCorrections.ts
+/**
+* Sets the rows' rolling-shutter corrections, from the first row of a lens's window to its last,
+* or turns every row with the frame when there are none.
+*/
+function applyRowCorrections(uniforms, corrections) {
+	if (!corrections) {
+		uniforms.uRowCorrected.value = false;
+		return;
+	}
+	ensureInvariant(corrections.length === 9, `a frame's rows take 9 corrections, not ${corrections.length}`);
+	uniforms.uRowCorrection.value = corrections.map((rotation) => toThreeMatrix(rotation));
+	uniforms.uRowCorrected.value = true;
+}
+//#endregion
+export { applyRowCorrections };

package/dist/packages/adapters/three/src/shaders/lensSampling.js

@@ -1,4 +1,4 @@
 //#region ../../packages/adapters/three/src/shaders/lensSampling.glsl?raw
-var lensSampling_default = "// How a body direction becomes a texel of one lens, for the stitch and the seam meters: the\n// pose and field as uniforms, and the sampling through each lens model, the texel as its\n// exposure signal. Needs lensTextures.glsl, displayConversion.glsl and lensModels.glsl.\nuniform vec2 uFeather;\nuniform mat3 uLensRotation[MAX_LENSES];\nuniform int uLensKind[MAX_LENSES];\nuniform float uLensHalfFov[MAX_LENSES];\nuniform vec4 uLensWindow[MAX_LENSES];\n\nstruct LensSample {\n  bool isImaged;\n  // Angle from the lens's optical axis.\n  float theta;\n  // The texel where the lens's exposure is a factor (displayConversion.glsl).\n  vec3 signal;\n};\n\n// Where lens i images direction d on its calibration canvas; the principal point, and not\n// known, for a kind of lens this shader does not know.\nvec2 canvasPixel(int i, vec3 d, float theta, out bool isKnown) {\n  isKnown = true;\n  if (uLensKind[i] == LENS_MEI) {\n    return projectMei(i, d);\n  }\n  if (uLensKind[i] == LENS_RADIAL_POLYNOMIAL) {\n    return projectRadialPolynomial(i, d, theta);\n  }\n  isKnown = false;\n  return uLensPrincipalPoint[i];\n}\n\n// What lens i shows in a body direction, read as `sampling` says, if it images it at all:\n// outside its field, or beyond the window the frame shows, nothing. The footprint is taken and\n// the texture read in every fragment before the gates: a read inside a branch that some pixels\n// of a 2x2 quad skip took a far too coarse footprint on Apple GPUs (rawLenses.frag.glsl).\nLensSample sampleLensWith(int i, vec3 dirBody, int sampling) {\n  vec3 d = uLensRotation[i] * dirBody;\n  // atan keeps its precision near the axis where acos loses it.\n  float theta = atan(length(d.xy), d.z);\n  bool isKnown;\n  vec2 pixel = canvasPixel(i, d, theta, isKnown);\n  vec2 windowUv = (pixel - uLensWindow[i].xy) / uLensWindow[i].zw;\n  Footprint footprint = footprintOf(i, windowUv);\n  bool isInWindow =\n    all(greaterThanEqual(windowUv, vec2(0.0))) && all(lessThanEqual(windowUv, vec2(1.0)));\n  vec3 texel = sampleLens(uLensTexture[i], footprint, sampling).rgb;\n  LensSample result;\n  result.theta = theta;\n  result.isImaged = isKnown && theta < uLensHalfFov[i] && isInWindow;\n  result.signal = result.isImaged ? exposureSignalOf(i, texel) : vec3(0.0);\n  return result;\n}\n\n// What lens i shows in a body direction, read as the picture is.\nLensSample sampleLensAt(int i, vec3 dirBody) {\n  return sampleLensWith(i, dirBody, uSampling);\n}\n";
+var lensSampling_default = "// How a body direction becomes a texel of one lens, for the stitch and the seam meters: the\n// pose and field as uniforms, and the sampling through each lens model, the texel as its\n// exposure signal. Needs lensTextures.glsl, displayConversion.glsl and lensModels.glsl.\nuniform vec2 uFeather;\nuniform mat3 uLensRotation[MAX_LENSES];\nuniform int uLensKind[MAX_LENSES];\nuniform float uLensHalfFov[MAX_LENSES];\nuniform vec4 uLensWindow[MAX_LENSES];\n// Rolling-shutter corrections (ADR 0046): the body as it was when each row was read, from the\n// body at the frame's time, for rows from the top of every lens's window to its bottom.\nuniform bool uRowCorrected;\nuniform mat3 uRowCorrection[ROW_CORRECTIONS];\n\nstruct LensSample {\n  bool isImaged;\n  // Angle from the lens's optical axis.\n  float theta;\n  // The texel where the lens's exposure is a factor (displayConversion.glsl).\n  vec3 signal;\n};\n\n// Where lens i images direction d on its calibration canvas; the principal point, and not\n// known, for a kind of lens this shader does not know.\nvec2 canvasPixel(int i, vec3 d, float theta, out bool isKnown) {\n  isKnown = true;\n  if (uLensKind[i] == LENS_MEI) {\n    return projectMei(i, d);\n  }\n  if (uLensKind[i] == LENS_RADIAL_POLYNOMIAL) {\n    return projectRadialPolynomial(i, d, theta);\n  }\n  isKnown = false;\n  return uLensPrincipalPoint[i];\n}\n\n// The body direction as it was when lens i read the row it images the direction in: found by\n// where the direction lands at the frame's time, which the correction moves by a few rows at\n// most, so one step is enough.\nvec3 rowCorrected(int i, vec3 dirBody) {\n  if (!uRowCorrected) return dirBody;\n  vec3 d = uLensRotation[i] * dirBody;\n  float theta = atan(length(d.xy), d.z);\n  bool isKnown;\n  vec2 pixel = canvasPixel(i, d, theta, isKnown);\n  float row = clamp((pixel.y - uLensWindow[i].y) / uLensWindow[i].w, 0.0, 1.0);\n  float step = row * float(ROW_CORRECTIONS - 1);\n  int below = min(int(floor(step)), ROW_CORRECTIONS - 2);\n  vec3 above = uRowCorrection[below] * dirBody;\n  vec3 next = uRowCorrection[below + 1] * dirBody;\n  return normalize(mix(above, next, step - float(below)));\n}\n\n// What lens i shows in a body direction, read as `sampling` says, if it images it at all:\n// outside its field, or beyond the window the frame shows, nothing. The footprint is taken and\n// the texture read in every fragment before the gates: a read inside a branch that some pixels\n// of a 2x2 quad skip took a far too coarse footprint on Apple GPUs (rawLenses.frag.glsl).\nLensSample sampleLensWith(int i, vec3 dirBody, int sampling) {\n  vec3 d = uLensRotation[i] * rowCorrected(i, dirBody);\n  // atan keeps its precision near the axis where acos loses it.\n  float theta = atan(length(d.xy), d.z);\n  bool isKnown;\n  vec2 pixel = canvasPixel(i, d, theta, isKnown);\n  vec2 windowUv = (pixel - uLensWindow[i].xy) / uLensWindow[i].zw;\n  Footprint footprint = footprintOf(i, windowUv);\n  bool isInWindow =\n    all(greaterThanEqual(windowUv, vec2(0.0))) && all(lessThanEqual(windowUv, vec2(1.0)));\n  vec3 texel = sampleLens(uLensTexture[i], footprint, sampling).rgb;\n  LensSample result;\n  result.theta = theta;\n  result.isImaged = isKnown && theta < uLensHalfFov[i] && isInWindow;\n  result.signal = result.isImaged ? exposureSignalOf(i, texel) : vec3(0.0);\n  return result;\n}\n\n// What lens i shows in a body direction, read as the picture is.\nLensSample sampleLensAt(int i, vec3 dirBody) {\n  return sampleLensWith(i, dirBody, uSampling);\n}\n";
 //#endregion
 export { lensSampling_default as default };

package/dist/packages/core/src/application/recording/motionOf.js

@@ -1,6 +1,7 @@
 import { imuFrameFor } from "../../domain/motion/imu/ImuFrame.js";
 import { mountingOf, uprightImuFrame } from "../../domain/motion/mounting/Mounting.js";
 import { OrientationTrack } from "../../domain/motion/orientation/OrientationTrack.js";
+import { rollingShutterFor } from "../../domain/motion/rollingShutter/RollingShutter.js";
 //#region ../../packages/core/src/application/recording/motionOf.ts
 var NO_GYRO_WARNING = "the recording has no gyro record; stabilization is unavailable";
 /**
@@ -27,7 +28,8 @@ async function motionOf(recording, clock) {
 		setup: {
 			orientations,
 			mounting,
-			imuFrame
+			imuFrame,
+			rollingShutter: rollingShutterFor(recording.info)
 		},
 		warnings
 	};

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

@@ -1,9 +1,11 @@
 import { rotationIntoBody } from "../../domain/motion/mounting/Mounting.js";
+import { rowCorrectionsAt } from "../../domain/motion/rollingShutter/RollingShutter.js";
 import { OffStabilization } 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
-* exposure and tells the sink how to turn the picture for the current stabilization mode.
+* exposure and tells the sink how to turn the picture for the current stabilization mode, and,
+* for a camera whose rolling shutter is known, how to turn each row for the time it was read.
 */
 var StabilizingFrameSink = class {
 	parts;
@@ -19,6 +21,8 @@ var StabilizingFrameSink = class {
 		const { orientations, mounting } = this.parts.motion;
 		const rotation = this.stabilizer.nextRotation(orientations.orientationAt(time), time);
 		this.parts.sink.setStabilization(rotationIntoBody(mounting, rotation));
+		const { rollingShutter } = this.parts;
+		if (rollingShutter) this.parts.sink.setRowCorrections(rowCorrectionsAt(this.parts.motion, time, rollingShutter));
 		this.parts.sink.present(presentation);
 	}
 	/**

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

@@ -123,6 +123,17 @@ var A1_IMU_FRAME = measuredImuFrame("A1", [
 */
 var X3_IMU_FRAME = measuredImuFrame("X3", QUARTER_TURN_ABOUT_LATERAL);
 /**
+* Measured on one ONE R recording with the 5.7K 360 lens module, a skydive that turns throughout
+* (ADR 0009): the stillness ranking puts it first in Chromium and WebKit, 41.0 against 52.1
+* unstabilized and 46.8 for the next. The X5's arrangement turned a half turn about the lateral
+* axis. The ONE R names itself "Insta360 OneR", another model than the ONE RS.
+*/
+var ONE_R_IMU_FRAME = measuredImuFrame("ONE R", [
+	"x",
+	"-z",
+	"y"
+]);
+/**
 * Assumed for the ONE RS until a recording that turns is ranked (ADR 0009). On one tripod
 * recording of the 1-inch 360 edition, standing upright, gravity lies along the IMU's x, so the
 * body's down is the IMU's x; of the four arrangements that agree, the levelling ranking puts
@@ -153,6 +164,7 @@ var IMU_FRAMES_BY_MODEL = /* @__PURE__ */ new Map([
 	["Insta360 X4 Air", X4_AIR_IMU_FRAME],
 	["Insta360 X5", X5_IMU_FRAME],
 	["Insta360 X6", X6_IMU_FRAME],
+	["Insta360 OneR", ONE_R_IMU_FRAME],
 	["Insta360 OneRS", ONE_RS_IMU_FRAME]
 ]);
 /**
@@ -163,4 +175,4 @@ function imuFrameFor(hints) {
 	return IMU_FRAMES_BY_MODEL.get(hints.model?.trim() ?? "") ?? ALIGNED_IMU_FRAME;
 }
 //#endregion
-export { A1_IMU_FRAME, ALIGNED_IMU_FRAME, ONE_RS_IMU_FRAME, X3_IMU_FRAME, X4_AIR_IMU_FRAME, X5_IMU_FRAME, X6_IMU_FRAME, assumedImuFrame, imuFrameFor, isProperRotation, toBodyFrame };
+export { A1_IMU_FRAME, ALIGNED_IMU_FRAME, ONE_RS_IMU_FRAME, ONE_R_IMU_FRAME, X3_IMU_FRAME, X4_AIR_IMU_FRAME, X5_IMU_FRAME, X6_IMU_FRAME, assumedImuFrame, imuFrameFor, isProperRotation, toBodyFrame };

package/dist/packages/core/src/domain/motion/rollingShutter/RollingShutter.js

@@ -0,0 +1,46 @@
+import { seconds } from "../../../shared/units/time.js";
+import { multiplyMatrices, transposeMatrix } from "../../../shared/math/Matrix3.js";
+import { quaternionToMatrix } from "../../../shared/math/Quaternion.js";
+/**
+* Where a frame's time lies down its rows: the middle row's (ADR 0034).
+*/
+var FRAME_TIME_ROW = .5;
+/**
+* Keyed by the whole model name, as the IMU frames are: a camera's row order is measured on a
+* recording of it (ADR 0046), never assumed.
+*/
+var ROW_ORDERS_BY_MODEL = /* @__PURE__ */ new Map([["Insta360 OneR", "top-first"]]);
+/**
+* The rolling shutter to correct, for a camera whose row order is measured and whose info record
+* states its readout; nothing otherwise, and its frames turn whole.
+*/
+function rollingShutterFor(info) {
+	const rowOrder = ROW_ORDERS_BY_MODEL.get(info.model?.trim() ?? "");
+	const readout = info.readoutTime;
+	return rowOrder && readout !== void 0 && readout > 0 ? {
+		readout,
+		rowOrder
+	} : void 0;
+}
+/**
+* For each of {@link ROW_CORRECTION_COUNT} rows down a lens's window, the rotation taking a
+* direction in the body as it was at the frame's `time` into the body as it was when that row was
+* read: the camera turned between the two, so the world a row shows lies that much elsewhere.
+* Every stabilization mode turns the picture at the frame's time, so the corrections apply after
+* it, whatever the mode.
+*/
+function rowCorrectionsAt(motion, time, shutter) {
+	const { orientations, mounting } = motion;
+	const atTime = quaternionToMatrix(orientations.orientationAt(time));
+	const fromBody = transposeMatrix(mounting.toBody);
+	const last = 8;
+	return Array.from({ length: 9 }, (_, index) => {
+		const step = shutter.rowOrder === "top-first" ? index : last - index;
+		const rowTime = seconds(time + (step / last - FRAME_TIME_ROW) * shutter.readout);
+		const atRow = quaternionToMatrix(orientations.orientationAt(rowTime));
+		const uprightTurn = multiplyMatrices(transposeMatrix(atRow), atTime);
+		return multiplyMatrices(mounting.toBody, multiplyMatrices(uprightTurn, fromBody));
+	});
+}
+//#endregion
+export { rollingShutterFor, rowCorrectionsAt };

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

@@ -154,7 +154,8 @@ function sinkOver(renderer, opened) {
 	const stabilizing = new StabilizingFrameSink({
 		sink: renderer,
 		motion: opened.motion,
-		frameTimes: opened.frameTimes
+		frameTimes: opened.frameTimes,
+		rollingShutter: opened.motion.rollingShutter
 	});
 	return {
 		sink: stabilizing,