matterviz 0.4.2 → 0.4.3

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;

package/dist/isosurface/types.js

@@ -75,7 +75,7 @@ export function pad_periodic_grid(grid, dims, pad_fraction) {
 }
 // Max total grid points before downsampling is applied for isosurface extraction.
 // 500K balances visual quality with interactive performance (<200ms marching cubes).
-const MAX_GRID_POINTS = 500_000;
+export const MAX_GRID_POINTS = 500_000;
 // Downsample a 3D volumetric grid to keep total point count under a budget.
 // Uses block averaging to preserve data fidelity while reducing grid dimensions.
 // Returns original grid/dims if already within budget.
@@ -147,16 +147,17 @@ export const DEFAULT_ISOSURFACE_SETTINGS = {
     wireframe: false,
     halo: 0,
 };
+const field_has_significant_negatives = ({ min, abs_max }) => min < -abs_max * 0.01;
+const default_isovalue = ({ abs_max }) => abs_max > 0 ? abs_max * 0.2 : DEFAULT_ISOSURFACE_SETTINGS.isovalue;
 // Compute reasonable isosurface settings from a volume's data range.
 // Sets isovalue to 20% of abs_max and enables negative lobe when data has
 // significant negative values (>1% of max).
 export function auto_isosurface_settings(data_range) {
-    const has_negatives = data_range.min < -data_range.abs_max * 0.01;
     return {
         ...DEFAULT_ISOSURFACE_SETTINGS,
         // Fall back to default isovalue for all-zero grids to keep controls usable
-        isovalue: data_range.abs_max > 0 ? data_range.abs_max * 0.2 : DEFAULT_ISOSURFACE_SETTINGS.isovalue,
-        show_negative: has_negatives,
+        isovalue: default_isovalue(data_range),
+        show_negative: field_has_significant_negatives(data_range),
     };
 }
 // Generate N evenly-spaced isosurface layers across a data range.
@@ -165,7 +166,7 @@ export function auto_isosurface_settings(data_range) {
 export function generate_layers(data_range, n_layers) {
     if (n_layers <= 0 || data_range.abs_max <= 0)
         return [];
-    const has_negatives = data_range.min < -data_range.abs_max * 0.01;
+    const show_negative = field_has_significant_negatives(data_range);
     // Space isovalues from high (inner) to low (outer)
     return Array.from({ length: n_layers }, (_, idx) => {
         // Fraction from 0.8 (inner) to 0.1 (outer)
@@ -175,18 +176,129 @@ export function generate_layers(data_range, n_layers) {
             color: LAYER_COLORS[idx % LAYER_COLORS.length],
             opacity: n_layers === 1 ? 0.6 : 0.8 - idx * (0.5 / Math.max(n_layers - 1, 1)),
             visible: true,
-            show_negative: has_negatives,
+            show_negative,
             negative_color: LAYER_COLORS[(idx + 1) % LAYER_COLORS.length],
         };
     });
 }
-// Tile (repeat) volumetric data to fill a supercell.
+// Build a default isosurface layer for a newly added volume: isovalue at 20% of
+// abs_max, next unused palette color, and negative lobe when the data is signed.
+export function auto_volume_layer(volume, volume_idx, color_offset = 0) {
+    return {
+        isovalue: default_isovalue(volume.data_range),
+        color: LAYER_COLORS[color_offset % LAYER_COLORS.length],
+        opacity: 0.6,
+        visible: true,
+        show_negative: field_has_significant_negatives(volume.data_range),
+        negative_color: LAYER_COLORS[(color_offset + 1) % LAYER_COLORS.length],
+        volume_idx,
+    };
+}
+// Convert single-isovalue settings into an explicit layers array (no-op when
+// layers already exist — an explicit empty array means zero surfaces and is
+// preserved). Used when entering multi-volume mode so the implicit
+// active-volume surface survives as an editable layer.
+export function materialize_layers(settings, active_volume_idx) {
+    if (settings.layers) {
+        // Pin any layers still relying on the implicit active volume
+        return settings.layers.map((layer) => ({
+            ...layer,
+            volume_idx: layer.volume_idx ?? active_volume_idx,
+        }));
+    }
+    return [
+        {
+            isovalue: settings.isovalue,
+            color: settings.positive_color,
+            opacity: settings.opacity,
+            visible: true,
+            show_negative: settings.show_negative,
+            negative_color: settings.negative_color,
+            volume_idx: active_volume_idx,
+        },
+    ];
+}
+// Remove a volume from the registry: drops layers whose geometry references it,
+// unsets color sources pointing at it, and shifts higher indices down by one.
+// Layers without an explicit volume_idx implicitly reference `active_volume_idx`.
+export function remove_volume(volumes, layers, removed_idx, active_volume_idx = 0) {
+    const remap = (idx) => {
+        if (idx === undefined || idx === removed_idx)
+            return undefined;
+        return idx > removed_idx ? idx - 1 : idx;
+    };
+    return {
+        volumes: volumes.filter((_vol, idx) => idx !== removed_idx),
+        layers: layers
+            .filter((layer) => (layer.volume_idx ?? active_volume_idx) !== removed_idx)
+            .map((layer) => ({
+            ...layer,
+            volume_idx: remap(layer.volume_idx ?? active_volume_idx) ?? 0,
+            color_volume_idx: remap(layer.color_volume_idx),
+        })),
+    };
+}
+// Label volumes parsed from a file with a stable `source` id (compression-
+// stripped filename) and a display label (multi-block files like spin-polarized
+// CHGCAR get "<file>: <block label>" labels).
+export function label_file_volumes(volumes, filename) {
+    const source = filename.replace(/\.(?:gz|gzip|bz2|xz|zst)$/i, ``);
+    return volumes.map((vol, idx) => ({
+        ...vol,
+        source,
+        label: volumes.length > 1 ? `${source}: ${vol.label ?? idx + 1}` : source,
+    }));
+}
+// Two lattices describe the same cell when all matrix entries agree within
+// tolerance — the signal that an imported file is another scalar field of the
+// already-loaded system and should be appended rather than replace the scene.
+export const lattices_match = (lattice_a, lattice_b, tolerance = 0.05) => Boolean(lattice_a && lattice_b) &&
+    lattice_a.every((row, row_idx) => row.every((val, col_idx) => Math.abs(val - lattice_b[row_idx][col_idx]) < tolerance));
+// Merge volumes from a newly imported file (pre-labeled via label_file_volumes)
+// into an existing registry. Reimporting a source with the same block count
+// replaces its volumes in place, preserving user-tuned layers; a changed block
+// count drops the stale group (remapping layer indices) before appending fresh
+// volumes. New volumes each get an auto-generated layer.
+// Layers without an explicit volume_idx implicitly reference `active_volume_idx`
+// and are pinned to it up front so index remapping treats them correctly.
+export function merge_imported_volumes(existing, existing_layers, incoming, active_volume_idx = 0) {
+    const source = incoming[0]?.source;
+    let volumes = [...existing];
+    let layers = existing_layers.map((layer) => ({
+        ...layer,
+        volume_idx: layer.volume_idx ?? active_volume_idx,
+    }));
+    const group_indices = volumes
+        .map((vol, idx) => (source !== undefined && vol.source === source ? idx : -1))
+        .filter((idx) => idx >= 0);
+    if (group_indices.length === incoming.length && incoming.length > 0) {
+        // Same source, same block count: replace in place, keep layer settings
+        for (const [incoming_idx, vol_idx] of group_indices.entries()) {
+            volumes[vol_idx] = incoming[incoming_idx];
+        }
+        return { volumes, layers, first_touched_idx: group_indices[0], n_added: 0 };
+    }
+    // Drop any stale volumes from the same source (block count changed)
+    for (let removed = group_indices.length - 1; removed >= 0; removed--) {
+        ;
+        ({ volumes, layers } = remove_volume(volumes, layers, group_indices[removed]));
+    }
+    const first_touched_idx = volumes.length;
+    for (const vol of incoming) {
+        layers.push(auto_volume_layer(vol, volumes.length, layers.length));
+        volumes.push(vol);
+    }
+    return { volumes, layers, first_touched_idx, n_added: incoming.length };
+}
+// Tile (repeat) periodic volumetric data to fill a supercell. Finite volumes
+// remain unchanged: structure supercells must not implicitly repeat molecular
+// or other bounded scalar fields.
 // Pre-downsamples the source grid when the tiled result would exceed MAX_GRID_POINTS
 // to avoid large temporary allocations. Returns the original volume unchanged for
 // [1,1,1] scaling.
 export function tile_volumetric_data(volume, scaling) {
     const [sx, sy, sz] = scaling;
-    if (sx === 1 && sy === 1 && sz === 1)
+    if (!volume.periodic || (sx === 1 && sy === 1 && sz === 1))
         return volume;
     const total_cells = sx * sy * sz;
     let src_grid = volume.grid;

package/dist/json-path.d.ts

@@ -0,0 +1,4 @@
+export declare const format_path: (segments: (string | number)[]) => string;
+export declare const build_path: (parent_path: string, key: string | number) => string;
+export declare function parse_path(path: string): (string | number)[];
+export declare function resolve_path(root: unknown, path: string): unknown;

package/dist/json-path.js

@@ -0,0 +1,89 @@
+// Dot/bracket path codec for arbitrary JavaScript object keys.
+// Special keys use JSON.stringify so quotes/backslashes/brackets round-trip.
+const PATH_IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/u;
+function format_path_segment(segment, is_first = false) {
+    if (typeof segment === `number`)
+        return `[${segment}]`;
+    if (PATH_IDENTIFIER_RE.test(segment))
+        return is_first ? segment : `.${segment}`;
+    return `[${JSON.stringify(segment)}]`;
+}
+export const format_path = (segments) => segments.map((segment, idx) => format_path_segment(segment, idx === 0)).join(``);
+export const build_path = (parent_path, key) => parent_path ? parent_path + format_path_segment(key) : format_path_segment(key, true);
+export function parse_path(path) {
+    if (!path)
+        return [];
+    const segments = [];
+    let pos = 0;
+    while (pos < path.length) {
+        const char = path[pos];
+        if (char === `.`) {
+            pos++;
+            continue;
+        }
+        if (char !== `[`) {
+            const start = pos;
+            while (pos < path.length && path[pos] !== `.` && path[pos] !== `[`)
+                pos++;
+            if (pos > start)
+                segments.push(path.slice(start, pos));
+            continue;
+        }
+        pos++; // skip `[`
+        if (path[pos] === `]`) {
+            pos++;
+            continue;
+        }
+        if (path[pos] === `"`) {
+            const json_start = pos;
+            let escaped = false;
+            pos++;
+            while (pos < path.length) {
+                const quote_char = path[pos];
+                if (escaped)
+                    escaped = false;
+                else if (quote_char === `\\`)
+                    escaped = true;
+                else if (quote_char === `"`)
+                    break;
+                pos++;
+            }
+            if (pos >= path.length) {
+                segments.push(path.slice(json_start + 1));
+                break;
+            }
+            try {
+                segments.push(JSON.parse(path.slice(json_start, pos + 1)));
+            }
+            catch {
+                segments.push(path.slice(json_start + 1, pos));
+            }
+            pos++;
+            if (path[pos] === `]`)
+                pos++;
+            continue;
+        }
+        const start = pos;
+        while (pos < path.length && path[pos] !== `]`)
+            pos++;
+        const token = path.slice(start, pos);
+        if (token) {
+            const num = Number(token);
+            segments.push(Number.isNaN(num) ? token : num);
+        }
+        if (path[pos] === `]`)
+            pos++;
+    }
+    return segments;
+}
+export function resolve_path(root, path) {
+    if (!path)
+        return root;
+    let current = root;
+    for (const key of parse_path(path)) {
+        if (current == null || typeof current !== `object`)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}