matterviz 0.4.1 → 0.4.3

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;

package/dist/isosurface/slice.js

@@ -2,56 +2,194 @@
 // crystallographic plane defined by Miller indices, using trilinear interpolation.
 import { reciprocal_lattice } from '../brillouin';
 import * as math from '../math';
-const safe_mod = (val, dim) => ((val % dim) + dim) % dim;
-// 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;
+import { create_volume_sampler, sanitize_display_range } from './sampling';
+const CELL_EDGES = [
+    [0, 1],
+    [0, 2],
+    [0, 4],
+    [1, 3],
+    [1, 5],
+    [2, 3],
+    [2, 6],
+    [3, 7],
+    [4, 5],
+    [4, 6],
+    [5, 7],
+    [6, 7],
+];
+const PLANE_TOLERANCE = 1e-9;
+const DEFAULT_MAX_PIXELS = 512 * 512;
+const UNIT_CELL_RANGE = [
+    [0, 1],
+    [0, 1],
+    [0, 1],
+];
+const cell_corners = (volume, bounds) => {
+    const frac_to_cart = math.create_frac_to_cart(volume.lattice);
+    return Array.from({ length: 8 }, (_, corner_idx) => math.add(volume.origin, frac_to_cart([
+        bounds[0][corner_idx & 1 ? 1 : 0],
+        bounds[1][corner_idx & 2 ? 1 : 0],
+        bounds[2][corner_idx & 4 ? 1 : 0],
+    ])));
+};
+const add_unique_point = (points, point) => {
+    if (points.some((existing) => (existing[0] - point[0]) ** 2 +
+        (existing[1] - point[1]) ** 2 +
+        (existing[2] - point[2]) ** 2 <
+        PLANE_TOLERANCE ** 2))
+        return;
+    points.push(point);
+};
+const plane_basis = (normal, up) => {
+    if (!up)
+        return math.compute_in_plane_basis(normal);
+    const normal_projection = math.dot(up, normal);
+    const projected = math.subtract(up, math.scale(normal, normal_projection));
+    if (Math.hypot(...projected) < PLANE_TOLERANCE) {
+        return math.compute_in_plane_basis(normal);
     }
-    const x0 = periodic
-        ? safe_mod(Math.floor(gx), nx)
-        : Math.max(0, Math.min(Math.floor(gx), nx - 2));
-    const y0 = periodic
-        ? safe_mod(Math.floor(gy), ny)
-        : Math.max(0, Math.min(Math.floor(gy), ny - 2));
-    const z0 = periodic
-        ? safe_mod(Math.floor(gz), nz)
-        : Math.max(0, Math.min(Math.floor(gz), nz - 2));
-    const x1 = periodic ? (x0 + 1) % nx : Math.min(x0 + 1, nx - 1);
-    const y1 = periodic ? (y0 + 1) % ny : Math.min(y0 + 1, ny - 1);
-    const z1 = periodic ? (z0 + 1) % nz : Math.min(z0 + 1, nz - 1);
-    // 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;
+    const u_axis = math.normalize_vec(projected);
+    return [u_axis, math.cross_3d(normal, u_axis)];
+};
+const intersect_plane_cell = (corners, point, normal, u_axis, v_axis) => {
+    const intersections = [];
+    for (const [start_idx, end_idx] of CELL_EDGES) {
+        const start = corners[start_idx];
+        const end = corners[end_idx];
+        const start_distance = math.dot(math.subtract(start, point), normal);
+        const end_distance = math.dot(math.subtract(end, point), normal);
+        if (Math.abs(start_distance) <= PLANE_TOLERANCE)
+            add_unique_point(intersections, start);
+        if (Math.abs(end_distance) <= PLANE_TOLERANCE)
+            add_unique_point(intersections, end);
+        if (start_distance * end_distance >= -(PLANE_TOLERANCE ** 2))
+            continue;
+        const fraction = start_distance / (start_distance - end_distance);
+        add_unique_point(intersections, [
+            start[0] + fraction * (end[0] - start[0]),
+            start[1] + fraction * (end[1] - start[1]),
+            start[2] + fraction * (end[2] - start[2]),
+        ]);
+    }
+    return math.convex_hull_2d(intersections.map((intersection) => {
+        const relative = math.subtract(intersection, point);
+        return [math.dot(relative, u_axis), math.dot(relative, v_axis)];
+    }), PLANE_TOLERANCE);
+};
+const point_in_convex_polygon = (point, polygon) => {
+    let orientation = 0;
+    for (let point_idx = 0; point_idx < polygon.length; point_idx++) {
+        const start = polygon[point_idx];
+        const end = polygon[(point_idx + 1) % polygon.length];
+        const cross = (end[0] - start[0]) * (point[1] - start[1]) - (end[1] - start[1]) * (point[0] - start[0]);
+        if (Math.abs(cross) <= PLANE_TOLERANCE)
+            continue;
+        const current_orientation = Math.sign(cross);
+        if (orientation && current_orientation !== orientation)
+            return false;
+        orientation = current_orientation;
+    }
+    return true;
+};
+const resolve_resolution = (resolution, u_span, v_span, max_grid_dim, max_pixels) => {
+    let counts;
+    if (Array.isArray(resolution)) {
+        counts = [Math.max(2, Math.round(resolution[0])), Math.max(2, Math.round(resolution[1]))];
+    }
+    else {
+        const longest_count = Math.max(2, Math.round(resolution ?? max_grid_dim));
+        const longest_span = Math.max(u_span, v_span, PLANE_TOLERANCE);
+        counts = [
+            Math.max(2, Math.round((longest_count * u_span) / longest_span)),
+            Math.max(2, Math.round((longest_count * v_span) / longest_span)),
+        ];
+    }
+    const pixel_budget = Number.isFinite(max_pixels)
+        ? Math.max(4, Math.floor(max_pixels))
+        : DEFAULT_MAX_PIXELS;
+    const shrink = Math.min(1, Math.sqrt(pixel_budget / (counts[0] * counts[1])));
+    if (shrink >= 1)
+        return counts;
+    counts = counts.map((count) => Math.max(2, Math.floor(count * shrink)));
+    if (counts[0] * counts[1] > pixel_budget) {
+        const axis = counts[0] >= counts[1] ? 0 : 1;
+        counts[axis] = Math.max(2, Math.floor(pixel_budget / counts[axis === 0 ? 1 : 0]));
+    }
+    return counts;
+};
+/** Sample a scalar volume on an arbitrary absolute Cartesian plane. */
+export function sample_plane_slice(volume, plane, options = {}) {
+    if (!plane.point.every(Number.isFinite) || !plane.normal.every(Number.isFinite))
+        return null;
+    if (plane.up && !plane.up.every(Number.isFinite))
+        return null;
+    if (Math.hypot(...plane.normal) < PLANE_TOLERANCE)
+        return null; // degenerate normal
+    const normal = math.normalize_vec(plane.normal);
+    // In-plane basis vectors
+    const [u_axis, v_axis] = plane_basis(normal, plane.up);
+    const bounds = sanitize_display_range(options.fractional_bounds ?? UNIT_CELL_RANGE, volume.periodic);
+    const corners = cell_corners(volume, bounds);
+    const polygon = intersect_plane_cell(corners, plane.point, normal, u_axis, v_axis);
+    if (polygon.length < 3)
+        return null;
+    // Project all 8 unit cell corners onto the (u, v) plane to find sampling bounds.
+    // Corners are at fractional coords (0 or 1) for each axis.
+    const { min, max, width: u_span, height: v_span } = math.compute_bounding_box_2d(polygon);
+    const u_range = [min[0], max[0]];
+    const v_range = [min[1], max[1]];
+    if (u_span <= PLANE_TOLERANCE || v_span <= PLANE_TOLERANCE)
+        return null;
+    // Sampling resolution: caller-specified or default to max grid dimension
+    const [width, height] = resolve_resolution(options.resolution, u_span, v_span, Math.max(...volume.grid_dims), options.max_pixels ?? DEFAULT_MAX_PIXELS);
+    const data = new Float64Array(width * height);
+    data.fill(Number.NaN);
+    const mask = new Uint8Array(width * height);
+    let data_min = Infinity;
+    let data_max = -Infinity;
+    const sample = create_volume_sampler(volume, {
+        out_of_bounds: volume.periodic ? `clamp` : `fallback`,
+    });
+    const u_step = u_span / (width - 1);
+    const v_step = v_span / (height - 1);
+    const cartesian = [0, 0, 0];
+    for (let row = 0; row < height; row++) {
+        const v_value = v_range[0] + row * v_step;
+        for (let col = 0; col < width; col++) {
+            const u_value = u_range[0] + col * u_step;
+            if (!point_in_convex_polygon([u_value, v_value], polygon))
+                continue;
+            const data_idx = row * width + col;
+            mask[data_idx] = 1;
+            // Cartesian position on the plane
+            cartesian[0] = plane.point[0] + u_value * u_axis[0] + v_value * v_axis[0];
+            cartesian[1] = plane.point[1] + u_value * u_axis[1] + v_value * v_axis[1];
+            cartesian[2] = plane.point[2] + u_value * u_axis[2] + v_value * v_axis[2];
+            const value = sample(cartesian);
+            if (!Number.isFinite(value))
+                continue;
+            data[data_idx] = value;
+            if (value < data_min)
+                data_min = value;
+            if (value > data_max)
+                data_max = value;
+        }
+    }
+    return {
+        data,
+        mask,
+        width,
+        height,
+        min: data_min === Infinity ? 0 : data_min,
+        max: data_max === -Infinity ? 0 : data_max,
+        point: [...plane.point],
+        normal,
+        u_axis,
+        v_axis,
+        u_range,
+        v_range,
+        polygon,
+    };
 }
 // Sample a 2D slice through volumetric data along a Miller-index plane.
 // `miller_indices` [h,k,l] defines the plane normal in reciprocal space.
@@ -61,81 +199,27 @@ export function sample_hkl_slice(volume, miller_indices, distance, n_points) {
     const [h_idx, k_idx, l_idx] = miller_indices;
     if (h_idx === 0 && k_idx === 0 && l_idx === 0)
         return null;
-    const { grid, grid_dims, lattice, periodic } = volume;
-    const [nx, ny, nz] = grid_dims;
     // Plane normal G = h*b1 + k*b2 + l*b3 where b_i are reciprocal lattice rows
-    const recip = reciprocal_lattice(lattice);
+    const recip = reciprocal_lattice(volume.lattice);
     const plane_normal = [
         h_idx * recip[0][0] + k_idx * recip[1][0] + l_idx * recip[2][0],
         h_idx * recip[0][1] + k_idx * recip[1][1] + l_idx * recip[2][1],
         h_idx * recip[0][2] + k_idx * recip[1][2] + l_idx * recip[2][2],
     ];
-    if (Math.hypot(...plane_normal) < 1e-12)
+    if (Math.hypot(...plane_normal) < PLANE_TOLERANCE)
         return null; // degenerate normal
     const unit_normal = math.normalize_vec(plane_normal);
-    // In-plane basis vectors
-    const [u_vec, v_vec] = math.compute_in_plane_basis(unit_normal);
-    const cart_to_frac = math.create_cart_to_frac(lattice);
-    // Project all 8 unit cell corners onto the (u, v) plane to find sampling bounds.
-    // Corners are at fractional coords (0 or 1) for each axis.
-    let u_min = Infinity;
-    let u_max = -Infinity;
-    let v_min = Infinity;
-    let v_max = -Infinity;
-    let normal_min = Infinity;
-    let normal_max = -Infinity;
-    for (let ci = 0; ci < 8; ci++) {
-        const fi = ci & 1 ? 1 : 0;
-        const fj = ci & 2 ? 1 : 0;
-        const fk = ci & 4 ? 1 : 0;
-        // Corner in Cartesian: frac * lattice
-        const corner = [
-            fi * lattice[0][0] + fj * lattice[1][0] + fk * lattice[2][0],
-            fi * lattice[0][1] + fj * lattice[1][1] + fk * lattice[2][1],
-            fi * lattice[0][2] + fj * lattice[1][2] + fk * lattice[2][2],
-        ];
-        const u_proj = math.dot(corner, u_vec);
-        const v_proj = math.dot(corner, v_vec);
-        const n_proj = math.dot(corner, unit_normal);
-        if (u_proj < u_min)
-            u_min = u_proj;
-        if (u_proj > u_max)
-            u_max = u_proj;
-        if (v_proj < v_min)
-            v_min = v_proj;
-        if (v_proj > v_max)
-            v_max = v_proj;
-        if (n_proj < normal_min)
-            normal_min = n_proj;
-        if (n_proj > normal_max)
-            normal_max = n_proj;
-    }
+    const corners = cell_corners(volume, UNIT_CELL_RANGE);
+    const projections = corners.map((corner) => math.dot(corner, unit_normal));
+    const normal_min = Math.min(...projections);
+    const normal_max = Math.max(...projections);
     // Plane position: fractional distance [0,1] along the normal extent
     const d_cartesian = normal_min + distance * (normal_max - normal_min);
-    // Sampling resolution: caller-specified or default to max grid dimension
-    const width = n_points ?? Math.max(nx, ny, nz);
-    const height = width;
-    const data = new Float64Array(width * height);
-    let data_min = Infinity;
-    let data_max = -Infinity;
-    const u_step = (u_max - u_min) / (width - 1 || 1);
-    const v_step = (v_max - v_min) / (height - 1 || 1);
-    for (let row = 0; row < height; row++) {
-        const v_val = v_min + row * v_step;
-        for (let col = 0; col < width; col++) {
-            const u_val = u_min + col * u_step;
-            // Cartesian position on the plane
-            const px = d_cartesian * unit_normal[0] + u_val * u_vec[0] + v_val * v_vec[0];
-            const py = d_cartesian * unit_normal[1] + u_val * u_vec[1] + v_val * v_vec[1];
-            const pz = d_cartesian * unit_normal[2] + u_val * u_vec[2] + v_val * v_vec[2];
-            const [fx, fy, fz] = cart_to_frac([px, py, pz]);
-            const val = trilinear_interpolate(grid, fx, fy, fz, periodic);
-            data[row * width + col] = val;
-            if (val < data_min)
-                data_min = val;
-            if (val > data_max)
-                data_max = val;
-        }
-    }
-    return { data, width, height, min: data_min, max: data_max };
+    const point = [
+        d_cartesian * unit_normal[0],
+        d_cartesian * unit_normal[1],
+        d_cartesian * unit_normal[2],
+    ];
+    const resolution = n_points ?? Math.max(...volume.grid_dims);
+    return sample_plane_slice(volume, { point, normal: unit_normal }, { resolution: [resolution, resolution] });
 }

package/dist/isosurface/types.d.ts

@@ -1,4 +1,5 @@
-import type { Matrix3x3, Vec3 } from '../math';
+import type { D3InterpolateName } from '../colors';
+import type { Matrix3x3, Vec2, Vec3 } from '../math';
 import type { ParsedStructure } from '../structure/parse';
 export interface DataRange {
     min: number;
@@ -15,6 +16,7 @@ export interface VolumetricData {
     data_order?: `x_fastest` | `z_fastest`;
     periodic: boolean;
     label?: string;
+    source?: string;
 }
 export interface VolumetricFileData {
     structure: ParsedStructure;
@@ -27,6 +29,10 @@ export interface IsosurfaceLayer {
     visible: boolean;
     show_negative: boolean;
     negative_color: string;
+    volume_idx?: number;
+    color_volume_idx?: number;
+    colormap?: D3InterpolateName;
+    color_range?: Vec2;
 }
 export interface IsosurfaceSettings {
     isovalue: number;
@@ -37,6 +43,7 @@ export interface IsosurfaceSettings {
     wireframe: boolean;
     halo: number;
     layers?: IsosurfaceLayer[];
+    display_range?: [Vec2, Vec2, Vec2];
 }
 export declare const LAYER_COLORS: readonly ["#3b82f6", "#ef4444", "#22c55e", "#a855f7", "#f97316", "#06b6d4", "#eab308", "#ec4899"];
 export declare function grid_data_range(grid: number[][][]): DataRange;
@@ -45,6 +52,7 @@ export declare function pad_periodic_grid(grid: number[][][], dims: Vec3, pad_fr
     dims: Vec3;
     offset: Vec3;
 };
+export declare const MAX_GRID_POINTS = 500000;
 export declare function downsample_grid(grid: number[][][], dims: Vec3, max_points?: number): {
     grid: number[][][];
     dims: Vec3;
@@ -53,4 +61,19 @@ export declare function downsample_grid(grid: number[][][], dims: Vec3, max_poin
 export declare const DEFAULT_ISOSURFACE_SETTINGS: IsosurfaceSettings;
 export declare function auto_isosurface_settings(data_range: DataRange): IsosurfaceSettings;
 export declare function generate_layers(data_range: DataRange, n_layers: number): IsosurfaceLayer[];
+export declare function auto_volume_layer(volume: VolumetricData, volume_idx: number, color_offset?: number): IsosurfaceLayer;
+export declare function materialize_layers(settings: IsosurfaceSettings, active_volume_idx: number): IsosurfaceLayer[];
+export declare function remove_volume(volumes: VolumetricData[], layers: IsosurfaceLayer[], removed_idx: number, active_volume_idx?: number): {
+    volumes: VolumetricData[];
+    layers: IsosurfaceLayer[];
+};
+export declare function label_file_volumes(volumes: VolumetricData[], filename: string): VolumetricData[];
+export declare const lattices_match: (lattice_a: readonly (readonly number[])[] | undefined, lattice_b: readonly (readonly number[])[] | undefined, tolerance?: number) => boolean;
+export interface VolumeMergeResult {
+    volumes: VolumetricData[];
+    layers: IsosurfaceLayer[];
+    first_touched_idx: number;
+    n_added: number;
+}
+export declare function merge_imported_volumes(existing: VolumetricData[], existing_layers: IsosurfaceLayer[], incoming: VolumetricData[], active_volume_idx?: number): VolumeMergeResult;
 export declare function tile_volumetric_data(volume: VolumetricData, scaling: Vec3): VolumetricData;