matterviz 0.3.5 → 0.3.6

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

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

@@ -0,0 +1,309 @@
+// 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),
+  }
+}