Camera.set ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

Method of Camera · stable · since 2.0.0 · called as session.camera.set

set(view: CameraView | LookAtView, options?: CameraCommitOptions<C> & CameraMoveOptions): Promise<Report>;

Moves the camera to a view (look-only, replacing; target: the view). durationMs: 0 lands exactly, with no damping. A LookAtView also clears the focal offset. Outcome: 'committed' when the move ends, or when a newer view write or a shopper's pointer or touch gesture ('camera:control-start'; not a wheel, which only changes the distance the move lands at) takes it over, so 'committed' does not say the view landed; through a tx, 'deferred'. To act only on a landed move (writing limits, which clamp the current view), note a gesture, and any newer view write of your own, while the move runs (second example); limits is a separate target, so it can also be written in the move's task. Not for: a camera that moves every frame, which is Frame.camera(view) in an onFrame hook. Errors: rejects HoloInputError on an invalid view; AbortError when signal aborts before the move ends, and the camera stops where the last frame drew it (CameraMoveOptions). To stop a move in place without a rejection, set the drawn view (azimuthDeg, polarDeg, distance, target, focalOffset of state) with durationMs: 0: it takes the move over.

Options ​

Through Session:

Refused here (typed never, so passing one fails to compile): dryRun, expectGroup, supersede, undo.

Through Tx:

Refused here (typed never, so passing one fails to compile): actor, checkpoint, dryRun, expectGroup, expectRevision, origin, supersede, undo.

Abort (signal) ​

This call is a write (SignalOption.signal, the kinds of call).

A write: before the commit point it rolls back and rejects AbortError; after it, no effect, except that a running camera move stops where the last frame drew it (CameraMoveOptions).

Through a tx the commit point is the transaction's: aborting a write still loading rejects AbortError and stages nothing (catch it: unobserved, it rolls the transaction back, spec section 6.1, O6); aborting one already staged unstages it, its paths keeping the latest other write to them as after a failed savepoint (O7), and its Promise stays resolved 'staged'.

Examples ​

Imports: values (has, validate, the Holo*Error classes, the pure helpers) from @holostep-configurators/runtime-client, types from @holostep-configurators/runtime-client/contract, /math and /testing names from those entries; boot from the runtime module the root's loadRuntimeAtFloor resolves to. A type your page defines is your app's: declare it there, never import it from the package.

Compiled under the contract's strict settings (examples/declaration/10-Camera.set-1.ts):

import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const sheetHeightPx: number;
// separate targets: neither waits for the other
await Promise.all([
  session.camera.lens(
    { insets: { top: 0, right: 0, bottom: sheetHeightPx, left: 0 } },
    { durationMs: 300 },
  ),
  session.camera.set(
    { position: { x: 2, y: 1.6, z: 3 }, target: { x: 0, y: 0.8, z: 0 } },
    { durationMs: 600 },
  ),
]);

Compiled under the contract's strict settings (examples/declaration/10-Camera.set-2.ts):

import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
// narrow the limits only once the opening shot has landed
let takenOver = false;
const stop = session.on('camera:control-start', () => { takenOver = true; }, { signal });
await session.camera.set(
  { position: { x: 2, y: 1.6, z: 3 }, target: { x: 0, y: 0.8, z: 0 } },
  { durationMs: 800 },
);
stop();
if (!takenOver) await session.camera.limits({ minAzimuthDeg: -10, maxAzimuthDeg: 70 });

Generic-API test (spec 3.1) ​