matterviz 0.3.4 → 0.3.6

package/dist/isosurface/slice.js

@@ -1,140 +0,0 @@
-// 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';
-// 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 safe_mod = (val, dim) => ((val % dim) + dim) % dim;
-    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

@@ -1,56 +0,0 @@
-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

@@ -1,227 +0,0 @@
-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 };
-}
-// 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 wrap = (val, size) => ((val % size) + size) % size;
-    const out = new Array(out_nx);
-    for (let ix = 0; ix < out_nx; ix++) {
-        const plane = new Array(out_ny);
-        const src_x = wrap(ix - px, nx);
-        for (let iy = 0; iy < out_ny; iy++) {
-            const row = new Array(out_nz);
-            const src_y = wrap(iy - py, ny);
-            for (let iz = 0; iz < out_nz; iz++) {
-                row[iz] = grid[src_x][src_y][wrap(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]
-    const clamp_dim = (src, fac) => Math.min(src, Math.max(2, Math.ceil(src / fac)));
-    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 partition = (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),
-    ]);
-    const x_ranges = partition(new_nx, nx);
-    const y_ranges = partition(new_ny, ny);
-    const z_ranges = partition(new_nz, nz);
-    const out = new Array(new_nx);
-    for (let ix = 0; ix < new_nx; ix++) {
-        const plane = new Array(new_ny);
-        const [sx_start, sx_end] = x_ranges[ix];
-        for (let iy = 0; iy < new_ny; iy++) {
-            const row = new 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 = new Array(new_nx);
-    for (let ix = 0; ix < new_nx; ix++) {
-        const plane = new Array(new_ny);
-        const src_x = ix % nx;
-        for (let iy = 0; iy < new_ny; iy++) {
-            const row = new 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

@@ -1,53 +0,0 @@
-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: 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;
-}>;