matterviz 0.3.6 → 0.3.7

package/dist/isosurface/slice.js

@@ -0,0 +1,140 @@
+// HKL plane slicing for volumetric data: samples a 3D grid along an arbitrary
+// 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;
+    }
+    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);
+    const xd = gx - Math.floor(gx);
+    const yd = gy - Math.floor(gy);
+    const zd = gz - Math.floor(gz);
+    // 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;
+}
+// Sample a 2D slice through volumetric data along a Miller-index plane.
+// `miller_indices` [h,k,l] defines the plane normal in reciprocal space.
+// `distance` is fractional [0,1] along the normal direction within the cell.
+// Returns null if indices are all zero.
+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 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)
+        return null; // degenerate normal
+    const unit_normal = math.normalize_vec3(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;
+    }
+    // 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 };
+}

package/dist/isosurface/types.d.ts

@@ -0,0 +1,56 @@
+import type { Matrix3x3, Vec3 } from '../math';
+import type { ParsedStructure } from '../structure/parse';
+export interface DataRange {
+    min: number;
+    max: number;
+    abs_max: number;
+    mean: number;
+}
+export interface VolumetricData {
+    grid: number[][][];
+    grid_dims: Vec3;
+    lattice: Matrix3x3;
+    origin: Vec3;
+    data_range: DataRange;
+    data_order?: `x_fastest` | `z_fastest`;
+    periodic: boolean;
+    label?: string;
+}
+export interface VolumetricFileData {
+    structure: ParsedStructure;
+    volumes: VolumetricData[];
+}
+export interface IsosurfaceLayer {
+    isovalue: number;
+    color: string;
+    opacity: number;
+    visible: boolean;
+    show_negative: boolean;
+    negative_color: string;
+}
+export interface IsosurfaceSettings {
+    isovalue: number;
+    opacity: number;
+    positive_color: string;
+    negative_color: string;
+    show_negative: boolean;
+    wireframe: boolean;
+    halo: number;
+    layers?: IsosurfaceLayer[];
+}
+export declare const LAYER_COLORS: readonly ["#3b82f6", "#ef4444", "#22c55e", "#a855f7", "#f97316", "#06b6d4", "#eab308", "#ec4899"];
+export declare function grid_data_range(grid: number[][][]): DataRange;
+export declare function pad_periodic_grid(grid: number[][][], dims: Vec3, pad_fraction: number): {
+    grid: number[][][];
+    dims: Vec3;
+    offset: Vec3;
+};
+export declare function downsample_grid(grid: number[][][], dims: Vec3, max_points?: number): {
+    grid: number[][][];
+    dims: Vec3;
+    factor: number;
+};
+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 tile_volumetric_data(volume: VolumetricData, scaling: Vec3): VolumetricData;

package/dist/isosurface/types.js

@@ -0,0 +1,227 @@
+import { scale_lattice_matrix } from '../math';
+// Categorical palette for auto-coloring isosurface layers (Tailwind-inspired)
+export const LAYER_COLORS = [
+    `#3b82f6`, // blue
+    `#ef4444`, // red
+    `#22c55e`, // green
+    `#a855f7`, // purple
+    `#f97316`, // orange
+    `#06b6d4`, // cyan
+    `#eab308`, // yellow
+    `#ec4899`, // pink
+];
+// Compute min/max/abs_max/mean of a 3D grid.
+// Prefer using the precomputed `data_range` field on VolumetricData when available.
+export function grid_data_range(grid) {
+    if (!grid.length || !grid[0]?.length || !grid[0][0]?.length) {
+        return { min: 0, max: 0, abs_max: 0, mean: 0 };
+    }
+    let [min_val, max_val] = [Infinity, -Infinity];
+    let sum = 0;
+    let count = 0;
+    for (const plane of grid) {
+        for (const row of plane) {
+            for (const val of row) {
+                if (val < min_val)
+                    min_val = val;
+                if (val > max_val)
+                    max_val = val;
+                sum += val;
+                count++;
+            }
+        }
+    }
+    const abs_max = Math.max(Math.abs(min_val), Math.abs(max_val));
+    return { min: min_val, max: max_val, abs_max, mean: count > 0 ? sum / count : 0 };
+}
+const wrap_grid_idx = (val, size) => ((val % size) + size) % size;
+const clamp_dim = (src, fac) => Math.min(src, Math.max(2, Math.ceil(src / fac)));
+const partition_ranges = (n_out, n_src) => Array.from({ length: n_out }, (_, idx) => [
+    Math.round((idx * n_src) / n_out),
+    Math.round(((idx + 1) * n_src) / n_out),
+]);
+// Pad a periodic 3D grid with halo cells from the opposite face so isosurfaces
+// extend beyond the unit cell and close into complete enclosed shapes.
+// Returns a larger grid with dims [nx+2*pad, ny+2*pad, nz+2*pad] and the
+// fractional offset that the padded grid's origin has shifted by.
+export function pad_periodic_grid(grid, dims, pad_fraction) {
+    const [nx, ny, nz] = dims;
+    const frac = Math.max(0, pad_fraction);
+    const px = Math.min(Math.ceil(nx * frac), Math.floor(nx / 2));
+    const py = Math.min(Math.ceil(ny * frac), Math.floor(ny / 2));
+    const pz = Math.min(Math.ceil(nz * frac), Math.floor(nz / 2));
+    if (px === 0 && py === 0 && pz === 0)
+        return { grid, dims, offset: [0, 0, 0] };
+    const out_nx = nx + 2 * px;
+    const out_ny = ny + 2 * py;
+    const out_nz = nz + 2 * pz;
+    const out = Array(out_nx);
+    for (let ix = 0; ix < out_nx; ix++) {
+        const plane = Array(out_ny);
+        const src_x = wrap_grid_idx(ix - px, nx);
+        for (let iy = 0; iy < out_ny; iy++) {
+            const row = Array(out_nz);
+            const src_y = wrap_grid_idx(iy - py, ny);
+            for (let iz = 0; iz < out_nz; iz++) {
+                row[iz] = grid[src_x][src_y][wrap_grid_idx(iz - pz, nz)];
+            }
+            plane[iy] = row;
+        }
+        out[ix] = plane;
+    }
+    // Fractional offset: the padded grid starts at -pad/n in each axis
+    const offset = [-px / nx, -py / ny, -pz / nz];
+    return { grid: out, dims: [out_nx, out_ny, out_nz], offset };
+}
+// 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;
+// 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.
+export function downsample_grid(grid, dims, max_points = MAX_GRID_POINTS) {
+    const [nx, ny, nz] = dims;
+    const total = nx * ny * nz;
+    if (total <= max_points)
+        return { grid, dims, factor: 1 };
+    // Floor at 1 to avoid Infinity in cbrt(total/0)
+    max_points = Math.max(1, max_points);
+    // Increase factor until the clamped output fits within budget.
+    // A single cbrt step can overshoot for anisotropic grids where max(2,...)
+    // clamping prevents a small axis from shrinking below 2.
+    // clamp_dim: returns 1 for single-cell axes, otherwise clamps to [2, src]
+    let factor = Math.ceil(Math.cbrt(total / max_points));
+    let new_nx = clamp_dim(nx, factor);
+    let new_ny = clamp_dim(ny, factor);
+    let new_nz = clamp_dim(nz, factor);
+    while (new_nx * new_ny * new_nz > max_points) {
+        factor++;
+        const prev_total = new_nx * new_ny * new_nz;
+        new_nx = clamp_dim(nx, factor);
+        new_ny = clamp_dim(ny, factor);
+        new_nz = clamp_dim(nz, factor);
+        // dims hit their floor (2 per axis or 1 for single-cell) — stop to avoid infinite loop
+        if (new_nx * new_ny * new_nz === prev_total)
+            break;
+    }
+    // Proportional partitioning: evenly divides [0, n) into new_n non-empty blocks.
+    // Unlike fixed-stride (ix * factor), this is safe when max(2,...) clamping
+    // produces more output cells than ceil(n/factor) would — no empty blocks.
+    const x_ranges = partition_ranges(new_nx, nx);
+    const y_ranges = partition_ranges(new_ny, ny);
+    const z_ranges = partition_ranges(new_nz, nz);
+    const out = Array(new_nx);
+    for (let ix = 0; ix < new_nx; ix++) {
+        const plane = Array(new_ny);
+        const [sx_start, sx_end] = x_ranges[ix];
+        for (let iy = 0; iy < new_ny; iy++) {
+            const row = Array(new_nz);
+            const [sy_start, sy_end] = y_ranges[iy];
+            for (let iz = 0; iz < new_nz; iz++) {
+                let sum = 0;
+                const [sz_start, sz_end] = z_ranges[iz];
+                for (let sx = sx_start; sx < sx_end; sx++) {
+                    const src_plane = grid[sx];
+                    for (let sy = sy_start; sy < sy_end; sy++) {
+                        const src_row = src_plane[sy];
+                        for (let sz = sz_start; sz < sz_end; sz++) {
+                            sum += src_row[sz];
+                        }
+                    }
+                }
+                row[iz] = sum / ((sx_end - sx_start) * (sy_end - sy_start) * (sz_end - sz_start));
+            }
+            plane[iy] = row;
+        }
+        out[ix] = plane;
+    }
+    return { grid: out, dims: [new_nx, new_ny, new_nz], factor };
+}
+// Default isosurface rendering settings
+export const DEFAULT_ISOSURFACE_SETTINGS = {
+    isovalue: 0.05,
+    opacity: 0.6,
+    positive_color: `#3b82f6`, // blue
+    negative_color: `#ef4444`, // red
+    show_negative: false,
+    wireframe: false,
+    halo: 0,
+};
+// 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,
+    };
+}
+// Generate N evenly-spaced isosurface layers across a data range.
+// Layers are spaced from 10% to 80% of abs_max with decreasing opacity
+// for outer (lower-isovalue) shells so inner shells remain visible.
+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;
+    // Space isovalues from high (inner) to low (outer)
+    return Array.from({ length: n_layers }, (_, idx) => {
+        // Fraction from 0.8 (inner) to 0.1 (outer)
+        const fraction = n_layers === 1 ? 0.2 : 0.8 - (idx / (n_layers - 1)) * 0.7;
+        return {
+            isovalue: data_range.abs_max * fraction,
+            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,
+            negative_color: LAYER_COLORS[(idx + 1) % LAYER_COLORS.length],
+        };
+    });
+}
+// Tile (repeat) volumetric data to fill a supercell.
+// 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)
+        return volume;
+    const total_cells = sx * sy * sz;
+    let src_grid = volume.grid;
+    let [nx, ny, nz] = volume.grid_dims;
+    // Pre-downsample source grid so the tiled result stays within budget.
+    // Clamp budget to 8 (minimum downsample output = 2^3) to prevent infinite
+    // loops in downsample_grid when total_cells is very large.
+    if (nx * ny * nz * total_cells > MAX_GRID_POINTS) {
+        const budget = Math.max(8, Math.floor(MAX_GRID_POINTS / total_cells));
+        const ds = downsample_grid(src_grid, [nx, ny, nz], budget);
+        src_grid = ds.grid;
+        [nx, ny, nz] = ds.dims;
+    }
+    const new_nx = nx * sx;
+    const new_ny = ny * sy;
+    const new_nz = nz * sz;
+    const new_grid = Array(new_nx);
+    for (let ix = 0; ix < new_nx; ix++) {
+        const plane = Array(new_ny);
+        const src_x = ix % nx;
+        for (let iy = 0; iy < new_ny; iy++) {
+            const row = Array(new_nz);
+            const src_y = iy % ny;
+            const src_row = src_grid[src_x][src_y];
+            for (let iz = 0; iz < new_nz; iz++) {
+                row[iz] = src_row[iz % nz];
+            }
+            plane[iy] = row;
+        }
+        new_grid[ix] = plane;
+    }
+    return {
+        ...volume,
+        grid: new_grid,
+        grid_dims: [new_nx, new_ny, new_nz],
+        lattice: scale_lattice_matrix(volume.lattice, scaling),
+    };
+}

package/dist/labels.d.ts

@@ -0,0 +1,53 @@
+import type { ChemicalElement, ElementCategory } from './element/types';
+import type { Vec3 } from './math';
+import type { SymbolType } from 'd3-shape';
+import * as d3_symbols from 'd3-shape';
+export type D3Symbol = keyof typeof d3_symbols & `symbol${Capitalize<string>}`;
+export type D3SymbolName = Exclude<D3Symbol extends `symbol${infer Name}` ? Name : never, ``>;
+export declare const symbol_names: D3SymbolName[];
+export declare const symbol_map: Partial<Record<D3SymbolName, SymbolType>>;
+export declare function format_value(value: number, formatter?: string): string;
+export declare const ELEM_PROPERTY_LABELS: Partial<Record<keyof ChemicalElement, [string, string | null]>>;
+export declare const ELEM_HEATMAP_KEYS: (keyof ChemicalElement)[];
+export declare const ELEM_HEATMAP_LABELS: Partial<Record<string, keyof ChemicalElement>>;
+export declare const DEFAULT_FMT: [string, string];
+export declare const FRACTION_GLYPHS: ReadonlyArray<readonly [number, string]>;
+export declare const format_num: (num: number, fmt?: string | number) => string;
+export declare const format_vec3: (vec: Readonly<Vec3>, fmt_spec?: string) => string;
+export declare const format_bytes: (bytes?: number) => string;
+export declare function format_fractional(value: number): string;
+export declare function parse_si_float<T extends string | number | null | undefined>(value: T): T | number | string;
+export declare const CATEGORY_COUNTS: Record<ElementCategory, number>;
+export declare const ELEMENT_CATEGORIES: readonly ["actinide", "alkali metal", "alkaline earth metal", "diatomic nonmetal", "lanthanide", "metalloid", "noble gas", "polyatomic nonmetal", "post-transition metal", "transition metal"];
+export declare const ELEM_SYMBOLS: readonly ["H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne", "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca", "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn", "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr", "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn", "Sb", "Te", "I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd", "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb", "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg", "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th", "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm", "Md", "No", "Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt", "Ds", "Rg", "Cn", "Nh", "Fl", "Mc", "Lv", "Ts", "Og"];
+export declare const SUPERSCRIPT_MAP: {
+    readonly '0': "⁰";
+    readonly '1': "¹";
+    readonly '2': "²";
+    readonly '3': "³";
+    readonly '4': "⁴";
+    readonly '5': "⁵";
+    readonly '6': "⁶";
+    readonly '7': "⁷";
+    readonly '8': "⁸";
+    readonly '9': "⁹";
+    readonly '+': "⁺";
+    readonly '-': "⁻";
+};
+export declare const SUBSCRIPT_MAP: {
+    readonly '0': "₀";
+    readonly '1': "₁";
+    readonly '2': "₂";
+    readonly '3': "₃";
+    readonly '4': "₄";
+    readonly '5': "₅";
+    readonly '6': "₆";
+    readonly '7': "₇";
+    readonly '8': "₈";
+    readonly '9': "₉";
+};
+export declare const superscript_digits: (input: string) => string;
+export declare const trajectory_property_config: Record<string, {
+    label: string;
+    unit: string;
+}>;