@equinor/videx-3d 3.0.0 → 3.1.0

package/dist/src/sdk/materials/shaderLib/procedural-normal.glsl

@@ -0,0 +1,274 @@
+// Procedural (texture-free) normal-detail helpers.
+//
+// Pure functions - no uniforms, no varyings - so any material can reuse them by
+// supplying its own inputs and controls. Include this file in a FRAGMENT shader
+// (it relies on screen-space derivatives, dFdx/dFdy).
+//
+// Dependencies the consuming material must provide when calling perturbNormalHeight:
+//   - normal   : the shading normal to perturb, in VIEW space
+//   - viewPos  : the surface position in VIEW space (e.g. -vViewPosition)
+//   - height   : a scalar height field sampled at this fragment (produced by the
+//                pnGranular / pnGrain / pnScratches helpers below, summed); the caller
+//                scales it to taste (its "strength"/bump amount) and may fade it by
+//                distance
+// And when sampling a pattern height (pnGranular / pnGrain / pnScratches):
+//   - uv         : a 2D coordinate ALREADY scaled by the caller's frequency. The
+//                  caller owns the units (world distance, normalized, radius-based,
+//                  ...) and which axis maps to uv.y (the grain/stretch axis).
+//   - octaves    : fbm octave count for pnGranular / pnGrain (1..N). pnScratches is
+//                  segment-based and takes NO octave count.
+//   - periodX    : if > 0, the noise tiles seamlessly every `periodX` cells in x (pass
+//                  the number of cells around a circumference to remove the wrap seam
+//                  on a closed cylinder; pass 0 to disable). Tiling is exact for
+//                  granular and for grain/scratches at angle 0.
+// The patterns return scalar heights; combine several by summing (optionally weighted)
+// and feed the result to perturbNormalHeight.
+//
+// "width" of the features is controlled by the caller's frequency/anisotropy/angle
+// folded into uv; "height" of the bump is the caller-owned scalar passed to
+// perturbNormalHeight. No CPU data or vertex attributes are required beyond whatever
+// the material already uses to build its uv.
+
+// Lattice wrap period (cells). The value-noise lattice (and the scratch seed grid) repeat
+// every PN_WRAP cells per axis, so a caller that reduces a very large sample coordinate
+// into [0, PN_WRAP) - to keep floor()/fract() float-precise at oilfield scale, where
+// metres-along-trajectory x frequency reaches ~1e5 and fract() quantises into visible
+// banding - still tiles SEAMLESSLY at the wrap. Large enough (4096 cells) that the repeat
+// is invisible for fine detail; a no-op (mod = identity) for the small coords normal use
+// produces.
+#define PN_WRAP 4096.0
+
+// Precision-robust 2D->1D hash (Dave Hoskins). fract() is applied BEFORE any multiply/
+// dot so the working values stay in [0,1) - this survives the large sample coordinates
+// that occur at oilfield scale (a pattern sampled by metres-along-trajectory times a
+// frequency reaches ~1e5+), where the older fract(p*c) + dot(p, p) form overflowed
+// float32 precision so fract() returned near-constant values and the noise collapsed /
+// stretched with distance down the well.
+float pnHash2(vec2 p) {
+  vec3 p3 = fract(vec3(p.xyx) * 0.1031);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+
+// 2D value noise (smoothstep-interpolated).
+float pnValueNoise2(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  // Wrap the integer lattice at PN_WRAP so the noise tiles seamlessly when a caller reduces
+  // a huge coordinate into [0, PN_WRAP) (identity for the small coords normal use produces).
+  vec2 i0 = mod(i, PN_WRAP);
+  vec2 i1 = mod(i + 1.0, PN_WRAP);
+  float a = pnHash2(i0);
+  float b = pnHash2(vec2(i1.x, i0.y));
+  float c = pnHash2(vec2(i0.x, i1.y));
+  float d = pnHash2(i1);
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+// Fractional Brownian motion with a dynamic (uniform-driven) octave count. The loop
+// bound is a compile-time constant (GLSL requirement); `octaves` clamps it at runtime.
+float pnFbm2(vec2 p, int octaves) {
+  float sum = 0.0;
+  float amp = 0.5;
+  float norm = 0.0;
+  for(int o = 0; o < 8; o++) {
+    if(o >= octaves)
+      break;
+    sum += amp * pnValueNoise2(p);
+    norm += amp;
+    p *= 2.02;
+    amp *= 0.5;
+  }
+  return norm > 0.0 ? sum / norm : 0.0;
+}
+
+// Tiling value noise: the integer lattice wraps at `periodX` cells in x, so a pattern
+// sampled over exactly `periodX` units in x is seamless (used to wrap around a
+// cylinder's circumference). y is not tiled.
+float pnValueNoise2Tiled(vec2 p, float periodX) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  float x0 = mod(i.x, periodX);
+  float x1 = mod(i.x + 1.0, periodX);
+  float y0 = mod(i.y, PN_WRAP);
+  float y1 = mod(i.y + 1.0, PN_WRAP);
+  float a = pnHash2(vec2(x0, y0));
+  float b = pnHash2(vec2(x1, y0));
+  float c = pnHash2(vec2(x0, y1));
+  float d = pnHash2(vec2(x1, y1));
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+// fbm on the x-tiling noise; lacunarity 2.0 so every octave's period stays integer.
+float pnFbm2Tiled(vec2 p, float periodX, int octaves) {
+  float sum = 0.0;
+  float amp = 0.5;
+  float norm = 0.0;
+  float per = max(periodX, 1.0);
+  for(int o = 0; o < 8; o++) {
+    if(o >= octaves)
+      break;
+    sum += amp * pnValueNoise2Tiled(p, per);
+    norm += amp;
+    p *= 2.0;
+    per *= 2.0;
+    amp *= 0.5;
+  }
+  return norm > 0.0 ? sum / norm : 0.0;
+}
+
+// fbm that tiles in x when periodX > 0, else plain (non-tiling) fbm.
+float pnFbm2Auto(vec2 p, int octaves, float periodX) {
+  return periodX > 0.5 ? pnFbm2Tiled(p, periodX, octaves) : pnFbm2(p, octaves);
+}
+
+// GRANULAR: isotropic value-noise bumps; `anisotropy` (0..1) stretches the cells along
+// uv.y. Signed height. periodX > 0 tiles x (e.g. a circumference).
+float pnGranular(vec2 uv, float anisotropy, int octaves, float periodX) {
+  vec2 p = vec2(uv.x, uv.y * mix(1.0, 0.04, anisotropy));
+  return pnFbm2Auto(p, octaves, periodX) - 0.5;
+}
+
+// BRUSHED: a directional fine grain - thin parallel ridges running at `angle` (radians;
+// 0 = along uv.y). `sharpness` (0..1) thins the ridges (their "width"); `uniformity`
+// (0..1) blends from an irregular grain to perfectly regular flutes. Positive height.
+// Tiling is exact only for angle == 0; other angles degrade gracefully (a faint seam).
+float pnGrain(vec2 uv, float angle, float sharpness, float uniformity, int octaves, float periodX) {
+  float ca = cos(angle), sa = sin(angle);
+  vec2 r = vec2(uv.x * ca - uv.y * sa, uv.x * sa + uv.y * ca);
+  float tile = abs(angle) < 1e-3 ? periodX : 0.0;
+  float n = pnFbm2Auto(vec2(r.x, r.y * 0.06), octaves, tile);
+  // Irregular grain (fbm-smooth, so it has no cusp to alias); `sharpness` thins the ridges.
+  float irregular = pow(1.0 - abs(2.0 * n - 1.0), mix(2.0, 8.0, clamp(sharpness, 0.0, 1.0)));
+  // Regular flutes: footprint-anti-aliased evenly-spaced ridges (period 1 in r.x). A
+  // smoothstep whose transition is never narrower than the pixel footprint (fwidth)
+  // keeps the ridge crisp up close WITHOUT the sharp cusp of the old (1-|sin|)^pow form
+  // - that cusp under-sampled the normal and shimmered even close up - and naturally
+  // band-limits into a flat tone once a flute drops below a pixel far away. `sharpness`
+  // sets the ridge width.
+  float dCentre = abs(r.x - floor(r.x + 0.5)); // 0 at a flute centre .. 0.5 between
+  float hw = mix(0.35, 0.05, clamp(sharpness, 0.0, 1.0));
+  float aaw = max(fwidth(r.x), 1e-4);
+  float regular = 1.0 - smoothstep(hw - aaw, hw + aaw, dCentre);
+  // Once a flute period approaches the pixel footprint (fwidth ~ 0.5, i.e. the sine is
+  // near screen-Nyquist at the grazing sides of the shell), flatten the flutes toward
+  // their duty-cycle mean (~2*hw). Without this the ridge stays a smooth-but-undersampled
+  // sine there and still shimmers even though the edges are footprint-AA'd.
+  regular = mix(regular, 2.0 * hw, smoothstep(0.3, 0.5, aaw));
+  return mix(irregular, regular, clamp(uniformity, 0.0, 1.0));
+}
+
+// SCRATCHES: sparse, thin grooves crossing at varied angles/lengths - a cell/segment
+// field rather than parallel lanes, so it reads like real scuffing. `density` (0..1) =
+// fraction of seed cells that carry a scratch; `angle` = orientation bias and `wander`
+// (0..1) widens the spread of directions around it (0 = all parallel, 1 = fully random);
+// `lengthScale` (>0) scales each groove's length; `halfWidth` sets the groove width in
+// sample (uv) units - pass (world-width x frequency) to get a FREQUENCY-INDEPENDENT width
+// so lowering the frequency lengthens/thins-out the scratches without widening them. Two
+// families are summed by pnScratches:
+// a fine layer (short/medium scratches) plus a coarse layer (fewer, much longer ones).
+// Each groove is analytically anti-aliased (edge widened to the pixel footprint).
+// Negative height.
+
+// One scratch "family": line segments seeded on an integer grid at the coordinate scale
+// of `r`. Each present cell (gated by `density`) spawns a groove with a random midpoint,
+// direction (biased toward `angle`, spread by `wander`), half-length, width and depth. A
+// 3x3 neighbourhood is scanned so segments crossing in from adjacent cells are caught;
+// half-length is capped below the search radius so grooves stay unbroken. `seed`
+// decorrelates layers; x wraps at `periodX` cells (when angle ~ 0) for a seamless
+// circumference seam.
+float pnScratchLayer(vec2 r, float angle, float density, float lengthScale, float halfWidth, float wander, float periodX, float seed) {
+  float aaw = max(length(fwidth(r)), 1e-4);
+  vec2 cell = floor(r);
+  float acc = 0.0;
+  bool tile = periodX > 0.5 && abs(angle) < 1e-3;
+  for(int j = -1; j <= 1; j++) {
+    for(int i = -1; i <= 1; i++) {
+      vec2 c = cell + vec2(float(i), float(j));
+      vec2 h = mod(c, PN_WRAP); // keep hash coords small/precise + seamless at the axial wrap
+      if(tile)
+        // max() keeps the divisor provably non-zero: callers that disable tiling pass
+        // periodX = 0.0, and some backends (ANGLE/D3D) constant-fold the mod() division
+        // inside this branch BEFORE dead-code elimination and warn "X4008: floating
+        // point division by zero". Only reached when tile (periodX > 0.5), so this is a
+        // no-op at runtime.
+        h.x = mod(c.x, max(periodX, 1.0)); // seamless wrap around the circumference
+      h += seed;
+      if(pnHash2(h + 3.1) > density)
+        continue; // sparsity
+      vec2 mid = c + vec2(pnHash2(h + 7.3), pnHash2(h + 13.7));
+      float a = angle + (pnHash2(h + 21.1) - 0.5) * 3.14159265 * clamp(wander, 0.0, 1.0);
+      vec2 d = vec2(cos(a), sin(a));
+      vec2 perp = vec2(-d.y, d.x);
+      float hl = clamp(mix(0.1, 0.55, pnHash2(h + 29.3)) * max(lengthScale, 0.05), 0.03, 0.92);
+      float w = halfWidth * mix(0.7, 1.3, pnHash2(h + 41.7)); // world-scaled half-width (freq-independent)
+      float rStr = mix(0.3, 1.0, pnHash2(h + 37.7));   // random depth/brightness
+      float bend = (pnHash2(h + 51.9) - 0.5) * 0.7;    // shallow curvature so lines aren't dead straight
+      vec2 pr = r - mid;
+      float t = clamp(dot(pr, d), -hl, hl);            // nearest point on the straight axis
+      float u = t / max(hl, 1e-3);
+      vec2 foot = d * t + perp * (bend * u * u * hl);  // bow the centre-line across its length
+      float dist = length(pr - foot);
+      acc = max(acc, (1.0 - smoothstep(w - aaw, w + aaw, dist)) * rStr);
+    }
+  }
+  return acc;
+}
+
+float pnScratches(vec2 uv, float angle, float density, float lengthScale, float halfWidth, float wander, float periodX, float coarseWeight) {
+  float ca = cos(angle), sa = sin(angle);
+  vec2 r = vec2(uv.x * ca - uv.y * sa, uv.x * sa + uv.y * ca);
+
+  // Fine family: many short/medium scratches at the caller's frequency.
+  float fine = pnScratchLayer(r, angle, density, lengthScale, halfWidth, wander, periodX, 0.0);
+
+  // Coarse family: a few much longer grooves, seeded on a ~3x larger grid (bigger cells
+  // => longer scratches within the same 3x3 search). x is rescaled to an INTEGER period
+  // so the circumference seam stays seamless; y (never tiled) is just divided down. The
+  // half-width is scaled by the same factor so the coarse grooves keep the SAME world
+  // width as the fine ones (longer, not fatter). It is the most repetition-prone / "big"
+  // family AND doubles the per-fragment cost, so `coarseWeight` lets the caller drop it
+  // entirely (pass 0 - the whole 3x3 loop is then skipped): the branch is expected to be
+  // driven by a uniform (e.g. a quality knob) so it stays divergence-free.
+  float coarse = 0.0;
+  if(coarseWeight > 0.0) {
+    float coarsePeriod = max(floor(periodX / 3.0 + 0.5), 1.0);
+    float scale = coarsePeriod / max(periodX, 1.0);
+    vec2 rc = vec2(r.x * scale, r.y / 3.0);
+    coarse = pnScratchLayer(rc, angle, density * 0.5, lengthScale, halfWidth * scale, wander, coarsePeriod, 7.0) * coarseWeight;
+  }
+
+  return -max(fine, coarse);
+}
+
+// Footprint anti-aliasing factor (1 near .. 0 sub-pixel). Fades a pattern out as its
+// finest octave shrinks toward a pixel - with distance or at grazing angles - so the
+// high-frequency detail never becomes a shimmering/aliasing signal. `uv` is the
+// (frequency-scaled) sample coordinate; `octaves` is the fbm octave count. Must be
+// called under uniform control flow (uses screen-space derivatives).
+float pnFootprintFade(vec2 uv, int octaves) {
+  // cells per pixel of the sample coordinate (mildly boosted for finer octaves). Fade
+  // BEFORE the Nyquist limit: a cell must stay >~2 px to sample cleanly, so start fading
+  // around 2.5 px/cell and reach zero by ~1 px/cell. (A looser threshold left the pattern
+  // near full strength at ~1 cell/pixel, so it stippled/aliased on thin, minified faces
+  // such as the end caps and slice faces.)
+  float cellsPerPixel = max(fwidth(uv.x), fwidth(uv.y)) * (1.0 + 0.5 * float(octaves - 1));
+  return 1.0 - smoothstep(0.4, 1.0, cellsPerPixel);
+}
+
+// Perturb a view-space normal by a scalar height field using the screen-space surface
+// gradient (Mikkelsen) - no tangent/bitangent attributes needed. `height` must be the
+// value sampled at THIS fragment; its screen-space derivatives give the slope.
+vec3 perturbNormalHeight(vec3 normal, vec3 viewPos, float height) {
+  vec3 sx = dFdx(viewPos);
+  vec3 sy = dFdy(viewPos);
+  float hx = dFdx(height);
+  float hy = dFdy(height);
+  vec3 r1 = cross(sy, normal);
+  vec3 r2 = cross(normal, sx);
+  float det = dot(sx, r1);
+  vec3 grad = sign(det) * (hx * r1 + hy * r2);
+  return normalize(abs(det) * normal - grad);
+}

package/dist/types/components/Wellbores/Casings/CasingMaterial.d.ts

@@ -1,5 +1,137 @@
 import { MeshStandardMaterial, MeshStandardMaterialParameters, Uniform, WebGLProgramParametersWithUniforms } from 'three';
+/**
+ * Parameters accepted by {@link CasingMaterial}. A `MeshStandardMaterial` at heart, so
+ * it takes the familiar PBR knobs (`color`, `roughness`, `metalness`, `emissive`,
+ * `envMap`, `envMapIntensity`, ...) plus the casing texture-UV units and the grouped
+ * {@link CasingEffects | effects} below.
+ *
+ * @expand
+ */
+export type CasingMaterialParameters = MeshStandardMaterialParameters & {
+    /** UV units for the base `map` (and the aoMap/lightMap/emissiveMap/metalnessMap/
+     * roughnessMap group): `'normalized'` = 0..1 around/along, `'world'` = object-space
+     * distance (arc length x trajectory distance) so `texture.repeat` becomes a density
+     * that stays consistent across sections of different radius and length. Default
+     * `'normalized'`. */
+    mapUvUnits?: 'normalized' | 'world';
+    /** UV units for `normalMap` / `bumpMap`, independent of `mapUvUnits`. Default
+     * `'normalized'`. */
+    normalMapUvUnits?: 'normalized' | 'world';
+    /** Grouped casing stylization effects (silhouette outline, section edge shading,
+     * procedural weathering, per-section variation and micro-normal surface detail).
+     * Every sub-effect is optional and independent; omitted ones fall back to their
+     * defaults (mostly off). */
+    effects?: CasingEffects;
+};
+/**
+ * Composable casing stylization effects for {@link CasingMaterial}. Every field is
+ * optional and independent; the procedural surface-detail layers (`granular`,
+ * `brushed`, `scratches`) simply sum. Strengths default to 0 (off) unless noted.
+ * @expand
+ */
+export type CasingEffects = {
+    /** View-space silhouette darkening that outlines each shell, helping nested strings
+     * read apart (especially under slicing / auto-slice). */
+    silhouette?: {
+        /** 0-1 strength (0 = off). Default 0. */
+        strength?: number;
+        /** Exponent tightening the rim toward the edge (higher = tighter). Default 3. */
+        power?: number;
+    };
+    /** Darkening at each section's own top/bottom edges. */
+    edgeShading?: {
+        /** 0-1 strength (0 = off). Default 0. */
+        strength?: number;
+        /** Distance in metres the darkening reaches from each edge, independent of section
+         * length. Default 0.2. */
+        width?: number;
+    };
+    /** Procedural wear/tear/spill (no textures), pinned in world space. */
+    weathering?: {
+        /** 0-1 strength (0 = off). Default 0. */
+        strength?: number;
+        /** Noise frequency in cells per real-world metre (lower = larger, sparser smears).
+         * Default 1.5. */
+        scale?: number;
+        /** 0-1 per-material multiplier (1 = full wear, 0 = none) so a preset such as the
+         * matte shoe can resist the weathering. Default 1. */
+        resistance?: number;
+    };
+    /** 0-1 per-section wear variation so adjacent telescoping strings read apart by
+     * looking differently worn rather than by a colour/value ramp. Default 0. */
+    sectionVariation?: number;
+    /** 0-1 performance vs. quality of the procedural surface detail (a fill-rate knob;
+     * off-effects always cost nothing regardless). Lower = cheaper: fewer weathering fbm
+     * octaves (2 at 0 .. 4 at 1) and the coarse/long scratch family only runs at >= 0.66.
+     * 1 = full-detail reference. Default 0.6. */
+    detailQuality?: number;
+    /** Isotropic value-noise bumps. */
+    granular?: {
+        /** 0-1 strength (0 = off). Default 0. */
+        strength?: number;
+        /** Cells per world (object-distance) unit. Default 2. */
+        frequency?: number;
+        /** 1-5 fbm octaves. Default 3. */
+        octaves?: number;
+        /** 0-1 stretch of the cells along the trajectory axis. Default 0. */
+        anisotropy?: number;
+    };
+    /** Directional fine grain (many thin parallel ridges). */
+    brushed?: {
+        /** 0-1 strength (0 = off). Default 0. */
+        strength?: number;
+        /** Cells per world (object-distance) unit. Default 2. */
+        frequency?: number;
+        /** 1-5 fbm octaves. Default 3. */
+        octaves?: number;
+        /** Grain direction in radians (0 = along the trajectory axis; non-zero angles
+         * reintroduce a faint seam on a full shell). Default 0. */
+        angle?: number;
+        /** 0-1 line thinness. Default 0.5. */
+        sharpness?: number;
+        /** 0-1 blend from an irregular grain (0) to regular, evenly-spaced flutes (1).
+         * Default 0. */
+        uniformity?: number;
+    };
+    /** Sparse, hair-thin surface scuffs that glint under changing light (their relief is
+     * kept very shallow - visibility comes from a localized polish, not depth). */
+    scratches?: {
+        /** 0-1 strength (0 = off). Default 0. */
+        strength?: number;
+        /** Cells per world (object-distance) unit. Default 10. */
+        frequency?: number;
+        /** Scratch direction in radians (0 = along the trajectory axis). Default 0. */
+        angle?: number;
+        /** 0-1 how many scratches survive. Default 0.4. */
+        density?: number;
+        /** Average scratch length multiplier (>0). Default 0.6. */
+        length?: number;
+        /** 0-1 how much the scratch direction drifts. Default 1. */
+        wander?: number;
+        /** 0-1 groove width, frequency-independent (world-scaled, hair/needle-thin:
+         * ~0.02..0.12mm half-width). Default 0.15. */
+        width?: number;
+    };
+};
+/**
+ * Physically-based (PBR) material for `Casings` / `CasingSection`. A
+ * `MeshStandardMaterial` at its core - so casings pick up real image-based
+ * reflections from the scene `environment`, exactly matching neighbouring
+ * `CompletionTools` - with the casing-specific stylization (procedural weathering,
+ * granular/brushed/scratch micro-normal detail, silhouette darkening and edge shading)
+ * spliced into its shaders via `onBeforeCompile`, and the slicing/vertex
+ * transform driven by the same custom attributes as the picking material.
+ *
+ * OIT-capable via {@link makeOitCompatible} so casings participate in the
+ * `OITRenderPass` hybrid pipeline (a no-op in the default render loop).
+ */
 export declare class CasingMaterial extends MeshStandardMaterial {
+    isCasingMaterial: boolean;
+    private _weathering;
+    private _wearResistance;
+    private _wellLength;
+    /** Custom uniforms bound into the patched program in `onBeforeCompile` and
+     * shared by reference with the OIT variants so per-frame updates propagate. */
     uniforms: {
         sizeMultiplier: Uniform<number>;
         radius: Uniform<number>;
@@ -7,8 +139,40 @@ export declare class CasingMaterial extends MeshStandardMaterial {
         sliceOffset: Uniform<number>;
         sliceAngle: Uniform<number>;
         autoSlicePosition: Uniform<boolean>;
+        sectionVariation: Uniform<number>;
+        silhouette: Uniform<number>;
+        silhouettePower: Uniform<number>;
+        edgeShading: Uniform<number>;
+        edgeShadingWidth: Uniform<number>;
+        sectionIndex: Uniform<number>;
+        detailFadeNear: Uniform<number>;
+        detailFadeFar: Uniform<number>;
+        detailQuality: Uniform<number>;
+        schematic: Uniform<number>;
+        mapUvWorld: Uniform<number>;
+        normalMapUvWorld: Uniform<number>;
+        wellLength: Uniform<number>;
+        granularStrength: Uniform<number>;
+        granularFrequency: Uniform<number>;
+        granularOctaves: Uniform<number>;
+        granularAnisotropy: Uniform<number>;
+        brushedStrength: Uniform<number>;
+        brushedFrequency: Uniform<number>;
+        brushedOctaves: Uniform<number>;
+        brushedAngle: Uniform<number>;
+        brushedSharpness: Uniform<number>;
+        brushedUniformity: Uniform<number>;
+        scratchStrength: Uniform<number>;
+        scratchFrequency: Uniform<number>;
+        scratchAngle: Uniform<number>;
+        scratchDensity: Uniform<number>;
+        scratchLength: Uniform<number>;
+        scratchWander: Uniform<number>;
+        scratchWidth: Uniform<number>;
+        weathering: Uniform<number>;
+        weatheringScale: Uniform<number>;
     };
-    constructor(params?: MeshStandardMaterialParameters);
+    constructor(parameters?: CasingMaterialParameters);
     get sizeMultiplier(): number;
     set sizeMultiplier(v: number);
     get radius(): number;
@@ -21,5 +185,69 @@ export declare class CasingMaterial extends MeshStandardMaterial {
     set sliceAngle(v: number);
     get autoSlicePosition(): boolean;
     set autoSlicePosition(v: boolean);
+    /** 0-1 strength of the per-section wear variation: how much each section's
+     * procedural wear is offset (seed) and scaled (amount) by its index, so adjacent
+     * telescoping strings read apart by looking differently worn rather than by a
+     * colour/value ramp. */
+    get sectionVariation(): number;
+    set sectionVariation(v: number);
+    /** 0-1 strength of the view-space silhouette darkening (outlines each shell). */
+    get silhouette(): number;
+    set silhouette(v: number);
+    /** Exponent tightening the silhouette rim toward the edge (higher = tighter). Default 3. */
+    get silhouettePower(): number;
+    set silhouettePower(v: number);
+    /** 0-1 strength of the edge shading (darkening at each section's own top/bottom edges). */
+    get edgeShading(): number;
+    set edgeShading(v: number);
+    /** Distance in metres the edge shading reaches from each section edge. Default 0.2. */
+    get edgeShadingWidth(): number;
+    set edgeShadingWidth(v: number);
+    /** Index of this section within the wellbore's casing stack, used to seed the
+     * per-section variation of the stylization effects. */
+    get sectionIndex(): number;
+    set sectionIndex(v: number);
+    /** 0-1 performance vs. quality of the procedural surface detail (fill-rate knob).
+     * Lower = cheaper (fewer weathering fbm octaves; the coarse scratch family only runs
+     * at >= 0.66); 1 = full-detail reference. */
+    get detailQuality(): number;
+    set detailQuality(v: number);
+    /** Unlit "schematic" shading mode: flat material `color` + `silhouette` outline only,
+     * with all lighting/env, textures and realism detail ignored. Set by the `Casings`
+     * component's `schematic` prop; the slice is locked separately (component side). */
+    get schematic(): boolean;
+    set schematic(v: boolean);
+    /** 0-1 strength of the procedural wear/tear/spill surface detail (no textures). The
+     * effective amount is scaled per-material by {@link wearResistance}. */
+    get weathering(): number;
+    set weathering(v: number);
+    /** 0-1 per-material wear multiplier (1 = full wear, 0 = none). Lets material presets
+     * (e.g. the matte shoe) resist the procedural weathering the component applies
+     * globally via {@link weathering}. */
+    get wearResistance(): number;
+    set wearResistance(v: number);
+    /** Weathering noise frequency in cells per real-world metre (lower = larger,
+     * sparser smears). */
+    get weatheringScale(): number;
+    set weatheringScale(v: number);
+    /** Real-world total length (metres) of the whole wellbore trajectory. Uploaded as a
+     * uniform and used by the vertex shader to derive each section's physical length
+     * (`vSectionLength`) and the along-axis coordinate (`casingAxial`). The weathering is
+     * pinned in world space (via `vWorldPos`) and does not use it. */
+    get wellLength(): number;
+    set wellLength(v: number);
+    /** UV units for the base `map` group. `'world'` uses object-space distance so
+     * `texture.repeat` is a radius/length-consistent density. */
+    get mapUvUnits(): 'normalized' | 'world';
+    set mapUvUnits(v: 'normalized' | 'world');
+    /** UV units for `normalMap` / `bumpMap`, independent of {@link mapUvUnits}. */
+    get normalMapUvUnits(): 'normalized' | 'world';
+    set normalMapUvUnits(v: 'normalized' | 'world');
+    /** Grouped casing stylization effects (silhouette, edge shading, weathering,
+     * per-section variation and the granular/brushed/scratch micro-normal layers).
+     * Reading returns the current settings reconstructed from the uniforms. Assigning
+     * applies the whole group at once - omitted sub-effects reset to their defaults. */
+    get effects(): CasingEffects;
+    set effects(v: CasingEffects | undefined);
     onBeforeCompile(parameters: WebGLProgramParametersWithUniforms): void;
 }

package/dist/types/components/Wellbores/Casings/CasingSection.d.ts

@@ -1,4 +1,5 @@
 import { PointerEvents } from '../../../main';
+import { CasingEffects } from './CasingMaterial';
 import { CasingSectionMaterialOptions } from './Casings';
 import { CasingSectionType } from './casings-defs';
 type CasingSectionProps = {
@@ -11,6 +12,10 @@ type CasingSectionProps = {
     autoSlicePosition?: boolean;
     opacity?: number;
     renderOrder?: number;
+    effects?: CasingEffects;
+    wellLength?: number;
+    sectionIndex?: number;
+    schematic?: boolean;
 } & PointerEvents;
-export declare const CasingSection: ({ section, materialOptions, radialSegments, sizeMultiplier, sliceAngle, sliceOffset, autoSlicePosition, opacity, renderOrder, onPointerClick, onPointerEnter, onPointerLeave, onPointerMove, }: CasingSectionProps) => import("react/jsx-runtime").JSX.Element;
+export declare const CasingSection: ({ section, materialOptions, radialSegments, sizeMultiplier, sliceAngle, sliceOffset, autoSlicePosition, opacity, renderOrder, effects, wellLength, sectionIndex, schematic, onPointerClick, onPointerEnter, onPointerLeave, onPointerMove, }: CasingSectionProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/components/Wellbores/Casings/Casings.d.ts

@@ -1,16 +1,17 @@
 import { ReactElement } from 'react';
-import { Group, MeshStandardMaterialParameters, Object3D } from 'three';
+import { Group, Object3D } from 'three';
 import { CommonComponentProps } from '../../../common/types';
 import { PointerEvents } from '../../../main';
+import { CasingEffects, CasingMaterialParameters } from './CasingMaterial';
 import { CasingSectionType } from './casings-defs';
 /**
  * CasingSectionMaterialOptions
  * @expand
  */
 export type CasingSectionMaterialOptions = {
-    primary: MeshStandardMaterialParameters;
-    inner?: MeshStandardMaterialParameters;
-    slice?: MeshStandardMaterialParameters;
+    primary: CasingMaterialParameters;
+    inner?: CasingMaterialParameters;
+    slice?: CasingMaterialParameters;
 };
 /**
  * MaterialOptions
@@ -31,9 +32,29 @@ export type CasingProps = PointerEvents & CommonComponentProps & {
     shoeFactor?: number;
     overrideSegmentsPerMeter?: number;
     overrideSimplificationThreshold?: number;
+    /** Schematic (diagram) mode: an unlit, flat-shaded look for a clean "cutaway
+     * schematic" rather than realism. Locks the slice to a half-cut that always faces
+     * the camera (`sliceAngle = PI`, `autoSlicePosition = true`, `sliceOffset = 0` -
+     * those props are ignored), renders each face with only its flat `color` (all
+     * lighting/env, textures and realism detail are ignored) plus the `silhouette`
+     * outline for contrast. Dropping the specular lighting also removes the dominant
+     * source of casing aliasing; note that geometric silhouette-edge anti-aliasing still
+     * relies on the host render pipeline (MSAA/FXAA/SMAA). Default false. */
+    schematic?: boolean;
+    /** Maps each section to its material parameters. Keep this a STABLE reference
+     * (module-level function or `useCallback`) - a new function identity each render
+     * rebuilds every section's materials and forces a shader recompile per frame,
+     * which is the main cause of sluggish casing updates. Defaults to a stable
+     * module-level function. */
     materialOptions?: MaterialOptions;
     opacity?: number;
     priority?: number;
+    /** Grouped casing stylization effects (silhouette outline, section edge shading,
+     * procedural weathering, per-section variation and micro-normal surface detail).
+     * Applied as the global default for every section; a section's per-face
+     * `materialOptions.*.effects` override individual sub-effects on top of this.
+     * Defaults to {@link defaultCasingEffects}. */
+    effects?: CasingEffects;
 };
 /**
  * Generic render of casings based on depths, diameters and type. Must be a child of the `Wellbore` component.
@@ -66,7 +87,27 @@ export declare const Casings: import('react').ForwardRefExoticComponent<PointerE
     shoeFactor?: number;
     overrideSegmentsPerMeter?: number;
     overrideSimplificationThreshold?: number;
+    /** Schematic (diagram) mode: an unlit, flat-shaded look for a clean "cutaway
+     * schematic" rather than realism. Locks the slice to a half-cut that always faces
+     * the camera (`sliceAngle = PI`, `autoSlicePosition = true`, `sliceOffset = 0` -
+     * those props are ignored), renders each face with only its flat `color` (all
+     * lighting/env, textures and realism detail are ignored) plus the `silhouette`
+     * outline for contrast. Dropping the specular lighting also removes the dominant
+     * source of casing aliasing; note that geometric silhouette-edge anti-aliasing still
+     * relies on the host render pipeline (MSAA/FXAA/SMAA). Default false. */
+    schematic?: boolean;
+    /** Maps each section to its material parameters. Keep this a STABLE reference
+     * (module-level function or `useCallback`) - a new function identity each render
+     * rebuilds every section's materials and forces a shader recompile per frame,
+     * which is the main cause of sluggish casing updates. Defaults to a stable
+     * module-level function. */
     materialOptions?: MaterialOptions;
     opacity?: number;
     priority?: number;
+    /** Grouped casing stylization effects (silhouette outline, section edge shading,
+     * procedural weathering, per-section variation and micro-normal surface detail).
+     * Applied as the global default for every section; a section's per-face
+     * `materialOptions.*.effects` override individual sub-effects on top of this.
+     * Defaults to {@link defaultCasingEffects}. */
+    effects?: CasingEffects;
 } & import('react').RefAttributes<Group<import('three').Object3DEventMap>>>;

package/dist/types/components/Wellbores/Casings/casings-defs.d.ts

@@ -1,4 +1,6 @@
+import { Color } from 'three';
 import { Vec3 } from '../../../sdk';
+import { CasingEffects } from './CasingMaterial';
 export declare const casings = "casings";
 export type CasingSectionType = {
     type: string;
@@ -15,3 +17,45 @@ export type CasingSectionType = {
     };
 };
 export type CasingsGeneratorResponse = CasingSectionType[];
+/**
+ * The component-level default {@link CasingEffects} applied globally to every section
+ * (a section's per-face `materialOptions.*.effects` can override individual sub-effects
+ * on top of this). Tuned to help adjacent/nested strings read apart.
+ */
+export declare const defaultCasingEffects: CasingEffects;
+/**
+ * A custom function may be passed to the component, but this is not well documented at this time
+ * as this behavior is subject to change.
+ */
+export declare const defaultMaterialOptions: (section: CasingSectionType) => {
+    primary: {
+        color: string;
+        roughness: number;
+        metalness: number;
+        effects: {
+            weathering: {
+                resistance: number;
+            };
+        };
+    };
+    inner: {
+        color: string;
+        roughness: number;
+        metalness: number;
+    };
+    slice: {
+        color: Color;
+        roughness: number;
+        metalness: number;
+        effects: {
+            weathering: {
+                resistance: number;
+            };
+        };
+    } | {
+        color: Color;
+        roughness: number;
+        metalness: number;
+        effects?: undefined;
+    };
+};