# `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`](Camera.project.md) projects through
[`camera.state`](Camera.state.md) only): where points land in a capture before you take it. Pass the `view` and
`size` you will pass to [`capture`](Session.capture.md); 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`](CameraLens.horizontalFovDeg.md)). Pass the
lens your page or a `lens()` call set; after a shot, [`CaptureResult.snapshot.camera`](CaptureResult.snapshot.md) (as
`view`, with its `fovDeg`) projects as the shot drew. The camera's own arithmetic, so it agrees
with [`camera.project`](Camera.project.md) through the same view, lens and size to well within a pixel.

## Members

| Member | Kind | Summary |
| --- | --- | --- |
| <a id="project"></a>[`project`](math.projection.project.md) | method | `points` as [`camera.project`](Camera.project.md) 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) |