@field/cascade 0.3.1 → 0.4.0

package/dist/runtime/builtins/core/camera.d.ts

@@ -0,0 +1,252 @@
+import { type NodeExecutionContext } from "@field/cascade/contracts";
+/**
+ * `cascade.core.Camera` — Houdini's `/obj/cam`, as a node.
+ *
+ * Marcus, 2026-09-08: *"I think it just requires a camera. camera should be a
+ * core node."* So a renderer takes a camera on a port rather than carrying its
+ * own copy of the same eight parameters, which is what `volume-render` was
+ * doing.
+ *
+ * The split between inputs and props is the usual one and it matters here:
+ * **what a camera move animates is an input** — position, orientation, the
+ * look-at target, the lens — and **what defines the frame is a prop**, because
+ * clipping planes, resolution and projection are set once and left. `focal` is
+ * an input for exactly this reason: a focus pull is a camera move.
+ */
+export declare const cameraDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Camera";
+    readonly description: "A camera, following Houdini's /obj/cam.";
+    readonly icon: "Video";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly translate: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 5];
+            readonly description: "World position.";
+        };
+        readonly rotate: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 0];
+            readonly description: "Degrees, XYZ order. The camera looks down its own -Z.";
+        };
+        readonly focal: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 50;
+            readonly min: 1;
+            readonly max: 300;
+            readonly description: "Focal length in millimetres.";
+        };
+        readonly lookat: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 0, 0];
+            readonly description: "Point to aim at. Used only when Look At is on, and it replaces Rotate.";
+        };
+        readonly up: {
+            readonly kind: "data";
+            readonly type: "vec3";
+            readonly default: readonly [0, 1, 0];
+            readonly description: "Up vector for Look At.";
+        };
+        readonly spin: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 0;
+            readonly description: "Degrees added to the Y rotation, after Look At. For turntables.";
+        };
+    };
+    readonly outputs: {
+        readonly camera: {
+            readonly kind: "data";
+            readonly type: "camera";
+        };
+    };
+    readonly props: {
+        readonly lookAt: {
+            readonly type: "bool";
+            readonly default: false;
+            readonly label: "Look At";
+            readonly description: "Aim at the Look At point instead of using Rotate.";
+        };
+        readonly aperture: {
+            readonly type: "float";
+            readonly default: 41.4214;
+            readonly min: 1;
+            readonly max: 200;
+            readonly label: "Aperture";
+            readonly description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view.";
+        };
+        readonly resolution: {
+            readonly type: "vec2i";
+            readonly default: readonly [1280, 720];
+            readonly label: "Resolution";
+            readonly description: "Frame size in pixels. The vertical field of view is derived from this.";
+        };
+        readonly aspect: {
+            readonly type: "float";
+            readonly default: 1;
+            readonly min: 0.1;
+            readonly max: 10;
+            readonly label: "Pixel Aspect";
+            readonly description: "The aspect of one pixel, not of the frame.";
+        };
+        readonly projection: {
+            readonly type: "string";
+            readonly default: "perspective";
+            readonly label: "Projection";
+            readonly control: "select";
+            readonly options: readonly [{
+                readonly value: "perspective";
+                readonly label: "Perspective";
+            }, {
+                readonly value: "orthographic";
+                readonly label: "Orthographic";
+            }];
+        };
+        readonly orthowidth: {
+            readonly type: "float";
+            readonly default: 2;
+            readonly min: 0.01;
+            readonly label: "Ortho Width";
+            readonly description: "Width of the orthographic frame in world units.";
+        };
+        readonly near: {
+            readonly type: "float";
+            readonly default: 0.001;
+            readonly min: 0;
+            readonly label: "Near Clip";
+        };
+        readonly far: {
+            readonly type: "float";
+            readonly default: 10000;
+            readonly min: 0;
+            readonly label: "Far Clip";
+        };
+    };
+};
+export declare function executeCamera(context: NodeExecutionContext<typeof cameraDefinition>): void;
+export declare const cameraRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Camera";
+        readonly description: "A camera, following Houdini's /obj/cam.";
+        readonly icon: "Video";
+        readonly runsOn: "portable";
+        readonly inputs: {
+            readonly translate: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 5];
+                readonly description: "World position.";
+            };
+            readonly rotate: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 0];
+                readonly description: "Degrees, XYZ order. The camera looks down its own -Z.";
+            };
+            readonly focal: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly default: 50;
+                readonly min: 1;
+                readonly max: 300;
+                readonly description: "Focal length in millimetres.";
+            };
+            readonly lookat: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 0, 0];
+                readonly description: "Point to aim at. Used only when Look At is on, and it replaces Rotate.";
+            };
+            readonly up: {
+                readonly kind: "data";
+                readonly type: "vec3";
+                readonly default: readonly [0, 1, 0];
+                readonly description: "Up vector for Look At.";
+            };
+            readonly spin: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly default: 0;
+                readonly description: "Degrees added to the Y rotation, after Look At. For turntables.";
+            };
+        };
+        readonly outputs: {
+            readonly camera: {
+                readonly kind: "data";
+                readonly type: "camera";
+            };
+        };
+        readonly props: {
+            readonly lookAt: {
+                readonly type: "bool";
+                readonly default: false;
+                readonly label: "Look At";
+                readonly description: "Aim at the Look At point instead of using Rotate.";
+            };
+            readonly aperture: {
+                readonly type: "float";
+                readonly default: 41.4214;
+                readonly min: 1;
+                readonly max: 200;
+                readonly label: "Aperture";
+                readonly description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view.";
+            };
+            readonly resolution: {
+                readonly type: "vec2i";
+                readonly default: readonly [1280, 720];
+                readonly label: "Resolution";
+                readonly description: "Frame size in pixels. The vertical field of view is derived from this.";
+            };
+            readonly aspect: {
+                readonly type: "float";
+                readonly default: 1;
+                readonly min: 0.1;
+                readonly max: 10;
+                readonly label: "Pixel Aspect";
+                readonly description: "The aspect of one pixel, not of the frame.";
+            };
+            readonly projection: {
+                readonly type: "string";
+                readonly default: "perspective";
+                readonly label: "Projection";
+                readonly control: "select";
+                readonly options: readonly [{
+                    readonly value: "perspective";
+                    readonly label: "Perspective";
+                }, {
+                    readonly value: "orthographic";
+                    readonly label: "Orthographic";
+                }];
+            };
+            readonly orthowidth: {
+                readonly type: "float";
+                readonly default: 2;
+                readonly min: 0.01;
+                readonly label: "Ortho Width";
+                readonly description: "Width of the orthographic frame in world units.";
+            };
+            readonly near: {
+                readonly type: "float";
+                readonly default: 0.001;
+                readonly min: 0;
+                readonly label: "Near Clip";
+            };
+            readonly far: {
+                readonly type: "float";
+                readonly default: 10000;
+                readonly min: 0;
+                readonly label: "Far Clip";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeCamera>;
+};
+//# sourceMappingURL=camera.d.ts.map

package/dist/runtime/builtins/core/camera.js

@@ -0,0 +1,149 @@
+import { CAMERA_DEFAULTS } from "@field/cascade/contracts";
+import { lookAtRotation } from "../../camera/index.js";
+/**
+ * `cascade.core.Camera` — Houdini's `/obj/cam`, as a node.
+ *
+ * Marcus, 2026-09-08: *"I think it just requires a camera. camera should be a
+ * core node."* So a renderer takes a camera on a port rather than carrying its
+ * own copy of the same eight parameters, which is what `volume-render` was
+ * doing.
+ *
+ * The split between inputs and props is the usual one and it matters here:
+ * **what a camera move animates is an input** — position, orientation, the
+ * look-at target, the lens — and **what defines the frame is a prop**, because
+ * clipping planes, resolution and projection are set once and left. `focal` is
+ * an input for exactly this reason: a focus pull is a camera move.
+ */
+export const cameraDefinition = {
+    apiVersion: 1,
+    label: "Camera",
+    description: "A camera, following Houdini's /obj/cam.",
+    icon: "Video",
+    runsOn: "portable",
+    inputs: {
+        translate: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 5],
+            description: "World position.",
+        },
+        rotate: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 0],
+            description: "Degrees, XYZ order. The camera looks down its own -Z.",
+        },
+        focal: {
+            kind: "data",
+            type: "float",
+            default: 50,
+            min: 1,
+            max: 300,
+            description: "Focal length in millimetres.",
+        },
+        lookat: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 0, 0],
+            description: "Point to aim at. Used only when Look At is on, and it replaces Rotate.",
+        },
+        up: {
+            kind: "data",
+            type: "vec3",
+            default: [0, 1, 0],
+            description: "Up vector for Look At.",
+        },
+        spin: {
+            kind: "data",
+            type: "float",
+            default: 0,
+            description: "Degrees added to the Y rotation, after Look At. For turntables.",
+        },
+    },
+    outputs: {
+        camera: { kind: "data", type: "camera" },
+    },
+    props: {
+        lookAt: {
+            type: "bool",
+            default: false,
+            label: "Look At",
+            description: "Aim at the Look At point instead of using Rotate.",
+        },
+        aperture: {
+            type: "float",
+            default: 41.4214,
+            min: 1,
+            max: 200,
+            label: "Aperture",
+            description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view.",
+        },
+        resolution: {
+            type: "vec2i",
+            default: [1280, 720],
+            label: "Resolution",
+            description: "Frame size in pixels. The vertical field of view is derived from this.",
+        },
+        aspect: {
+            type: "float",
+            default: 1,
+            min: 0.1,
+            max: 10,
+            label: "Pixel Aspect",
+            description: "The aspect of one pixel, not of the frame.",
+        },
+        projection: {
+            type: "string",
+            default: "perspective",
+            label: "Projection",
+            control: "select",
+            options: [
+                { value: "perspective", label: "Perspective" },
+                { value: "orthographic", label: "Orthographic" },
+            ],
+        },
+        orthowidth: {
+            type: "float",
+            default: 2,
+            min: 0.01,
+            label: "Ortho Width",
+            description: "Width of the orthographic frame in world units.",
+        },
+        near: { type: "float", default: 0.001, min: 0, label: "Near Clip" },
+        far: { type: "float", default: 10000, min: 0, label: "Far Clip" },
+    },
+};
+export function executeCamera(context) {
+    const { translate, rotate, focal, lookat, up, spin } = context.inputs;
+    const props = context.props;
+    const aimed = props.lookAt
+        ? lookAtRotation(translate, lookat, up)
+        : rotate;
+    // Spin is applied after look-at rather than folded into it, so a turntable
+    // keeps pointing at its subject while it goes round. Degrees, because
+    // `rotate` is degrees and adding a different unit to it would be a trap.
+    const oriented = spin === 0
+        ? aimed
+        : [aimed[0], aimed[1] + spin, aimed[2]];
+    const camera = {
+        ...CAMERA_DEFAULTS,
+        translate: translate,
+        rotate: oriented,
+        focal,
+        aperture: props.aperture,
+        resolution: props.resolution,
+        aspect: props.aspect,
+        projection: props.projection === "orthographic" ? "orthographic" : "perspective",
+        orthowidth: props.orthowidth,
+        near: props.near,
+        far: props.far,
+    };
+    context.outputs.camera.set(camera);
+}
+export const cameraRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.core.Camera",
+    definition: cameraDefinition,
+    loadExecute: async () => executeCamera,
+};
+//# sourceMappingURL=camera.js.map

package/dist/runtime/builtins/core/index.d.ts

@@ -1,9 +1,10 @@
 import type { DefinitionNodeRegistration } from "../../types.js";
+import { cameraRegistration } from "./camera.js";
 import { randomRegistration } from "./random.js";
 import { remapRegistration } from "./remap.js";
 import { mergeRegistration, nullRegistration, selectRegistration, switchRegistration } from "./routing.js";
 import { inputRegistration, outputRegistration, subnetRegistration } from "./structural.js";
-export { inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, };
+export { cameraRegistration, inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, };
 export declare const coreNodeRegistrations: readonly DefinitionNodeRegistration[];
 export declare function coreNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/builtins/core/index.js

@@ -1,8 +1,9 @@
+import { cameraRegistration } from "./camera.js";
 import { randomRegistration } from "./random.js";
 import { remapRegistration } from "./remap.js";
 import { mergeRegistration, nullRegistration, selectRegistration, switchRegistration } from "./routing.js";
 import { inputRegistration, outputRegistration, subnetRegistration } from "./structural.js";
-export { inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, };
+export { cameraRegistration, inputRegistration, mergeRegistration, nullRegistration, outputRegistration, randomRegistration, remapRegistration, selectRegistration, subnetRegistration, switchRegistration, };
 export const coreNodeRegistrations = Object.freeze([
     subnetRegistration,
     inputRegistration,
@@ -13,6 +14,7 @@ export const coreNodeRegistrations = Object.freeze([
     selectRegistration,
     randomRegistration,
     remapRegistration,
+    cameraRegistration,
 ]);
 const registrationsById = new Map(coreNodeRegistrations.map((registration) => [registration.moduleId, registration]));
 export function coreNodeRegistration(moduleId) {

package/dist/runtime/camera/index.d.ts

@@ -0,0 +1,60 @@
+import type { Camera, Mat4, Vec3 } from "@field/cascade/contracts";
+/** The camera's own axes in world space. */
+export interface CameraBasis {
+    /** Where the camera is. */
+    readonly eye: Vec3;
+    /** Unit vector the camera looks along — its own -Z. */
+    readonly forward: Vec3;
+    /** Unit vector to the camera's right — its own +X. */
+    readonly right: Vec3;
+    /** Unit vector for the camera's up — its own +Y. */
+    readonly up: Vec3;
+}
+/**
+ * The rotation the camera needs to look at a point, as Houdini's look-at does.
+ *
+ * Returned as degrees in XYZ order so it can be written straight into
+ * `camera.rotate` — which is what makes look-at an override of the transform
+ * rather than a second, parallel way to orient a camera.
+ *
+ * **`up` chooses the roll, and only the roll.** Yaw and pitch are fixed the
+ * moment a direction is given; all an up vector can still decide is the
+ * rotation about that direction. The default `[0, 1, 0]` is Houdini's own
+ * `upvector` default and gives roll zero for any horizontal up, which is why
+ * every ordinary orbit never needs to think about it.
+ *
+ * Written first with `roll = 0` and the parameter ignored, which was wrong in
+ * the way this codebase keeps finding: the node exposes `up` as an input, so a
+ * value set there did nothing at all and nothing said so.
+ */
+export declare function lookAtRotation(from: Vec3, to: Vec3, up?: Vec3): Vec3;
+/** The camera's axes, applying Houdini's XYZ rotation order to a camera that
+ *  looks down -Z at rest. */
+export declare function cameraBasis(camera: Camera): CameraBasis;
+/**
+ * The horizontal field of view in degrees, from the lens rather than stored.
+ *
+ * Houdini's defaults of 50 mm and 41.4214 mm are exactly 45°, which is the
+ * check worth having in a test: it is the one value that proves the formula and
+ * the defaults agree.
+ */
+export declare function horizontalFov(camera: Camera): number;
+/**
+ * The VERTICAL field of view in degrees.
+ *
+ * Houdini does not store a vertical aperture; it derives one from the
+ * horizontal aperture, the resolution ratio and the pixel aspect. Which is why
+ * `resolution` is on the camera at all — without it there is no vertical angle
+ * to be had.
+ */
+export declare function verticalFov(camera: Camera): number;
+/** Frame aspect — the shape of the picture, pixel aspect included. Distinct
+ *  from `camera.aspect`, which is the aspect of one pixel. */
+export declare function frameAspect(camera: Camera): number;
+/** Column-major, GLSL convention, matching `MATRIX_TYPES` in Studio: element 0
+ *  starts the first COLUMN. */
+export declare function viewMatrix(camera: Camera): Mat4;
+/** Column-major, and orthographic when the camera says so — `orthowidth` is a
+ *  width in world units, so the height comes from the frame aspect. */
+export declare function projectionMatrix(camera: Camera): Mat4;
+//# sourceMappingURL=index.d.ts.map