matterviz 0.3.1 → 0.3.3

package/dist/io/url-drop.js

@@ -0,0 +1,117 @@
+import { load_binary_traj } from '../trajectory/parse';
+const BINARY_EXTENSIONS = new Set(`h5 hdf5 traj npz pkl dat gz gzip zip bz2 xz brml`.split(` `));
+const TEXT_EXTENSIONS = new Set(`xyz extxyz json cif poscar yaml yml txt md py js ts css html xml`.split(` `));
+const VASP_BASENAME_RE = /^(poscar|xdatcar|contcar)$/i;
+// Extract filename from Content-Disposition header, falling back to url_basename.
+function extract_filename(headers, fallback) {
+    if (!headers)
+        return fallback;
+    const content_disposition_str = headers.get(`content-disposition`);
+    if (!content_disposition_str)
+        return fallback;
+    const star_match = /filename\*=(?:UTF-8''|)([^;]+)/i.exec(content_disposition_str);
+    if (star_match?.[1]) {
+        const raw = star_match[1].trim().replace(/^"|"$/g, ``);
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    const plain_match = /filename\s*=\s*"?([^";]+)"?/i.exec(content_disposition_str);
+    return plain_match?.[1]?.trim() || fallback;
+}
+// Handle URL-based file drop data by fetching content lazily
+export async function handle_url_drop(drag_event, callback) {
+    const json_data = drag_event.dataTransfer?.getData(`application/json`);
+    if (!json_data)
+        return false;
+    let file_info;
+    try {
+        file_info = JSON.parse(json_data);
+    }
+    catch {
+        return false;
+    }
+    if (!file_info.url)
+        return false;
+    await load_from_url(file_info.url, callback);
+    return true;
+}
+export async function load_from_url(url, callback) {
+    const url_basename = url.split(`/`).pop() || url;
+    const ext = url_basename.split(`.`).pop()?.toLowerCase() || ``;
+    if (BINARY_EXTENSIONS.has(ext)) {
+        // Force binary mode for known binary files to handle GitHub Pages content-type issues
+        const resp = await fetch(url);
+        if (!resp.ok)
+            throw new Error(`Fetch failed: ${resp.status}`);
+        const filename = extract_filename(resp.headers, url_basename);
+        // Handle gzipped files with proper content-encoding detection
+        if (ext === `gz` || ext === `gzip`) {
+            if (resp.headers.get(`content-encoding`) === `gzip`) {
+                // Browser automatically decompressed it, so it's text
+                return callback(await resp.text(), filename);
+            }
+            else {
+                // Need to decompress manually
+                const { decompress_data } = await import(`./decompress`);
+                const buffer = await resp.arrayBuffer();
+                const content = await decompress_data(buffer, `gzip`);
+                // Remove .gz extension when manually decompressing
+                return callback(content, filename.replace(/\.gz$/, ``));
+            }
+        }
+        // For H5 files, always load as binary regardless of signature
+        // to handle files that have .h5/.hdf5 extensions but may not have the proper HDF5 signature
+        if (ext === `h5` || ext === `hdf5`) {
+            const result = await load_binary_traj(resp, `H5`, true);
+            // Log warning if signature doesn't match (only for ArrayBuffer results)
+            if (result instanceof ArrayBuffer && result.byteLength >= 8) {
+                const view = new Uint8Array(result.slice(0, 8));
+                const hdf5_signature = [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a];
+                if (!hdf5_signature.every((byte, idx) => view[idx] === byte)) {
+                    console.warn(`File has .h5/.hdf5 extension but missing HDF5 signature`);
+                }
+            }
+            return callback(result, filename);
+        }
+        // For .traj files, ensure we always get ArrayBuffer for proper ASE parsing
+        if (ext === `traj`) {
+            const buffer = await load_binary_traj(resp, `.traj`);
+            return callback(buffer, filename);
+        }
+        if (resp.headers.get(`content-encoding`) === `gzip`) {
+            return callback(await resp.text(), filename);
+        }
+        return callback(await resp.arrayBuffer(), filename);
+    }
+    // Skip Range requests for known text formats to avoid production server issues
+    // Include VASP files that don't have extensions (POSCAR, XDATCAR, CONTCAR)
+    const is_known_text = TEXT_EXTENSIONS.has(ext) || VASP_BASENAME_RE.test(url_basename);
+    if (!is_known_text) {
+        try {
+            // Check for magic bytes only for unknown formats
+            const head = await fetch(url, { headers: { Range: `bytes=0-15` } });
+            if (head.ok) {
+                const buf = new Uint8Array(await head.arrayBuffer());
+                const is_gzip = buf[0] === 0x1f && buf[1] === 0x8b;
+                const is_hdf5 = buf[0] === 0x89 && buf[1] === 0x48 && buf[2] === 0x44 && buf[3] === 0x46;
+                if (is_gzip || is_hdf5) {
+                    const resp = await fetch(url);
+                    if (!resp.ok)
+                        throw new Error(`Fetch failed: ${resp.status}`);
+                    return callback(await resp.arrayBuffer(), extract_filename(resp.headers, url_basename));
+                }
+            }
+        }
+        catch {
+            // Fall through to text fetch if HEAD request fails
+        }
+    }
+    const resp = await fetch(url);
+    if (!resp.ok)
+        throw new Error(`Fetch failed: ${resp.status}`);
+    return callback(await resp.text(), extract_filename(resp.headers, url_basename));
+}

package/dist/isosurface/Isosurface.svelte

@@ -1,122 +1,232 @@
-<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 } 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;
+<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 type { Matrix3x3, Vec3 } from '../math'
+  import { T } from '@threlte/core'
+  import {
+    BackSide,
+    BufferAttribute,
+    BufferGeometry,
+    DoubleSide,
+    FrontSide,
+    Uint32BufferAttribute,
+  } from 'three'
+  import type { IsosurfaceLayer, IsosurfaceSettings, VolumetricData } from './types'
+  import {
+    DEFAULT_ISOSURFACE_SETTINGS,
+    downsample_grid,
+    pad_periodic_grid,
+  } from './types'
+
+  let { volume, settings = DEFAULT_ISOSURFACE_SETTINGS }: {
+    volume: VolumetricData
+    settings?: IsosurfaceSettings
+  } = $props()
+
+  // Resolve layers: use explicit layers array if provided, else build from single-isovalue settings
+  let resolved_layers = $derived.by((): IsosurfaceLayer[] => {
+    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;
+      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: Vec3[],
+    faces: number[][],
+  ): BufferGeometry | null {
+    if (vertices.length === 0 || faces.length === 0) return null
+
     // Flatten vertices: Vec3[] → Float32Array
-    const positions = new Float32Array(vertices.length * 3);
+    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];
+      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);
+    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 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;
-}
-// Run marching cubes at the given isovalue.
-// Uses volume.periodic for correct coordinate scaling:
-// periodic grids (CHGCAR) use 1/N spacing, non-periodic (.cube) use 1/(N-1).
-function extract_surface(isovalue) {
-    if (!volume || isovalue === 0)
-        return null;
-    const result = marching_cubes(volume.grid, isovalue, volume.lattice, {
-        periodic: volume.periodic,
-        interpolate: true,
-        centered: false,
-        normals: false,
-    });
-    return build_geometry(result.vertices, result.faces);
-}
-let active_geometries = $state([]);
-let raf_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());
-// Rebuild all layer geometries on next animation frame when layers or volume change
-$effect(() => {
-    const layers = resolved_layers;
-    const vol = volume;
-    if (!vol) {
-        dispose_all();
-        return;
+
+    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: number,
+    mc_grid: number[][][],
+    mc_lattice: Matrix3x3,
+    origin_shift: Vec3 | null,
+  ): BufferGeometry | null {
+    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]
+      }
     }
-    raf_id = requestAnimationFrame(() => {
-        const old = active_geometries;
-        const entries = [];
-        for (let layer_idx = 0; layer_idx < layers.length; layer_idx++) {
-            const layer = layers[layer_idx];
-            if (!layer.visible || layer.isovalue <= 0)
-                continue;
-            // Render order: inner shells (higher isovalue) first for correct transparency.
-            // Each layer gets 4 slots (positive back/front + negative back/front).
-            const base_order = (layers.length - 1 - layer_idx) * 4;
-            const pos_geo = extract_surface(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 = extract_surface(-layer.isovalue);
-                if (neg_geo) {
-                    entries.push({
-                        geometry: neg_geo,
-                        color: layer.negative_color,
-                        opacity: layer.opacity,
-                        render_order: base_order + 2,
-                    });
-                }
-            }
+
+    return build_geometry(result.vertices, result.faces)
+  }
+
+  // === Multi-layer geometry management ===
+  // Each layer produces up to 2 geometries (positive + optional negative lobe).
+  // Keyed by "layer_idx:sign" for cache invalidation.
+  type GeoEntry = {
+    geometry: BufferGeometry
+    color: string
+    opacity: number
+    render_order: number
+  }
+  let active_geometries = $state<GeoEntry[]>([])
+  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: IsosurfaceLayer[]) {
+    if (!volume || !ds_result) return
+    const old = active_geometries
+    const entries: GeoEntry[] = []
+
+    // 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: Matrix3x3 = volume.lattice
+    let origin_shift: Vec3 | null = 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: number) =>
+      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<number, number>(
+      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();
-    });
-    return () => cancelAnimationFrame(raf_id);
-});
+      }
+    }
+
+    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 -->

package/dist/isosurface/IsosurfaceControls.svelte

@@ -1,35 +1,53 @@
-<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(() => {
+<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 type { IsosurfaceLayer, IsosurfaceSettings, VolumetricData } from './types'
+  import { DEFAULT_ISOSURFACE_SETTINGS, generate_layers } from './types'
+
+  let {
+    settings = $bindable({ ...DEFAULT_ISOSURFACE_SETTINGS }),
+    volumes = [],
+    active_volume_idx = $bindable(0),
+  }: {
+    settings?: IsosurfaceSettings
+    volumes?: VolumetricData[]
+    active_volume_idx?: number
+  } = $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;
+      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) {
+  })
+
+  // 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: number) {
     if (count <= 1) {
-        settings.layers = undefined;
+      settings.layers = undefined
+    } else {
+      settings.layers = generate_layers(data_range, count)
     }
-    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);
-}
+  }
+
+  function update_layer(idx: number, updates: Partial<IsosurfaceLayer>) {
+    if (!settings.layers) return
+    settings.layers = settings.layers.map((layer, layer_idx) =>
+      layer_idx === idx ? { ...layer, ...updates } : layer
+    )
+  }
 </script>
 
 <SettingsSection
@@ -39,6 +57,7 @@ function update_layer(idx, updates) {
     opacity: settings.opacity,
     show_negative: settings.show_negative,
     wireframe: settings.wireframe,
+    halo: settings.halo,
     layers: n_layers,
   }}
   on_reset={() => {
@@ -205,6 +224,24 @@ function update_layer(idx, updates) {
     </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; [{