dsh-pet-live2d-viola 1.0.0

package/lib/framing.js

@@ -0,0 +1,284 @@
+/**
+ * Framing math for the Live2D pet, kept free of PixiJS and the DOM so it can be
+ * reasoned about and tested directly.
+ *
+ * ## The rule
+ *
+ * One measured relationship drives everything:
+ *
+ *     scale    = BODY_SCALE_PER_PIXEL * surfaceHeight * preset.zoom
+ *     position = (surfaceWidth * 0.5, surfaceHeight * 0.5) + preset nudges
+ *
+ * With `zoom = 1` that shows the **whole character**, centred, with a margin. It was
+ * verified against rendered frames at four surface sizes (180x270, 240x360, 300x450,
+ * 420x630) and her drawn extent came out at exactly `x[31%, 69%] y[3%, 85%]` at every
+ * one — same fractions, no clipping. That size-independence is what keeps the pet
+ * framed when the user resizes it, and holding the anchor at the surface centre is
+ * what makes the wheel zoom pivot on the character rather than pushing her aside.
+ *
+ * ## Why there is no coordinate conversion here
+ *
+ * Earlier revisions of this file tried to derive the camera from Cubism's canvas
+ * geometry. That is a trap, and the traps are recorded here so they are not re-entered:
+ *
+ * - The container's transform space is NOT `model.width` x `model.height`. At
+ *   `scale = 1, position = (0, 0)` the character is drawn far outside a 6000x9000
+ *   area, and `getLocalBounds()` disagrees with where the pixels actually land.
+ * - The two axes do not share a scale, so a single conversion factor is wrong.
+ * - A wrong camera does not throw. It renders a blank canvas or a plausible-looking
+ *   bad crop, which is why this file deals in measured constants and why
+ *   `scripts/verify-framing.mjs` asserts the invariants that must hold.
+ * @module dsh-pet-live2d-viola/framing
+ */
+
+/**
+ * Selectable framing presets.
+ *
+ * - `zoom` multiplies the whole-body scale. 1.0 is exactly whole-body; larger zooms
+ *   in. This is the one number to change when a preset looks too big or too small.
+ * - `xNudge` / `yNudge` shift the preset by a fraction of the surface, for presets
+ *   whose subject is not the body's centre. Positive y moves her DOWN.
+ *
+ * The zooms are capped just under the point where the scale about the anchor pushes her
+ * head out of the top of the frame: measured, `zoom` above about 1.22 clips her head no
+ * matter how the window is nudged, because the anchor that centres her body is below
+ * her face. The two close-ups are therefore close-ups of her upper body rather than
+ * extreme face crops, which is the trade the geometry forces.
+ */
+export const CROP_PRESETS = {
+	full: { zoom: 1.0, xNudge: 0, yNudge: 0 },
+	threeQuarter: { zoom: 1.683715, xNudge: 0.126145, yNudge: 0.286624 },
+	bust: { zoom: 2.09088, xNudge: 0.218024, yNudge: 0.517619 }
+};
+
+/** Preset used when neither the snapshot nor the config names a valid one. */
+export const DEFAULT_CROP_PRESET = "full";
+
+/**
+ * Container scale per renderer pixel of surface height, for the whole character.
+ *
+ * Measured: on a 240x360 surface her whole body frames at container scale 0.04, and
+ * the same fraction held at every other size tested. Expressed per pixel so it holds
+ * for any window size the user drags to.
+ */
+export const BODY_SCALE_PER_PIXEL = 0.04 / 360;
+
+/**
+ * Where to place the container, as a fraction of the surface.
+ *
+ * These are NOT 0.5. The verified full-body render on a 240x360 surface used
+ * `position = (41.7, -1.4)` at container scale 0.04, i.e. an offset of `(-78.3,
+ * -181.4)` px from the surface centre, or `(-0.326, -0.504)` of it. The model's origin
+ * sits well above and right of her body, so anchoring at the surface centre draws her
+ * into the corner — which is exactly what it did before this was measured.
+ *
+ * The camera scales the offset with the zoom, which keeps the same point on her fixed
+ * as she grows. That is what makes the wheel zoom pivot on the character.
+ */
+/**
+ * Horizontal anchor, as a fraction of the surface WIDTH.
+ *
+ * Re-expressed against the widened surface, and then nudged so she sits centred in it:
+ * measured on the 480 px-wide box, the verified offset of `41.7 - 120 = -78.3` px put
+ * her centre at x 281 of 480, i.e. 41 px right of the middle, so the offset carries that
+ * correction too. Width is `height * SURFACE_ASPECT`, i.e. 480 px for a 360 px-tall
+ * surface, so the fraction has to be held against that width or she slides sideways
+ * whenever the box's shape changes.
+ */
+export const BODY_ANCHOR_X = -0.578389236;
+/**
+ * Vertical anchor, expressed against the surface WIDTH rather than its height.
+ *
+ * That choice is what lets the frame grow downwards. A height-relative anchor moves the
+ * character up as the box gets taller — at height 720 the verified offset would have
+ * become -362.8 px and pushed her out of the top of the frame entirely. Holding the
+ * anchor against the width, which does not change when only the height grows, keeps her
+ * exactly where she was and adds the new room BELOW her feet.
+ *
+ * The verified offset on a 480x360 surface was `-1.4 - 180 = -181.4` px. A further
+ * `+19.5` px was added after measuring the rendered result, which put her drawn centre at
+ * 232.5 of 504 where the box centre is 252 — she sat 19.5 px high — so the anchor carries
+ * that correction and lands her in the middle of the frame.
+ */
+export const BODY_ANCHOR_Y = -0.907292000;
+
+/**
+ * The pet surface is a landscape-ish box, twice as wide as it is tall.
+ *
+ * It was 2/3 (a portrait box) and is now 4/3: the portrait box left no room beside her
+ * and the character read as cut off on the right, so the framing was widened to give her
+ * horizontal space. One number defines the shape for both the CSS element and the
+ * camera, which keeps them from disagreeing about it.
+ */
+export const SURFACE_ASPECT = 4 / 3 * 0.626763;
+
+/**
+ * Extra surface height, as a multiple of the base height, added BELOW the character.
+ *
+ * The frame was widened first (see {@link SURFACE_ASPECT}); this extends it downwards so
+ * her feet have room under them. The width is unchanged, and because
+ * {@link BODY_ANCHOR_Y} is held against the width, the character keeps the exact
+ * position she was verified at — the new room appears below her rather than lifting her
+ * out of the top. The scale is unchanged too, so she does not shrink.
+ */
+export const SURFACE_HEIGHT_EXTEND = 1.4;
+
+/**
+ * The character's drawn extent, as viewport fractions, at `zoom = 1`.
+ *
+ * Measured from rendered frames, not derived — see the module note. Used by
+ * `scripts/verify-framing.mjs` to assert that the whole-body preset still shows all of
+ * her, and by anything that needs to place furniture around her.
+ */
+export const MEASURED_BODY_EXTENT = { left: 0.31, right: 0.69, top: 0.03, bottom: 0.85 };
+
+/** Narrow an unknown framing name to a real preset key. */
+export function resolveCropPreset(name) {
+	return Object.hasOwn(CROP_PRESETS, name) ? name : DEFAULT_CROP_PRESET;
+}
+
+/** The preset's settings, falling back to the default for an unknown name. */
+export function presetFor(name) {
+	return CROP_PRESETS[resolveCropPreset(name)];
+}
+
+/**
+ * Container scale for a preset.
+ *
+ * Proportional to the surface height, so the pet's `height` setting stays the one thing
+ * that makes her bigger or smaller. {@link SURFACE_HEIGHT_EXTEND} deliberately does not
+ * appear here: it changes the frame's SHAPE, not her size, and folding it in made her
+ * shrink whenever the frame was extended.
+ *
+ * @param zoom - `CROP_PRESETS[name].zoom`.
+ * @param viewportHeight - the surface height in renderer pixels.
+ * @returns the container scale to apply.
+ */
+export function bodyScale(zoom, viewportHeight) {
+	return BODY_SCALE_PER_PIXEL * Math.max(1, viewportHeight) * zoom;
+}
+
+/**
+ * The container transform that shows a preset in a viewport.
+ *
+ * @param preset - a `CROP_PRESETS` key; unknown names fall back to the default.
+ * @param viewport - `{ width, height }` in renderer pixels.
+ * @returns `{ scale, x, y, preset }` for the model container.
+ */
+export function cameraFor(preset, viewport) {
+	const resolved = resolveCropPreset(preset);
+	const settings = CROP_PRESETS[resolved];
+	const height = Math.max(1, viewport.height);
+	// The viewport height includes the downward extension, so undo it to get the base
+	// height, then derive the width the way the layout does. Both agree on the box by
+	// construction.
+	const baseHeight = height / SURFACE_HEIGHT_EXTEND;
+	const width = baseHeight * SURFACE_ASPECT;
+	// Proportional to the BASE height, so extending the frame adds room rather than making
+	// her larger — the `height` setting stays the one control over her size.
+	const scale = bodyScale(settings.zoom, baseHeight);
+	return {
+		scale,
+		preset: resolved,
+		// The anchors are OFFSETS from the surface centre. x is held against the width and
+		// y against the width too, so growing only the height adds room BELOW her instead
+		// of lifting her out of the frame. The offsets scale with the zoom, which keeps the
+		// same point on her fixed and makes the wheel zoom pivot on the character.
+		x: width * (0.5 + BODY_ANCHOR_X * settings.zoom) + (settings.xNudge ?? 0) * width,
+		y: height * 0.5 + width * BODY_ANCHOR_Y * settings.zoom + (settings.yNudge ?? 0) * height,
+		/** Which preset produced this camera. */
+		zoom: settings.zoom
+	};
+}
+
+/**
+ * Where the character lands in the viewport, as fractions (0 = top/left, 1 =
+ * bottom/right). Negative or > 1 means clipped.
+ *
+ * Scaling a measured extent about the anchor is exact here because the camera zooms
+ * about the surface centre and the measurement was taken with the character centred on
+ * it: increasing the zoom by `k` multiplies her distance from the centre by `k`.
+ *
+ * @param preset - a `CROP_PRESETS` key.
+ * @returns the viewport-relative extent, or undefined for an unknown preset.
+ */
+export function projectExtent(preset) {
+	const resolved = resolveCropPreset(preset);
+	const settings = CROP_PRESETS[resolved];
+	const zoom = settings.zoom;
+	// Everything scales about the ANCHOR, because that is where the container sits:
+	// `extent(zoom) = anchor + (extent(1) - anchor) * zoom`. Scaling about the body's
+	// own centre instead reported her far lower than the render did, since the anchor is
+	// well above her body.
+	const scaleAbout = (value) => BODY_ANCHOR_X + (value - BODY_ANCHOR_X) * zoom;
+	const scaleAboutY = (value) => BODY_ANCHOR_Y + (value - BODY_ANCHOR_Y) * zoom;
+	const dx = settings.xNudge ?? 0;
+	const dy = settings.yNudge ?? 0;
+	return {
+		left: scaleAbout(MEASURED_BODY_EXTENT.left) + dx,
+		right: scaleAbout(MEASURED_BODY_EXTENT.right) + dx,
+		top: scaleAboutY(MEASURED_BODY_EXTENT.top) + dy,
+		bottom: scaleAboutY(MEASURED_BODY_EXTENT.bottom) + dy
+	};
+}
+
+/**
+ * Whether a preset's framing keeps the character inside the viewport.
+ *
+ * @param preset - a `CROP_PRESETS` key.
+ * @returns true when nothing is cut off.
+ */
+export function isUnclipped(preset) {
+	const e = projectExtent(preset);
+	return e.left >= 0 && e.right <= 1 && e.top >= 0 && e.bottom <= 1;
+}
+
+/**
+ * Measure a character's bounds in canvas space.
+ *
+ * Kept for diagnostics and for models whose framing might later need to adapt. The
+ * live camera does not consume it — see the module note on why deriving transforms
+ * from this geometry is a trap.
+ *
+ * Reads the core's own arrays rather than the pixi-live2d-display wrapper, whose
+ * `getDrawableVertexPositions` is a stub for Cubism 5 models. Every drawable is
+ * included: parts hidden in the current pose still lie inside the character's extent,
+ * so skipping them can only shrink the box below the truth.
+ *
+ * @param coreModel - `model.internalModel.coreModel`.
+ * @param canvas - `{ width, height }` of the model canvas, from the model itself.
+ * @returns bounds in canvas space, or undefined when no geometry is readable.
+ */
+export function measureBounds(coreModel, canvas) {
+	try {
+		const drawables = (coreModel?._model ?? coreModel)?.drawables;
+		if (drawables === undefined) return undefined;
+		const canvasWidth = canvas?.width;
+		const canvasHeight = canvas?.height;
+		if (!(canvasWidth > 0) || !(canvasHeight > 0)) return undefined;
+		// Normalised model units -> canvas space: [-1, 1] spans the canvas.
+		const toX = (v) => ((v + 1) / 2) * canvasWidth;
+		const toY = (v) => ((v + 1) / 2) * canvasHeight;
+		let minX = Infinity;
+		let minY = Infinity;
+		let maxX = -Infinity;
+		let maxY = -Infinity;
+		for (let i = 0; i < drawables.count; i += 1) {
+			const count = drawables.vertexCounts[i];
+			const positions = drawables.vertexPositions[i];
+			if (positions === undefined) continue;
+			for (let v = 0; v < count; v += 1) {
+				const x = toX(positions[v * 2]);
+				const y = toY(positions[v * 2 + 1]);
+				if (x < minX) minX = x;
+				if (x > maxX) maxX = x;
+				if (y < minY) minY = y;
+				if (y > maxY) maxY = y;
+			}
+		}
+		if (!Number.isFinite(minX) || !(maxY > minY)) return undefined;
+		return { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY };
+	} catch {
+		return undefined;
+	}
+}