@zkmake/three-cameras 0.0.0 → 0.2.0

package/dist/lab-D4PnOVwG.js

@@ -1,605 +0,0 @@
-import { CameraHelper, Euler, Quaternion, Vector3, Vector4 } from "three";
-//#region src/core/discover.ts
-const isCubeCamera = (object) => object.type === "CubeCamera";
-const isCamera = (object) => object.isCamera === true;
-const kindOf = (camera) => {
-	if (isCubeCamera(camera)) return "cube";
-	if (camera.isArrayCamera) return "array";
-	if (camera.isPerspectiveCamera) return "perspective";
-	if (camera.isOrthographicCamera) return "orthographic";
-	return "other";
-};
-/** Every camera under `root`, in scene order, `root` included. */
-const findCameras = (root) => {
-	const found = [];
-	const visit = (object) => {
-		if (isCubeCamera(object)) {
-			found.push(object);
-			return;
-		}
-		if (isCamera(object)) found.push(object);
-		for (const child of object.children) visit(child);
-	};
-	visit(root);
-	return found;
-};
-/** Where it sits: its ancestors' names (or types) from the root down, `scene › rig › cam`. */
-const pathOf = (object) => {
-	const path = [];
-	for (let node = object.parent; node; node = node.parent) path.unshift(node.name || node.type);
-	return path;
-};
-//#endregion
-//#region src/core/pose.ts
-/**
-* A camera's pose: where it is, which way it faces, and how it projects. Poses are what saved
-* views hold now and what keyframes will: capture one, put one back, and blend between two.
-*
-* Position and rotation are the camera's own (local, relative to its parent), so a pose put back
-* lands where it was taken even if the parent has moved since, the same way a keyframe would.
-*/
-const isPerspective = (camera) => camera.isPerspectiveCamera === true;
-const projects = (camera) => isPerspective(camera) || camera.isOrthographicCamera === true;
-const capturePose = (camera) => {
-	const { position, quaternion } = camera;
-	const pose = {
-		position: [
-			position.x,
-			position.y,
-			position.z
-		],
-		quaternion: [
-			quaternion.x,
-			quaternion.y,
-			quaternion.z,
-			quaternion.w
-		],
-		near: 0,
-		far: 0,
-		zoom: 1
-	};
-	if (projects(camera)) {
-		pose.near = camera.near;
-		pose.far = camera.far;
-		pose.zoom = camera.zoom;
-	}
-	if (isPerspective(camera)) pose.fov = camera.fov;
-	return pose;
-};
-const applyPose = (camera, pose) => {
-	camera.position.fromArray(pose.position);
-	camera.quaternion.fromArray(pose.quaternion);
-	if (projects(camera)) {
-		camera.near = pose.near;
-		camera.far = pose.far;
-		camera.zoom = pose.zoom;
-		if (isPerspective(camera) && pose.fov !== void 0) camera.fov = pose.fov;
-		camera.updateProjectionMatrix();
-	}
-};
-const lerp = (a, b, t) => a + (b - a) * t;
-const from = new Quaternion();
-const to = new Quaternion();
-const va = new Vector3();
-const vb = new Vector3();
-/** The pose `t` of the way from `a` to `b`: positions and lenses straight, rotation by slerp. */
-const blendPoses = (a, b, t) => {
-	const position = va.fromArray(a.position).lerp(vb.fromArray(b.position), t);
-	const quaternion = from.fromArray(a.quaternion).slerp(to.fromArray(b.quaternion), t);
-	const pose = {
-		position: [
-			position.x,
-			position.y,
-			position.z
-		],
-		quaternion: [
-			quaternion.x,
-			quaternion.y,
-			quaternion.z,
-			quaternion.w
-		],
-		near: lerp(a.near, b.near, t),
-		far: lerp(a.far, b.far, t),
-		zoom: lerp(a.zoom, b.zoom, t)
-	};
-	if (a.fov !== void 0 && b.fov !== void 0) pose.fov = lerp(a.fov, b.fov, t);
-	return pose;
-};
-/** Slow in, slow out: a camera move that starts and settles gently. */
-const easeInOut = (t) => t < .5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
-const round = (value, digits = 4) => {
-	const text = value.toFixed(digits);
-	return text.includes(".") ? text.replace(/\.?0+$/, "") : text;
-};
-/** Three.js to recreate the pose on a camera called `name`. */
-const poseToCode = (pose, name = "camera") => {
-	const [x, y, z, w] = pose.quaternion;
-	const lines = [`${name}.position.set(${pose.position.map((value) => round(value)).join(", ")});`, `${name}.quaternion.set(${[
-		x,
-		y,
-		z,
-		w
-	].map((value) => round(value, 5)).join(", ")});`];
-	if (pose.fov !== void 0) lines.push(`${name}.fov = ${round(pose.fov, 2)};`);
-	if (pose.zoom !== 1) lines.push(`${name}.zoom = ${round(pose.zoom, 3)};`);
-	lines.push(`${name}.near = ${round(pose.near)};`, `${name}.far = ${round(pose.far)};`);
-	lines.push(`${name}.updateProjectionMatrix();`);
-	return lines.join("\n");
-};
-//#endregion
-//#region src/core/lab.ts
-/**
-* `CameraLab`: the cameras a scene has and the ones drawing it. No UI; the panel drives it.
-*
-* Cameras come from two places: the scene graph, and the renderer. The camera an app renders with
-* is often not in the scene at all (R3F's default camera isn't; most vanilla apps never add
-* theirs), so the lab wraps `renderer.render` and notes every camera it's handed: that's how it
-* knows which are live, and how often each draws.
-*
-* Entries are named by the `cameras` option, else the camera's name, else its kind, numbered when
-* they repeat. A name holds for as long as the camera is listed, and saved views are kept by it.
-*
-* The same watch lets the lab act on frames: "look through" hands the renderer another camera in
-* place of the app's main one (fitted to its aspect for that frame), and a move to a saved view
-* steps once per frame, before the frame draws.
-*/
-/** Rendered this recently counts as live, ms. */
-const LIVE_MS = 500;
-/** A camera outside the scene stays listed this long after its last frame, ms. */
-const KEEP_MS = 5e3;
-/** A move to a saved view, ms. */
-const MOVE_MS = 800;
-const memoryViews = () => {
-	let views = {};
-	return {
-		load: () => views,
-		save: (next) => {
-			views = next;
-		}
-	};
-};
-const KIND_LABELS = {
-	perspective: "perspective",
-	orthographic: "orthographic",
-	array: "array",
-	cube: "cube",
-	other: "camera"
-};
-const now = () => typeof performance === "undefined" ? Date.now() : performance.now();
-const toDegrees = (radians) => radians * 180 / Math.PI;
-const toRadians = (degrees) => degrees * Math.PI / 180;
-const projectionOf = (camera, kind) => {
-	if (kind === "perspective" || kind === "array") {
-		const { near, far, zoom, fov, aspect } = camera;
-		return {
-			near,
-			far,
-			zoom,
-			fov,
-			aspect
-		};
-	}
-	if (kind === "orthographic") {
-		const { near, far, zoom, left, right, top, bottom } = camera;
-		return {
-			near,
-			far,
-			zoom,
-			left,
-			right,
-			top,
-			bottom
-		};
-	}
-	return null;
-};
-var CameraLab = class {
-	options;
-	records = /* @__PURE__ */ new Map();
-	byId = /* @__PURE__ */ new Map();
-	listeners = /* @__PURE__ */ new Set();
-	tweens = /* @__PURE__ */ new Map();
-	store;
-	saved;
-	restoreRender = null;
-	/** Look-through: the camera shown, and the app camera it stands in for. */
-	looking = null;
-	standIn = null;
-	/** The frame being drawn: what to put back after it. */
-	fitted = null;
-	viewport = new Vector4();
-	notifyQueued = false;
-	disposed = false;
-	constructor(options) {
-		this.options = options;
-		this.store = options.store ?? memoryViews();
-		this.saved = { ...this.store.load() };
-		this.watch(options.renderer);
-		this.refresh();
-	}
-	/** Whether the lab sees frames: look-through and animated moves need a renderer. */
-	get watching() {
-		return this.restoreRender !== null;
-	}
-	subscribe(listener) {
-		this.listeners.add(listener);
-		return () => {
-			this.listeners.delete(listener);
-		};
-	}
-	/** Every camera, in scene order; ones only the renderer knows about after. */
-	entries() {
-		const time = now();
-		return [...this.byId.values()].map((item) => this.entryOf(item, time));
-	}
-	entry(id) {
-		const item = this.byId.get(id);
-		return item ? this.entryOf(item, now()) : null;
-	}
-	/** Where it is and how it projects, read now. */
-	details(id) {
-		const item = this.byId.get(id);
-		if (!item) return null;
-		const { camera } = item;
-		const position = new Vector3();
-		const quaternion = new Quaternion();
-		camera.updateWorldMatrix(true, false);
-		camera.matrixWorld.decompose(position, quaternion, new Vector3());
-		const euler = new Euler().setFromQuaternion(quaternion);
-		const own = camera.rotation;
-		return {
-			position: [
-				position.x,
-				position.y,
-				position.z
-			],
-			rotation: [
-				toDegrees(euler.x),
-				toDegrees(euler.y),
-				toDegrees(euler.z)
-			],
-			local: {
-				position: [
-					camera.position.x,
-					camera.position.y,
-					camera.position.z
-				],
-				rotation: [
-					toDegrees(own.x),
-					toDegrees(own.y),
-					toDegrees(own.z)
-				]
-			},
-			projection: projectionOf(camera, item.kind)
-		};
-	}
-	/**
-	* Change a camera: its own position or rotation, or its lens. The projection updates, and a
-	* render-on-demand loop gets a frame. An app that sets the camera every frame wins on the next.
-	*/
-	set(id, patch) {
-		const item = this.require(id);
-		const camera = item.camera;
-		if (patch.position) camera.position.set(...patch.position);
-		if (patch.rotation) {
-			const [x, y, z] = patch.rotation.map(toRadians);
-			camera.rotation.set(x, y, z);
-		}
-		if (this.projects(item)) {
-			const lens = camera;
-			if (patch.near !== void 0) lens.near = patch.near;
-			if (patch.far !== void 0) lens.far = patch.far;
-			if (patch.zoom !== void 0) lens.zoom = patch.zoom;
-			if (patch.fov !== void 0 && item.kind === "perspective") lens.fov = patch.fov;
-			lens.updateProjectionMatrix();
-		}
-		this.tweens.delete(item);
-		this.options.invalidate?.();
-	}
-	/**
-	* Show the main view through `id`, or back through the app's own camera with `null`. The camera
-	* it stands in for is the app's main view: the one drawing the most of the screen (a
-	* picture-in-picture inset or a render target loses to it), most often on a tie.
-	*/
-	lookThrough(id) {
-		if (id === null || this.looking?.id === id) {
-			this.looking = null;
-			this.standIn = null;
-		} else {
-			const item = this.require(id);
-			if (!this.projects(item)) throw new Error(`three-cameras: "${id}" can't be looked through (${item.kind})`);
-			const time = now();
-			const main = [...this.records.values()].filter((other) => other !== item && isCamera(other.camera)).map((other) => ({
-				other,
-				fps: other.frames.filter((at) => time - at <= 1e3).length
-			})).filter(({ fps }) => fps > 0).sort((a, b) => b.other.area - a.other.area || b.fps - a.fps)[0];
-			if (!main) throw new Error("three-cameras: no camera is drawing, so there's no view to look through");
-			this.looking = item;
-			this.standIn = main.other.camera;
-		}
-		this.options.invalidate?.();
-		this.notify();
-	}
-	/** Save where the camera is and how it projects, as a view to go back to. */
-	saveView(id, name) {
-		const item = this.require(id);
-		if (!this.projects(item)) throw new Error(`three-cameras: "${id}" has no lens to save (${item.kind})`);
-		const list = this.saved[id] ?? [];
-		const taken = new Set(list.map((view) => view.name));
-		let label = name ?? `view ${list.length + 1}`;
-		for (let n = 2; taken.has(label); n += 1) label = `${name ?? "view"} ${n}`;
-		const view = {
-			id: `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
-			name: label,
-			pose: capturePose(item.camera)
-		};
-		this.saved = {
-			...this.saved,
-			[id]: [...list, view]
-		};
-		this.store.save(this.saved);
-		this.notify();
-		return view;
-	}
-	views(id) {
-		return this.saved[id] ?? [];
-	}
-	deleteView(id, viewId) {
-		const list = this.saved[id] ?? [];
-		this.saved = {
-			...this.saved,
-			[id]: list.filter((view) => view.id !== viewId)
-		};
-		this.store.save(this.saved);
-		this.notify();
-	}
-	/**
-	* Move the camera to a saved view: eased over `duration` ms, stepped once per frame (so it needs
-	* a renderer; without one, or with `duration: 0`, it lands at once).
-	*/
-	goToView(id, viewId, { duration = MOVE_MS } = {}) {
-		const item = this.require(id);
-		const view = this.views(id).find((saved) => saved.id === viewId);
-		if (!view) throw new Error(`three-cameras: "${id}" has no saved view "${viewId}"`);
-		const camera = item.camera;
-		if (duration <= 0 || !this.watching) {
-			this.tweens.delete(item);
-			applyPose(camera, view.pose);
-		} else this.tweens.set(item, {
-			from: capturePose(camera),
-			to: view.pose,
-			start: now(),
-			duration
-		});
-		this.options.invalidate?.();
-	}
-	/**
-	* Look at the scene again: new cameras get entries, ones that left go (a camera outside the
-	* scene stays while it's still rendering, and a few seconds after).
-	*/
-	refresh() {
-		if (this.disposed) return;
-		const time = now();
-		const listed = /* @__PURE__ */ new Set();
-		let changed = false;
-		for (const camera of findCameras(this.options.scene)) listed.add(camera);
-		for (const info of this.options.cameras ?? []) listed.add(info.camera);
-		for (const [camera, item] of this.records) {
-			const last = item.frames.at(-1);
-			if (last !== void 0 && time - last < KEEP_MS || camera === this.standIn) listed.add(camera);
-		}
-		for (const camera of listed) if (!this.records.has(camera)) {
-			this.add(camera);
-			changed = true;
-		}
-		for (const [camera, item] of this.records) if (!listed.has(camera)) {
-			this.remove(item);
-			changed = true;
-		}
-		if (this.looking && !this.records.has(this.looking.camera)) {
-			this.looking = null;
-			this.standIn = null;
-		}
-		if (changed) this.notify();
-	}
-	/** Show or hide a camera's frustum. The helper sits in the lab's scene and follows the camera. */
-	setHelper(id, on) {
-		const item = this.require(id);
-		if (on === (item.helper !== null)) return;
-		if (on) {
-			if (!this.canHelp(item)) throw new Error(`three-cameras: "${id}" has no frustum to draw (${item.kind})`);
-			const helper = new CameraHelper(item.camera);
-			helper.name = `${id} (three-cameras helper)`;
-			helper.userData.threeCameras = true;
-			this.options.scene.add(helper);
-			item.helper = helper;
-		} else this.dropHelper(item);
-		this.options.invalidate?.();
-		this.notify();
-	}
-	dispose() {
-		this.disposed = true;
-		for (const item of this.records.values()) this.dropHelper(item);
-		this.looking = null;
-		this.standIn = null;
-		this.tweens.clear();
-		this.restoreRender?.();
-		this.restoreRender = null;
-		this.listeners.clear();
-	}
-	watch(renderer) {
-		const target = renderer;
-		if (!target || typeof target.render !== "function") return;
-		const render = target.render;
-		const own = Object.hasOwn(target, "render");
-		const before = (camera, host) => this.beforeFrame(camera, host);
-		const after = () => this.afterFrame();
-		const watched = function(scene, camera, ...rest) {
-			const shown = before(camera, this);
-			try {
-				return render.call(this, scene, shown, ...rest);
-			} finally {
-				after();
-			}
-		};
-		target.render = watched;
-		this.restoreRender = () => {
-			if (target.render !== watched) return;
-			if (own) target.render = render;
-			else delete target.render;
-		};
-	}
-	/** Before a frame: count it, step moves, and pick the camera it's drawn with. */
-	beforeFrame(camera, host) {
-		if (this.disposed || !camera) return camera;
-		const time = now();
-		this.count(camera, time);
-		this.measure(camera, host);
-		this.step(time);
-		let shown = camera;
-		if (this.looking && camera === this.standIn) {
-			shown = this.looking.camera;
-			this.count(shown, time);
-			const lens = shown;
-			const view = camera;
-			if (lens.isPerspectiveCamera && view.isPerspectiveCamera && lens.aspect !== view.aspect) {
-				this.fitted = {
-					camera: lens,
-					aspect: lens.aspect
-				};
-				lens.aspect = view.aspect;
-				lens.updateProjectionMatrix();
-			}
-		}
-		for (const other of this.records.values()) if (other.helper) {
-			other.helper.visible = other.camera !== shown;
-			other.helper.update();
-		}
-		return shown;
-	}
-	afterFrame() {
-		if (this.fitted) {
-			this.fitted.camera.aspect = this.fitted.aspect;
-			this.fitted.camera.updateProjectionMatrix();
-			this.fitted = null;
-		}
-	}
-	/** How much of the screen this frame covers, if the renderer says. */
-	measure(camera, host) {
-		const item = this.records.get(camera);
-		if (!item || typeof host?.getCurrentViewport !== "function") return;
-		const offscreen = typeof host.getRenderTarget === "function" && host.getRenderTarget() !== null;
-		const viewport = host.getCurrentViewport(this.viewport);
-		item.area = offscreen ? 0 : viewport.z * viewport.w;
-	}
-	count(camera, time) {
-		const item = this.records.get(camera);
-		if (item) {
-			item.frames.push(time);
-			while (item.frames.length > 0 && time - item.frames[0] > 1e3) item.frames.shift();
-		} else if (this.findOwner(camera) === null) {
-			this.add(camera).frames.push(time);
-			this.notifySoon();
-		}
-	}
-	/** Moves to saved views, one step per frame. */
-	step(time) {
-		if (this.tweens.size === 0) return;
-		for (const [item, tween] of this.tweens) {
-			const t = Math.min(1, (time - tween.start) / tween.duration);
-			applyPose(item.camera, blendPoses(tween.from, tween.to, easeInOut(t)));
-			if (t >= 1) this.tweens.delete(item);
-		}
-		this.options.invalidate?.();
-	}
-	/** A camera the renderer was handed that belongs to one listed, like a CubeCamera's faces. */
-	findOwner(camera) {
-		for (let node = camera.parent; node; node = node.parent) if (this.records.has(node)) return node;
-		return null;
-	}
-	canHelp(item) {
-		return this.projects(item);
-	}
-	projects(item) {
-		return item.kind === "perspective" || item.kind === "orthographic";
-	}
-	add(camera) {
-		const kind = kindOf(camera);
-		const registered = this.options.cameras?.find((info) => info.camera === camera)?.name;
-		const id = this.uniqueName(registered || camera.name || `${KIND_LABELS[kind]} camera`);
-		const item = {
-			id,
-			camera,
-			kind,
-			helper: null,
-			frames: [],
-			area: 0
-		};
-		this.records.set(camera, item);
-		this.byId.set(id, item);
-		return item;
-	}
-	remove(item) {
-		this.dropHelper(item);
-		this.tweens.delete(item);
-		this.records.delete(item.camera);
-		this.byId.delete(item.id);
-	}
-	dropHelper(item) {
-		if (item.helper) {
-			item.helper.removeFromParent();
-			item.helper.dispose();
-			item.helper = null;
-		}
-	}
-	uniqueName(base) {
-		let name = base;
-		for (let n = 2; this.byId.has(name); n += 1) name = `${base} ${n}`;
-		return name;
-	}
-	inScene(camera) {
-		let top = camera;
-		while (top.parent) top = top.parent;
-		return top === this.options.scene;
-	}
-	entryOf(item, time) {
-		const recent = item.frames.filter((at) => time - at <= 1e3);
-		const last = recent.at(-1);
-		return {
-			id: item.id,
-			kind: item.kind,
-			camera: item.camera,
-			inScene: this.inScene(item.camera),
-			live: last !== void 0 && time - last < LIVE_MS,
-			fps: recent.length,
-			helper: item.helper !== null,
-			canHelp: this.canHelp(item),
-			path: pathOf(item.camera),
-			projects: this.projects(item),
-			viewing: this.looking === item,
-			standingIn: this.looking !== null && this.standIn === item.camera,
-			views: this.saved[item.id]?.length ?? 0
-		};
-	}
-	require(id) {
-		const item = this.byId.get(id);
-		if (!item) throw new Error(`three-cameras: no camera "${id}"`);
-		return item;
-	}
-	notifySoon() {
-		if (!this.notifyQueued) {
-			this.notifyQueued = true;
-			queueMicrotask(() => {
-				this.notifyQueued = false;
-				this.notify();
-			});
-		}
-	}
-	notify() {
-		for (const listener of this.listeners) listener();
-	}
-};
-//#endregion
-export { easeInOut as a, isCamera as c, pathOf as d, capturePose as i, isCubeCamera as l, applyPose as n, poseToCode as o, blendPoses as r, findCameras as s, CameraLab as t, kindOf as u };
-
-//# sourceMappingURL=lab-D4PnOVwG.js.map