@zkmake/three-cameras 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zubin Khavarian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @zkmake/three-cameras
+
+A dev panel for the cameras in a three.js scene. It lists every camera: the ones in the scene
+graph, and the one the renderer draws with even when it isn't in the scene (R3F's default camera,
+most vanilla apps' main camera). It marks which cameras are drawing right now and how often,
+reads each one's position and projection live, and draws a camera's frustum in the scene.
+
+Pick a camera and you control it: edit its position, rotation and lens by typing or scrubbing, look
+through it in place of the app's main view, copy its setup as code, and save views to fly back to.
+Keyframed camera moves with curve and graph editors are next.
+
+```sh
+bun add -d @zkmake/three-cameras   # or npm i -D / yarn add -D / pnpm add -D
+```
+
+Live demo: [three-kit.pages.dev/three-cameras](https://three-kit.pages.dev/three-cameras/), with a
+vanilla three and a React Three Fiber take on the same set: an orbit view, a dolly camera circling
+the set and drawing a picture-in-picture inset, an overhead orthographic camera and a security
+camera.
+
+## Vanilla three
+
+```ts
+import { mountCameraPanel } from "@zkmake/three-cameras/ui";
+
+const panel = mountCameraPanel({ scene, renderer });
+// later: panel.dispose()
+```
+
+## React Three Fiber
+
+```tsx
+import { CameraPanel } from "@zkmake/three-cameras/react";
+
+<Canvas>
+  <CameraPanel />
+</Canvas>;
+```
+
+It reads the scene and renderer from the canvas, so the canvas's camera shows as live, and asks for
+a frame after a frustum toggles, so `frameloop="demand"` works.
+
+## What each row shows
+
+| Part          | What it is                                                                                    |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| icon          | The kind: perspective, orthographic, array or cube. Green while the camera draws.             |
+| live · 60 fps | It drew a frame in the last half second, and how many in the last second                      |
+| second line   | fov, near–far and aspect (perspective), or zoom and near–far (orthographic); "not in scene"   |
+| look through  | Show the main view through it (see below)                                                     |
+| frustum       | Draw its view volume in the scene. It follows the camera, and hides while you look through it |
+
+Rows are named by the `cameras` option, else the camera's `name`, else its kind (`perspective camera
+2`). Name your cameras and the panel reads better.
+
+## Controlling a camera
+
+Pick a row (click its name) and it opens into the camera's controls:
+
+- **Position and rotation**, its own (relative to its parent), rotation in degrees, and **lens**: fov,
+  near, far and zoom. Type a value, or drag a field's label to scrub it: Shift for fine steps, Alt
+  for coarse. An app that sets the camera every frame wins on its next frame.
+- **Copy as code**: three.js that sets the camera up as it is now, named after the camera.
+- **Save view**: keeps where it is and how it projects. Click a saved view to fly back to it (eased
+  over 0.8 s); the docked panel keeps them in localStorage, by camera name.
+- A readout of what isn't edited here: world position, aspect, frame rate, where it sits.
+
+**Look through** swaps a camera into the app's main view: the view drawing the most of the screen,
+so a picture-in-picture inset or a render target keeps its own camera. The camera is fitted to that
+view's aspect for the frame and put back after, and the app's camera is left where it was. A banner
+shows what you're looking through, with a way back.
+
+## How it finds cameras
+
+- **The scene graph:** anything with `isCamera` under `scene`. A `CubeCamera` is one row; its six face
+  cameras aren't listed.
+- **The renderer:** the lab wraps `renderer.render` on the instance and notes every camera it's
+  handed. A camera the scene doesn't hold gets a row on its first frame and stays while it keeps
+  drawing (a few seconds after it stops). Post-processing that calls `renderer.render` counts too.
+
+`dispose()` puts `render` back, unless something wrapped it after the panel did, in which case the
+panel's wrapper stays in place and just passes through.
+
+## Options
+
+| Option             | Default                             | What it does                                                                      |
+| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
+| `scene`            | required                            | Where to look for cameras, and where frustum helpers go                           |
+| `renderer`         | none                                | Watched for the cameras it draws with; without it nothing is "live"               |
+| `cameras`          | `[]`                                | `{ name, camera }` to list whether or not the scene holds them yet                |
+| `invalidate`       | none                                | Ask for frames after an edit, a toggle, or during a move (render-on-demand loops) |
+| `store`            | localStorage, by `storageKey`       | Where saved views live: `{ load(), save(views) }`                                 |
+| `storageKey`       | `"three-cameras"`                   | localStorage prefix for the dock and compact state; `null` for none               |
+| `defaultPlacement` | `{ edge: "right", align: "start" }` | Where it docks on a first visit                                                   |
+| `theme`            | `"system"`                          | `"dark"`, `"light"` or `"system"`                                                 |
+| `compact`          | `false`                             | Start compact, showing the brand row and the count                                |
+| `container`        | `document.body`                     | Where to mount                                                                    |
+
+## The engine
+
+`CameraLab` is the panel's engine, with no DOM, for scripting or a panel of your own:
+
+```ts
+import { CameraLab } from "@zkmake/three-cameras";
+import { createCameraPanel } from "@zkmake/three-cameras/ui";
+
+const lab = new CameraLab({ scene, renderer });
+
+lab.entries(); // [{ id, kind, camera, inScene, live, fps, helper, viewing, views, … }]
+lab.details("dolly"); // { position, rotation, local: { position, rotation }, projection }
+lab.set("dolly", { fov: 30, position: [0, 2, 8] });
+lab.lookThrough("dolly"); // null to go back
+lab.setHelper("dolly", true);
+
+const home = lab.saveView("dolly", "home");
+lab.goToView("dolly", home.id, { duration: 800 });
+
+tab.append(createCameraPanel(lab).element); // the bare panel, for a host with its own tabs
+```
+
+## The dev-panel frame
+
+It docks in three-meter's `mountDevPanel`, so it drags, snaps to an edge, compacts and dims exactly
+like the three-meter HUD and the three-textures panel, with its brand label on top.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { C as pathOf, S as kindOf, _ as CameraKind, a as CameraLabOptions, b as isCamera, c as RendererLike, d as Pose, f as applyPose, g as poseToCode, h as easeInOut, i as CameraLab, l as SavedView, m as capturePose, n as CameraEntry, o as CameraPatch, p as blendPoses, r as CameraInfo, s as Projection, t as CameraDetails, u as ViewStore, v as SceneCamera, x as isCubeCamera, y as findCameras } from "./lab-AaEFBp_R.js";
+export { type CameraDetails, type CameraEntry, type CameraInfo, type CameraKind, CameraLab, type CameraLabOptions, type CameraPatch, type Pose, type Projection, type RendererLike, type SavedView, type SceneCamera, type ViewStore, applyPose, blendPoses, capturePose, easeInOut, findCameras, isCamera, isCubeCamera, kindOf, pathOf, poseToCode };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as easeInOut, c as isCamera, d as pathOf, i as capturePose, l as isCubeCamera, n as applyPose, o as poseToCode, r as blendPoses, s as findCameras, t as CameraLab, u as kindOf } from "./lab-D4PnOVwG.js";
+export { CameraLab, applyPose, blendPoses, capturePose, easeInOut, findCameras, isCamera, isCubeCamera, kindOf, pathOf, poseToCode };

package/dist/lab-AaEFBp_R.d.ts

@@ -0,0 +1,206 @@
+import { Camera, Object3D } from "three";
+//#region src/core/discover.d.ts
+type CameraKind = "perspective" | "orthographic" | "array" | "cube" | "other";
+/** A camera, or a `CubeCamera`, which is an `Object3D` holding six. */
+type SceneCamera = Camera | Object3D;
+declare const isCubeCamera: (object: Object3D) => boolean;
+declare const isCamera: (object: Object3D) => object is Camera;
+declare const kindOf: (camera: SceneCamera) => CameraKind;
+/** Every camera under `root`, in scene order, `root` included. */
+declare const findCameras: (root: Object3D) => SceneCamera[];
+/** Where it sits: its ancestors' names (or types) from the root down, `scene › rig › cam`. */
+declare const pathOf: (object: Object3D) => string[];
+//#endregion
+//#region src/core/pose.d.ts
+type Pose = {
+  position: [number, number, number];
+  /** x, y, z, w. */
+  quaternion: [number, number, number, number];
+  near: number;
+  far: number;
+  zoom: number;
+  /** Perspective cameras only. */
+  fov?: number;
+};
+declare const capturePose: (camera: Camera) => Pose;
+declare const applyPose: (camera: Camera, pose: Pose) => void;
+/** The pose `t` of the way from `a` to `b`: positions and lenses straight, rotation by slerp. */
+declare const blendPoses: (a: Pose, b: Pose, t: number) => Pose;
+/** Slow in, slow out: a camera move that starts and settles gently. */
+declare const easeInOut: (t: number) => number;
+/** Three.js to recreate the pose on a camera called `name`. */
+declare const poseToCode: (pose: Pose, name?: string) => string;
+//#endregion
+//#region src/core/lab.d.ts
+type CameraInfo = {
+  name: string;
+  camera: SceneCamera;
+};
+/** The part of a renderer the lab needs: `render(scene, camera)`. */
+type RendererLike = {
+  render: (scene: Object3D, camera: Camera, ...rest: never[]) => unknown;
+};
+type CameraLabOptions = {
+  /** Where to look for cameras, and where frustum helpers go. */
+  scene: Object3D;
+  /** A three renderer: its `render` is watched, so cameras outside the scene show up and live ones are marked. */
+  renderer?: unknown;
+  /** Cameras to list whether or not the scene holds them yet, with names. */
+  cameras?: readonly CameraInfo[];
+  /** Ask for a frame, for render-on-demand loops (R3F `frameloop="demand"`). */
+  invalidate?: () => void;
+  /** Where saved views live. Default: this page only. */
+  store?: ViewStore;
+};
+/** A pose saved on a camera, to go back to. */
+type SavedView = {
+  id: string;
+  name: string;
+  pose: Pose;
+};
+/** Saved views by camera name. `mountCameraPanel` keeps them in localStorage. */
+type ViewStore = {
+  load(): Record<string, SavedView[]>;
+  save(views: Record<string, SavedView[]>): void;
+};
+/** Values to set on a camera. Position and rotation are its own (local); rotation in degrees. */
+type CameraPatch = {
+  position?: readonly [number, number, number];
+  rotation?: readonly [number, number, number];
+  fov?: number;
+  near?: number;
+  far?: number;
+  zoom?: number;
+};
+type CameraEntry = {
+  id: string;
+  kind: CameraKind;
+  camera: SceneCamera;
+  /** Under the lab's scene. A camera only the renderer knows about isn't. */
+  inScene: boolean;
+  /** Drew a frame in the last half second. */
+  live: boolean;
+  /** Frames drawn with it in the last second. */
+  fps: number;
+  /** Its frustum helper is showing. */
+  helper: boolean;
+  /** A frustum helper can draw it: perspective and orthographic cameras. */
+  canHelp: boolean;
+  /** Its ancestors, root first. */
+  path: string[];
+  /** Perspective or orthographic: its lens can be edited, looked through and saved. */
+  projects: boolean;
+  /** The main view shows through it now. */
+  viewing: boolean;
+  /** The app's camera that it's standing in for, while another is looked through. */
+  standingIn: boolean;
+  /** Saved views on it. */
+  views: number;
+};
+type Projection = {
+  near: number;
+  far: number;
+  zoom: number;
+  /** Perspective: vertical field of view in degrees, and aspect. */
+  fov?: number;
+  aspect?: number;
+  /** Orthographic: the frustum's sides. */
+  left?: number;
+  right?: number;
+  top?: number;
+  bottom?: number;
+};
+type CameraDetails = {
+  /** World position. */
+  position: [number, number, number];
+  /** World rotation, XYZ Euler in degrees. */
+  rotation: [number, number, number];
+  /** Its own position and rotation (degrees), relative to its parent: what `set` changes. */
+  local: {
+    position: [number, number, number];
+    rotation: [number, number, number];
+  };
+  projection: Projection | null;
+};
+declare class CameraLab {
+  private readonly options;
+  private readonly records;
+  private readonly byId;
+  private readonly listeners;
+  private readonly tweens;
+  private readonly store;
+  private saved;
+  private restoreRender;
+  /** Look-through: the camera shown, and the app camera it stands in for. */
+  private looking;
+  private standIn;
+  /** The frame being drawn: what to put back after it. */
+  private fitted;
+  private readonly viewport;
+  private notifyQueued;
+  private disposed;
+  constructor(options: CameraLabOptions);
+  /** Whether the lab sees frames: look-through and animated moves need a renderer. */
+  get watching(): boolean;
+  subscribe(listener: () => void): () => void;
+  /** Every camera, in scene order; ones only the renderer knows about after. */
+  entries(): CameraEntry[];
+  entry(id: string): CameraEntry | null;
+  /** Where it is and how it projects, read now. */
+  details(id: string): CameraDetails | null;
+  /**
+   * 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: string, patch: CameraPatch): void;
+  /**
+   * 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: string | null): void;
+  /** Save where the camera is and how it projects, as a view to go back to. */
+  saveView(id: string, name?: string): SavedView;
+  views(id: string): SavedView[];
+  deleteView(id: string, viewId: string): void;
+  /**
+   * 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: string, viewId: string, { duration }?: {
+    duration?: number;
+  }): void;
+  /**
+   * 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(): void;
+  /** Show or hide a camera's frustum. The helper sits in the lab's scene and follows the camera. */
+  setHelper(id: string, on: boolean): void;
+  dispose(): void;
+  private watch;
+  /** Before a frame: count it, step moves, and pick the camera it's drawn with. */
+  private beforeFrame;
+  private afterFrame;
+  /** How much of the screen this frame covers, if the renderer says. */
+  private measure;
+  private count;
+  /** Moves to saved views, one step per frame. */
+  private step;
+  /** A camera the renderer was handed that belongs to one listed, like a CubeCamera's faces. */
+  private findOwner;
+  private canHelp;
+  private projects;
+  private add;
+  private remove;
+  private dropHelper;
+  private uniqueName;
+  private inScene;
+  private entryOf;
+  private require;
+  private notifySoon;
+  private notify;
+}
+//#endregion
+export { pathOf as C, kindOf as S, CameraKind as _, CameraLabOptions as a, isCamera as b, RendererLike as c, Pose as d, applyPose as f, poseToCode as g, easeInOut as h, CameraLab as i, SavedView as l, capturePose as m, CameraEntry as n, CameraPatch as o, blendPoses as p, CameraInfo as r, Projection as s, CameraDetails as t, ViewStore as u, SceneCamera as v, isCubeCamera as x, findCameras as y };
+//# sourceMappingURL=lab-AaEFBp_R.d.ts.map