matterviz 0.3.6 → 0.4.0

package/dist/src/lib/isosurface/slice.ts

@@ -1,175 +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 '$lib/brillouin'
-import type { Vec3 } from '$lib/math'
-import * as math from '$lib/math'
-import type { VolumetricData } from './types'
-
-// Result of sampling a 2D slice through volumetric data
-export interface SliceResult {
-  data: Float64Array // sampled values, row-major [height * width]
-  width: number
-  height: number
-  min: number // data minimum for colormap
-  max: number // data maximum for colormap
-}
-
-const safe_mod = (val: number, dim: number) => ((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: number[][][],
-  fx: number,
-  fy: number,
-  fz: number,
-  periodic: boolean,
-): number {
-  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: VolumetricData,
-  miller_indices: Vec3,
-  distance: number,
-  n_points?: number,
-): SliceResult | null {
-  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: Vec3 = [
-    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: Vec3 = [
-      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/src/lib/isosurface/types.ts

@@ -1,309 +0,0 @@
-// Type definitions and utilities for isosurface visualization (charge density, molecular orbitals, etc.)
-import type { Matrix3x3, Vec3 } from '$lib/math'
-import { scale_lattice_matrix } from '$lib/math'
-import type { ParsedStructure } from '$lib/structure/parse'
-
-// Precomputed statistics for a volumetric grid (min, max, abs_max, mean)
-export interface DataRange {
-  min: number
-  max: number
-  abs_max: number
-  mean: number
-}
-
-// Volumetric scalar data on a 3D grid (e.g. charge density, electrostatic potential)
-export interface VolumetricData {
-  grid: number[][][] // scalar values [nx][ny][nz]
-  grid_dims: Vec3 // [nx, ny, nz]
-  lattice: Matrix3x3 // real-space lattice vectors (rows are a, b, c)
-  origin: Vec3 // grid origin in Cartesian coordinates
-  data_range: DataRange // precomputed min/max/mean statistics
-  // Linearization order of values in the source file.
-  // VASP files are x-fastest; Gaussian .cube is z-fastest.
-  data_order?: `x_fastest` | `z_fastest`
-  // Whether the grid has periodic boundary conditions (affects coordinate scaling).
-  // Periodic grids (CHGCAR) span [0,1) with spacing 1/N; non-periodic (.cube molecular)
-  // span [0,1] with spacing 1/(N-1).
-  periodic: boolean
-  label?: string // e.g. "charge density", "spin density", "orbital"
-}
-
-// Result of parsing a volumetric file (contains both structure and volumetric data)
-export interface VolumetricFileData {
-  structure: ParsedStructure
-  volumes: VolumetricData[] // one or more volumes (e.g. total + magnetization for spin-polarized)
-}
-
-// A single isosurface layer at a specific isovalue with its own appearance
-export interface IsosurfaceLayer {
-  isovalue: number
-  color: string
-  opacity: number
-  visible: boolean
-  // When true, also render the -isovalue surface in `negative_color`
-  show_negative: boolean
-  negative_color: string
-}
-
-// Isosurface rendering settings
-export interface IsosurfaceSettings {
-  isovalue: number
-  opacity: number
-  positive_color: string // color for positive isovalue lobe
-  negative_color: string // color for negative isovalue lobe
-  show_negative: boolean // whether to render the negative lobe (-isovalue)
-  wireframe: boolean
-  halo: number // fraction of cell to extend isosurface beyond boundaries (0 = clip at cell edge, 0.5 = half cell)
-  layers?: IsosurfaceLayer[] // if set, overrides single-isovalue mode
-}
-
-// 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
-] as const
-
-// 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: number[][][]): DataRange {
-  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: number, size: number) => ((val % size) + size) % size
-const clamp_dim = (src: number, fac: number) =>
-  Math.min(src, Math.max(2, Math.ceil(src / fac)))
-const partition_ranges = (n_out: number, n_src: number): [number, number][] =>
-  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: number[][][],
-  dims: Vec3,
-  pad_fraction: number,
-): { grid: number[][][]; dims: Vec3; offset: Vec3 } {
-  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: number[][][] = Array(out_nx)
-  for (let ix = 0; ix < out_nx; ix++) {
-    const plane: number[][] = Array(out_ny)
-    const src_x = wrap_grid_idx(ix - px, nx)
-    for (let iy = 0; iy < out_ny; iy++) {
-      const row: number[] = 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: Vec3 = [-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: number[][][],
-  dims: Vec3,
-  max_points: number = MAX_GRID_POINTS,
-): { grid: number[][][]; dims: Vec3; factor: number } {
-  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: number[][][] = Array(new_nx)
-  for (let ix = 0; ix < new_nx; ix++) {
-    const plane: number[][] = Array(new_ny)
-    const [sx_start, sx_end] = x_ranges[ix]
-    for (let iy = 0; iy < new_ny; iy++) {
-      const row: number[] = 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: IsosurfaceSettings = {
-  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: DataRange): IsosurfaceSettings {
-  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: DataRange, n_layers: number): IsosurfaceLayer[] {
-  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: VolumetricData, scaling: Vec3): VolumetricData {
-  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: number[][][] = Array(new_nx)
-  for (let ix = 0; ix < new_nx; ix++) {
-    const plane: number[][] = Array(new_ny)
-    const src_x = ix % nx
-    for (let iy = 0; iy < new_ny; iy++) {
-      const row: number[] = 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),
-  }
-}