@equinor/videx-3d 2.0.0 → 3.1.0

package/dist/types/rendering/taa-resolver.d.ts

@@ -0,0 +1,161 @@
+import { Camera, Texture, WebGLRenderer, WebGLRenderTarget } from 'three';
+/**
+ * Reprojected temporal anti-aliasing (TAA) resolver for the {@link OITRenderPass}.
+ *
+ * Unlike {@link TemporalResolver} (which only accumulates while the camera is
+ * still), this reprojects the history every frame using the depth of the nearest
+ * visible surface, so anti-aliasing is retained *during* camera motion. The app's
+ * world is effectively static — only the camera moves — so no per-object velocity
+ * buffer is required; a depth-only camera reprojection recovers the motion.
+ *
+ * The reprojection depth is the nearer of the opaque hardware depth and the OIT
+ * front-layer's view-space linear depth (passed in from the pass). Transparent
+ * surfaces write no hardware depth, so reprojecting them by the opaque depth behind
+ * them is precisely what makes a naive TAA ghost transparent content; using the OIT
+ * front depth reprojects the visible transparent surface at its true position.
+ *
+ * Ghosting from content the reprojection cannot follow (additive highlights,
+ * animated objects, disocclusions) is bounded in the shader by clamping the
+ * reprojected history into the current frame's local 3x3 colour range and by
+ * falling back to the current frame where the reprojection lands off-screen. It is
+ * offered as an *optional* AA mode alongside `temporal`/`smaa`, not a replacement.
+ *
+ * Like {@link TemporalResolver}, the owning pass drives it: {@link applyJitter}
+ * before the scene render, {@link restoreJitter} + {@link resolve} after. The jitter
+ * is applied to the shared camera only between those calls, so it never leaks to
+ * later passes.
+ *
+ * @group Rendering
+ * @see {@link OITRenderPass}
+ */
+export declare class TaaResolver {
+    /**
+     * Number of unique sub-pixel jitter samples to cycle through (the length of the
+     * Halton sequence used).
+     */
+    sampleCount: number;
+    /**
+     * History weight when the reprojection is valid (the current frame contributes
+     * `1 - feedback`). Higher = smoother/more stable but slower to react and more
+     * prone to ghosting; lower = crisper but noisier. Typical range 0.85–0.95.
+     */
+    feedback: number;
+    /**
+     * Per-frame camera motion, in screen pixels (largest reprojected frustum-corner
+     * displacement), at/below which the neighbourhood clip is fully relaxed. Below this
+     * the camera is treated as still and the reprojected history is trusted verbatim
+     * (pure exponential average), so heavily aliased static geometry converges instead
+     * of wobbling against a single jittered frame's colour box.
+     */
+    stillPixelThreshold: number;
+    /**
+     * Camera motion, in screen pixels, at/above which the neighbourhood clip is fully
+     * applied (history clipped into the current frame's local colour range, bounding
+     * ghosting from disocclusions and untrackable content). Between this and
+     * {@link stillPixelThreshold} the clip strength ramps smoothly, so there is no pop
+     * as the camera starts or stops moving.
+     */
+    motionPixelThreshold: number;
+    /**
+     * Neighbourhood-clip strength retained while the camera is *still* (the floor the
+     * motion ramp starts from). **Default 0.2** — a low floor that stays firmly on the
+     * static-favoured side of the scale: heavily aliased near-Nyquist detail still
+     * converges to a near-supersampled result, while a touch of clip already bounds the
+     * worst ghost trails. Raise it (typically 0.6-0.9) to more aggressively suppress the
+     * trail an object animating under a still camera leaves — its history lands far
+     * outside the current frame's local colour box and is pulled in, while correctly
+     * converged static geometry (whose history sits *inside* the box, widened by
+     * {@link restBoxGamma}/{@link restNeighbourhoodRadius} for exactly this reason) is
+     * left untouched. 0 trusts history verbatim at rest; 1 clips fully even when still.
+     * Camera-motion protection is unaffected by this floor — the clip still ramps up on
+     * motion regardless.
+     */
+    restClampStrength: number;
+    /**
+     * Neighbourhood colour-box half-width (in sigmas) used while the camera is still.
+     * Wider than {@link motionBoxGamma} so a converged near-Nyquist feature stays inside
+     * the box (the rest clip is then a no-op on it) while a moving object's history is
+     * still caught.
+     */
+    restBoxGamma: number;
+    /** Neighbourhood colour-box half-width (in sigmas) used while the camera moves. */
+    motionBoxGamma: number;
+    /**
+     * Neighbourhood sampling stride (in texels) used while the camera is still. Wider
+     * than {@link motionNeighbourhoodRadius} so a field of thin bars is always
+     * represented in the box and its converged value is not falsely rejected.
+     */
+    restNeighbourhoodRadius: number;
+    /** Neighbourhood sampling stride (in texels) used while the camera moves. */
+    motionNeighbourhoodRadius: number;
+    private historyRead;
+    private historyWrite;
+    private resolveMaterial;
+    private blitMaterial;
+    private fullscreenRenderer;
+    private width;
+    private height;
+    /** Index into the jitter sequence for the current frame. */
+    private sampleIndex;
+    /** False until the first frame has been accumulated (and after a resize). */
+    private hasHistory;
+    /** True while a sub-pixel jitter is applied to the shared camera projection. */
+    private jittered;
+    /** The camera the jitter was applied to (restored in {@link restoreJitter}). */
+    private camera;
+    /** Snapshot of the clean projection matrix, restored exactly after the render. */
+    private savedProjection;
+    /** Snapshot of the clean projection inverse, restored alongside the projection. */
+    private savedProjectionInverse;
+    /** Scratch: current (un-jittered) world-space view-projection. */
+    private curViewProj;
+    /** Previous frame's (un-jittered) world-space view-projection (world -> clip). */
+    private prevViewProj;
+    /** Inverse of the previous frame's view-projection (clip -> world), for motion. */
+    private prevViewProjInverse;
+    /** Scratch: `curViewProj * prevViewProjInverse` (prev NDC -> cur NDC). */
+    private motionMatrix;
+    /** Scratch vector reused while reprojecting the frustum corners. */
+    private motionScratch;
+    constructor(sampleCount?: number, feedback?: number);
+    setSize(width: number, height: number): void;
+    /** Force the accumulation to restart on the next frame. */
+    reset(): void;
+    /**
+     * Apply this frame's sub-pixel jitter to the camera projection. Called by the
+     * owning pass immediately before it renders the scene; paired with
+     * {@link restoreJitter} after the render. Reprojection TAA jitters *every* frame
+     * (the history is reprojected, so a still and a moving frame are treated the
+     * same), unlike the still-only temporal accumulation.
+     */
+    applyJitter(camera: Camera): void;
+    /**
+     * Restore the camera projection (matrix + cached inverse) to the snapshot taken
+     * in {@link applyJitter}. Idempotent and safe to call when no jitter is applied.
+     */
+    restoreJitter(): void;
+    /**
+     * Reproject the running history to the current view and blend it with the freshly
+     * composited frame in `buffer`, writing the result back into `buffer`. Must be
+     * called after {@link restoreJitter} so the camera matrices are the clean
+     * (un-jittered) transform.
+     *
+     * `frontDepth` is the OIT front-layer's view-space linear depth (normalised by
+     * `camera.far`); pass `null` when it was not written this frame (front peel
+     * disabled or no transparent content), in which case only the opaque hardware
+     * depth is used for reprojection.
+     */
+    resolve(renderer: WebGLRenderer, buffer: WebGLRenderTarget, camera: Camera, frontDepth: Texture | null): void;
+    /**
+     * Per-frame camera-motion amount in `[0, 1]`, used to ramp the neighbourhood clip
+     * (strength, box width and sampling stride) between its still and full-motion
+     * settings. Builds `M = curViewProj * prevViewProjInverse` (prev NDC -> cur NDC; the
+     * identity when the camera is still), reprojects the 8 frustum corners through it and
+     * takes the largest corner displacement in pixels, then maps it through a smoothstep
+     * from {@link stillPixelThreshold} (0 = still) to {@link motionPixelThreshold}
+     * (1 = full motion). Working in NDC/pixels makes it independent of world scale and
+     * zoom. Returns 1 on the first frame (before any history exists).
+     */
+    private computeMotionAmount;
+    dispose(): void;
+}

package/dist/types/rendering/temporal-resolver.d.ts

@@ -0,0 +1,152 @@
+import { Camera, WebGLRenderer, WebGLRenderTarget } from 'three';
+/**
+ * Temporal supersampling resolver for the {@link OITRenderPass}.
+ *
+ * This is *not* reprojected TAA. Each frame the camera projection is offset by a
+ * sub-pixel Halton jitter (so a thin feature lands on different sub-pixel positions
+ * over time) and the freshly composited frame is blended into a running history
+ * average — but **only while the camera is still**. There is no depth/velocity
+ * reprojection: as soon as the camera moves the history is dropped (the current
+ * frame is shown), so nothing can ghost. When the camera comes to rest the average
+ * accumulates again and the static view converges to a genuinely supersampled
+ * image. This is the right trade for an inspection-heavy app (zoom in, hold still)
+ * and, crucially, it works identically for opaque, transparent (OIT) and additive
+ * content because it never tries to track any of it through motion.
+ *
+ * The {@link OITRenderPass} owns one of these and drives it: it calls
+ * {@link applyJitter} before rendering the scene and {@link restoreJitter} +
+ * {@link resolve} afterwards. The jitter is applied to the shared camera only
+ * between those two calls (inside the pass's own `render`), so it never leaks to
+ * later passes (annotations, picking) or other `useFrame` consumers.
+ *
+ * @group Rendering
+ * @see {@link OITRenderPass}
+ */
+export declare class TemporalResolver {
+    /**
+     * Number of unique sub-pixel jitter samples to cycle through (the length of the
+     * Halton sequence used). Higher spreads coverage over more sub-pixel positions.
+     */
+    sampleCount: number;
+    /**
+     * History weight while the camera is still (the current frame contributes
+     * `1 - feedback`). A fixed-feedback exponential average converges to a stable
+     * supersampled image without the endless `1 / n` wobble that previously needed a
+     * freeze, and - paired with the resolve shader's motion-adaptive rejection - lets
+     * content that animates under a still camera blend in immediately instead of
+     * freezing. Higher = smoother/slower to react; typical range 0.85-0.95.
+     */
+    feedback: number;
+    /**
+     * Threshold, in screen pixels, on the per-frame motion of the reprojected
+     * frustum corners (see {@link NDC_MOTION_CORNERS}) above which the camera is
+     * treated as moving (history dropped). Measured directly in pixels, so it behaves
+     * identically at any zoom level or scene/world scale. Kept slightly above the
+     * sub-pixel residual left by damped camera controls (which otherwise resets the
+     * accumulation every few frames as the view settles, pulsing the still image
+     * between an aliased and a converged frame). Motion this small is far below any
+     * visible blur, so treating it as still is safe. Lower = accumulates sooner after
+     * motion stops; higher = tolerates more residual drift before dropping history.
+     */
+    motionPixelThreshold: number;
+    /**
+     * Strength of the anti-ghost neighbourhood clip applied while the camera is still
+     * (the mode only accumulates while still). **Default 0.2** — a low floor that stays
+     * firmly on the static-favoured side of the scale: the still image still converges
+     * to a near-supersampled result, while a touch of clip already bounds the worst fade
+     * trails. Raise it (typically 0.6-0.9) to more aggressively suppress the trail an
+     * object animating under a still camera leaves — the clip pulls history that lands
+     * *far outside* the current frame's local colour box back in. It is a no-op for
+     * correctly converged static geometry: the box is deliberately widened (see the
+     * resolve shader's `BOX_GAMMA`/`NEIGHBOURHOOD_RADIUS`) so a heavily aliased
+     * near-Nyquist feature's converged value stays *inside* it and is never rejected.
+     * 0 restores the pure exponential average; 1 clips fully.
+     */
+    clampStrength: number;
+    private historyRead;
+    private historyWrite;
+    private resolveMaterial;
+    private blitMaterial;
+    private fullscreenRenderer;
+    private width;
+    private height;
+    /** Index into the jitter sequence for the current frame. */
+    private sampleIndex;
+    /** False until the first frame has been accumulated (and after a resize). */
+    private hasHistory;
+    /**
+     * Whether the camera was moving as of the last {@link resolve}. Read by
+     * {@link applyJitter} (which runs before motion can be detected for the current
+     * frame) to decide whether to jitter: moving frames are shown raw, so jittering
+     * them would read as the whole scene shaking. Starts `true` so the very first
+     * frame renders at its true position.
+     */
+    private moving;
+    /**
+     * Whether the camera was moving as of the last {@link resolve}. Lets the owning
+     * pass restrict a spatial AA pass (SMAA) to moving frames only, leaving the still
+     * frames to the temporal accumulation.
+     */
+    get isMoving(): boolean;
+    /** True while a sub-pixel jitter is applied to the shared camera projection. */
+    private jittered;
+    /** The camera the jitter was applied to (restored in {@link restoreJitter}). */
+    private camera;
+    /** Snapshot of the clean projection matrix, restored exactly after the render. */
+    private savedProjection;
+    /** Snapshot of the clean projection inverse, restored alongside the projection. */
+    private savedProjectionInverse;
+    /** Scratch: current (un-jittered) view-projection, for motion detection. */
+    private curViewProj;
+    /** Inverse of the previous frame's (un-jittered) view-projection. */
+    private prevViewProjInverse;
+    /** Scratch: `curViewProj * prevViewProjInverse` (prev NDC -> cur NDC). */
+    private motionMatrix;
+    /** Scratch vector reused while reprojecting the frustum corners. */
+    private motionScratch;
+    constructor(sampleCount?: number, feedback?: number);
+    setSize(width: number, height: number): void;
+    /** Force the accumulation to restart on the next frame. */
+    reset(): void;
+    /**
+     * Apply this frame's sub-pixel jitter to the camera projection. Called by the
+     * owning pass immediately before it renders the scene; paired with
+     * {@link restoreJitter} after the render. The clean projection (matrix + cached
+     * inverse) is snapshotted so it can be restored exactly, leaving no drift.
+     *
+     * The jitter is only applied while the camera is still ({@link moving} is false).
+     * While the camera moves, frames are displayed raw (blend = 1), so a per-frame
+     * sub-pixel offset would show up as the entire scene shaking; rendering moving
+     * frames at their true (un-jittered) position keeps them rock-steady. Sub-pixel
+     * coverage is only needed once the view holds still and the average accumulates.
+     */
+    applyJitter(camera: Camera): void;
+    /**
+     * Restore the camera projection (matrix + cached inverse) to the snapshot taken
+     * in {@link applyJitter}. Idempotent and safe to call when no jitter is applied.
+     */
+    restoreJitter(): void;
+    /**
+     * Blend the freshly composited frame in `buffer` with the running history and
+     * write the result back into `buffer`. Must be called after {@link restoreJitter}
+     * so the camera matrices sampled for motion detection are the clean transform.
+     *
+     * Reads `buffer.texture` as the current frame and writes the average into the
+     * history target, then copies that back into `buffer` (an overwrite blit, so the
+     * buffer's alpha is replaced rather than blended). The history targets are
+     * ping-ponged for the next frame.
+     */
+    resolve(renderer: WebGLRenderer, buffer: WebGLRenderTarget, camera: Camera): void;
+    /**
+     * True when the rendered image moved more than {@link motionPixelThreshold}
+     * pixels since the last frame. Builds `M = curViewProj * prevViewProjInverse`,
+     * which maps the previous frame's NDC back to the current frame's NDC (the
+     * identity when the camera is still), reprojects the 8 frustum corners through it
+     * and takes the largest corner displacement converted to pixels. Operating in
+     * NDC/pixels makes this independent of world scale and zoom, unlike a raw
+     * view-projection matrix delta (whose magnitude grows with camera distance and so
+     * goes undetected when zoomed out).
+     */
+    private detectMotion;
+    dispose(): void;
+}

package/dist/types/sdk/geometries/boundary-loops.d.ts

@@ -0,0 +1,38 @@
+import { BufferGeometry } from 'three';
+import { Vec2 } from '../types/common';
+/**
+ * Extract the boundary loops of an indexed triangle mesh as ordered arrays of
+ * vertex indices. A boundary edge is one used by a single triangle, so the
+ * loops include both the outer outline and any internal hole rings. Useful for
+ * outlining a mesh or relaxing/snapping only its rim vertices.
+ *
+ * @group Geometries
+ */
+export declare function extractBoundaryLoops(geometry: BufferGeometry): number[][];
+/**
+ * Smooth the given vertex loops (e.g. from {@link extractBoundaryLoops}) in
+ * place with an iterated windowed moving average, moving only the X/Z position
+ * of the existing boundary vertices and leaving their Y untouched. Unlike a
+ * local corner-cutting pass (which only rounds individual steps into small
+ * arcs), the averaging window spans several vertices, so long grid-aligned
+ * staircase runs collapse onto their straight centre line — the rim reads as one
+ * continuous curve rather than a chain of little bumps. The window grows with
+ * `strength`.
+ *
+ * @group Geometries
+ */
+export declare function smoothBoundaryLoops(geometry: BufferGeometry, loops: number[][], strength: number): void;
+/**
+ * Snap the boundary (rim) vertices of an indexed mesh onto the nearest point of
+ * a set of reference polylines (closed world-X/Z outlines). Used to pull a mesh
+ * rim exactly onto a shared outline, so two meshes that meet at an edge (e.g. a
+ * surface and the floor it bounds) share one rim curve instead of two
+ * independently triangulated (and diverging) ones.
+ *
+ * When `getY` is provided, each snapped rim vertex's Y is also set to
+ * `getY(x, z)` at its new position, so the rim can be pinned to a shared height
+ * as well as X/Z. When omitted, only X/Z are moved and Y is left as-is.
+ *
+ * @group Geometries
+ */
+export declare function snapBoundaryToOutline(geometry: BufferGeometry, polylines: Vec2[][], getY?: (x: number, z: number) => number): void;

package/dist/types/sdk/geometries/geometry-attributes.d.ts

@@ -0,0 +1,37 @@
+import { BufferGeometry } from 'three';
+import { Vec2 } from '../types/common';
+/**
+ * Assemble an indexed {@link BufferGeometry} from flat `position`, `normal` and
+ * `uv` arrays plus a triangle index list. The index buffer is automatically
+ * `Uint16Array` or `Uint32Array` depending on the vertex count, and bounding
+ * volumes are computed. Optional draw `groups` (`[start, count, materialIndex]`)
+ * may be supplied for multi-material meshes.
+ *
+ * @group Geometries
+ */
+export declare function createIndexedGeometry(positions: ArrayLike<number>, normals: ArrayLike<number>, uvs: ArrayLike<number>, indices: ArrayLike<number>, groups?: number[][] | null): BufferGeometry;
+/**
+ * Rotate a geometry about the +Y axis by `degrees`, pivoting around `origin`
+ * (world X/Z, default `[0, 0]`). Both the position and normal attributes are
+ * rotated. A no-op when `degrees` is 0. Bounding volumes are refreshed.
+ *
+ * @group Geometries
+ */
+export declare function rotateGeometryY(geometry: BufferGeometry, degrees: number, origin?: Vec2): void;
+/**
+ * Set per-vertex UVs in `[0, 1]` from the X/Z bounding box of the geometry,
+ * giving a planar projection onto the world X/Z plane (suitable for flat or
+ * near-flat meshes such as terrain, water and ground planes).
+ *
+ * @group Geometries
+ */
+export declare function computePlanarXZUv(geometry: BufferGeometry): void;
+/**
+ * Compute smooth vertex normals and ensure they point up (+Y). After a height
+ * field is mirrored through `y = 0` or comes from an arbitrary triangulation the
+ * winding may yield downward normals; if so the index winding is reversed and
+ * the normals recomputed. Bounding volumes are refreshed.
+ *
+ * @group Geometries
+ */
+export declare function computeUpwardNormals(geometry: BufferGeometry): void;

package/dist/types/sdk/geometries/grid-sampling.d.ts

@@ -0,0 +1,50 @@
+import { BufferGeometry } from 'three';
+/**
+ * Flag the invalid samples of a row-major grid that are connected (4-neighbour)
+ * to the grid border, returning a mask where `1` marks a border-connected
+ * ("external") invalid sample. Invalid samples fully enclosed by valid data
+ * (internal holes) are left as `0`, so the caller can distinguish the outer rim
+ * of a footprint from holes punched inside it (e.g. to fill the latter while
+ * keeping the former as the true outline).
+ *
+ * @param values row-major grid of length `nx * ny`
+ * @param nx number of columns
+ * @param ny number of rows
+ * @param isInvalid predicate marking a sample value as missing/hole
+ *
+ * @group Geometries
+ */
+export declare function floodFillExternalHoles(values: ArrayLike<number>, nx: number, ny: number, isInvalid: (v: number) => boolean): Uint8Array;
+/**
+ * Bilinear sample of a row-major grid that ignores hole/invalid samples: only
+ * the valid corners contribute (re-normalised by their weights). Sampling on or
+ * just outside a footprint outline therefore returns the true edge value instead
+ * of blending in a far-away `fallback`. When all four corners are invalid the
+ * nearest valid sample (within a small search radius) is used, falling back to
+ * `fallback` only if none is found nearby.
+ *
+ * @param fx fractional column coordinate (`worldX / cellW`)
+ * @param fz fractional row coordinate (`worldZ / cellH`)
+ *
+ * @group Geometries
+ */
+export declare function sampleValidGrid(values: ArrayLike<number>, nx: number, ny: number, fx: number, fz: number, isInvalid: (v: number) => boolean, fallback: number): number;
+/**
+ * Build a flat plane at `y = 0` covering the cells of a regular grid for which a
+ * `present` predicate holds at all four corners, so the plane follows the
+ * outline of an arbitrary (possibly holed) footprint rather than a plain
+ * rectangle. Unused grid vertices are dropped (compacted) so the result can be
+ * cheaply subdivided afterwards. UVs span `[0, 1]` across the full grid extent.
+ *
+ * @param nx number of columns of grid vertices
+ * @param ny number of rows of grid vertices
+ * @param cellW column spacing in world units
+ * @param cellH row spacing in world units
+ * @param present `(c, r) => boolean`, whether the grid vertex at column `c`,
+ *   row `r` lies inside the footprint
+ * @param originX world X of column 0 (default 0)
+ * @param originZ world Z of row 0 (default 0)
+ *
+ * @group Geometries
+ */
+export declare function buildMaskedGridPlane(nx: number, ny: number, cellW: number, cellH: number, present: (c: number, r: number) => boolean, originX?: number, originZ?: number): BufferGeometry;