Camera Object Facade (CameraObject)
The CameraObject represents a viewport source or secondary camera rig in the 3D scene (type: 'CAMERA'). It extends the base ISceneObject interface and exposes properties to configure optical characteristics, field-of-view thresholds, and runtime snapshot generation.
Developers declare relationships to CameraObject instances using the @SceneObjectProperty() decorator. Once hydrated, Operators can dynamically focus viewpoints, configure resolution bounds, trigger snapshots, and listen to gesture events.
Example: Capturing Snapshot Sequences#
Example showing how to imperatively capture a snapshot image from a CameraObject.
// Imperatively trigger image capture sequence
this.securityCam.captureImage();Example: Image Capture Handling & Memory Teardown#
Example showing how to subscribe to snapshot image output events on a CameraObject and dispose the listener.
import { Setup, Dispose, Operator, SceneObjectProperty, CameraObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Snapshot Receiver",
type: "SNAPSHOT_RECEIVER"
})
export class SnapshotReceiver {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
securityCam: CameraObject = SceneObjects.SECURITY_CAM_1;
private unsubscribeToImage?: () => void;
@Setup()
setup() {
// Attach click listener and save unsubscribe callback
this.unsubscribeToImage = this.securityCam.imageOutput.addListener((base64Data) => {
console.log("Captured image segment! Length:", base64Data.length);
// Do logic with base64 data here
});
}
@Dispose()
dispose() {
// Prevent memory leaks by cleaning up the listener
this.unsubscribeToImage?.();
}
}Example: Referencing a CameraObject#
Example showing how to declare a CameraObject property and configure resolution bounds during setup.
import { Setup, Operator, SceneObjectProperty, CameraObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Security Snapshot Manager",
type: "SECURITY_SNAPSHOT_MANAGER"
})
export class SnapshotManager {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
securityCam: CameraObject = SceneObjects.SECURITY_CAM_1;
@Setup()
setup() {
// Set standard snapshot resolution bounds
this.securityCam.imageCaptureWidth = 1024;
this.securityCam.imageCaptureHeight = 1024;
}
}Example: Custom Camera Projection Setup#
Example showing how to configure fov, near, and far clipping planes on a CameraObject.
// Configure wide-angle lens with low clip margins for close-up scanning
this.securityCam.fov = 90;
this.securityCam.near = 0.05;
this.securityCam.far = 150;CameraObject Action Inputs (@Input)#
Inputs represent imperative methods that can be called on CameraObject facades:
Available Inputs:
- show(): Unhides camera helper lines in viewports.
- hide(): Hides helper bounds from scene viewports.
- captureImage(): Triggers an immediate snapshot render pipeline process and dispatches the base64 output through imageOutput.
- dataInput(payload: DataBlock[]): Streams dynamic data blocks to drive visual positioning or configurations.
- show() / hide(): Auxiliary camera helper display toggles.
- captureImage(): Imperative trigger to output snapshots.
- dataInput(payload): Dynamic pipeline data intake.
CameraObject Event Outputs (@Output)#
Outputs allow Operators to subscribe to reactive runtime events dispatched by the CameraObject:
Available Outputs:
- imageOutput: AirEvent<string>: Emits the captured base64 screenshot string immediately after captureImage() finishes.
- onClick: AirEvent<void>: Fired once upon completing a click interaction on the camera helper body.
- whileHeld: AirEvent<void>: Dispatched continuously every tick while the user maintains an active select on the helper body.
- onRelease: AirEvent<void>: Dispatched when a click, select, or hold gesture is ended.
- dataOutput: AirEvent<DataBlock[]>: Emits custom pipeline values downstream to other nodes.
- imageOutput: Snapshot stream delivering base64 image strings.
- onClick: Pointer click trigger.
- whileHeld: Pointer hold interaction stream.
- onRelease: Hold ended trigger.
- dataOutput: Custom pipeline event emitter for transferring serializable states.
CameraObject Direct Properties#
A CameraObject exposes direct geometric and optical properties to manage physical projections and snapshot generation scales in real time.
Optical Properties:
- fov: number: Vertical Field of View (FLOAT, Range: 1 to 180).
- maintainHorizontalFOV: boolean: Standardizes aspect ratios to lock the horizontal dimension instead.
- near: number: Minimum physical rendering clip boundary (FLOAT, Range: 0.01 to 1).
- far: number: Maximum distance clipping boundary (FLOAT, Range: 1 to 200).
Image Capture Properties:
- imageCaptureWidth: number: Resolution width of snapshot outputs (FLOAT, Range: 64 to 2048).
- imageCaptureHeight: number: Resolution height of snapshot outputs (FLOAT, Range: 64 to 2048).
- fov: Optical Field of View in vertical degrees.
- near / far: Distance clipping planes to optimize rendering.
- imageCaptureWidth / Height: Sets resolution constraints on captured snapshot string payloads.
Transform and Effects Facades#
Every CameraObject hosts sub-facades to delegate spatial coordinates and custom post-processing layers:
- .transform: Coordinates spatial positioning, scaling, and rotation. (See the 3D Transforms & Coordinates reference guide).
- .effects: Configures custom camera post-processing and visual shader overlaps.
> [!NOTE] > Unlike geometry objects, cameras do not host a .material facade.