matterviz 0.4.1 → 0.4.3

package/dist/isosurface/IsosurfaceControls.svelte.d.ts

@@ -4,6 +4,6 @@ type $$ComponentProps = {
     volumes?: VolumetricData[];
     active_volume_idx?: number;
 };
-declare const IsosurfaceControls: import("svelte").Component<$$ComponentProps, {}, "settings" | "active_volume_idx">;
+declare const IsosurfaceControls: import("svelte").Component<$$ComponentProps, {}, "volumes" | "settings" | "active_volume_idx">;
 type IsosurfaceControls = ReturnType<typeof IsosurfaceControls>;
 export default IsosurfaceControls;

package/dist/isosurface/VolumeSlice.svelte

@@ -0,0 +1,224 @@
+<script lang="ts">
+  import { get_d3_interpolator, type D3InterpolateName } from '../colors'
+  import type { Vec2 } from '../math'
+  import ColorBar from '../plot/core/components/ColorBar.svelte'
+  import { contours as create_contours } from 'd3-contour'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import type { SliceResult } from './slice'
+  import {
+    resolve_contour_thresholds,
+    resolve_slice_color_range,
+    slice_to_rgba,
+    type VolumeSliceMode,
+  } from './slice-rendering'
+
+  let {
+    slice,
+    mode = `both`,
+    colormap = `interpolateRdBu`,
+    color_range,
+    symmetric = `auto`,
+    contour_levels = 10,
+    contour_color = `currentColor`,
+    contour_width = 1,
+    flip_y = true,
+    show_colorbar = true,
+    colorbar_title = `Value`,
+    canvas = $bindable(),
+    onrender,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    slice?: SliceResult | null
+    mode?: VolumeSliceMode
+    colormap?: D3InterpolateName
+    color_range?: Vec2
+    symmetric?: boolean | `auto`
+    contour_levels?: number | number[]
+    contour_color?: string
+    contour_width?: number
+    flip_y?: boolean
+    show_colorbar?: boolean
+    colorbar_title?: string
+    canvas?: HTMLCanvasElement
+    onrender?: (detail: {
+      canvas: HTMLCanvasElement
+      color_range: Vec2
+      contour_thresholds: number[]
+      slice: SliceResult
+    }) => void
+  } = $props()
+
+  let resolved_color_range = $derived<Vec2>(
+    slice ? resolve_slice_color_range(slice, color_range, symmetric) : [0, 1],
+  )
+  let contour_thresholds = $derived(
+    resolve_contour_thresholds(resolved_color_range, contour_levels),
+  )
+  let colorbar_color_scale = $derived.by(() => {
+    const interpolator = get_d3_interpolator(colormap)
+    const [range_start, range_end] = resolved_color_range
+    const span = range_end - range_start
+    return (value: number): string => {
+      const normalized =
+        span === 0 ? 0.5 : Math.max(0, Math.min(1, (value - range_start) / span))
+      return interpolator(normalized)
+    }
+  })
+  let image_data: ImageData | undefined
+  let contour_values = new Float64Array()
+  let aspect_ratio = $derived.by(() => {
+    if (!slice) return 1
+    const u_span = slice.u_range[1] - slice.u_range[0]
+    const v_span = slice.v_range[1] - slice.v_range[0]
+    return v_span > 0 ? u_span / v_span : 1
+  })
+
+  function clip_to_slice_polygon(
+    context: CanvasRenderingContext2D,
+    current_slice: SliceResult,
+  ): void {
+    const u_span = current_slice.u_range[1] - current_slice.u_range[0]
+    const v_span = current_slice.v_range[1] - current_slice.v_range[0]
+    context.beginPath()
+    for (let point_idx = 0; point_idx < current_slice.polygon.length; point_idx++) {
+      const point = current_slice.polygon[point_idx]
+      const pixel_x =
+        ((point[0] - current_slice.u_range[0]) / u_span) * (current_slice.width - 1) + 0.5
+      const sampled_y =
+        ((point[1] - current_slice.v_range[0]) / v_span) * (current_slice.height - 1) + 0.5
+      const pixel_y = flip_y ? current_slice.height - sampled_y : sampled_y
+      if (point_idx === 0) context.moveTo(pixel_x, pixel_y)
+      else context.lineTo(pixel_x, pixel_y)
+    }
+    context.closePath()
+    context.clip()
+  }
+
+  function draw_contours(context: CanvasRenderingContext2D, current_slice: SliceResult): void {
+    if (contour_thresholds.length === 0) return
+    const threshold_min = contour_thresholds[0]
+    const outside_value =
+      Math.min(...resolved_color_range, threshold_min) -
+      Math.max(
+        1,
+        Math.abs(threshold_min),
+        Math.abs(resolved_color_range[1] - resolved_color_range[0]),
+      )
+    if (contour_values.length !== current_slice.data.length) {
+      contour_values = new Float64Array(current_slice.data.length)
+    }
+    for (let data_idx = 0; data_idx < current_slice.data.length; data_idx++) {
+      const value = current_slice.data[data_idx]
+      contour_values[data_idx] =
+        current_slice.mask[data_idx] && Number.isFinite(value) ? value : outside_value
+    }
+    const shapes = create_contours()
+      .size([current_slice.width, current_slice.height])
+      .thresholds(contour_thresholds)(contour_values as unknown as number[])
+
+    context.save()
+    clip_to_slice_polygon(context, current_slice)
+    context.strokeStyle =
+      contour_color === `currentColor` && canvas
+        ? getComputedStyle(canvas).color
+        : contour_color
+    context.lineWidth = Math.max(0.1, contour_width)
+    context.lineJoin = `round`
+    for (const shape of shapes) {
+      context.beginPath()
+      for (const polygon of shape.coordinates) {
+        for (const ring of polygon) {
+          for (let point_idx = 0; point_idx < ring.length; point_idx++) {
+            const [point_x, sampled_y] = ring[point_idx]
+            const point_y = flip_y ? current_slice.height - sampled_y : sampled_y
+            if (point_idx === 0) context.moveTo(point_x, point_y)
+            else context.lineTo(point_x, point_y)
+          }
+          context.closePath()
+        }
+      }
+      context.stroke()
+    }
+    context.restore()
+  }
+
+  function render_slice(): void {
+    if (!canvas) return
+    if (!slice) {
+      canvas.getContext(`2d`)?.clearRect(0, 0, canvas.width, canvas.height)
+      image_data = undefined
+      return
+    }
+    canvas.width = slice.width
+    canvas.height = slice.height
+    const context = canvas.getContext(`2d`)
+    if (!context) return
+    context.clearRect(0, 0, slice.width, slice.height)
+    if (mode !== `contours`) {
+      if (image_data?.width !== slice.width || image_data?.height !== slice.height) {
+        image_data = context.createImageData(slice.width, slice.height)
+      }
+      slice_to_rgba(slice, colormap, resolved_color_range, {
+        flip_y,
+        out: image_data.data,
+      })
+      context.putImageData(image_data, 0, 0)
+    }
+    if (mode !== `filled`) draw_contours(context, slice)
+    onrender?.({
+      canvas,
+      color_range: resolved_color_range,
+      contour_thresholds,
+      slice,
+    })
+  }
+
+  $effect(render_slice)
+</script>
+
+<div {...rest} class={[`volume-slice`, rest.class]}>
+  <div class="canvas-wrapper">
+    <canvas
+      bind:this={canvas}
+      aria-label="Volumetric scalar-field slice"
+      style:aspect-ratio={aspect_ratio}
+    ></canvas>
+  </div>
+  {#if show_colorbar && slice}
+    <ColorBar
+      title={colorbar_title}
+      color_scale={colormap}
+      color_scale_fn={colorbar_color_scale}
+      color_scale_domain={resolved_color_range}
+      range={resolved_color_range}
+      tick_labels={5}
+      bar_style="width: 100%"
+      wrapper_style="width: 100%"
+      --cbar-font-size="0.75em"
+      --cbar-tick-label-font-weight="normal"
+    />
+  {/if}
+</div>
+
+<style>
+  .volume-slice {
+    display: grid;
+    gap: 0.5rem;
+    width: 100%;
+  }
+  .canvas-wrapper {
+    display: grid;
+    place-items: center;
+    min-width: 0;
+  }
+  canvas {
+    display: block;
+    width: min(100%, var(--volume-slice-max-width, 600px));
+    height: auto;
+    max-height: var(--volume-slice-max-height, 600px);
+    color: var(--volume-slice-contour-color, currentColor);
+    outline: 1px solid var(--border-color, #ccc);
+    border-radius: 4px;
+    image-rendering: auto;
+  }
+</style>

package/dist/isosurface/VolumeSlice.svelte.d.ts

@@ -0,0 +1,28 @@
+import { type D3InterpolateName } from '../colors';
+import type { Vec2 } from '../math';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { SliceResult } from './slice';
+import { type VolumeSliceMode } from './slice-rendering';
+type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
+    slice?: SliceResult | null;
+    mode?: VolumeSliceMode;
+    colormap?: D3InterpolateName;
+    color_range?: Vec2;
+    symmetric?: boolean | `auto`;
+    contour_levels?: number | number[];
+    contour_color?: string;
+    contour_width?: number;
+    flip_y?: boolean;
+    show_colorbar?: boolean;
+    colorbar_title?: string;
+    canvas?: HTMLCanvasElement;
+    onrender?: (detail: {
+        canvas: HTMLCanvasElement;
+        color_range: Vec2;
+        contour_thresholds: number[];
+        slice: SliceResult;
+    }) => void;
+};
+declare const VolumeSlice: import("svelte").Component<$$ComponentProps, {}, "canvas">;
+type VolumeSlice = ReturnType<typeof VolumeSlice>;
+export default VolumeSlice;

package/dist/isosurface/coloring.d.ts

@@ -0,0 +1,20 @@
+import type { D3InterpolateName } from '../colors';
+import type { Vec2 } from '../math';
+import type { DataRange } from './types';
+export declare const ISO_COLORMAPS: readonly ["interpolateViridis", "interpolatePlasma", "interpolateInferno", "interpolateMagma", "interpolateCividis", "interpolateTurbo", "interpolateRdBu", "interpolateRdYlBu", "interpolateSpectral", "interpolatePiYG", "interpolateBrBG", "interpolatePuOr"];
+export type IsoColormap = (typeof ISO_COLORMAPS)[number];
+export declare const DEFAULT_ISO_COLORMAP: IsoColormap;
+export declare const is_signed_range: (data_range: DataRange) => boolean;
+export interface VertexColorOptions {
+    colormap: D3InterpolateName;
+    color_range: Vec2;
+    fallback_color?: string;
+}
+export declare function scalars_to_vertex_colors(scalars: Float32Array, { colormap, color_range, fallback_color }: VertexColorOptions, out?: Float32Array): Float32Array;
+export declare function auto_color_config(data_range: DataRange): {
+    colormap: IsoColormap;
+    color_range: Vec2;
+};
+export declare function compute_scalar_range(scalar_arrays: Float32Array[], { symmetric }?: {
+    symmetric?: boolean;
+}): Vec2;

package/dist/isosurface/coloring.js

@@ -0,0 +1,118 @@
+import { get_d3_interpolator } from '../colors';
+import { Color } from 'three';
+// Curated continuous colormaps offered in the isosurface controls UI.
+// Sequential maps for densities/potential magnitudes, diverging for signed fields.
+export const ISO_COLORMAPS = [
+    `interpolateViridis`,
+    `interpolatePlasma`,
+    `interpolateInferno`,
+    `interpolateMagma`,
+    `interpolateCividis`,
+    `interpolateTurbo`,
+    `interpolateRdBu`,
+    `interpolateRdYlBu`,
+    `interpolateSpectral`,
+    `interpolatePiYG`,
+    `interpolateBrBG`,
+    `interpolatePuOr`,
+];
+export const DEFAULT_ISO_COLORMAP = `interpolateViridis`;
+// A field counts as signed when it has significant values of both signs
+// (e.g. ESP, magnetization, orbitals) — drives diverging-colormap defaults.
+export const is_signed_range = (data_range) => data_range.min < -data_range.abs_max * 0.01 && data_range.max > data_range.abs_max * 0.01;
+const LUT_SIZE = 256;
+// LUTs cached per colormap name — building one parses 256 CSS color strings.
+// Private so the mutable cached arrays cannot be corrupted by consumers.
+const lut_cache = new Map();
+// Parse a CSS color to linear-space RGB via Three.js (vertex color attributes
+// are interpreted as Linear-sRGB by the renderer, so sRGB values from d3 must
+// be converted or surfaces render too bright)
+const scratch_color = new Color();
+const parse_linear_rgb = (css_color) => {
+    scratch_color.set(css_color);
+    return [scratch_color.r, scratch_color.g, scratch_color.b];
+};
+function get_colormap_lut(colormap) {
+    const cached = lut_cache.get(colormap);
+    if (cached)
+        return cached;
+    const interpolator = get_d3_interpolator(colormap);
+    const lut = new Float32Array(LUT_SIZE * 3);
+    for (let idx = 0; idx < LUT_SIZE; idx++) {
+        const [red, green, blue] = parse_linear_rgb(interpolator(idx / (LUT_SIZE - 1)));
+        lut[idx * 3] = red;
+        lut[idx * 3 + 1] = green;
+        lut[idx * 3 + 2] = blue;
+    }
+    lut_cache.set(colormap, lut);
+    return lut;
+}
+// Map per-vertex scalars to a flat linear-RGB Float32Array (3 components per
+// vertex) suitable for a Three.js 'color' BufferAttribute. Values outside
+// color_range clamp to the ends of the colormap; non-finite values get
+// fallback_color. Pass an existing array of the right size to fill in place
+// (avoids reallocating GPU-bound buffers on recolor).
+export function scalars_to_vertex_colors(scalars, { colormap, color_range, fallback_color = `#808080` }, out) {
+    const lut = get_colormap_lut(colormap);
+    const [range_min, range_max] = color_range;
+    const span = range_max - range_min;
+    const inv_span = span !== 0 ? 1 / span : 0;
+    const [fb_r, fb_g, fb_b] = parse_linear_rgb(fallback_color);
+    const colors = out?.length === scalars.length * 3 ? out : new Float32Array(scalars.length * 3);
+    for (let idx = 0; idx < scalars.length; idx++) {
+        const value = scalars[idx];
+        if (!Number.isFinite(value)) {
+            colors[idx * 3] = fb_r;
+            colors[idx * 3 + 1] = fb_g;
+            colors[idx * 3 + 2] = fb_b;
+            continue;
+        }
+        // span === 0 maps everything to the middle of the colormap
+        const normalized = span === 0 ? 0.5 : (value - range_min) * inv_span;
+        const clamped = normalized < 0 ? 0 : Math.min(1, normalized);
+        const lut_idx = Math.round(clamped * (LUT_SIZE - 1)) * 3;
+        colors[idx * 3] = lut[lut_idx];
+        colors[idx * 3 + 1] = lut[lut_idx + 1];
+        colors[idx * 3 + 2] = lut[lut_idx + 2];
+    }
+    return colors;
+}
+// Suggest a colormap and value range for coloring by a volume with the given
+// data range: signed fields (e.g. ESP, magnetization) get a diverging RdBu map
+// with a symmetric range about zero; non-negative fields get Viridis over [min, max].
+export function auto_color_config(data_range) {
+    const { min, max, abs_max } = data_range;
+    if (is_signed_range(data_range)) {
+        // RdBu with symmetric range: negative → red, positive → blue (ESP convention)
+        return { colormap: `interpolateRdBu`, color_range: [-abs_max, abs_max] };
+    }
+    return { colormap: DEFAULT_ISO_COLORMAP, color_range: [min, max] };
+}
+// Fit a color range to the scalar values actually present on the surface(s),
+// ignoring non-finite (out-of-bounds) markers. This is the default when a layer
+// has no explicit color_range: the whole-volume range is usually dominated by
+// extreme values near nuclei that never appear on the rendered surface.
+// `symmetric` (pass when the source field is signed) forces a range symmetric
+// about zero even when the sampled values happen to be one-signed, so diverging
+// colormaps keep zero at their center.
+export function compute_scalar_range(scalar_arrays, { symmetric = false } = {}) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const scalars of scalar_arrays) {
+        for (const value of scalars) {
+            if (!Number.isFinite(value))
+                continue;
+            if (value < min)
+                min = value;
+            if (value > max)
+                max = value;
+        }
+    }
+    if (min === Infinity)
+        return [0, 1]; // no finite samples
+    if (symmetric || (min < 0 && max > 0)) {
+        const abs_max = Math.max(Math.abs(min), Math.abs(max));
+        return [-abs_max, abs_max];
+    }
+    return [min, max];
+}

package/dist/isosurface/geometry-worker-types.d.ts

@@ -0,0 +1,38 @@
+import type { Matrix3x3, Vec3 } from '../math';
+import type { DisplayRange } from './sampling';
+import type { VolumetricData } from './types';
+export type TransferableVolume = Pick<VolumetricData, `grid_dims` | `lattice` | `origin` | `periodic`> & {
+    grid_values: Float64Array;
+};
+export interface GeometryWorkerRequest {
+    volumes: {
+        token: number;
+        volume: TransferableVolume;
+        range: DisplayRange | null;
+        reference_origin: Vec3;
+        surfaces: {
+            token: string;
+            isovalue: number;
+        }[];
+    }[];
+}
+interface GeometryWorkerVolumeResult {
+    token: number;
+    grid_dims: Vec3;
+    lattice: Matrix3x3;
+    origin: Vec3;
+    prepared_values: Float64Array;
+    prepare_geometry_ms: number;
+    surfaces: {
+        token: string;
+        positions: Float32Array;
+        indices: Uint32Array;
+        marching_cubes_ms: number;
+    }[];
+}
+export type GeometryWorkerResponse = {
+    volumes: GeometryWorkerVolumeResult[];
+} | {
+    error: string;
+};
+export {};

package/dist/isosurface/geometry.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/isosurface/geometry.worker.js

@@ -0,0 +1,59 @@
+import { marching_cubes_buffers } from '../marching-cubes';
+import { flatten_grid, inflate_grid } from './grid';
+import { prepare_geometry_grid } from './sampling';
+const worker_scope = globalThis;
+const inflate_volume = ({ grid_values, ...metadata }) => ({
+    ...metadata,
+    grid: inflate_grid(grid_values, metadata.grid_dims),
+    data_range: { min: 0, max: 0, mean: 0, abs_max: 0 },
+});
+worker_scope.addEventListener(`message`, ({ data: request }) => {
+    try {
+        const transfer = [];
+        const volume_results = [];
+        for (const job of request.volumes) {
+            const prepare_start = performance.now();
+            const volume = inflate_volume(job.volume);
+            const { grid, lattice, origin } = prepare_geometry_grid(volume, job.range);
+            const { values: prepared_values, dims: grid_dims } = flatten_grid(grid);
+            transfer.push(prepared_values.buffer);
+            const prepare_geometry_ms = performance.now() - prepare_start;
+            const surfaces = job.surfaces.map(({ token, isovalue }) => {
+                const marching_start = performance.now();
+                const buffers = marching_cubes_buffers(grid, isovalue, lattice, {
+                    periodic: false,
+                    interpolate: true,
+                    centered: false,
+                    normals: false,
+                    position_offset: [
+                        origin[0] - job.reference_origin[0],
+                        origin[1] - job.reference_origin[1],
+                        origin[2] - job.reference_origin[2],
+                    ],
+                });
+                transfer.push(buffers.positions.buffer, buffers.indices.buffer);
+                return {
+                    token,
+                    positions: buffers.positions,
+                    indices: buffers.indices,
+                    marching_cubes_ms: performance.now() - marching_start,
+                };
+            });
+            volume_results.push({
+                token: job.token,
+                grid_dims,
+                lattice,
+                origin,
+                prepared_values,
+                prepare_geometry_ms,
+                surfaces,
+            });
+        }
+        worker_scope.postMessage({ volumes: volume_results }, transfer);
+    }
+    catch (error) {
+        worker_scope.postMessage({
+            error: error instanceof Error ? error.message : String(error),
+        }, []);
+    }
+});

package/dist/isosurface/grid.d.ts

@@ -0,0 +1,10 @@
+import type { Vec3 } from '../math';
+interface FlatGrid3D {
+    values: Float64Array;
+    dims: Vec3;
+}
+export declare const grid_dimensions: (grid: number[][][]) => Vec3;
+export declare const grid_point_count: (grid: number[][][]) => number;
+export declare function flatten_grid(grid: number[][][]): FlatGrid3D;
+export declare function inflate_grid(values: Float64Array, [nx, ny, nz]: Vec3): number[][][];
+export {};

package/dist/isosurface/grid.js

@@ -0,0 +1,31 @@
+export const grid_dimensions = (grid) => [
+    grid.length,
+    grid[0]?.length ?? 0,
+    grid[0]?.[0]?.length ?? 0,
+];
+export const grid_point_count = (grid) => grid_dimensions(grid).reduce((product, count) => product * count, 1);
+export function flatten_grid(grid) {
+    const dims = grid_dimensions(grid);
+    const values = new Float64Array(dims[0] * dims[1] * dims[2]);
+    let offset = 0;
+    for (const plane of grid) {
+        for (const row of plane) {
+            values.set(row, offset);
+            offset += row.length;
+        }
+    }
+    return { values, dims };
+}
+export function inflate_grid(values, [nx, ny, nz]) {
+    const grid = Array(nx);
+    let offset = 0;
+    for (let x_idx = 0; x_idx < nx; x_idx++) {
+        const plane = Array(ny);
+        for (let y_idx = 0; y_idx < ny; y_idx++) {
+            plane[y_idx] = Array.from(values.subarray(offset, offset + nz));
+            offset += nz;
+        }
+        grid[x_idx] = plane;
+    }
+    return grid;
+}

package/dist/isosurface/index.d.ts

@@ -1,5 +1,9 @@
 export { default as Isosurface } from './Isosurface.svelte';
 export { default as IsosurfaceControls } from './IsosurfaceControls.svelte';
+export { default as VolumeSlice } from './VolumeSlice.svelte';
+export * from './coloring';
 export * from './parse';
+export * from './sampling';
 export * from './slice';
+export * from './slice-rendering';
 export * from './types';

package/dist/isosurface/index.js

@@ -1,6 +1,10 @@
 // Isosurface visualization module for volumetric data (CHGCAR, .cube files)
 export { default as Isosurface } from './Isosurface.svelte';
 export { default as IsosurfaceControls } from './IsosurfaceControls.svelte';
+export { default as VolumeSlice } from './VolumeSlice.svelte';
+export * from './coloring';
 export * from './parse';
+export * from './sampling';
 export * from './slice';
+export * from './slice-rendering';
 export * from './types';

package/dist/isosurface/parse-vaspwave.d.ts

@@ -0,0 +1,3 @@
+import type { VolumetricFileData } from './types';
+export declare const is_vaspwave_filename: (filename: string) => boolean;
+export declare function parse_vaspwave_charge(buffer: ArrayBuffer, filename?: string): Promise<VolumetricFileData>;