math.projection ​

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

Const · import { projection } from '@holostep-configurators/runtime-client/math'; · labs, @experimental · since 2.0.0 · section 23. /math

Projection through a camera you describe, not the live one (camera.project projects through camera.state only): where points land in a capture before you take it. Pass the view and size you will pass to capture; the lens is a capture's with its own view or size, no insets: horizontalFovDeg held at the size's aspect, else fovDeg as the vertical, else the default lens as the camera draws it (CameraLens.horizontalFovDeg). Pass the lens your page or a lens() call set; after a shot, CaptureResult.snapshot.camera (as view, with its fovDeg) projects as the shot drew. The camera's own arithmetic, so it agrees with camera.project through the same view, lens and size to well within a pixel.

Members ​

Member Kind Summary
project method points as camera.project would place them through camera.view in an image of camera.size CSS px: x and y from its top-left, depth metres along the view, visible when in front and inside.

Declaration ​

ts
export const projection: {
  project(camera: {
    view: CameraView | LookAtView;
    size: {
      width: number;
      height: number;
    };
    fovDeg?: number;
    horizontalFovDeg?: number;
  }, points: readonly Point3[]): Array<ProjectedPoint | null>;
};

Example ​

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/23-projection.ts):

ts
import { projection } from '@holostep-configurators/runtime-client/math';
import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
// a quote still: back off until every corner of the product is inside 94% of the frame
async function quoteStill(size: { width: number; height: number }) {
  const box = session.find({ role: 'product' }).bounds();
  if (!box) return null;
  const corners = [box.min, box.max].flatMap((a) =>
    [box.min, box.max].flatMap((b) => [box.min, box.max].map((c) => ({ x: a.x, y: b.y, z: c.z }))),
  );
  const ndc = (v: number, of: number) => Math.abs((v / of) * 2 - 1);
  let view = { target: box.center, azimuthDeg: 35, polarDeg: 70, distance: 2 };
  const inside = () =>
    projection
      .project({ view, size }, corners)
      .every((p) => p !== null && ndc(p.x, size.width) <= 0.94 && ndc(p.y, size.height) <= 0.94);
  while (!inside() && view.distance < 50) view = { ...view, distance: view.distance * 1.1 };
  return session.capture({ view, size });
}
const still = await quoteStill({ width: 1200, height: 800 });
if (still) console.log(still.snapshot.camera.fovDeg);

Generic-API test (spec 3.1) ​

Rule Result
1. Neutral name pass: projection names no product
2. A precedent not recorded: no ledger row (coverage.json) names this member or its owner
3. Two apps, or labs labs (@experimental at a stable path, reached through has() or supports()): it graduates when a second app uses it
4. The cheaper fix first not recorded per member (Appendix B decides it per need)