@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/space/Space.d.ts

@@ -0,0 +1,325 @@
+import { type Box, Point, type Point2Like, type PointLike } from '@expofp/geometry';
+import { type Camera, Matrix4, Ray, Raycaster, Vector2, type Vector2Like, Vector3, type Vector3Like } from 'three';
+/**
+ * A point in **plan space**: the plan's own coordinates, the ones every def is authored in. Reads x
+ * right, y down and z **up**, so an elevation is a positive number.
+ *
+ * Plan points are `@expofp/geometry` points because plan space crosses the public API — a pointer
+ * event reports where it landed as one, and floorplan authors its defs in the same type. So does
+ * {@link CanvasPoint}, for the same reason: those two are what a caller converts between.
+ */
+export type PlanPoint = Point & {
+    __space: 'plan';
+};
+/**
+ * A plain object in plan space — what a caller may pass in.
+ *
+ * The brand is required rather than optional, so a bare `{ x, y }` is assignable to no space at all
+ * and crossing into one is an explicit `as`. An optional brand would make every plain object
+ * assignable to *every* space, which is the mistake these types exist to catch.
+ */
+export type PlanPointLike = PointLike & {
+    __space: 'plan';
+};
+/**
+ * A point in **world space**: three's own space, the one the camera is placed in. Right-handed, so
+ * world z grows *away* from the viewer — which is why {@link Space} mirrors the plan's z.
+ *
+ * World and NDC points are three's vectors instead of `@expofp/geometry`: neither is part of the
+ * public API, and both exist only to be multiplied by matrices and unprojected through cameras.
+ */
+export type WorldPoint = Vector3 & {
+    __space: 'world';
+};
+/** A plain object point in world space. */
+export type WorldPointLike = Vector3Like & {
+    __space: 'world';
+};
+/**
+ * A point in **canvas space**: css pixels from the canvas's top-left corner, x right and y **down**,
+ * the coordinates a DOM pointer event reports.
+ *
+ * Two dimensions and no more, unlike a plan point: what is drawn at a canvas position has a height,
+ * but the position itself does not — which is why {@link Space.ndcToCanvas} writes a zero `z` rather
+ * than carrying one through.
+ *
+ * Canvas and plan points are the pair most easily confused — both are 2D `{ x, y }` over comparable
+ * ranges, and both read as "where on screen" — so this is the brand that earns its keep most.
+ */
+export type CanvasPoint = Point & {
+    __space: 'canvas';
+};
+/** A plain object point in canvas space — what a caller reading a DOM event may pass in. */
+export type CanvasPointLike = Point2Like & {
+    __space: 'canvas';
+};
+/**
+ * A point in **normalized device coordinates**: where something sits on the canvas irrespective of
+ * its size, `[-1, 1]` on both axes with the origin at the centre and y growing upward.
+ */
+export type NDCPoint = Vector2 & {
+    __space: 'ndc';
+};
+/** A plain object point in normalized device coordinates. */
+export type NDCPointLike = Vector2Like & {
+    __space: 'ndc';
+};
+/** How a {@link Space} maps the plan onto the canvas. */
+export interface SpaceOptions {
+    /** The scene's viewbox, in plan units — the region the fit frames. */
+    viewbox: Box;
+    /** The canvas width in css pixels. */
+    width: number;
+    /** The canvas height in css pixels. */
+    height: number;
+    /**
+     * The device pixel ratio the canvas draws at.
+     *
+     * Separate rather than pre-multiplied into css pixels because both are needed: the fit measures the buffer pixels,
+     * while canvas coordinates arrive from DOM events in css pixels. Passing the buffer size instead would just move the
+     * division to the other side.
+     */
+    dpr: number;
+    /**
+     * A caller-supplied plan → world matrix, 16 elements column-major, in the host's own coordinates.
+     * When present it *replaces* the viewbox fit rather than composing with it; the z mirror both
+     * paths end with is not the caller's to supply (see {@link HANDEDNESS_FLIP}).
+     */
+    staticTransform?: number[];
+}
+/**
+ * The scene's space.
+ * @returns The space {@link Scene} published, or the identity one when rendered outside a scene.
+ */
+export declare function useSpace(): Space;
+/**
+ * The mapping between the plan's own coordinates and the world the camera is placed in, and the
+ * conversions that ride on it.
+ *
+ * The mapping is one matrix. Without a `staticTransform` it is the **viewbox fit**: centre the
+ * viewbox on the world origin and scale it uniformly to best fill the drawing buffer. That fit is
+ * what makes one world unit one device pixel when the plan exactly fills the canvas, which in turn
+ * is what lets the camera's zoom math be written without reference to the scene at all — see
+ * {@link Camera}.
+ *
+ * With a `staticTransform` the matrix is whatever the caller supplied, and the fit is not computed:
+ * a host like maplibre places the plan itself, in its own space.
+ *
+ * Either way the matrix ends with {@link HANDEDNESS_FLIP}, which is what makes the space three's
+ * rather than the plan's or a host's — a positive elevation then lands nearer the camera.
+ *
+ * **Stable for the scene's lifetime.** A resize does not build a new space — {@link Scene} refits
+ * this one in place — so every holder reads the current fit through the same object and none of
+ * them re-render for it. What makes that safe is a reading discipline: render output must never be
+ * derived from these fields, because no render follows a refit. Read them at the moment of use —
+ * in event handlers, effects and the frame loop, which always run against the current fit. `Scene`
+ * itself is the one exception, and it re-applies the world matrix from the same effect that refits.
+ */
+export declare class Space {
+    /** Plan → world. */
+    readonly matrix: Matrix4;
+    /** World → plan. */
+    readonly matrixInverse: Matrix4;
+    private _scale;
+    private _isExternal;
+    /** The canvas width in css pixels, which the canvas conversions measure against. */
+    private width;
+    /** The canvas height in css pixels. */
+    private height;
+    /**
+     * @param options - How to map the plan onto the canvas. Omit them entirely for the identity
+     *   space, in which world coordinates already read as plan coordinates; the individual fields are
+     *   not separately optional, because a fit needs all of them.
+     */
+    constructor(options?: SpaceOptions);
+    /**
+     * World units per plan unit: the geometric mean of the two transformed axes, rather than the
+     * length of one of them.
+     *
+     * Both paths that build a matrix produce a similarity — the fit scales x and y alike, and the
+     * maplibre solver forces uniform scale and no shear — so the two axes agree and the mean is
+     * simply their common length. It differs only for a transform this renderer does not produce, and
+     * there no single number is right anyway: an anisotropic plan covers different amounts of plan per
+     * pixel along each axis, and the mean is the one that preserves area.
+     */
+    get scale(): number;
+    /**
+     * Whether an external host placed the plan itself, by supplying a valid `staticTransform`,
+     * rather than this renderer fitting the viewbox to the canvas — external mode, where the host
+     * owns the canvas, the camera and the frames.
+     */
+    get isExternal(): boolean;
+    /**
+     * Refits the plan onto the canvas in place, leaving every held reference reading the new fit.
+     * @param options - How to map the plan onto the canvas.
+     */
+    refit(options: SpaceOptions): void;
+    /**
+     * Converts a point from plan to world coordinates.
+     * @param point - The plan-space point; a missing `z` is read as `0`.
+     * @param out - Where to write the result.
+     * @returns The world-space point.
+     */
+    planToWorld(point: PlanPointLike, out?: WorldPoint): WorldPoint;
+    /**
+     * Converts a point from world to plan coordinates.
+     * @param point - The world-space point.
+     * @param out - Where to write the result.
+     * @returns The plan-space point.
+     */
+    worldToPlan(point: WorldPointLike, out?: PlanPoint): PlanPoint;
+    /**
+     * Converts a point on the canvas — css pixels from its top-left corner — to normalized device
+     * coordinates, clamped to the canvas.
+     * @param point - The canvas-space point.
+     * @param out - Where to write the result.
+     * @returns The point in normalized device coordinates.
+     */
+    canvasToNdc(point: CanvasPointLike, out?: NDCPoint): NDCPoint;
+    /**
+     * Where a point in normalized device coordinates lands on the canvas, in css pixels from its
+     * top-left corner.
+     *
+     * **Unclamped, where {@link canvasToNdc} clamps**, and the asymmetry is the point: clamping on the
+     * way in keeps a pointer event on the canvas it was dispatched from, while clamping on the way out
+     * would erase the one thing a caller asking about an off-screen point wants to know.
+     *
+     * No guard on a canvas with no size either, where `canvasToNdc` needs one — this multiplies by the
+     * size where that divides by it, so an unsized canvas gives an honest zero rather than a `NaN`.
+     * @param ndc - The point in normalized device coordinates.
+     * @param out - Where to write the result.
+     * @returns The canvas-space point.
+     */
+    ndcToCanvas(ndc: NDCPointLike, out?: CanvasPoint): CanvasPoint;
+    /**
+     * Where a ray crosses the plan, in plan units.
+     *
+     * The ray is taken into plan space and crossed with plan `z = 0` there, rather than crossed with
+     * the plan's image in world space and converted back. Both agree for the viewbox fit; only this
+     * one stays correct for a `staticTransform` that rotates or lifts the plan off world `z = 0`.
+     * @param ray - The ray, in world space.
+     * @param out - Where to write the result.
+     * @returns The crossing, or `undefined` when the ray runs parallel to the plan.
+     */
+    rayToPlan(ray: Ray, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * Where a point in normalized device coordinates lands on the plan.
+     * @param ndc - The point in normalized device coordinates.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The plan position, or `undefined` when the camera never meets the plan.
+     */
+    ndcToPlan(ndc: NDCPointLike, camera: Camera, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * Where a point on the plan lands in normalized device coordinates — the inverse of
+     * {@link ndcToPlan}, and the projection every question about "where is this on screen" is built
+     * from.
+     *
+     * Carried through **clip space** rather than through three's `Vector3.project`, which divides by
+     * `w` without looking at its sign: a point behind the camera comes back mirrored through the
+     * origin, and so lands inside the canvas as convincingly as a point in front of it. Reading `w`
+     * first is what separates the two.
+     *
+     * The camera's view offset rides in `projectionMatrix`, so a scene framed inside a `visibleRect`
+     * projects through this with no seam — the same way picking and culling follow it.
+     * @param point - The plan-space point; a missing `z` is read as `0`.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The point in normalized device coordinates, unclamped, or `undefined` when it sits
+     *   behind the camera and has no image on the canvas at all.
+     */
+    planToNdc(point: PlanPointLike, camera: Camera, out?: NDCPoint): NDCPoint | undefined;
+    /**
+     * Where a point on the canvas — css pixels from its top-left corner — lands on the plan.
+     * @param point - The canvas-space point.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The plan position, or `undefined` when the camera never meets the plan.
+     */
+    canvasToPlan(point: CanvasPointLike, camera: Camera, out?: PlanPoint): PlanPoint | undefined;
+    /**
+     * Where a point on the plan lands on the canvas, in css pixels from its top-left corner — the
+     * inverse of {@link canvasToPlan}, composed from the same two halves the other way round.
+     * @param point - The plan-space point; a missing `z` is read as `0`.
+     * @param camera - The camera the canvas is drawn through.
+     * @param out - Where to write the result.
+     * @returns The canvas position, unclamped, or `undefined` when the point sits behind the camera.
+     */
+    planToCanvas(point: PlanPointLike, camera: Camera, out?: CanvasPoint): CanvasPoint | undefined;
+    /**
+     * Whether a caller supplied a usable plan → world matrix, warning when they supplied an unusable
+     * one rather than silently falling back.
+     * @param staticTransform - What the caller supplied, if anything.
+     * @returns Whether it should be used as the matrix.
+     */
+    private validateStaticTransform;
+}
+/**
+ * The scale that fits a viewbox inside a drawing buffer, contain-style: the constraining axis fills
+ * and the other one keeps slack.
+ *
+ * Exported because it is also what tells a caller how large the plan is drawn: `VisibleRect` needs
+ * the plan's footprint in device pixels, and deriving it from this rather than from `Space.scale`
+ * keeps it free of the commit-ordering hazard the class documents — the fit is a function of the
+ * props it already holds.
+ * @param viewbox - The region to frame, in plan units.
+ * @param bufferWidth - The drawing buffer's width in device pixels.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @returns World units per plan unit, or `1` while either is degenerate.
+ */
+export declare function fitScale(viewbox: Box, bufferWidth: number, bufferHeight: number): number;
+/**
+ * The scene's space, published by {@link Scene}. The default is the identity space, so a component
+ * rendered without one still converts — it just converts nothing.
+ */
+export declare const SpaceContext: import("react").Context<Space>;
+/**
+ * Points a raycaster from a camera through a point in normalized device coordinates.
+ *
+ * The fallback is for a camera whose projection was handed to it rather than derived from a frustum
+ * — an external host like maplibre supplies one — which three's own `setFromCamera` refuses. It unprojects the
+ * same screen point on the near and far planes; both lie on the true ray whatever the matrix folds,
+ * where anchoring the origin at the eye would need a camera transform such a camera does not carry.
+ *
+ * Exported for the external event system, which must aim R3F's raycaster the same way; the space's own
+ * conversions go through the module's private raycaster.
+ * @param raycaster - The raycaster to aim.
+ * @param ndc - The point in normalized device coordinates.
+ * @param camera - The camera to cast from.
+ */
+export declare function castRay(raycaster: Raycaster, ndc: NDCPointLike, camera: Camera): void;
+/**
+ * The last step of both paths into world space: mirror z.
+ *
+ * Plan space is left-handed — x right, y **down**, z up — where three's world is right-handed, so
+ * one axis has to flip and z is it: the plan's up is world `-z`, the side the camera is on.
+ *
+ * The flip belongs in the plan → world matrix and nowhere else. three reads a face's winding from
+ * that matrix's determinant alone (`matrixWorld.determinantAffine() < 0`) and never from the
+ * projection, so a reflection anywhere else is invisible to it: every `DoubleSide` lit surface
+ * negates its normal and shades from behind.
+ *
+ * **Assumes a host's world shares the plan's handedness**, which mercator does — x east, y south,
+ * z up — resolving the clash inside its own projection instead (`MercatorTransform._calcMatrices`
+ * scales by `[1, -1, 1]`). So the same flip serves both paths, and external mode undoes it on the
+ * host's own matrix (`setExternalCameraProjection`). A host with a right-handed world would
+ * need it skipped on both — a `leftHandedWorld` flag on the external contract is where that choice
+ * would go.
+ */
+export declare const HANDEDNESS_FLIP: Matrix4;
+/**
+ * The plan's y-down convention, mirrored for a consumer that reads y as up.
+ *
+ * One value, two unrelated roles. In `ImageInstance.tsx` it is the plan-to-view y mirror composed
+ * into a screen-space quad's own 2D linear map, so the quad's offset reads correctly once the
+ * shader plants it in the view basis. In `MemberTexture.ts` it is the camera's own rest pose
+ * relative to the plan. Its job there is to stop that pose being applied twice, once baked into a
+ * member's own matrix and once more by the ordinary view transform at draw time. That role does
+ * not depend on the sign of a member's own `scale.y`. The requirement is that the billboard matrix
+ * equal the flat matrix at the rest pose, and the scale cancels from both sides of that equality.
+ *
+ * The two roles share a value by coincidence of geometry, not by a shared derivation. Check both
+ * call sites before changing this constant for either reason.
+ */
+export declare const Y_DOWN_FLIP: Matrix4;
+//# sourceMappingURL=Space.d.ts.map