matterviz 0.3.0 → 0.3.2

package/dist/isosurface/Isosurface.svelte

@@ -0,0 +1,231 @@
+<script lang="ts">// Threlte component that renders isosurface meshes from volumetric data using marching cubes.
+// Supports multiple layers at different isovalues with independent colors,
+// plus positive/negative lobes and two-pass transparency.
+import { marching_cubes } from '../marching-cubes';
+import { T } from '@threlte/core';
+import { BackSide, BufferAttribute, BufferGeometry, DoubleSide, FrontSide, Uint32BufferAttribute, } from 'three';
+import { DEFAULT_ISOSURFACE_SETTINGS, downsample_grid, pad_periodic_grid, } from './types';
+let { volume, settings = DEFAULT_ISOSURFACE_SETTINGS, } = $props();
+// Resolve layers: use explicit layers array if provided, else build from single-isovalue settings
+let resolved_layers = $derived.by(() => {
+    if (settings.layers?.length)
+        return settings.layers;
+    return [{
+            isovalue: settings.isovalue,
+            color: settings.positive_color,
+            opacity: settings.opacity,
+            visible: true,
+            show_negative: settings.show_negative,
+            negative_color: settings.negative_color,
+        }];
+});
+// Build indexed BufferGeometry from marching cubes output.
+// Uses Three.js index buffer to avoid tripling vertex data, and
+// computeVertexNormals() for fast GPU-friendly normals.
+function build_geometry(vertices, faces) {
+    if (vertices.length === 0 || faces.length === 0)
+        return null;
+    // Flatten vertices: Vec3[] → Float32Array
+    const positions = new Float32Array(vertices.length * 3);
+    for (let idx = 0; idx < vertices.length; idx++) {
+        const vert = vertices[idx];
+        positions[idx * 3] = vert[0];
+        positions[idx * 3 + 1] = vert[1];
+        positions[idx * 3 + 2] = vert[2];
+    }
+    // Flatten face indices: number[][] → Uint32Array
+    const indices = new Uint32Array(faces.length * 3);
+    for (let idx = 0; idx < faces.length; idx++) {
+        const face = faces[idx];
+        indices[idx * 3] = face[0];
+        indices[idx * 3 + 1] = face[1];
+        indices[idx * 3 + 2] = face[2];
+    }
+    const geometry = new BufferGeometry();
+    geometry.setAttribute(`position`, new BufferAttribute(positions, 3));
+    geometry.setIndex(new Uint32BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+    return geometry;
+}
+// Downsample large grids once when volume changes to keep marching cubes interactive
+let ds_result = $derived.by(() => {
+    if (!volume)
+        return undefined;
+    return downsample_grid(volume.grid, volume.grid_dims);
+});
+// Run marching cubes at the given isovalue with pre-prepared grid/lattice/shift.
+function extract_surface(isovalue, mc_grid, mc_lattice, origin_shift) {
+    if (isovalue === 0)
+        return null;
+    const result = marching_cubes(mc_grid, isovalue, mc_lattice, {
+        periodic: false,
+        interpolate: true,
+        centered: false,
+        normals: false,
+    });
+    if (origin_shift) {
+        for (const vert of result.vertices) {
+            vert[0] += origin_shift[0];
+            vert[1] += origin_shift[1];
+            vert[2] += origin_shift[2];
+        }
+    }
+    return build_geometry(result.vertices, result.faces);
+}
+let active_geometries = $state([]);
+let raf_id = 0;
+let debounce_id = 0;
+// Dispose all current geometries
+function dispose_all() {
+    for (const entry of active_geometries)
+        entry.geometry.dispose();
+    active_geometries = [];
+}
+// Dispose on unmount
+$effect(() => () => dispose_all());
+function rebuild_geometries(layers) {
+    if (!volume || !ds_result)
+        return;
+    const old = active_geometries;
+    const entries = [];
+    // Prepare grid/lattice/shift once for all layers.
+    // When halo > 0 for periodic volumes, the downsampled grid is padded with
+    // halo cells from the opposite face so isosurfaces extend beyond the unit
+    // cell and close into complete enclosed shapes around boundary atoms.
+    let mc_grid = ds_result.grid;
+    let mc_lattice = volume.lattice;
+    let origin_shift = null;
+    if (settings.halo > 0 && volume.periodic) {
+        const padded = pad_periodic_grid(ds_result.grid, ds_result.dims, settings.halo);
+        mc_grid = padded.grid;
+        // marching_cubes maps [0,1] fractional -> Cartesian via lattice.
+        // The padded grid covers a wider fractional range, so scale the lattice
+        // to match. Then shift all vertices by the fractional offset.
+        const [la, lb, lc] = volume.lattice;
+        const sx = padded.dims[0] / ds_result.dims[0];
+        const sy = padded.dims[1] / ds_result.dims[1];
+        const sz = padded.dims[2] / ds_result.dims[2];
+        mc_lattice = [
+            [la[0] * sx, la[1] * sx, la[2] * sx],
+            [lb[0] * sy, lb[1] * sy, lb[2] * sy],
+            [lc[0] * sz, lc[1] * sz, lc[2] * sz],
+        ];
+        const [ox, oy, oz] = padded.offset;
+        origin_shift = [
+            ox * la[0] + oy * lb[0] + oz * lc[0],
+            ox * la[1] + oy * lb[1] + oz * lc[1],
+            ox * la[2] + oy * lb[2] + oz * lc[2],
+        ];
+    }
+    const surface_at = (isovalue) => extract_surface(isovalue, mc_grid, mc_lattice, origin_shift);
+    // Render lower-isovalue (outer) shells earlier so per-layer back/front passes
+    // interleave back-to-front across shells and reduce transparency artefacts.
+    const layer_render_rank = new Map(layers
+        .map((layer, layer_idx) => ({ layer_idx, isovalue: layer.isovalue }))
+        .sort((layer_a, layer_b) => layer_a.isovalue - layer_b.isovalue)
+        .map(({ layer_idx }, rank) => [layer_idx, rank]));
+    for (let layer_idx = 0; layer_idx < layers.length; layer_idx++) {
+        const layer = layers[layer_idx];
+        if (!layer.visible || layer.isovalue <= 0)
+            continue;
+        // Each layer gets 4 slots (positive back/front + negative back/front).
+        const base_order = (layer_render_rank.get(layer_idx) ?? layer_idx) * 4;
+        const pos_geo = surface_at(layer.isovalue);
+        if (pos_geo) {
+            entries.push({
+                geometry: pos_geo,
+                color: layer.color,
+                opacity: layer.opacity,
+                render_order: base_order,
+            });
+        }
+        if (layer.show_negative) {
+            const neg_geo = surface_at(-layer.isovalue);
+            if (neg_geo) {
+                entries.push({
+                    geometry: neg_geo,
+                    color: layer.negative_color,
+                    opacity: layer.opacity,
+                    render_order: base_order + 2,
+                });
+            }
+        }
+    }
+    active_geometries = entries;
+    for (const entry of old)
+        entry.geometry.dispose();
+}
+// Rebuild all layer geometries when layers or volume change.
+// Debounces rapid changes (e.g. slider drags) to avoid repeated expensive marching cubes.
+$effect(() => {
+    const layers = resolved_layers;
+    void settings.halo;
+    if (!ds_result) {
+        dispose_all();
+        return;
+    }
+    debounce_id = window.setTimeout(() => {
+        raf_id = requestAnimationFrame(() => rebuild_geometries(layers));
+    }, 50);
+    return () => {
+        clearTimeout(debounce_id);
+        cancelAnimationFrame(raf_id);
+    };
+});
+</script>
+
+<!-- Render each geometry entry with appropriate material -->
+{#each active_geometries as entry (entry)}
+  {#if settings.wireframe}
+    <T.Mesh geometry={entry.geometry} frustumCulled={false}>
+      <T.MeshBasicMaterial
+        color={entry.color}
+        wireframe
+        transparent={entry.opacity < 1}
+        opacity={entry.opacity}
+      />
+    </T.Mesh>
+  {:else if entry.opacity < 1}
+    <!-- Two-pass rendering for correct transparency -->
+    <T.Mesh
+      geometry={entry.geometry}
+      renderOrder={entry.render_order}
+      frustumCulled={false}
+    >
+      <T.MeshStandardMaterial
+        color={entry.color}
+        transparent
+        opacity={entry.opacity}
+        side={BackSide}
+        depthWrite={false}
+        metalness={0.1}
+        roughness={0.6}
+      />
+    </T.Mesh>
+    <T.Mesh
+      geometry={entry.geometry}
+      renderOrder={entry.render_order + 1}
+      frustumCulled={false}
+    >
+      <T.MeshStandardMaterial
+        color={entry.color}
+        transparent
+        opacity={entry.opacity}
+        side={FrontSide}
+        depthWrite={false}
+        metalness={0.1}
+        roughness={0.6}
+      />
+    </T.Mesh>
+  {:else}
+    <T.Mesh geometry={entry.geometry} frustumCulled={false}>
+      <T.MeshStandardMaterial
+        color={entry.color}
+        side={DoubleSide}
+        metalness={0.1}
+        roughness={0.6}
+      />
+    </T.Mesh>
+  {/if}
+{/each}

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

@@ -0,0 +1,8 @@
+import type { IsosurfaceSettings, VolumetricData } from './types';
+type $$ComponentProps = {
+    volume: VolumetricData;
+    settings?: IsosurfaceSettings;
+};
+declare const Isosurface: import("svelte").Component<$$ComponentProps, {}, "">;
+type Isosurface = ReturnType<typeof Isosurface>;
+export default Isosurface;

package/dist/isosurface/IsosurfaceControls.svelte

@@ -0,0 +1,273 @@
+<script lang="ts">// Controls panel for isosurface visualization settings (isovalue, opacity, colors, etc.)
+// Supports both single-isovalue mode and multi-layer mode.
+import { format_num } from '../labels';
+import { SettingsSection } from '../layout';
+import { tooltip } from 'svelte-multiselect/attachments';
+import { DEFAULT_ISOSURFACE_SETTINGS, generate_layers } from './types';
+let { settings = $bindable({ ...DEFAULT_ISOSURFACE_SETTINGS }), volumes = [], active_volume_idx = $bindable(0), } = $props();
+// Clamp active_volume_idx when volumes list changes (e.g. dataset swap)
+$effect(() => {
+    if (volumes.length > 0 && active_volume_idx >= volumes.length) {
+        active_volume_idx = 0;
+    }
+});
+// Use precomputed data_range from the active volume
+let data_range = $derived(volumes[active_volume_idx]?.data_range ?? { min: 0, max: 1, abs_max: 1, mean: 0 });
+let slider_max = $derived(Math.max(data_range.abs_max, 0.001));
+let step = $derived(slider_max / 200);
+let is_multi_layer = $derived((settings.layers?.length ?? 0) > 0);
+let n_layers = $derived(settings.layers?.length ?? 1);
+function set_layer_count(count) {
+    if (count <= 1) {
+        settings.layers = undefined;
+    }
+    else {
+        settings.layers = generate_layers(data_range, count);
+    }
+}
+function update_layer(idx, updates) {
+    if (!settings.layers)
+        return;
+    settings.layers = settings.layers.map((layer, layer_idx) => layer_idx === idx ? { ...layer, ...updates } : layer);
+}
+</script>
+
+<SettingsSection
+  title="Isosurface"
+  current_values={{
+    isovalue: settings.isovalue,
+    opacity: settings.opacity,
+    show_negative: settings.show_negative,
+    wireframe: settings.wireframe,
+    halo: settings.halo,
+    layers: n_layers,
+  }}
+  on_reset={() => {
+    settings = { ...DEFAULT_ISOSURFACE_SETTINGS }
+  }}
+>
+  <!-- Top row: volume selector (if multi-volume) + layer count + toggles -->
+  <div class="pane-row compact-row">
+    {#if volumes.length > 1}
+      <label
+        {@attach tooltip({
+          content: `Select which volume to display (e.g. charge vs magnetization)`,
+        })}
+      >
+        <span>Volume:</span>
+        <select bind:value={active_volume_idx}>
+          {#each volumes as vol, idx (idx)}
+            <option value={idx}>{vol.label ?? `Volume ${idx + 1}`}</option>
+          {/each}
+        </select>
+      </label>
+    {/if}
+    <label
+      {@attach tooltip({
+        content: `Number of isosurface shells at different density thresholds`,
+      })}
+    >
+      <span>Layers:</span>
+      <select
+        value={n_layers}
+        onchange={(event) =>
+        set_layer_count(Number((event.target as HTMLSelectElement).value))}
+      >
+        {#each [1, 2, 3, 4, 5] as count (count)}
+          <option value={count}>{count}</option>
+        {/each}
+      </select>
+    </label>
+    <!-- Sync both settings.show_negative (single-layer fallback) and all layer entries
+    so the toggle works consistently regardless of which mode is active -->
+    <label
+      {@attach tooltip({
+        content:
+          `Show negative lobe at −isovalue (for orbitals, ESP, magnetization)`,
+      })}
+    >
+      <span>Neg. lobe</span>
+      <input
+        type="checkbox"
+        checked={is_multi_layer
+        ? settings.layers?.some((layer) => layer.show_negative) ?? false
+        : settings.show_negative}
+        onchange={(event) => {
+          const checked = (event.target as HTMLInputElement).checked
+          settings.show_negative = checked
+          if (settings.layers) {
+            settings.layers = settings.layers.map((layer) => ({
+              ...layer,
+              show_negative: checked,
+            }))
+          }
+        }}
+      />
+    </label>
+    <label
+      {@attach tooltip({ content: `Render as wireframe mesh instead of solid surface` })}
+    >
+      <span>Wireframe</span>
+      <input type="checkbox" bind:checked={settings.wireframe} />
+    </label>
+  </div>
+
+  {#if is_multi_layer && settings.layers}
+    <!-- Multi-layer controls: each row has visibility, color, isovalue slider, opacity -->
+    {#each settings.layers as layer, idx (idx)}
+      <div class="layer-row">
+        <input
+          type="checkbox"
+          checked={layer.visible}
+          onchange={() => update_layer(idx, { visible: !layer.visible })}
+        />
+        <input
+          type="color"
+          value={layer.color}
+          onchange={(event) =>
+          update_layer(idx, { color: (event.target as HTMLInputElement).value })}
+        />
+        <input
+          type="range"
+          min={step}
+          max={slider_max}
+          {step}
+          value={layer.isovalue}
+          oninput={(event) =>
+          update_layer(idx, {
+            isovalue: Number((event.target as HTMLInputElement).value),
+          })}
+          style="flex: 1; min-width: 60px"
+        />
+        <span class="layer-value">{format_num(layer.isovalue, `.3~g`)}</span>
+        <input
+          type="range"
+          min={0.1}
+          max={1}
+          step={0.05}
+          value={layer.opacity}
+          oninput={(event) =>
+          update_layer(idx, {
+            opacity: Number((event.target as HTMLInputElement).value),
+          })}
+          style="width: 50px"
+          title="Opacity: {format_num(layer.opacity, `.2f`)}"
+        />
+      </div>
+    {/each}
+  {:else}
+    <!-- Single-layer: isovalue slider full width -->
+    <label
+      {@attach tooltip({
+        content: `Density threshold — surface is drawn where grid values equal this`,
+      })}
+    >
+      <span>Isovalue:</span>
+      <input
+        type="range"
+        min={step}
+        max={slider_max}
+        {step}
+        bind:value={settings.isovalue}
+      />
+      <span class="value">{format_num(settings.isovalue, `.4~g`)}</span>
+    </label>
+
+    <!-- Opacity + colors on one row -->
+    <div class="pane-row compact-row">
+      <label
+        {@attach tooltip({
+          content: `Surface transparency — lower values reveal inner structure`,
+        })}
+      >
+        <span>Opacity:</span>
+        <input
+          type="range"
+          min={0.1}
+          max={1}
+          step={0.05}
+          bind:value={settings.opacity}
+          style="width: 60px"
+        />
+        <span class="value">{format_num(settings.opacity, `.2f`)}</span>
+      </label>
+      <label {@attach tooltip({ content: `Color for the positive isovalue surface` })}>
+        <span>+ Color</span>
+        <input type="color" bind:value={settings.positive_color} />
+      </label>
+      {#if settings.show_negative}
+        <label
+          {@attach tooltip({ content: `Color for the negative (−isovalue) surface` })}
+        >
+          <span>&minus; Color</span>
+          <input type="color" bind:value={settings.negative_color} />
+        </label>
+      {/if}
+    </div>
+  {/if}
+
+  {#if volumes?.[active_volume_idx]?.periodic}
+    <label
+      {@attach tooltip({
+        content:
+          `Extend isosurface beyond cell boundaries to close partial spheres (fraction of cell)`,
+      })}
+    >
+      Halo: {format_num(settings.halo, `.2f`)}
+      <input
+        type="range"
+        min={0}
+        max={0.5}
+        step={0.01}
+        bind:value={settings.halo}
+      />
+    </label>
+  {/if}
+
+  {#if volumes[active_volume_idx]}
+    <div class="grid-info">
+      {volumes[active_volume_idx].grid_dims.join(` × `)} grid &nbsp;|&nbsp; [{
+        format_num(data_range.min, `.3~g`)
+      }, {format_num(data_range.max, `.3~g`)}]
+    </div>
+  {/if}
+</SettingsSection>
+
+<style>
+  .compact-row {
+    flex-wrap: wrap;
+    gap: 4pt 14pt;
+  }
+  label {
+    gap: 6pt;
+  }
+  .grid-info {
+    font-size: 0.75em;
+    opacity: 0.7;
+    padding: 2px 0;
+  }
+  .layer-row {
+    display: flex;
+    align-items: center;
+    gap: 0.3em;
+    font-size: 0.85em;
+    input[type='color'] {
+      width: 24px;
+      height: 20px;
+      padding: 0;
+      border: 1px solid var(--border-color, #ccc);
+      border-radius: 3px;
+      box-sizing: border-box;
+      cursor: pointer;
+    }
+    input[type='checkbox'] {
+      margin: 0;
+    }
+  }
+  .layer-value {
+    font-family: monospace;
+    font-size: 0.85em;
+    min-width: 3.5em;
+    text-align: right;
+  }
+</style>

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

@@ -0,0 +1,9 @@
+import type { IsosurfaceSettings, VolumetricData } from './types';
+type $$ComponentProps = {
+    settings?: IsosurfaceSettings;
+    volumes?: VolumetricData[];
+    active_volume_idx?: number;
+};
+declare const IsosurfaceControls: import("svelte").Component<$$ComponentProps, {}, "settings" | "active_volume_idx">;
+type IsosurfaceControls = ReturnType<typeof IsosurfaceControls>;
+export default IsosurfaceControls;

package/dist/isosurface/index.d.ts

@@ -0,0 +1,5 @@
+export { default as Isosurface } from './Isosurface.svelte';
+export { default as IsosurfaceControls } from './IsosurfaceControls.svelte';
+export * from './parse';
+export * from './slice';
+export * from './types';

package/dist/isosurface/index.js

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

package/dist/isosurface/parse.d.ts

@@ -0,0 +1,6 @@
+import type { VolumetricFileData } from './types';
+export declare function parse_chgcar(content: string): VolumetricFileData | null;
+export declare function parse_cube(content: string, options?: {
+    periodic?: boolean;
+}): VolumetricFileData | null;
+export declare function parse_volumetric_file(content: string, filename?: string): VolumetricFileData | null;