@equinor/videx-3d 1.1.1 → 3.0.0

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

@@ -0,0 +1,288 @@
+import { BufferGeometry } from 'three';
+import { Vec2 } from '../types/common';
+import { PlanarPolygonGeometry } from './planar-geometry';
+/** Options shared by the ocean geometry builders. */
+export type OceanGeometryOptions = {
+    /**
+     * Horizontal extent in world units (meters): a single number for a square, or
+     * `[width (X), length (Z)]`. Default 100000 (100 km).
+     */
+    size?: number | Vec2;
+    /**
+     * Water-surface tessellation: a single number for both axes, or `[X, Z]`.
+     * The default `0` uses the fewest triangles needed to fill the footprint
+     * outline (a flat surface needs no interior grid — the waves are shaded
+     * per-pixel). A positive value lays down a regular subdivision grid, which
+     * only matters when vertex displacement is enabled. Default 0.
+     */
+    surfaceSegments?: number | Vec2;
+    /** Center offset in world X/Z (meters). Default `[0, 0]`. */
+    origin?: Vec2;
+    /**
+     * Orientation in degrees, rotating the geometry about the +Y axis around
+     * {@link origin} (counter-clockwise viewed from above). Default 0.
+     */
+    rotation?: number;
+};
+/** Options for {@link createOceanPlane}. */
+export type OceanPlaneOptions = OceanGeometryOptions;
+/** Options for {@link createOceanBox}. */
+export type OceanBoxOptions = OceanGeometryOptions & {
+    /**
+     * Mean water depth in meters: distance from the surface (y = 0) down to the
+     * sea bed. Default 150.
+     */
+    waterDepth?: number;
+    /**
+     * Sea-bed depth variation in meters (±) around {@link waterDepth}. With the
+     * defaults the bed varies between 100 m and 200 m. Default 50.
+     */
+    depthVariation?: number;
+    /**
+     * Sea-bed tessellation: a single number for both axes, or `[X, Z]`. Controls
+     * how finely the depth variation is resolved. Default 32.
+     */
+    bedSegments?: number | Vec2;
+    /** Seed for the procedural sea-bed variation. Default 0. */
+    seed?: number;
+};
+/**
+ * The three separate geometries produced by {@link createOceanBox}. Each is a
+ * standalone {@link BufferGeometry} so they can be rendered as independent
+ * meshes (and routed independently through transparency / OIT).
+ */
+export type OceanBox = {
+    /** Top face (y = 0, normal +Y), tessellated for the waves. */
+    surface: BufferGeometry;
+    /** The four side walls (outward normals) forming the water body volume. */
+    body: BufferGeometry;
+    /** The displaced sea-bed bottom face (normals follow the bed slope). */
+    bed: BufferGeometry;
+};
+/**
+ * Build a flat ocean surface plane lying in the world X/Z plane (normal +Y) at
+ * y = 0, centered on `origin`. UVs span [0, 1] across the plane.
+ *
+ * The ocean animation is evaluated in world space, so this could equally be a
+ * set of tiled patches; this helper just provides a convenient single plane.
+ *
+ * @group Geometries
+ */
+export declare function createOceanPlane(options?: OceanPlaneOptions): BufferGeometry;
+/**
+ * Build an ocean box volume for a more complete water emulation. Returns three
+ * separate geometries so each can be rendered as its own mesh and routed
+ * independently through transparency / OIT:
+ *
+ * - **surface** — the top face (y = 0, normal +Y), tessellated for the waves.
+ * - **body** — the four side walls (outward normals); render with a
+ *   double-sided volume material so the interior reads as a tinted water body.
+ * - **bed** — the bottom face, displaced to a procedurally varying depth
+ *   between `waterDepth - depthVariation` and `waterDepth + depthVariation`
+ *   (default 100–200 m), with normals following the bed slope.
+ *
+ * Pair with `<Ocean>` by passing `geometry={box.surface}` plus
+ * `bodyGeometry={box.body}` and `bedGeometry={box.bed}`.
+ *
+ * @group Geometries
+ */
+export declare function createOceanBox(options?: OceanBoxOptions): OceanBox;
+/** Options for {@link createOceanEllipseBox}. */
+export type OceanEllipseOptions = Omit<OceanGeometryOptions, 'surfaceSegments'> & {
+    /**
+     * Mean water depth in meters: distance from the surface (y = 0) down to the
+     * sea bed. Default 150.
+     */
+    waterDepth?: number;
+    /**
+     * Sea-bed depth variation in meters (±) around {@link waterDepth}. With the
+     * defaults the bed varies between 100 m and 200 m. Default 50.
+     */
+    depthVariation?: number;
+    /** Seed for the procedural sea-bed variation. Default 0. */
+    seed?: number;
+    /**
+     * Number of segments around the perimeter. Higher values give a rounder,
+     * smoother outline. Default 96.
+     */
+    perimeterSegments?: number;
+    /**
+     * Number of segments from the center out to the edge (concentric rings).
+     * Higher values resolve the sea-bed depth variation more finely and give
+     * smoother wave displacement. The default `0` is auto: just enough rings to
+     * keep the radial spacing close to the perimeter spacing (so triangles stay
+     * well-shaped without an excessive count). Default 0.
+     */
+    radialSegments?: number;
+};
+/**
+ * Build a round ocean box: a circular footprint when `size` is a single number
+ * (or an equal `[width, height]` pair), or an oval/ellipse when width and height
+ * differ. Returns the same three independent geometries as {@link createOceanBox}
+ * (surface, body walls, sea bed).
+ *
+ * A rounded outline avoids the hard corners of a rectangular box, so a very
+ * large body of water reads as endless / gently curving (like the curvature of
+ * the earth) rather than a visibly cut rectangle.
+ *
+ * `size` is the diameter on each axis: `[width (X), height (Z)]` (a single
+ * number means both). The footprint is `width/2` × `height/2` radii, centered on
+ * `origin` and optionally spun by `rotation` degrees about +Y.
+ *
+ * Pair with `<Ocean>` by passing `geometry={box.surface}` plus
+ * `bodyGeometry={box.body}` and `bedGeometry={box.bed}`.
+ *
+ * @group Geometries
+ */
+export declare function createOceanEllipseBox(options?: OceanEllipseOptions): OceanBox;
+/**
+ * Header describing the regular grid of a depth surface (a subset of a
+ * `SurfaceMeta` header). Distances are in world units (meters); `rot` is in
+ * degrees, matching the surface data convention.
+ */
+export type SurfaceGridHeader = {
+    /** Number of columns (samples along X). */
+    nx: number;
+    /** Number of rows (samples along Z). */
+    ny: number;
+    /** Column spacing in meters. */
+    xinc: number;
+    /** Row spacing in meters. */
+    yinc: number;
+    /** Grid rotation in degrees (about +Y), as stored in the surface header. */
+    rot: number;
+};
+/** Options for {@link createOceanBoxFromSurface}. */
+export type OceanBoxFromSurfaceOptions = {
+    /** Value marking missing/hole samples in `values`. Default -1. */
+    nullValue?: number;
+    /**
+     * Depth used to fill *internal* holes (invalid samples fully enclosed by
+     * valid data) so the box stays watertight. Invalid samples connected to the
+     * grid border are treated as outside the surface footprint (the outer rim)
+     * and are left as holes, so the sea bed follows the true surface outline.
+     * Defaults to the deepest (maximum) valid sample in `values`.
+     */
+    fillDepth?: number;
+    /**
+     * Reference depth (datum) of the input values, in meters. Surface grids are
+     * often stored *depth-normalized* — e.g. as `referenceDepth - trueDepth` (the
+     * convention used by this repo's IRAP parser, where `referenceDepth` is the
+     * surface's maximum/deepest sample) — so the shallowest sample sits at 0
+     * instead of its true depth below sea level. When set, the true positive-down
+     * depth of each sample is recovered as `referenceDepth - value` before the bed
+     * and walls are built, so the sea bed sits at its real depth (matching the
+     * `Surface` component). Leave undefined when `values` already hold true,
+     * positive-down depths (the bed is then built directly from them).
+     */
+    referenceDepth?: number;
+    /**
+     * Target water-surface tessellation (a single number for both axes, or
+     * `[X, Z]`). The default `0` builds the surface from the same simplified
+     * triangulation as the sea bed, flattened to `y = 0` — the fewest triangles
+     * that still trace the surface outline (the waves are shaded per-pixel, so no
+     * interior grid is needed). A positive value instead lays down a regular grid
+     * at that density, clipped to and stitched to the exact data outline (which is
+     * kept intact), so the interior is uniform — useful only when the surface is
+     * vertex-displaced. The rim is shared with the walls and bed either way.
+     * Default 0.
+     */
+    surfaceSegments?: number | Vec2;
+    /** Sea-bed TIN simplification error (meters) passed to the triangulator. Default 5. */
+    maxError?: number;
+    /**
+     * Optional rim smoothing strength. `0` (default) keeps the grid-aligned rim,
+     * which can look pixelated since the surface follows a regular grid; `1`–`3`
+     * progressively smooth it. The outline (rim) vertices of the water surface
+     * and sea bed are filtered with a windowed moving average whose window grows
+     * with this value, so long staircase runs collapse onto their straight centre
+     * line and the rim reads as one continuous curve (rather than a chain of small
+     * arcs). Only the X/Z position of the existing boundary vertices is moved —
+     * their depth (Y), the sea-bed TIN and every interior vertex are left
+     * untouched, so bathymetry detail (and the triangulator's efficiency) is
+     * preserved.
+     */
+    rimSmoothing?: number;
+};
+/**
+ * Build an ocean box whose sea bed is the bathymetry of a depth surface,
+ * extracted (e.g. from an IRAP binary grid) as a row-major `Float32Array` plus
+ * the grid `header`. The function is data-agnostic — it takes the raw values
+ * and header, so it can be called from a generator or anywhere else.
+ *
+ * The result is positioned in the same local space as the `Surface` component
+ * (the far row is centered on the rotation pivot and the grid is rotated by
+ * `header.rot`; the world `xori`/`yori` origin is **not** baked in, so position
+ * the resulting `<Ocean>` exactly as you would a `Surface`). Sea level is the
+ * reference: the water surface lies at `y = 0` and the bed at `y = -depth`
+ * (depths are positive-down).
+ *
+ * Invalid samples connected to the grid border are treated as the outer rim
+ * (outside the surface footprint) and kept as holes, so the bed and walls
+ * follow the true surface outline; invalid samples fully enclosed by valid data
+ * are internal holes and get filled so the box stays watertight.
+ *
+ * - **surface** — flat water plane at `y = 0` tracing the same valid-region
+ *   outline as the walls and bed (not a plain rectangle).
+ * - **body** — walls tracing the outline of the valid region, from `y = 0`
+ *   down to the bathymetry.
+ * - **bed** — a simplified TIN of the (internal-hole-filled) bathymetry.
+ *
+ * Set `rimSmoothing` to relax the grid-aligned outline into a smooth, curved
+ * rim by moving only the existing boundary vertices in place (the sea-bed TIN
+ * and all interior detail are preserved).
+ *
+ * Set `referenceDepth` when the input grid is depth-normalized (e.g. stored as
+ * `referenceDepth - trueDepth`, as produced by this repo's IRAP parser) so the
+ * bed is placed at its true depth below sea level instead of being anchored to
+ * the shallowest sample; leave it undefined when `values` already hold true,
+ * positive-down depths.
+ *
+ * @group Geometries
+ */
+export declare function createOceanBoxFromSurface(values: Float32Array, header: SurfaceGridHeader, options?: OceanBoxFromSurfaceOptions): OceanBox;
+/** Options for {@link createOceanBoxFromPolygon}. */
+export type OceanBoxFromPolygonOptions = {
+    /** Mean water depth in meters (bed sits at `y = -waterDepth` on average). Default 150. */
+    waterDepth?: number;
+    /** Sea-bed depth variation in meters (±) around {@link waterDepth}. Default 50. */
+    depthVariation?: number;
+    /** Seed for the procedural sea-bed variation. Default 0. */
+    seed?: number;
+    /**
+     * Target water-surface tessellation (a single number for both axes, or
+     * `[X, Z]`). The default `0` triangulates the footprint straight from its
+     * outline (the fewest triangles that fill the shape — the waves are shaded
+     * per-pixel). A positive value instead lays down a regular grid at that
+     * density clipped to the outline, with a thin triangle band stitching the
+     * grid to the exact outline — so the interior stays a uniform grid (only
+     * deviating at the rim) for clean vertex displacement. Default 0.
+     */
+    surfaceSegments?: number | Vec2;
+    /**
+     * Target sea-bed tessellation (a single number for both axes, or `[X, Z]`).
+     * The default lays a regular grid at this density clipped to and stitched to
+     * the exact polygon outline, displaced to the procedural depth. It shares the
+     * exact outline rim with the surface and walls (so the box stays watertight)
+     * while resolving the bathymetry more finely than the flat surface. A value of
+     * `0` triangulates the footprint straight from its outline instead. Default
+     * 48.
+     */
+    bedSegments?: number | Vec2;
+};
+/**
+ * Build an ocean box whose footprint matches a 2D polygon outline (e.g. a field
+ * boundary parsed from GeoJSON). Supports multiple polygon rings, each with
+ * zero or more holes. The polygon's `[x, y]` coordinates map to world
+ * `(x, 0, -y)` — the same `rotateX(-PI/2)` convention used elsewhere — so the
+ * northing axis becomes -Z.
+ *
+ * - **surface** — flat water plane at `y = 0`, tessellated to the outline.
+ * - **body** — a vertical wall around every ring (outer boundaries and holes),
+ *   from `y = 0` down to the bed.
+ * - **bed** — the same outline tessellation displaced to a procedurally varying
+ *   depth (reusing the {@link createOceanBox} sea-bed model).
+ *
+ * @group Geometries
+ */
+export declare function createOceanBoxFromPolygon(polygon: PlanarPolygonGeometry, options?: OceanBoxFromPolygonOptions): OceanBox;

package/dist/types/sdk/geometries/packing.d.ts

@@ -33,7 +33,7 @@ export type PackedBufferGeometry = {
     userData?: any;
 };
 export type PackedBufferGeometryCollection = Record<string, PackedBufferGeometry>;
-export declare function getTypedArrayType(array: ArrayBufferLike | TypedArray): "Uint8Array" | "Float64Array" | "Uint16Array" | "Uint32Array" | "Int8Array" | "Int16Array" | "Int32Array" | "Float32Array";
+export declare function getTypedArrayType(array: ArrayBufferLike | TypedArray): "Uint8Array" | "Float32Array" | "Float64Array" | "Uint16Array" | "Uint32Array" | "Int8Array" | "Int16Array" | "Int32Array";
 export declare function getTypedArrayFromBuffer(buffer: ArrayBufferLike, type: string): Float32Array<ArrayBufferLike> | Int8Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int16Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Int32Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike>;
 export declare function packAttribute(typedArray: TypedArray, itemSize?: number): PackedBufferAttribute;
 export declare function packBufferGeometryLike(geometry: BufferGeometryLike): [PackedBufferGeometry, ArrayBufferLike[]];

package/dist/types/sdk/geometries/tessellation.d.ts

@@ -0,0 +1,25 @@
+import { BufferGeometry } from 'three';
+/**
+ * Midpoint-subdivide an indexed geometry `iterations` times, splitting every
+ * triangle into four (each edge midpoint is shared between adjacent triangles).
+ * Only the `position` attribute is interpolated; stale `normal`/`uv` attributes
+ * are dropped (recompute them afterwards). A no-op when the geometry has no
+ * index or `iterations <= 0`.
+ *
+ * @group Geometries
+ */
+export declare function subdivideGeometry(geometry: BufferGeometry, iterations: number): void;
+/**
+ * Refine an indexed triangle mesh `iterations` times by splitting only its
+ * INTERIOR edges, leaving boundary edges — and therefore the exact outline and
+ * its vertex count — untouched. Each interior edge contributes one midpoint that
+ * is shared by the two triangles adjacent to it, so the mesh stays conforming
+ * (no T-junctions) while the boundary loop is preserved exactly. This is what
+ * lets a surface or sea bed be densified for vertex displacement / detail while
+ * its rim still matches, vertex-for-vertex, walls extruded from the same
+ * outline. Only `position` is interpolated; stale `normal`/`uv` are dropped
+ * (recompute afterwards). A no-op without an index or when `iterations <= 0`.
+ *
+ * @group Geometries
+ */
+export declare function refineInteriorEdges(geometry: BufferGeometry, iterations: number): void;

package/dist/types/sdk/index.d.ts

@@ -7,13 +7,18 @@ export * from './data/helpers/formations-helpers';
 export * from './data/helpers/well-helpers';
 export * from './data/Store';
 export * from './data/types';
+export * from './geometries/boundary-loops';
 export * from './geometries/curve/curve-3d';
 export * from './geometries/curve/tube-geometry';
 export * from './geometries/delatin';
 export * from './geometries/fence';
 export * from './geometries/geometry';
+export * from './geometries/geometry-attributes';
+export * from './geometries/grid-sampling';
+export * from './geometries/ocean-geometry';
 export * from './geometries/packing';
 export * from './geometries/planar-geometry';
+export * from './geometries/tessellation';
 export * from './geometries/triangulate-grid';
 export * from './geometries/triangulate-grid-delaunay';
 export * from './managers/CameraManager';

package/dist/types/sdk/utils/elevation-map.d.ts

@@ -13,3 +13,26 @@ export declare function createNormalTexture(buffer: Uint8Array, width: number, h
  * Create a data texture from RGBA encoded depth values
  */
 export declare function createElevationTexture(buffer: Float32Array, width: number, height: number): DataTexture;
+/**
+ * Compute geometric surface normals from an elevation grid, encoded as a compact
+ * RG8 buffer (2 bytes/texel) using a hemisphere encoding: only the grid-local
+ * `x` and `z` components are stored (mapped to [0, 1]); the consumer reconstructs
+ * `y = sqrt(1 - x^2 - z^2)`.
+ *
+ * This replicates the per-fragment normal that `SurfaceMaterial`'s shader derives
+ * from the elevation texture (same four diagonal neighbours, cross products and
+ * hole handling), but pays the cost once on the CPU instead of in every OIT pass.
+ * The result is laid out to match the elevation buffer (row-major, intended for a
+ * `flipY = true` texture), so it samples 1:1 with the same grid UVs.
+ *
+ * @param data elevation values (row-major, holes < 0)
+ * @param columns number of columns (nx)
+ * @param rows number of rows (ny)
+ * @param xScale column spacing (xinc)
+ * @param yScale row spacing (yinc)
+ */
+export declare function computeSurfaceNormalsRG(data: Float32Array, columns: number, rows: number, xScale: number, yScale: number): Uint8Array<ArrayBuffer>;
+/**
+ * Create an RG8 data texture from a buffer produced by {@link computeSurfaceNormalsRG}.
+ */
+export declare function createPackedNormalTexture(buffer: Uint8Array, width: number, height: number): DataTexture;

package/dist/types/sdk/utils/trigonometry.d.ts

@@ -8,5 +8,8 @@ export declare const PI8: number;
  * Given a 2D rectangle and an angle off the center, find the point
  * of the closest corner. Used for anchoring connector lines
  * to annotation labels.
+ *
+ * Pass an optional `target` array to write the result into, avoiding
+ * an allocation in hot paths.
  */
-export declare function edgeOfRectangle(rect: Vec2, theta: number): Vec2;
+export declare function edgeOfRectangle(rect: Vec2, theta: number, target?: Vec2): Vec2;

package/dist/types/sdk/utils/vector-operations.d.ts

@@ -15,6 +15,13 @@ export declare function angleVec3(v1: Vec3, v2: Vec3): number;
 export declare function rotateVec3(vector: Vec3, axis?: Vec3, angle?: number): Vec3;
 export declare function directionVec3(v1: Vec3, v2: Vec3): Vec3;
 export declare function distanceVec3(v1: Vec3, v2: Vec3): number;
+/**
+ * Resolve a `number | Vec2 | undefined` parameter into a concrete `Vec2`. A
+ * single number is expanded to `[n, n]`; `undefined` falls back to
+ * `[fallback, fallback]`. Useful for options that accept either a uniform value
+ * or independent X/Z (or width/height) components.
+ */
+export declare function asVec2(value: number | Vec2 | undefined, fallback: number): Vec2;
 export declare function getVec2(buffer: number[], id: number): Vec2;
 export declare function setVec2(buffer: number[], id: number, value: Vec2): void;
 export declare function normalizeVec2(v: Vec2): Vec2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/videx-3d",
-  "version": "1.1.1",
+  "version": "3.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -68,12 +68,12 @@
     "zustand": "^5.0.3"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.0.1",
+    "@chromatic-com/storybook": "^5.2.1",
     "@eslint/js": "^9.39.3",
     "@react-three/drei": "^10.7.7",
     "@react-three/fiber": "^9.5.0",
-    "@storybook/addon-docs": "^10.2.13",
-    "@storybook/react-vite": "^10.2.13",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
     "@types/d3-array": "^3.2.1",
     "@types/d3-axis": "^3.0.6",
     "@types/d3-drag": "^3.0.7",
@@ -90,13 +90,13 @@
     "@types/react-dom": "^19.0.4",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "8.56.1",
-    "@vitejs/plugin-react": "^5.1.4",
+    "@vitejs/plugin-react": "^6.0.3",
     "@vitest/coverage-v8": "^4.0.18",
     "@vitest/ui": "^4.0.18",
     "eslint": "^9.39.3",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
-    "eslint-plugin-storybook": "^10.2.13",
+    "eslint-plugin-storybook": "^10.4.6",
     "globals": "^17.4.0",
     "lodash": "^4.17.23",
     "minimist": "^1.2.8",
@@ -105,16 +105,15 @@
     "react-dom": "^19.2.4",
     "rimraf": "^6.1.3",
     "sass": "^1.97.3",
-    "storybook": "^10.2.13",
+    "storybook": "^10.4.6",
     "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
     "unplugin-dts": "^1.0.0-beta.6",
-    "vite": "^7.3.1",
+    "vite": "^8.1.3",
     "vite-plugin-css-injected-by-js": "^4.0.1",
-    "vite-plugin-externalize-deps": "^0.10.0",
     "vite-plugin-glsl": "^1.5.5",
-    "vite-plugin-static-copy": "^3.2.0",
+    "vite-plugin-static-copy": "^4.1.1",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {