@webviz/subsurface-viewer 1.17.8 → 1.18.2

package/dist/layers/polyline_group/polylineGroupLayer.d.ts

@@ -0,0 +1,239 @@
+import type { Color, FilterContext, PickingInfo, UpdateParameters } from "@deck.gl/core";
+import { CompositeLayer } from "@deck.gl/core";
+import type { PathLayerProps } from "@deck.gl/layers";
+import { PathLayer } from "@deck.gl/layers";
+import type { Position } from "@deck.gl/core";
+import type { Point2D } from "../..";
+import type { ExtendedLayerProps, LayerPickInfo } from "../utils/layerTools";
+export type PolylineStyle = {
+    color?: Color;
+    width?: number;
+    dashArray?: [number, number];
+};
+export type Polyline = PolylineStyle & {
+    id?: string | number;
+    /**
+     * The geometry of this polyline.
+     *
+     * - `Position[]` — a single connected path (the common case).
+     * - `PolylineGroup` — a set of disjoint segments that share the same logical
+     *   identity (id, picking, visibility). Use this to represent a horizon that
+     *   is cut by faults: each segment in `group.polylines` is a full `Polyline`
+     *   and may carry its own `color`, `width`, and `dashArray` overrides, enabling
+     *   per-segment highlighting. The parent `Polyline` acts as the logical owner.
+     *
+     *   One level only — segment paths must be `Position[]`; nested `PolylineGroup`
+     *   paths inside segments are not supported.
+     *
+     *   `BinaryPolylines` inside the sub-group is not supported; use `Polyline[]`.
+     */
+    path: Position[] | PolylineGroup;
+};
+/**
+ * Binary format for high-performance rendering of large polyline sets.
+ * `positions` is a flat interleaved Float32Array: [x,y,z, x,y,z, ...].
+ * `startIndices` contains the vertex index where each polyline begins;
+ * the last polyline ends at the end of the positions array.
+ * Per-polyline color/width overrides are not supported — use group-level values.
+ *
+ * Optionally, `colors` (Uint8Array, RGBA, normalized, length = 4 * num vertices)
+ * and `widths` (Float32Array, length = num vertices) can be provided for per-vertex
+ * styling. If omitted, group-level color/width will be used for all vertices.
+ */
+export type BinaryPolylines = {
+    positions: Float32Array;
+    startIndices: Uint32Array;
+    colors?: Uint8Array;
+    widths?: Float32Array;
+};
+export type PolylineGroup = PolylineStyle & {
+    id?: string | number;
+    name?: string;
+    polylines: Polyline[] | BinaryPolylines;
+};
+/**
+ * Props accepted by {@link PolylineGroupLayer}.
+ *
+ * Styling is resolved through a cascade for each rendered path:
+ * 1. polyline-level accessor (`getPolylineColor` / `getPolylineWidth` / `getPolylineDashArray`)
+ * 2. `Polyline` field (`color` / `width` / `dashArray`)
+ * 3. group-level accessor (`getGroupColor` / `getGroupWidth` / `getGroupDashArray`)
+ * 4. `PolylineGroup` field (`color` / `width` / `dashArray`)
+ * 5. layer default (`defaultGroupStyle`)
+ */
+export interface PolylineGroupLayerProps extends ExtendedLayerProps, Pick<PathLayerProps, "widthUnits" | "widthScale" | "widthMinPixels" | "widthMaxPixels" | "jointRounded" | "capRounded" | "miterLimit" | "billboard"> {
+    /**
+     * Array of polyline groups. Each group holds a set of polylines and
+     * optional group-level color/width defaults.
+     */
+    data: PolylineGroup[];
+    /**
+     * Return an explicit color for all polylines in `group`.
+     * Takes precedence over `PolylineGroup.color`.
+     * Return `null` or `undefined` to fall through to the field value.
+     */
+    getGroupColor?: (group: PolylineGroup) => Color | null | undefined;
+    /**
+     * Return an explicit width for all polylines in `group`.
+     * Takes precedence over `PolylineGroup.width`.
+     * Return `null` or `undefined` to fall through to the field value.
+     */
+    getGroupWidth?: (group: PolylineGroup) => number | null | undefined;
+    /**
+     * Return an explicit color for an individual `polyline`.
+     * Takes precedence over the polyline's own `color` field and the group accessor.
+     * Return `null` or `undefined` to continue down the cascade.
+     */
+    getPolylineColor?: (polyline: Polyline, group: PolylineGroup) => Color | null | undefined;
+    /**
+     * Return an explicit width for an individual `polyline`.
+     * Takes precedence over the polyline's own `width` field and the group accessor.
+     * Return `null` or `undefined` to continue down the cascade.
+     */
+    getPolylineWidth?: (polyline: Polyline, group: PolylineGroup) => number | null | undefined;
+    /** Extract the polylines from a group object. Defaults to `g.polylines`. */
+    getGroupPolylines?: (group: PolylineGroup) => Polyline[] | BinaryPolylines;
+    /**
+     * Extract the path positions from a polyline object. Defaults to `p.path as Position[]`.
+     * Only called on leaf polylines whose `path` is `Position[]` (i.e. not on container
+     * polylines whose `path` is a `PolylineGroup`).
+     */
+    getPolylinePath?: (polyline: Polyline, group: PolylineGroup) => Position[];
+    /**
+     * Fallback style applied when no group or polyline style is resolved.
+     * Defaults to `{ color: [0, 128, 255, 255], width: 2 }`.
+     */
+    defaultGroupStyle?: PolylineStyle;
+    /**
+     * If true, input Z values are interpreted as depths (positive = down),
+     * so they are negated before rendering. Default: true.
+     */
+    ZIncreasingDownwards?: boolean;
+    /** Enable/disable depth testing when rendering layer. Default: true. */
+    depthTest?: boolean;
+    /**
+     * Set of group ids to hide. Groups not in the set remain visible.
+     * Uses GPU-side filtering — no re-flatten required when changed.
+     *
+     * @remarks Group ids can be defined using string or number. The set can
+     * contain a mix of both, but the type of ids in the set should match the
+     * type of `PolylineGroup.id` for correct filtering.
+     */
+    hiddenGroups?: Set<string | number>;
+    /**
+     * Set of polyline ids to hide. Only applies to polylines defined via
+     * the `Polyline[]` format (ids are unavailable in BinaryPolylines).
+     * Uses GPU-side filtering — no re-flatten required when changed.
+     *
+     * @remarks Polyline ids can be defined using string or number. The set can
+     * contain a mix of both, but the type of ids in the set should match the
+     * type of `Polyline.id` for correct filtering.
+     */
+    hiddenPolylines?: Set<string | number>;
+    /**
+     * Return a `[dashLength, gapLength]` dash pattern for all polylines in `group`.
+     * Providing this accessor (even for some groups) activates `PathStyleExtension`
+     * for the entire layer. Return `null` or `undefined` to fall through to the field value.
+     */
+    getGroupDashArray?: (group: PolylineGroup) => [number, number] | null | undefined;
+    /**
+     * Return a `[dashLength, gapLength]` dash pattern for an individual `polyline`,
+     * overriding the group-level pattern.
+     * Return `null` or `undefined` to continue down the cascade.
+     */
+    getPolylineDashArray?: (polyline: Polyline, group: PolylineGroup) => [number, number] | null | undefined;
+    /**
+     * Use high-precision dash rendering (avoids dash-length variation at segment
+     * joins). Slightly more expensive. Default: false.
+     */
+    highPrecisionDash?: boolean;
+    /**
+     * Path of the cross-section fence as 2-D world-space XY coordinates `[x, y]`.
+     * When provided, each polyline path point is interpreted as
+     * `[abscissa, depth]` where `abscissa` is the cumulative distance along this fence.
+     *
+     * - In a `SectionView` viewport the paths are rendered in abscissa/depth space.
+     * - In a 3D viewport the abscissa values are projected back onto the fence.
+     *
+     * @remarks Pass a stable reference (module-level or memoized constant) to avoid
+     * unnecessary re-computation of the section index.
+     */
+    sectionPath?: Point2D[];
+}
+/**
+ * A deck.gl {@link CompositeLayer} that renders collections of polylines
+ * organised into named groups.
+ *
+ * **Data formats**
+ *
+ * Each {@link PolylineGroup} holds one or more polylines. Two formats are
+ * supported for `PolylineGroup.polylines`:
+ * - `Polyline[]` — per-object format; supports `id`, and per-polyline `color`,
+ *   `width`, and `dashArray` overrides.
+ * - {@link BinaryPolylines} — flat typed-array format; more efficient for
+ *   large datasets loaded from binary sources. Group-level styling only.
+ *
+ * **Discontinuous polylines**
+ *
+ * A `Polyline.path` may be a nested {@link PolylineGroup}, making one logical
+ * polyline consist of disjoint segments (e.g. a seismic horizon cut by faults).
+ * All segments share the root `Polyline.id` for picking and visibility filtering.
+ *
+ * **Styling cascade**
+ *
+ * Color, width, and dash pattern are resolved per-path in this order:
+ * polyline accessor → `Polyline` field → group accessor → `PolylineGroup` field
+ * → layer default prop.
+ *
+ * **Section-view projection**
+ *
+ * When {@link PolylineGroupLayerProps.sectionPath} is provided, path coordinates
+ * are interpreted as `[abscissa, depth]`. The layer renders two sub-layers:
+ * one in abscissa/depth space for {@link SectionViewport}s, and one with
+ * abscissa values projected back to world XY for 3-D viewports.
+ *
+ * **GPU-side visibility**
+ *
+ * {@link PolylineGroupLayerProps.hiddenGroups} and
+ * {@link PolylineGroupLayerProps.hiddenPolylines} use `DataFilterExtension`.
+ * Changing these sets triggers only a GPU attribute update; the flattened
+ * data buffer is never rebuilt.
+ */
+export declare class PolylineGroupLayer extends CompositeLayer<PolylineGroupLayerProps> {
+    /** @override Builds the initial flat data buffer and section index from `props.data`. */
+    initializeState(): void;
+    /**
+     * @override
+     * Rebuilds the flat data buffer when `data` or any accessor/default prop changes.
+     * Rebuilds the section index when `sectionPath` changes.
+     */
+    updateState({ props, oldProps, }: UpdateParameters<PolylineGroupLayer>): void;
+    /**
+     * @override
+     * Routes the `paths-section` sub-layer to {@link SectionViewport}s and
+     * the `paths-3d` sub-layer to all other viewports.
+     * Only active when `sectionPath` is set; otherwise the single `paths` sub-layer
+     * is always visible.
+     */
+    filterSubLayer({ layer, viewport }: FilterContext): boolean;
+    /**
+     * @override
+     * Returns one or more `PathLayer` sub-layers.
+     * - Without `sectionPath`: a single `paths` sub-layer for non-binary groups,
+     *   plus a single `paths-binary` sub-layer that merges all binary groups into
+     *   combined typed-array buffers and passes them straight to the GPU.
+     * - With `sectionPath`: a `paths-section` sub-layer (abscissa/depth space)
+     *   and a `paths-3d` sub-layer (world XY space), routed by {@link filterSubLayer}.
+     *   Binary groups are not supported in section mode and are skipped with a warning.
+     */
+    renderLayers(): PathLayer[];
+    /**
+     * @override
+     * Enriches the pick result with the originating {@link PolylineGroup} (`info.group`),
+     * the root {@link Polyline} (`info.object`), and layer properties for display
+     * (group name, polyline id, depth at the picked coordinate).
+     */
+    getPickingInfo({ info }: {
+        info: PickingInfo;
+    }): LayerPickInfo;
+}