matterviz 0.4.2 → 0.4.3

package/dist/isosurface/sampling.js

@@ -0,0 +1,408 @@
+import { create_cart_to_frac_matrix, scale_lattice_matrix } from '../math';
+import { grid_dimensions } from './grid';
+import { downsample_grid, MAX_GRID_POINTS } from './types';
+const safe_mod = (val, dim) => ((val % dim) + dim) % dim;
+// Lower/upper voxel indices for one axis of a trilinear sample. Singleton axes
+// (n===1) pin both corners to 0 so nx-2 clamping never goes negative.
+const voxel_corners = (n, floor_g, periodic) => {
+    if (n === 1)
+        return [0, 0];
+    const lower = periodic ? safe_mod(floor_g, n) : Math.max(0, Math.min(floor_g, n - 2));
+    return [lower, periodic ? (lower + 1) % n : Math.min(lower + 1, n - 1)];
+};
+// Trilinear interpolation of a scalar 3D grid at fractional coordinates.
+// Periodic grids wrap with modulo; non-periodic return 0 for out-of-bounds.
+export function trilinear_interpolate(grid, fx, fy, fz, periodic) {
+    const nx = grid.length;
+    const ny = grid[0]?.length ?? 0;
+    const nz = grid[0]?.[0]?.length ?? 0;
+    if (nx === 0 || ny === 0 || nz === 0)
+        return 0;
+    // Convert fractional to grid coordinates
+    const gx = periodic ? fx * nx : fx * (nx - 1);
+    const gy = periodic ? fy * ny : fy * (ny - 1);
+    const gz = periodic ? fz * nz : fz * (nz - 1);
+    if (!periodic) {
+        // Out-of-bounds check for non-periodic grids
+        if (fx < 0 || fx > 1 || fy < 0 || fy > 1 || fz < 0 || fz > 1)
+            return 0;
+    }
+    const [x0, x1] = voxel_corners(nx, Math.floor(gx), periodic);
+    const [y0, y1] = voxel_corners(ny, Math.floor(gy), periodic);
+    const [z0, z1] = voxel_corners(nz, Math.floor(gz), periodic);
+    // deltas from clamped lower index (non-periodic x0 clamps to nx-2 so floor(gx) may != x0)
+    const xd = periodic ? gx - Math.floor(gx) : gx - x0;
+    const yd = periodic ? gy - Math.floor(gy) : gy - y0;
+    const zd = periodic ? gz - Math.floor(gz) : gz - z0;
+    // 8-point interpolation
+    const c000 = grid[x0][y0][z0];
+    const c001 = grid[x0][y0][z1];
+    const c010 = grid[x0][y1][z0];
+    const c011 = grid[x0][y1][z1];
+    const c100 = grid[x1][y0][z0];
+    const c101 = grid[x1][y0][z1];
+    const c110 = grid[x1][y1][z0];
+    const c111 = grid[x1][y1][z1];
+    const c00 = c000 + (c100 - c000) * xd;
+    const c01 = c001 + (c101 - c001) * xd;
+    const c10 = c010 + (c110 - c010) * xd;
+    const c11 = c011 + (c111 - c011) * xd;
+    const c0 = c00 + (c10 - c00) * yd;
+    const c1 = c01 + (c11 - c01) * yd;
+    return c0 + (c1 - c0) * zd;
+}
+// Small tolerance so vertices numerically on the boundary of a finite grid
+// (e.g. marching-cubes output at fractional coordinate 1.0 + 1e-16) still sample.
+const OOB_TOL = 1e-6;
+const prepared_sampler_cache = new WeakMap();
+const prepare_volume_sampler = (volume) => {
+    const grid_dims = grid_dimensions(volume.grid);
+    const signature = [
+        ...volume.lattice.flat(),
+        ...volume.origin,
+        ...grid_dims,
+        Number(volume.periodic),
+    ].join(`,`);
+    const cached = prepared_sampler_cache.get(volume);
+    if (cached?.grid === volume.grid && cached.signature === signature)
+        return cached;
+    const prepared = {
+        grid: volume.grid,
+        inv: create_cart_to_frac_matrix(volume.lattice),
+        origin: volume.origin,
+        periodic: volume.periodic,
+        grid_dims,
+        signature,
+    };
+    prepared_sampler_cache.set(volume, prepared);
+    return prepared;
+};
+// Create a sampler that maps absolute Cartesian positions (in the same physical
+// frame as the volume's `origin`) to trilinearly-interpolated scalar values.
+// Handles non-orthogonal lattices, origin offsets, and periodic wrapping, so it
+// works both for strictly matching grids and for general resampling between
+// volumes that share a Cartesian coordinate system.
+// The hot callback uses scalar arithmetic only (no per-call array allocations)
+// since it runs once per isosurface vertex.
+export function create_volume_sampler(volume, options = {}) {
+    const { out_of_bounds = `clamp` } = options;
+    const { grid, inv, origin, periodic } = prepare_volume_sampler(volume);
+    const [ox, oy, oz] = origin;
+    return (position) => {
+        const cx = position[0] - ox;
+        const cy = position[1] - oy;
+        const cz = position[2] - oz;
+        let fx = inv[0][0] * cx + inv[0][1] * cy + inv[0][2] * cz;
+        let fy = inv[1][0] * cx + inv[1][1] * cy + inv[1][2] * cz;
+        let fz = inv[2][0] * cx + inv[2][1] * cy + inv[2][2] * cz;
+        if (periodic) {
+            fx = safe_mod(fx, 1);
+            fy = safe_mod(fy, 1);
+            fz = safe_mod(fz, 1);
+        }
+        else {
+            if (out_of_bounds === `fallback` &&
+                (fx < -OOB_TOL ||
+                    fx > 1 + OOB_TOL ||
+                    fy < -OOB_TOL ||
+                    fy > 1 + OOB_TOL ||
+                    fz < -OOB_TOL ||
+                    fz > 1 + OOB_TOL))
+                return NaN;
+            // Clamp both genuine out-of-bounds ('clamp' policy = nearest edge value)
+            // and tiny numerical overshoot at the boundary
+            fx = Math.min(1, Math.max(0, fx));
+            fy = Math.min(1, Math.max(0, fy));
+            fz = Math.min(1, Math.max(0, fz));
+        }
+        return trilinear_interpolate(grid, fx, fy, fz, periodic);
+    };
+}
+// Sample a volume at many Cartesian positions (flat xyz triplets).
+// Returns one scalar per position; NaN marks out-of-bounds under 'fallback' policy.
+export function sample_volume_at_positions(volume, positions, options = {}) {
+    const { out_of_bounds = `clamp`, position_offset = [0, 0, 0] } = options;
+    const { grid, inv, origin, periodic, grid_dims } = prepare_volume_sampler(volume);
+    const [nx, ny, nz] = grid_dims;
+    const [offset_x, offset_y, offset_z] = position_offset;
+    const [origin_x, origin_y, origin_z] = origin;
+    const n_points = Math.floor(positions.length / 3);
+    const out = options.out?.length === n_points ? options.out : new Float32Array(n_points);
+    if (nx === 0 || ny === 0 || nz === 0) {
+        out.fill(0);
+        return out;
+    }
+    for (let idx = 0; idx < n_points; idx++) {
+        const position_idx = idx * 3;
+        const cart_x = positions[position_idx] + offset_x - origin_x;
+        const cart_y = positions[position_idx + 1] + offset_y - origin_y;
+        const cart_z = positions[position_idx + 2] + offset_z - origin_z;
+        let frac_x = inv[0][0] * cart_x + inv[0][1] * cart_y + inv[0][2] * cart_z;
+        let frac_y = inv[1][0] * cart_x + inv[1][1] * cart_y + inv[1][2] * cart_z;
+        let frac_z = inv[2][0] * cart_x + inv[2][1] * cart_y + inv[2][2] * cart_z;
+        if (periodic) {
+            frac_x = safe_mod(frac_x, 1);
+            frac_y = safe_mod(frac_y, 1);
+            frac_z = safe_mod(frac_z, 1);
+        }
+        else {
+            if (out_of_bounds === `fallback` &&
+                (frac_x < -OOB_TOL ||
+                    frac_x > 1 + OOB_TOL ||
+                    frac_y < -OOB_TOL ||
+                    frac_y > 1 + OOB_TOL ||
+                    frac_z < -OOB_TOL ||
+                    frac_z > 1 + OOB_TOL)) {
+                out[idx] = Number.NaN;
+                continue;
+            }
+            frac_x = Math.min(1, Math.max(0, frac_x));
+            frac_y = Math.min(1, Math.max(0, frac_y));
+            frac_z = Math.min(1, Math.max(0, frac_z));
+        }
+        const grid_x = frac_x * (periodic ? nx : nx - 1);
+        const grid_y = frac_y * (periodic ? ny : ny - 1);
+        const grid_z = frac_z * (periodic ? nz : nz - 1);
+        const floor_x = Math.floor(grid_x);
+        const floor_y = Math.floor(grid_y);
+        const floor_z = Math.floor(grid_z);
+        const [x_lower, x_upper] = voxel_corners(nx, floor_x, periodic);
+        const [y_lower, y_upper] = voxel_corners(ny, floor_y, periodic);
+        const [z_lower, z_upper] = voxel_corners(nz, floor_z, periodic);
+        const x_weight = grid_x - x_lower;
+        const y_weight = grid_y - y_lower;
+        const z_weight = grid_z - z_lower;
+        const row_00 = grid[x_lower][y_lower];
+        const row_01 = grid[x_lower][y_upper];
+        const row_10 = grid[x_upper][y_lower];
+        const row_11 = grid[x_upper][y_upper];
+        const value_00 = row_00[z_lower] + (row_10[z_lower] - row_00[z_lower]) * x_weight;
+        const value_01 = row_00[z_upper] + (row_10[z_upper] - row_00[z_upper]) * x_weight;
+        const value_10 = row_01[z_lower] + (row_11[z_lower] - row_01[z_lower]) * x_weight;
+        const value_11 = row_01[z_upper] + (row_11[z_upper] - row_01[z_upper]) * x_weight;
+        const value_0 = value_00 + (value_10 - value_00) * y_weight;
+        const value_1 = value_01 + (value_11 - value_01) * y_weight;
+        out[idx] = value_0 + (value_1 - value_0) * z_weight;
+    }
+    return out;
+}
+const incompatible_grids = (reason) => ({ ok: false, reason });
+const fmt_vec = (vec) => `[${vec.map((val) => Number(val.toPrecision(6))).join(`, `)}]`;
+// Strictly compare two volumetric grids: identical dimensions, origins equal
+// within tolerance, all voxel vectors equal within tolerance, and matching
+// periodic/finite boundary modes. Cross-volume coloring via create_volume_sampler
+// works for any two volumes sharing a Cartesian frame, but strictly matching
+// grids guarantee the sampled field is exact (no cross-grid resampling).
+export function compare_volume_grids(vol_a, vol_b, { tolerance = 1e-4 } = {}) {
+    const [nx_a, ny_a, nz_a] = vol_a.grid_dims;
+    const [nx_b, ny_b, nz_b] = vol_b.grid_dims;
+    if (nx_a !== nx_b || ny_a !== ny_b || nz_a !== nz_b) {
+        return incompatible_grids(`grid dimensions differ: ${nx_a}×${ny_a}×${nz_a} vs ${nx_b}×${ny_b}×${nz_b}`);
+    }
+    if (vol_a.periodic !== vol_b.periodic) {
+        return incompatible_grids(`boundary modes differ: ${vol_a.periodic ? `periodic` : `finite`} vs ${vol_b.periodic ? `periodic` : `finite`}`);
+    }
+    for (let axis = 0; axis < 3; axis++) {
+        const delta = Math.abs(vol_a.origin[axis] - vol_b.origin[axis]);
+        if (delta > tolerance) {
+            return incompatible_grids(`origins differ by ${delta.toPrecision(3)} Å along axis ${axis}: ${fmt_vec(vol_a.origin)} vs ${fmt_vec(vol_b.origin)}`);
+        }
+    }
+    // Compare voxel vectors: lattice_row / n for periodic grids (spacing 1/n),
+    // lattice_row / (n-1) for finite grids (spacing 1/(n-1), endpoints included).
+    // Dims and boundary modes already match at this point, so one divisor per
+    // axis suffices for both volumes.
+    for (let axis = 0; axis < 3; axis++) {
+        const divisor = Math.max(vol_a.periodic ? vol_a.grid_dims[axis] : vol_a.grid_dims[axis] - 1, 1);
+        for (let comp = 0; comp < 3; comp++) {
+            const voxel_delta = Math.abs(vol_a.lattice[axis][comp] - vol_b.lattice[axis][comp]) / divisor;
+            if (voxel_delta > tolerance) {
+                return incompatible_grids(`voxel vectors differ along axis ${axis}: ${fmt_vec(vol_a.lattice[axis])} vs ${fmt_vec(vol_b.lattice[axis])} (lattice rows)`);
+            }
+        }
+    }
+    return { ok: true };
+}
+// Replace invalid axes (non-finite bounds or non-positive width) with [0, 1].
+// Non-periodic volumes additionally clamp to [0, 1] — a finite volume must not
+// be repeated implicitly.
+export function sanitize_display_range(range, periodic) {
+    return range.map(([lo, hi]) => {
+        if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi - lo <= 1e-6)
+            return [0, 1];
+        if (periodic)
+            return [lo, hi];
+        const clamped = [Math.max(lo, 0), Math.min(hi, 1)];
+        return clamped[1] - clamped[0] > 1e-6 ? clamped : [0, 1];
+    });
+}
+// Resolve the finite window used for marching cubes. Periodic volumes always
+// need an endpoint-inclusive window, including for an integer structure
+// supercell: a periodic N-point grid spans [0, 1), while finite marching cubes
+// interprets N points as spanning [0, 1]. Resampling [0, S] to N*S + 1 points
+// preserves the original voxel spacing and closes the final periodic interval.
+// Finite volumes only get a window when one is explicitly requested and are
+// never repeated to follow the structure supercell.
+export function resolve_volume_display_range(volume, { display_range, tiling = [1, 1, 1], halo = 0 } = {}) {
+    if (!display_range && !volume.periodic)
+        return null;
+    const range = display_range
+        ? sanitize_display_range(display_range, volume.periodic)
+        : tiling.map((factor) => [0, factor]);
+    if (!volume.periodic)
+        return range;
+    const padding = Math.max(0, halo);
+    return range.map(([lo, hi]) => [lo - padding, hi + padding]);
+}
+const precompute_axis_interpolation = (range, count, source_dim, periodic) => {
+    const intervals = periodic ? source_dim : Math.max(source_dim - 1, 1);
+    const fractional_step = (range[1] - range[0]) / (count - 1);
+    const grid_step = fractional_step * intervals;
+    const grid_start = range[0] * intervals;
+    const direct = Math.abs(grid_step - 1) < 1e-10 && Math.abs(grid_start - Math.round(grid_start)) < 1e-10;
+    const lower = new Int32Array(count);
+    const upper = new Int32Array(count);
+    const weight = new Float64Array(count);
+    for (let sample_idx = 0; sample_idx < count; sample_idx++) {
+        const grid_coord = grid_start + sample_idx * grid_step;
+        const grid_floor = Math.floor(grid_coord);
+        if (periodic) {
+            lower[sample_idx] = safe_mod(grid_floor, source_dim);
+            upper[sample_idx] = (lower[sample_idx] + 1) % source_dim;
+            weight[sample_idx] = grid_coord - grid_floor;
+        }
+        else {
+            lower[sample_idx] = Math.max(0, Math.min(grid_floor, source_dim - 2));
+            upper[sample_idx] = Math.min(lower[sample_idx] + 1, source_dim - 1);
+            weight[sample_idx] = grid_coord - lower[sample_idx];
+        }
+    }
+    return { lower, upper, weight, direct };
+};
+// Resample a volume over a fractional display range (VESTA-style non-integer
+// supercell) into a finite grid whose bounds land exactly on the requested
+// fractional coordinates, so marching cubes clips repeated surfaces precisely
+// at the range instead of at integer cell boundaries. Periodic volumes wrap;
+// the sample resolution follows the source voxel density, capped at max_points
+// (matching the downsampling budget applied to integer-tiled grids).
+// The returned volume's lattice spans the range and its origin shifts by
+// range_min·lattice, keeping vertices in the same Cartesian frame as the source.
+export function extract_volume_range(volume, range, max_points = MAX_GRID_POINTS) {
+    const [rx, ry, rz] = sanitize_display_range(range, volume.periodic);
+    const widths = [rx[1] - rx[0], ry[1] - ry[0], rz[1] - rz[0]];
+    // Sample counts follow the source voxel density (inclusive endpoints), capped
+    // to the point budget. The reduction loop guards against cbrt undershoot when
+    // the min-2 floor prevents an axis from shrinking.
+    let counts = widths.map((width, axis) => {
+        const source_intervals = volume.periodic
+            ? volume.grid_dims[axis]
+            : Math.max(volume.grid_dims[axis] - 1, 1);
+        return Math.max(2, Math.round(width * source_intervals) + 1);
+    });
+    const total = counts[0] * counts[1] * counts[2];
+    if (total > max_points) {
+        const shrink = Math.cbrt(max_points / total);
+        counts = counts.map((count) => Math.max(2, Math.floor(count * shrink)));
+        while (counts[0] * counts[1] * counts[2] > Math.max(max_points, 8)) {
+            const largest = counts.indexOf(Math.max(...counts));
+            counts[largest] = Math.max(2, Math.floor(counts[largest] * 0.9));
+        }
+    }
+    const [nx, ny, nz] = counts;
+    const grid = Array(nx);
+    const x_samples = precompute_axis_interpolation(rx, nx, volume.grid_dims[0], volume.periodic);
+    const y_samples = precompute_axis_interpolation(ry, ny, volume.grid_dims[1], volume.periodic);
+    const z_samples = precompute_axis_interpolation(rz, nz, volume.grid_dims[2], volume.periodic);
+    let [min_val, max_val, sum] = [Infinity, -Infinity, 0];
+    const direct_copy = x_samples.direct && y_samples.direct && z_samples.direct;
+    if (direct_copy) {
+        for (let x_idx = 0; x_idx < nx; x_idx++) {
+            const source_x = x_samples.weight[x_idx] > 0.5 ? x_samples.upper[x_idx] : x_samples.lower[x_idx];
+            const source_plane = volume.grid[source_x];
+            const plane = Array(ny);
+            for (let y_idx = 0; y_idx < ny; y_idx++) {
+                const source_y = y_samples.weight[y_idx] > 0.5 ? y_samples.upper[y_idx] : y_samples.lower[y_idx];
+                const source_row = source_plane[source_y];
+                const row = Array(nz);
+                for (let z_idx = 0; z_idx < nz; z_idx++) {
+                    const source_z = z_samples.weight[z_idx] > 0.5 ? z_samples.upper[z_idx] : z_samples.lower[z_idx];
+                    const value = source_row[source_z];
+                    row[z_idx] = value;
+                    if (value < min_val)
+                        min_val = value;
+                    if (value > max_val)
+                        max_val = value;
+                    sum += value;
+                }
+                plane[y_idx] = row;
+            }
+            grid[x_idx] = plane;
+        }
+    }
+    else {
+        for (let x_idx = 0; x_idx < nx; x_idx++) {
+            const x_lower_plane = volume.grid[x_samples.lower[x_idx]];
+            const x_upper_plane = volume.grid[x_samples.upper[x_idx]];
+            const x_weight = x_samples.weight[x_idx];
+            const plane = Array(ny);
+            for (let y_idx = 0; y_idx < ny; y_idx++) {
+                const y_lower = y_samples.lower[y_idx];
+                const y_upper = y_samples.upper[y_idx];
+                const y_weight = y_samples.weight[y_idx];
+                const row_00 = x_lower_plane[y_lower];
+                const row_01 = x_lower_plane[y_upper];
+                const row_10 = x_upper_plane[y_lower];
+                const row_11 = x_upper_plane[y_upper];
+                const row = Array(nz);
+                for (let z_idx = 0; z_idx < nz; z_idx++) {
+                    const z_lower = z_samples.lower[z_idx];
+                    const z_upper = z_samples.upper[z_idx];
+                    const z_weight = z_samples.weight[z_idx];
+                    const value_00 = row_00[z_lower] + (row_10[z_lower] - row_00[z_lower]) * x_weight;
+                    const value_01 = row_00[z_upper] + (row_10[z_upper] - row_00[z_upper]) * x_weight;
+                    const value_10 = row_01[z_lower] + (row_11[z_lower] - row_01[z_lower]) * x_weight;
+                    const value_11 = row_01[z_upper] + (row_11[z_upper] - row_01[z_upper]) * x_weight;
+                    const value_0 = value_00 + (value_10 - value_00) * y_weight;
+                    const value_1 = value_01 + (value_11 - value_01) * y_weight;
+                    const value = value_0 + (value_1 - value_0) * z_weight;
+                    row[z_idx] = value;
+                    if (value < min_val)
+                        min_val = value;
+                    if (value > max_val)
+                        max_val = value;
+                    sum += value;
+                }
+                plane[y_idx] = row;
+            }
+            grid[x_idx] = plane;
+        }
+    }
+    const [row_a, row_b, row_c] = volume.lattice;
+    return {
+        ...volume,
+        grid,
+        grid_dims: counts,
+        lattice: scale_lattice_matrix(volume.lattice, widths),
+        origin: [
+            volume.origin[0] + rx[0] * row_a[0] + ry[0] * row_b[0] + rz[0] * row_c[0],
+            volume.origin[1] + rx[0] * row_a[1] + ry[0] * row_b[1] + rz[0] * row_c[1],
+            volume.origin[2] + rx[0] * row_a[2] + ry[0] * row_b[2] + rz[0] * row_c[2],
+        ],
+        data_range: {
+            min: min_val,
+            max: max_val,
+            abs_max: Math.max(Math.abs(min_val), Math.abs(max_val)),
+            mean: sum / (nx * ny * nz),
+        },
+        periodic: false, // the extracted block is a finite window; endpoints included
+    };
+}
+export function prepare_geometry_grid(volume, range) {
+    if (range)
+        return extract_volume_range(volume, range);
+    return {
+        grid: downsample_grid(volume.grid, volume.grid_dims).grid,
+        lattice: volume.lattice,
+        origin: volume.origin,
+    };
+}

package/dist/isosurface/slice-rendering.d.ts

@@ -0,0 +1,13 @@
+import { type D3InterpolateName } from '../colors';
+import type { Vec2 } from '../math';
+import type { SliceResult } from './slice';
+export type VolumeSliceMode = `both` | `contours` | `filled`;
+/** Resolve an explicit or automatic slice color range. */
+export declare function resolve_slice_color_range(slice: Pick<SliceResult, `min` | `max`>, color_range?: Vec2, symmetric?: boolean | `auto`): Vec2;
+/** Convert a sampled slice to browser-sRGB RGBA pixels, preserving its exact mask. */
+export declare function slice_to_rgba(slice: Pick<SliceResult, `data` | `mask` | `width` | `height`>, colormap: D3InterpolateName, color_range: Vec2, { flip_y, out }?: {
+    flip_y?: boolean;
+    out?: Uint8ClampedArray;
+}): Uint8ClampedArray;
+/** Resolve a contour count or explicit threshold list against a color range. */
+export declare function resolve_contour_thresholds(color_range: Vec2, contour_levels: number | number[]): number[];

package/dist/isosurface/slice-rendering.js

@@ -0,0 +1,79 @@
+import { get_d3_interpolator } from '../colors';
+import { rgb } from 'd3-color';
+const SLICE_LUT_SIZE = 256;
+const MAX_CONTOUR_LEVELS = 256;
+const slice_lut_cache = new Map();
+const get_slice_lut = (colormap) => {
+    const cached = slice_lut_cache.get(colormap);
+    if (cached)
+        return cached;
+    const interpolator = get_d3_interpolator(colormap);
+    const lut = new Uint8ClampedArray(SLICE_LUT_SIZE * 3);
+    for (let color_idx = 0; color_idx < SLICE_LUT_SIZE; color_idx++) {
+        const color = rgb(interpolator(color_idx / (SLICE_LUT_SIZE - 1)));
+        lut[color_idx * 3] = color.r;
+        lut[color_idx * 3 + 1] = color.g;
+        lut[color_idx * 3 + 2] = color.b;
+    }
+    slice_lut_cache.set(colormap, lut);
+    return lut;
+};
+/** Resolve an explicit or automatic slice color range. */
+export function resolve_slice_color_range(slice, color_range, symmetric = `auto`) {
+    if (color_range)
+        return [...color_range];
+    if (symmetric === true || (symmetric === `auto` && slice.min < 0 && slice.max > 0)) {
+        const abs_max = Math.max(Math.abs(slice.min), Math.abs(slice.max));
+        return [-abs_max, abs_max];
+    }
+    return [slice.min, slice.max];
+}
+/** Convert a sampled slice to browser-sRGB RGBA pixels, preserving its exact mask. */
+export function slice_to_rgba(slice, colormap, color_range, { flip_y = true, out } = {}) {
+    const pixels = out?.length === slice.data.length * 4 ? out : new Uint8ClampedArray(slice.data.length * 4);
+    const lut = get_slice_lut(colormap);
+    const [range_min, range_max] = color_range;
+    const span = range_max - range_min;
+    const inv_span = span === 0 ? 0 : 1 / span;
+    for (let row_idx = 0; row_idx < slice.height; row_idx++) {
+        const target_row = flip_y ? slice.height - 1 - row_idx : row_idx;
+        for (let col_idx = 0; col_idx < slice.width; col_idx++) {
+            const source_idx = row_idx * slice.width + col_idx;
+            const pixel_idx = (target_row * slice.width + col_idx) * 4;
+            if (!slice.mask[source_idx] || !Number.isFinite(slice.data[source_idx])) {
+                pixels[pixel_idx] = 0;
+                pixels[pixel_idx + 1] = 0;
+                pixels[pixel_idx + 2] = 0;
+                pixels[pixel_idx + 3] = 0;
+                continue;
+            }
+            const normalized = span === 0
+                ? 0.5
+                : Math.max(0, Math.min(1, (slice.data[source_idx] - range_min) * inv_span));
+            const lut_idx = Math.round(normalized * (SLICE_LUT_SIZE - 1)) * 3;
+            pixels[pixel_idx] = lut[lut_idx];
+            pixels[pixel_idx + 1] = lut[lut_idx + 1];
+            pixels[pixel_idx + 2] = lut[lut_idx + 2];
+            pixels[pixel_idx + 3] = 255;
+        }
+    }
+    return pixels;
+}
+/** Resolve a contour count or explicit threshold list against a color range. */
+export function resolve_contour_thresholds(color_range, contour_levels) {
+    if (Array.isArray(contour_levels)) {
+        // Sort before truncating so the cap keeps the lowest thresholds deterministically
+        // regardless of input order
+        return contour_levels
+            .filter(Number.isFinite)
+            .sort((left, right) => left - right)
+            .slice(0, MAX_CONTOUR_LEVELS);
+    }
+    const count = Number.isFinite(contour_levels)
+        ? Math.min(MAX_CONTOUR_LEVELS, Math.max(0, Math.floor(contour_levels)))
+        : 0;
+    const [range_min, range_max] = color_range;
+    if (count === 0 || range_min === range_max)
+        return [];
+    return Array.from({ length: count }, (_, level_idx) => range_min + ((level_idx + 1) / (count + 1)) * (range_max - range_min)).sort((left, right) => left - right);
+}

package/dist/isosurface/slice.d.ts

@@ -1,11 +1,31 @@
-import type { Vec3 } from '../math';
+import type { Vec2, Vec3 } from '../math';
+import { type DisplayRange } from './sampling';
 import type { VolumetricData } from './types';
+export interface CartesianPlane {
+    point: Vec3;
+    normal: Vec3;
+    up?: Vec3;
+}
+export interface PlaneSliceOptions {
+    resolution?: number | Vec2;
+    max_pixels?: number;
+    fractional_bounds?: DisplayRange;
+}
 export interface SliceResult {
     data: Float64Array;
+    mask: Uint8Array;
     width: number;
     height: number;
     min: number;
     max: number;
+    point: Vec3;
+    normal: Vec3;
+    u_axis: Vec3;
+    v_axis: Vec3;
+    u_range: Vec2;
+    v_range: Vec2;
+    polygon: Vec2[];
 }
-export declare function trilinear_interpolate(grid: number[][][], fx: number, fy: number, fz: number, periodic: boolean): number;
+/** Sample a scalar volume on an arbitrary absolute Cartesian plane. */
+export declare function sample_plane_slice(volume: VolumetricData, plane: CartesianPlane, options?: PlaneSliceOptions): SliceResult | null;
 export declare function sample_hkl_slice(volume: VolumetricData, miller_indices: Vec3, distance: number, n_points?: number): SliceResult | null;