@bubo-squared/gyroview 0.1.0

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

@@ -0,0 +1,62 @@
+import { seconds } from "../../shared/units/time.js";
+import { interpolateVectors } from "../../shared/math/Vector3.js";
+import { clamp } from "../../shared/math/clamp.js";
+var DEFAULT_TIME_CONSTANT_SECONDS = 1.5;
+/**
+* A channel darker than this (0..1) carries no exposure information; its gain is left at one.
+*/
+var DARK_CHANNEL = .01;
+var UNIT_GAIN = [
+	1,
+	1,
+	1
+];
+var DEFAULT_GAIN_MATCH_OPTIONS = {
+	maxGain: 2,
+	timeConstant: seconds(DEFAULT_TIME_CONSTANT_SECONDS)
+};
+/**
+* Per-channel gains that bring every lens's overlap brightness to the first lens's. Lens 0 is
+* the reference and keeps unit gain; the first is the lens the viewer starts facing, so its
+* exposure is the one that must not shift under them.
+*/
+function gainsMatching(overlapMeans, maxGain) {
+	const [reference] = overlapMeans;
+	return reference ? overlapMeans.map((mean, lensIndex) => lensIndex === 0 ? UNIT_GAIN : channelGains(reference, mean, maxGain)) : [];
+}
+function channelGains(reference, mean, maxGain) {
+	return [
+		channelGain(reference[0], mean[0], maxGain),
+		channelGain(reference[1], mean[1], maxGain),
+		channelGain(reference[2], mean[2], maxGain)
+	];
+}
+function channelGain(reference, mean, maxGain) {
+	return reference < DARK_CHANNEL || mean < DARK_CHANNEL ? 1 : clamp(reference / mean, 1 / maxGain, maxGain);
+}
+/**
+* Follows the matching gains over time with a first-order low-pass, so a cloud passing one
+* lens does not flicker the other. The first measurement is taken as is.
+*/
+var GainMatcher = class {
+	options;
+	current;
+	lastTime;
+	constructor(options = DEFAULT_GAIN_MATCH_OPTIONS) {
+		this.options = options;
+	}
+	/**
+	* Feeds the overlap means measured at `time` (media time) and returns the gains to apply.
+	*/
+	update(overlapMeans, time) {
+		const target = gainsMatching(overlapMeans, this.options.maxGain);
+		const elapsed = this.lastTime === void 0 ? Infinity : Math.max(time - this.lastTime, 0);
+		this.lastTime = time;
+		const weight = this.current ? 1 - Math.exp(-elapsed / this.options.timeConstant) : 1;
+		const previous = this.current;
+		this.current = target.map((gain, lensIndex) => interpolateVectors(previous?.[lensIndex] ?? UNIT_GAIN, gain, weight));
+		return this.current;
+	}
+};
+//#endregion
+export { GainMatcher, gainsMatching };

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

@@ -0,0 +1,18 @@
+import { radians } from "../../shared/units/angle.js";
+//#region ../../packages/core/src/domain/optics/lensGeometry.ts
+function toPolar(direction) {
+	const [x, y, z] = direction;
+	const lateral = Math.hypot(x, y);
+	return {
+		theta: radians(Math.atan2(lateral, z)),
+		radialUnit: lateral === 0 ? [0, 0] : [x / lateral, y / lateral]
+	};
+}
+function pixelAtRadius(principalPoint, radius, radialUnit) {
+	return {
+		x: principalPoint.x + radius * radialUnit[0],
+		y: principalPoint.y + radius * radialUnit[1]
+	};
+}
+//#endregion
+export { pixelAtRadius, toPolar };

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

@@ -0,0 +1,35 @@
+import { HALF_TURN, QUARTER_TURN, degrees, degreesToRadians } from "../../shared/units/angle.js";
+import { multiplyMatrices, rotationAboutX, rotationAboutY, rotationAboutZ } from "../../shared/math/Matrix3.js";
+//#region ../../packages/core/src/domain/optics/lensPose.ts
+/**
+* The roll the rotation applies for a calibration roll: mirrored about the sensor's mounting,
+* the quarter turn nearest to it, since the strings measure the in-plane roll in the other sense
+* than the lens frame turns (measured on two X5 units, ADR 0025). The mounting itself is kept,
+* so a sensor mounted sideways, as on the X5, or upright stays so.
+*/
+function mirroredRoll(roll) {
+	const mounting = Math.round(roll / QUARTER_TURN) * QUARTER_TURN;
+	return degrees(2 * mounting - roll);
+}
+/**
+* Turns directions in the camera body frame (x right, y down, z forward along lens 0's optical
+* axis) into the lens frame the {@link LensCalibration.model} projects from.
+*
+* The calibration's yaw (about the body's vertical) and pitch (about its lateral axis) turn each
+* lens in the body frame, alike for both lenses; then lens `i` turns half a turn per lens index
+* about the lateral axis to face backwards, its sensor upside down relative to the front one
+* (ADR 0008); then the roll turns the image about the optical axis, read mirrored
+* ({@link mirroredRoll}), the order measured in ADR 0025. The X5 strings carry a roll near 90
+* degrees for both lenses and no half turn, which is why the facing is part of the convention.
+*/
+function lensRotation(lens) {
+	const { yaw, pitch, roll } = lens.orientation;
+	const yawed = rotationAboutY(degreesToRadians(yaw));
+	const pitched = multiplyMatrices(rotationAboutX(degreesToRadians(pitch)), yawed);
+	const facing = rotationAboutX(degreesToRadians(degrees(HALF_TURN * lens.lensIndex)));
+	const faced = multiplyMatrices(facing, pitched);
+	const rolled = rotationAboutZ(degreesToRadians(mirroredRoll(roll)));
+	return multiplyMatrices(rolled, faced);
+}
+//#endregion
+export { lensRotation, mirroredRoll };

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

@@ -0,0 +1,5 @@
+import { degrees, degreesToRadians } from "../../shared/units/angle.js";
+var HALF_FIELD_OF_VIEW = degreesToRadians(degrees(100));
+var LEGACY_RADIUS_ANGLE = degreesToRadians(degrees(96));
+//#endregion
+export { HALF_FIELD_OF_VIEW, LEGACY_RADIUS_ANGLE };

package/dist/packages/core/src/domain/playback/PlayerState.js

@@ -0,0 +1,83 @@
+import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+//#region ../../packages/core/src/domain/playback/PlayerState.ts
+/**
+* Every legal transition; anything else is a programming error. A session is `ready` from
+* construction (its parts are already open). `buffering` is playing without a picture to show:
+* the clock waits for the decoders, on starting, after a seek and when they fall behind. A
+* seek always resumes through `buffering` or lands `paused`; the end is reached from `playing`
+* only; `error` leads only to `disposed`, which is terminal.
+*/
+var TRANSITIONS = {
+	ready: [
+		"playing",
+		"buffering",
+		"paused",
+		"seeking",
+		"error",
+		"disposed"
+	],
+	playing: [
+		"buffering",
+		"paused",
+		"seeking",
+		"ended",
+		"error",
+		"disposed"
+	],
+	buffering: [
+		"playing",
+		"paused",
+		"seeking",
+		"error",
+		"disposed"
+	],
+	paused: [
+		"playing",
+		"buffering",
+		"seeking",
+		"error",
+		"disposed"
+	],
+	seeking: [
+		"buffering",
+		"paused",
+		"error",
+		"disposed"
+	],
+	ended: [
+		"seeking",
+		"error",
+		"disposed"
+	],
+	error: ["disposed"],
+	disposed: []
+};
+var FLOWING_STATES = /* @__PURE__ */ new Set(["playing", "buffering"]);
+/**
+* Whether playback is under way: frames flow, or the clock holds for them. A media element is not
+* `paused` then.
+*/
+function isFlowing(state) {
+	return state !== void 0 && FLOWING_STATES.has(state);
+}
+/**
+* Explicit player lifecycle instead of a set of booleans.
+*/
+var PlayerStateMachine = class {
+	current = "ready";
+	get state() {
+		return this.current;
+	}
+	canTransitionTo(next) {
+		return TRANSITIONS[this.current].includes(next);
+	}
+	transitionTo(next) {
+		if (!this.canTransitionTo(next)) throw new GyroViewError("invariant-violation", `player cannot go from ${this.current} to ${next}`);
+		this.current = next;
+	}
+	isOneOf(...states) {
+		return states.includes(this.current);
+	}
+};
+//#endregion
+export { PlayerStateMachine, isFlowing };

package/dist/packages/core/src/domain/stitching/LensLayout.js

@@ -0,0 +1,21 @@
+//#region ../../packages/core/src/domain/stitching/LensLayout.ts
+var FULL_FRAME = {
+	x: 0,
+	y: 0,
+	width: 1,
+	height: 1
+};
+var LEFT_HALF = {
+	x: 0,
+	y: 0,
+	width: .5,
+	height: 1
+};
+var RIGHT_HALF = {
+	x: .5,
+	y: 0,
+	width: .5,
+	height: 1
+};
+//#endregion
+export { FULL_FRAME, LEFT_HALF, RIGHT_HALF };

package/dist/packages/core/src/domain/stitching/StitchingSetup.js

@@ -0,0 +1,78 @@
+import { degrees, degreesToRadians } from "../../shared/units/angle.js";
+import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+import { lensRotation } from "../optics/lensPose.js";
+import { SEAM_RING_ANGLE } from "./seamRing.js";
+//#region ../../packages/core/src/domain/stitching/StitchingSetup.ts
+/**
+* Two 200-degree lenses overlap between 80 and 100 degrees from their axes; the blend spans 5
+* degrees either side of the seam ring, which lies 90 degrees from both.
+*/
+var FEATHER_HALF_WIDTH_DEGREES = 5;
+var DEFAULT_FEATHER = {
+	start: degreesToRadians(degrees(SEAM_RING_ANGLE - FEATHER_HALF_WIDTH_DEGREES)),
+	end: degreesToRadians(degrees(SEAM_RING_ANGLE + FEATHER_HALF_WIDTH_DEGREES))
+};
+/**
+* The distinct video tracks a layout draws from, in order of first use by lens index. The
+* composition root hands the session its readers in this order, and {@link LensStitch.frameSlot}
+* indexes the pairs the session presents.
+*/
+function lensFrameOrder(layout) {
+	const keys = [];
+	for (const source of layout.sources) if (keys.every((key) => !isSameSource(key, source))) keys.push({
+		inputIndex: source.inputIndex,
+		trackIndex: source.trackIndex
+	});
+	return keys;
+}
+/**
+* Use case: joins the factory calibration with the detected lens layout into the per-lens
+* parameters a renderer binds. Pure; the renderer only copies numbers into uniforms.
+*/
+function buildStitchingSetup(inputs) {
+	const { calibration, layout } = inputs;
+	if (calibration.lenses.length !== layout.sources.length) throw new GyroViewError("unsupported-layout", `the calibration describes ${calibration.lenses.length} lenses but the layout has ${layout.sources.length}`);
+	const frames = lensFrameOrder(layout);
+	return {
+		lenses: layout.sources.map((source) => {
+			const lens = lensOf(calibration, source.lensIndex);
+			return {
+				lensIndex: source.lensIndex,
+				frameSlot: frames.findIndex((key) => isSameSource(key, source)),
+				region: source.region,
+				window: canvasWindowOf(calibration, lens),
+				rotation: lensRotation(lens),
+				projection: lens.model.projection,
+				halfFieldOfView: lens.model.halfFieldOfView
+			};
+		}),
+		frameSlotCount: frames.length,
+		feather: DEFAULT_FEATHER
+	};
+}
+function isSameSource(key, source) {
+	return key.inputIndex === source.inputIndex && key.trackIndex === source.trackIndex;
+}
+function lensOf(calibration, lensIndex) {
+	const lens = calibration.lenses.find((candidate) => candidate.lensIndex === lensIndex);
+	if (!lens) throw new GyroViewError("invalid-calibration", `the calibration has no lens ${lensIndex}`);
+	return lens;
+}
+/**
+* The canvas holds the lens images side by side in squares of its height; each lens's square is
+* the one holding its principal point, and the encoded frame shows that whole square. The info
+* record's sensor window (5312 of 5376 at offset 0 on the X5) is deliberately not applied: the
+* fisheye image circle sits at the centre of every X5 frame, where the whole square puts the
+* principal point, not 32 canvas pixels off where the window would (ADR 0014).
+*/
+function canvasWindowOf(calibration, lens) {
+	const side = calibration.canvas.height;
+	return {
+		x: Math.floor(lens.model.principalPoint.x / side) * side,
+		y: 0,
+		width: side,
+		height: side
+	};
+}
+//#endregion
+export { buildStitchingSetup, lensFrameOrder };

package/dist/packages/core/src/domain/stitching/seamDisparity.js

@@ -0,0 +1,4 @@
+import { degrees } from "../../shared/units/angle.js";
+import "./seamStrip.js";
+degrees(-6), degrees(10), degrees(.25);
+//#endregion

package/dist/packages/core/src/domain/stitching/seamDisparityField.js

@@ -0,0 +1,5 @@
+import "../../shared/units/angle.js";
+import { seconds } from "../../shared/units/time.js";
+import "./seamStrip.js";
+seconds(.25);
+//#endregion

package/dist/packages/core/src/domain/stitching/seamJoin.js

@@ -0,0 +1,16 @@
+import { degrees } from "../../shared/units/angle.js";
+import { SEAM_BIN_COUNT } from "./seamStrip.js";
+Array.from({ length: SEAM_BIN_COUNT }, () => degrees(0));
+degrees(15);
+degrees(4);
+/**
+* Beyond the most a bent join bends, the blend narrows from the feather band to this half width
+* as the rest of the disparity grows to {@link SEAM_CUT_DISPARITY}: a degree still hides the step
+* in exposure between the lenses, and a double image farther apart than three degrees reads as
+* two objects.
+*/
+var CUT_HALF_WIDTH_DEGREES = 1;
+var CUT_DISPARITY_DEGREES = 3;
+degrees(CUT_HALF_WIDTH_DEGREES);
+degrees(CUT_DISPARITY_DEGREES);
+//#endregion

package/dist/packages/core/src/domain/stitching/seamMismatch.js

@@ -0,0 +1 @@
+//#endregion

package/dist/packages/core/src/domain/stitching/seamRing.js

@@ -0,0 +1,4 @@
+import { degrees } from "../../shared/units/angle.js";
+var SEAM_RING_ANGLE = degrees(90);
+//#endregion
+export { SEAM_RING_ANGLE };

package/dist/packages/core/src/domain/stitching/seamStrip.js

@@ -0,0 +1,26 @@
+import { degrees } from "../../shared/units/angle.js";
+import { SEAM_RING_ANGLE } from "./seamRing.js";
+//#region ../../packages/core/src/domain/stitching/seamStrip.ts
+/**
+* The seam strip: the band of body directions 83 to 97 degrees from body +z, where both lenses
+* see the same scene and their agreement is measured. It is sampled every half degree in
+* azimuth and in the angle from body +z, and read in 5-degree azimuth bins.
+*
+* Azimuth runs from body +x (the right seam) towards body +y (down): 0 right, 90 nadir, 180
+* left, 270 zenith. The strip reaches 7 degrees either side of the ring; a slide of one lens's
+* sampling moves the directions it reads, and the share of each bin both lenses still image
+* (its validity) says how much of a slide the strip holds.
+*/
+var STRIP_HALF_WIDTH_DEGREES = 7;
+var STRIP_STEP_DEGREES = .5;
+var BIN_WIDTH_DEGREES = 5;
+var FULL_CIRCLE_DEGREES = 360;
+degrees(SEAM_RING_ANGLE - STRIP_HALF_WIDTH_DEGREES);
+degrees(STRIP_STEP_DEGREES);
+degrees(BIN_WIDTH_DEGREES);
+Math.round(14 / STRIP_STEP_DEGREES);
+Math.round(BIN_WIDTH_DEGREES / STRIP_STEP_DEGREES);
+var SEAM_BIN_COUNT = Math.round(FULL_CIRCLE_DEGREES / BIN_WIDTH_DEGREES);
+degrees(60), degrees(120);
+//#endregion
+export { SEAM_BIN_COUNT };

package/dist/packages/core/src/domain/view/Framing.js

@@ -0,0 +1,31 @@
+import { DEFAULT_VIEW, isSameView } from "./ViewState.js";
+import { FITTED, isSameMagnification } from "./magnification.js";
+//#region ../../packages/core/src/domain/view/Framing.ts
+var DEFAULT_FRAMING = {
+	view: DEFAULT_VIEW,
+	panorama: FITTED,
+	lenses: FITTED
+};
+function isSameFraming(a, b) {
+	return isSameView(a.view, b.view) && isSameMagnification(a.panorama, b.panorama) && isSameMagnification(a.lenses, b.lenses);
+}
+/**
+* The framing with the normal view replaced, the flat pictures' parts kept.
+*/
+function withView(framing, view) {
+	return {
+		...framing,
+		view
+	};
+}
+/**
+* The framing with the lens tiles' magnification replaced, the other parts kept.
+*/
+function withLenses(framing, lenses) {
+	return {
+		...framing,
+		lenses
+	};
+}
+//#endregion
+export { DEFAULT_FRAMING, isSameFraming, withLenses, withView };

package/dist/packages/core/src/domain/view/PictureQuality.js

@@ -0,0 +1,26 @@
+//#region ../../packages/core/src/domain/view/PictureQuality.ts
+var PICTURE_QUALITIES = [
+	"fast",
+	"balanced",
+	"high"
+];
+/**
+* A mip chain per frame per lens is what every platform the player targets affords, and what
+* the equirectangular view and the raw tiles need to hold still.
+*/
+var DEFAULT_PICTURE_QUALITY = "balanced";
+/**
+* The most device pixels per CSS pixel each quality draws: the screen's own ratio up to this.
+* Above two, the stitch's cost grows faster than what the eye gains from it, so only `high`
+* follows a phone's screen all the way.
+*/
+var PIXEL_RATIO_CAPS = {
+	fast: 1,
+	balanced: 2,
+	high: 3
+};
+function pixelRatioCapOf(quality) {
+	return PIXEL_RATIO_CAPS[quality];
+}
+//#endregion
+export { DEFAULT_PICTURE_QUALITY, PICTURE_QUALITIES, pixelRatioCapOf };

package/dist/packages/core/src/domain/view/ViewMode.js

@@ -0,0 +1,9 @@
+//#region ../../packages/core/src/domain/view/ViewMode.ts
+var VIEW_MODES = [
+	"raw-lenses",
+	"equirectangular",
+	"normal"
+];
+var DEFAULT_VIEW_MODE = "raw-lenses";
+//#endregion
+export { DEFAULT_VIEW_MODE, VIEW_MODES };

package/dist/packages/core/src/domain/view/ViewState.js

@@ -0,0 +1,48 @@
+import { degrees, degreesToRadians, wrapHalfTurn } from "../../shared/units/angle.js";
+import { ensureInvariant } from "../../shared/errors/GyroViewError.js";
+import { clamp } from "../../shared/math/clamp.js";
+import { multiplyMatrices, rotationAboutX, rotationAboutY } from "../../shared/math/Matrix3.js";
+//#region ../../packages/core/src/domain/view/ViewState.ts
+/**
+* From a short telephoto to a wide angle: past 120 degrees a rectilinear view stretches its
+* edges more than it shows.
+*/
+var NARROWEST_DEGREES = 30;
+var WIDEST_DEGREES = 120;
+var DEFAULT_FIELD_OF_VIEW_DEGREES = 90;
+var MAX_PITCH_DEGREES = 90;
+var DEFAULT_VIEW = {
+	yaw: degrees(0),
+	pitch: degrees(0),
+	fieldOfView: degrees(DEFAULT_FIELD_OF_VIEW_DEGREES)
+};
+/**
+* Keeps the view inside the sphere: yaw wrapped to (-180, 180], pitch within the poles, field
+* of view within its bounds. Non-finite angles are a programming error.
+*/
+function clampView(view) {
+	ensureInvariant([
+		view.yaw,
+		view.pitch,
+		view.fieldOfView
+	].every((angle) => Number.isFinite(angle)), "view angles must be finite");
+	return {
+		...view,
+		yaw: wrapHalfTurn(view.yaw),
+		pitch: degrees(clamp(view.pitch, -90, MAX_PITCH_DEGREES)),
+		fieldOfView: degrees(clamp(view.fieldOfView, NARROWEST_DEGREES, WIDEST_DEGREES))
+	};
+}
+function isSameView(a, b) {
+	return a.yaw === b.yaw && a.pitch === b.pitch && a.fieldOfView === b.fieldOfView;
+}
+/**
+* Turns view-space directions (z forward) into camera body directions: pitch about the body's
+* lateral axis first, then yaw about its vertical axis. Body y points down, so a positive
+* rotation about x tilts the forward direction upwards.
+*/
+function viewRotation(view) {
+	return multiplyMatrices(rotationAboutY(degreesToRadians(view.yaw)), rotationAboutX(degreesToRadians(view.pitch)));
+}
+//#endregion
+export { DEFAULT_VIEW, clampView, isSameView, viewRotation };

package/dist/packages/core/src/domain/view/lensTilesView.js

@@ -0,0 +1,63 @@
+import { aspectOf, boundsOf, lensTiles, shiftOf } from "./screenLayout.js";
+import { FITTED, clampMagnification, magnifiedArea, magnifyAt, panMagnification } from "./magnification.js";
+import { withLenses } from "./Framing.js";
+//#region ../../packages/core/src/domain/view/lensTilesView.ts
+/**
+* An arrow's angle moves zoomed tiles as a drag across the viewport would move them, a 90-degree
+* sweep crossing its width: as far as the arrow turns the normal view at its default field of
+* view, so the arrows feel alike in both.
+*/
+var DEGREES_ACROSS_VIEWPORT = 90;
+/**
+* The lens tiles fitted into the viewport, and the rectangle they fill together.
+*/
+function fittedTiles({ viewport, lensCount }) {
+	const tiles = lensTiles(lensCount, aspectOf(viewport));
+	return {
+		tiles,
+		bounds: boundsOf(tiles)
+	};
+}
+function panLenses(framing, delta, context) {
+	const shift = shiftOf(delta, context.viewport);
+	return withLenses(framing, panMagnification(fittedTiles(context).bounds, framing.lenses, shift));
+}
+function turnLenses(framing, turn, context) {
+	const pixelsPerDegree = context.viewport.width / DEGREES_ACROSS_VIEWPORT;
+	return panLenses(framing, {
+		x: -(turn.yaw * pixelsPerDegree),
+		y: turn.pitch * pixelsPerDegree
+	}, context);
+}
+/**
+* Every tile moved and enlarged by the same map that takes the fitted tiles to the magnified.
+*/
+function magnifiedTiles(framing, context) {
+	const { tiles, bounds } = fittedTiles(context);
+	const lenses = clampMagnification(bounds, framing.lenses);
+	const area = magnifiedArea(bounds, lenses);
+	return tiles.map((tile) => ({
+		x: area.x + (tile.x - bounds.x) * lenses.scale,
+		y: area.y + (tile.y - bounds.y) * lenses.scale,
+		width: tile.width * lenses.scale,
+		height: tile.height * lenses.scale
+	}));
+}
+/**
+* The decoded images as the camera recorded them, magnified up to four times toward the pointer
+* and moved within their edges once zoomed; never turned or stitched.
+*/
+var LENS_TILES_VIEW = {
+	isStabilized: false,
+	canPan: ({ lenses }) => lenses.scale > 1,
+	pan: panLenses,
+	turn: turnLenses,
+	zoom: (framing, zoom, context) => withLenses(framing, magnifyAt(fittedTiles(context).bounds, framing.lenses, zoom)),
+	reset: (framing) => withLenses(framing, FITTED),
+	picture: (framing, context) => ({
+		kind: "lens-tiles",
+		tiles: magnifiedTiles(framing, context)
+	})
+};
+//#endregion
+export { LENS_TILES_VIEW };

package/dist/packages/core/src/domain/view/magnification.js

@@ -0,0 +1,103 @@
+import { clamp } from "../../shared/math/clamp.js";
+import { HALF, SCREEN_CENTRE, pictureAt } from "./screenLayout.js";
+import { zoomFactor } from "./viewGestures.js";
+/**
+* The picture whole: every flat picture starts fitted into the viewport, its middle at the
+* viewport's centre.
+*/
+var FITTED = {
+	scale: 1,
+	centre: {
+		x: HALF,
+		y: HALF
+	}
+};
+/**
+* A scale this close to 1 is the fitted picture: zooming out notch by notch as far as it zoomed
+* in lands within rounding of 1, and must show the picture fitted again, not a hair enlarged.
+*/
+var FITTED_TOLERANCE = 1e-9;
+function isSameMagnification(a, b) {
+	return a.scale === b.scale && a.centre.x === b.centre.x && a.centre.y === b.centre.y;
+}
+/**
+* Where the magnified picture lies on the viewport, given where it lies fitted. The fitted
+* rectangle is centred, as every fitted picture is.
+*/
+function magnifiedArea(fitted, magnification) {
+	const width = fitted.width * magnification.scale;
+	const height = fitted.height * magnification.scale;
+	return {
+		x: SCREEN_CENTRE.x - magnification.centre.x * width,
+		y: SCREEN_CENTRE.y - magnification.centre.y * height,
+		width,
+		height
+	};
+}
+/**
+* The magnification brought within its limits: a scale from fitted to `MAX_MAGNIFICATION`, and a
+* centre that leaves no bar along an axis where the picture is larger than the viewport, and
+* keeps the picture centred along an axis where it is smaller.
+*/
+function clampMagnification(fitted, magnification) {
+	const limited = clamp(magnification.scale, 1, 4);
+	const scale = limited - 1 < FITTED_TOLERANCE ? 1 : limited;
+	return {
+		scale,
+		centre: {
+			x: clampedCentre(magnification.centre.x, fitted.width * scale),
+			y: clampedCentre(magnification.centre.y, fitted.height * scale)
+		}
+	};
+}
+/**
+* Magnifies by the zoom's steps, keeping the point of the picture under its focus where it is,
+* as far as the limits allow.
+*/
+function magnifyAt(fitted, magnification, zoom) {
+	const current = clampMagnification(fitted, magnification);
+	const underFocus = pictureAt(magnifiedArea(fitted, current), zoom.focus);
+	const scale = current.scale * zoomFactor(zoom.steps);
+	return clampMagnification(fitted, {
+		scale,
+		centre: {
+			x: underFocus.x + (SCREEN_CENTRE.x - zoom.focus.x) / (fitted.width * scale),
+			y: underFocus.y + (SCREEN_CENTRE.y - zoom.focus.y) / (fitted.height * scale)
+		}
+	});
+}
+/**
+* Moves the picture by a shift across the viewport, as far as its edges allow.
+*/
+function panMagnification(fitted, magnification, shift) {
+	const current = clampMagnification(fitted, magnification);
+	const moved = pictureShiftOf(fitted, current, shift);
+	return clampMagnification(fitted, {
+		scale: current.scale,
+		centre: {
+			x: current.centre.x - moved.across,
+			y: current.centre.y - moved.down
+		}
+	});
+}
+/**
+* A shift across the viewport as fractions of the picture as magnified: the part of the picture
+* that passes under a fixed point.
+*/
+function pictureShiftOf(fitted, magnification, shift) {
+	return {
+		across: shift.across / (fitted.width * magnification.scale),
+		down: shift.down / (fitted.height * magnification.scale)
+	};
+}
+/**
+* Along one axis: the picture's centre point within the range that keeps the viewport covered,
+* `extent` being the picture's size in viewport lengths; the middle when it cannot cover it.
+*/
+function clampedCentre(centre, extent) {
+	if (extent <= 1) return HALF;
+	const halfViewport = HALF / extent;
+	return clamp(centre, halfViewport, 1 - halfViewport);
+}
+//#endregion
+export { FITTED, clampMagnification, isSameMagnification, magnifiedArea, magnifyAt, panMagnification, pictureShiftOf };