matterviz 0.4.1 → 0.4.3

package/dist/file-viewer/parse.js

@@ -0,0 +1,170 @@
+// Worker-safe file parsing with no Svelte or DOM imports.
+import { COMPRESSION_EXTENSIONS_REGEX } from '../constants';
+import { parse_fermi_file } from '../fermi-surface/parse';
+import { decompress_data, decompress_data_binary, detect_compression_format, } from '../io/decompress';
+import { parse_volumetric_file } from '../isosurface/parse';
+import { is_vaspwave_filename, parse_vaspwave_charge } from '../isosurface/parse-vaspwave';
+import { parse_structure_file } from '../structure/parse';
+import { is_trajectory_file, parse_trajectory_data } from '../trajectory/parse';
+import { FERMI_FILE_RE, VOLUMETRIC_EXT_RE, VOLUMETRIC_VASP_RE } from './types';
+import { detect_view_type } from './detect';
+// Maps detect.ts RenderableType to ViewType for direct rendering.
+// Types not listed here fall through to json_browser (which can render all types
+// via its internal mount_into, giving the user a tree view alongside the viz).
+// structure and volumetric have special handling in parse_file_content below.
+const DETECTION_TO_VIEW_TYPE = {
+    fermi_surface: `fermi_surface`,
+    band_grid: `fermi_surface`,
+    convex_hull: `convex_hull`,
+    phase_diagram: `phase_diagram`,
+};
+// Convert base64 to ArrayBuffer for binary files
+export function base64_to_array_buffer(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let idx = 0; idx < binary.length; idx++) {
+        bytes[idx] = binary.charCodeAt(idx);
+    }
+    return bytes.buffer;
+}
+// Parse file content and determine if it's a structure or trajectory
+export const parse_file_content = async (content, filename, is_base64 = false) => {
+    // Handle base64-encoded compressed/binary files by converting them first
+    if (is_base64) {
+        let buffer = base64_to_array_buffer(content);
+        const compression_format = detect_compression_format(filename);
+        if (compression_format) {
+            const normalized_filename = filename.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
+            if (detect_compression_format(normalized_filename)) {
+                throw new Error(`Nested compression is not supported: ${filename}`);
+            }
+            filename = normalized_filename;
+        }
+        // Compressed binary formats (e.g. vaspwave.h5.gz as ferrox stores them on S3,
+        // or compressed ASE .traj files): decompress to binary first — generic text
+        // decompression would corrupt their bytes — so routing sees the inner name.
+        const is_binary_format = /\.(?:h5|hdf5|traj)$/i.test(filename);
+        if (compression_format === `zip`) {
+            const { unzipSync } = await import(`fflate`);
+            const payload = Object.entries(unzipSync(new Uint8Array(buffer))).find(([entry_name]) => !entry_name.endsWith(`/`))?.[1];
+            if (!payload)
+                throw new Error(`ZIP archive contains no files: ${filename}`);
+            if (is_binary_format)
+                buffer = payload.slice().buffer;
+            else
+                content = new TextDecoder().decode(payload);
+        }
+        else if (compression_format) {
+            // Unified handling for all supported compression formats
+            // Unsupported formats fail here with a clear extraction error
+            if (is_binary_format)
+                buffer = await decompress_data_binary(buffer, compression_format);
+            else
+                content = await decompress_data(buffer, compression_format);
+        }
+        // vaspwave.h5 holds charge density (+ wavefunctions), not a trajectory —
+        // route to the volumetric parser so it renders as an isosurface.
+        if (is_vaspwave_filename(filename)) {
+            const data = await parse_vaspwave_charge(buffer, filename);
+            return { type: `isosurface`, data, filename };
+        }
+        // Binary trajectory formats: pass buffer directly to trajectory parser
+        if (is_binary_format) {
+            const data = await parse_trajectory_data(buffer, filename);
+            // DOS/bands-only vaspout.h5 (e.g. phelel band paths): no frames to animate,
+            // route the electronic results to the spectral components instead.
+            // Require at least one renderable result rather than trusting the
+            // parser's invariant (the metadata cast is unchecked): an empty
+            // electronic object would otherwise mount <Dos doses={null}>.
+            const electronic = data.metadata?.electronic;
+            if (data.frames.length === 0 && (electronic?.dos || electronic?.bands)) {
+                return { type: `vaspout_electronic`, filename, data: electronic };
+            }
+            return { type: `trajectory`, filename, data };
+        }
+    }
+    // Fermi surface files (.bxsf, .frmsf)
+    // Use basename for regex matching in case filename retains a directory prefix
+    const basename = filename.split(`/`).pop() ?? filename;
+    if (FERMI_FILE_RE.test(basename)) {
+        // parse_fermi_file throws a descriptive error when parsing fails
+        return { type: `fermi_surface`, data: parse_fermi_file(content, filename), filename };
+    }
+    // Volumetric data files (.cube, CHGCAR, AECCAR*, ELFCAR, LOCPOT, PARCHG)
+    if (VOLUMETRIC_EXT_RE.test(basename) || VOLUMETRIC_VASP_RE.test(basename)) {
+        const data = parse_volumetric_file(content, filename);
+        if (data)
+            return { type: `isosurface`, data, filename };
+        throw new Error(`Failed to parse volumetric file: ${filename}`);
+    }
+    let parsed_json;
+    let has_parsed_json = false;
+    // JSON files: render typed JSON before filename heuristics. Otherwise names like
+    // convex-hull.json can be mistaken for trajectory keywords such as nve.
+    if (/\.json$/i.test(filename)) {
+        try {
+            parsed_json = JSON.parse(content);
+            has_parsed_json = true;
+            // Check if the top-level value matches a known visualization type
+            const detected = detect_view_type(parsed_json);
+            if (detected) {
+                // Structure JSON needs normalization (OPTIMADE, fractional coords, etc.)
+                if (detected === `structure`) {
+                    try {
+                        const structure = parse_structure_file(content, filename);
+                        return {
+                            type: `structure`,
+                            data: { ...structure, id: filename.replace(/\.[^/.]+$/, ``) },
+                            filename,
+                        };
+                    }
+                    catch {
+                        // Detailed parse failed despite structure-like shape — fall through to
+                        // generic JSON handling below
+                    }
+                }
+                // Volumetric JSON needs wrapping in { structure, volumes } for the isosurface renderer
+                if (detected === `volumetric`) {
+                    const vol = parsed_json;
+                    return {
+                        type: `isosurface`,
+                        data: { structure: { sites: [], lattice: vol.lattice }, volumes: [parsed_json] },
+                        filename,
+                    };
+                }
+                return {
+                    type: DETECTION_TO_VIEW_TYPE[detected] ?? `json_browser`,
+                    data: parsed_json,
+                    filename,
+                };
+            }
+        }
+        catch {
+            // JSON parse failed, fall through to structure parser
+        }
+    }
+    // Try trajectory parsing if it looks like a trajectory
+    if (is_trajectory_file(filename, content)) {
+        try {
+            const data = await parse_trajectory_data(content, filename);
+            return { type: `trajectory`, data, filename };
+        }
+        catch (error) {
+            // Trajectory-looking filename but not trajectory-shaped JSON (e.g. nve-config.json):
+            // fall through to the JSON browser instead of failing the render
+            if (!has_parsed_json)
+                throw error;
+        }
+    }
+    // No top-level match -- show JSON browser for navigation
+    if (has_parsed_json)
+        return { type: `json_browser`, data: parsed_json, filename };
+    // Parse as structure (CIF, POSCAR, XYZ, etc.) — throws descriptive reasons on failure
+    const structure = parse_structure_file(content, filename);
+    // parse_structure_file throws on parse failure but can still return zero atoms (e.g. a
+    // CIF with cell params but no _atom_site records), which is invalid downstream
+    if (!structure.sites?.length)
+        throw new Error(`No atoms found in ${filename}`);
+    const data = { ...structure, id: filename.replace(/\.[^/.]+$/, ``) };
+    return { type: `structure`, data, filename };
+};

package/dist/file-viewer/plot-utils.d.ts

@@ -0,0 +1,24 @@
+import type { BarSeries, DataSeries, DataSeries3D } from '../plot';
+export type PlotType = `scatter` | `scatter3d` | `bar` | `histogram` | `table`;
+export interface ColumnInfo {
+    values: unknown[];
+    type: `numeric` | `string` | `mixed`;
+    n_valid: number;
+}
+export interface AxisMapping {
+    x?: string;
+    y?: string;
+    z?: string;
+    color?: string;
+    size?: string;
+}
+export declare function extract_columns(data: unknown): Map<string, ColumnInfo>;
+export declare const col_keys: (columns: Map<string, ColumnInfo>, type: ColumnInfo[`type`]) => string[];
+export declare function suggest_mapping(columns: Map<string, ColumnInfo>): {
+    plot_type: PlotType;
+    mapping: AxisMapping;
+};
+export declare function build_scatter_series(columns: Map<string, ColumnInfo>, mapping: AxisMapping): DataSeries;
+export declare function build_scatter3d_series(columns: Map<string, ColumnInfo>, mapping: AxisMapping): DataSeries3D;
+export declare function build_bar_series(columns: Map<string, ColumnInfo>, mapping: AxisMapping): BarSeries;
+export declare function build_histogram_series(columns: Map<string, ColumnInfo>, mapping: AxisMapping): DataSeries;

package/dist/file-viewer/plot-utils.js

@@ -0,0 +1,191 @@
+// Utilities for extracting plottable columns from JSON data and building plot series.
+// Extract columns from row-based or column-based tabular data
+export function extract_columns(data) {
+    const columns = new Map();
+    if (Array.isArray(data) &&
+        data.length > 0 &&
+        typeof data[0] === `object` &&
+        data[0] !== null) {
+        // Row-based: [{ a: 1, b: 'x' }, ...]
+        const sample = data.slice(0, 100);
+        const all_keys = new Set();
+        for (const row of sample) {
+            if (row && typeof row === `object`) {
+                for (const key of Object.keys(row))
+                    all_keys.add(key);
+            }
+        }
+        for (const key of all_keys) {
+            columns.set(key, classify_column(data.map((row) => row && typeof row === `object` ? row[key] : undefined)));
+        }
+    }
+    else if (data && typeof data === `object` && !Array.isArray(data)) {
+        // Column-based: { a: [1,2,3], b: ['x','y','z'] }
+        const array_entries = Object.entries(data).filter(([, val]) => Array.isArray(val) && val.length > 0);
+        if (array_entries.length < 1)
+            return columns;
+        const target_len = array_entries[0][1].length;
+        for (const [key, val] of array_entries) {
+            const arr = val;
+            if (arr.length === target_len) {
+                columns.set(key, classify_column(arr));
+            }
+        }
+    }
+    return columns;
+}
+function classify_column(values) {
+    let n_numeric = 0;
+    let n_string = 0;
+    let n_valid = 0;
+    for (const val of values) {
+        if (val == null || (typeof val === `number` && !isFinite(val)))
+            continue;
+        n_valid++;
+        if (typeof val === `number`)
+            n_numeric++;
+        else if (typeof val === `string`)
+            n_string++;
+    }
+    let type = `mixed`;
+    if (n_valid > 0) {
+        if (n_numeric >= n_valid * 0.8)
+            type = `numeric`;
+        else if (n_string >= n_valid * 0.8)
+            type = `string`;
+    }
+    return { values, type, n_valid };
+}
+// Extract column keys of a given type from a column map
+export const col_keys = (columns, type) => [...columns.entries()].filter(([, col]) => col.type === type).map(([key]) => key);
+// Well-known column name patterns for heuristic axis assignment
+const X_NAMES = new Set([`x`, `time`, `step`, `index`, `iteration`, `frame`, `epoch`]);
+const Y_NAMES = new Set([`y`, `energy`, `value`, `force`, `stress`, `loss`, `score`]);
+const Z_NAMES = new Set([`z`, `altitude`, `depth`, `height`]);
+// Heuristic: suggest initial axis mapping and plot type from columns
+export function suggest_mapping(columns) {
+    const numeric_cols = col_keys(columns, `numeric`);
+    const string_cols = col_keys(columns, `string`);
+    const mapping = {};
+    // Assign x: prefer named numeric match, then string column (bar chart), then first numeric
+    const x_match = numeric_cols.find((key) => X_NAMES.has(key.toLowerCase()));
+    const x_string_match = string_cols.find((key) => !Y_NAMES.has(key.toLowerCase()));
+    mapping.x =
+        x_match ?? x_string_match ?? (numeric_cols.length >= 2 ? numeric_cols[0] : undefined);
+    // Assign y
+    const remaining_numeric = numeric_cols.filter((key) => key !== mapping.x);
+    const y_match = remaining_numeric.find((key) => Y_NAMES.has(key.toLowerCase()));
+    mapping.y = y_match ?? remaining_numeric[0];
+    // Assign z (only if 3+ numeric columns and one matches z-like name)
+    const after_xy = remaining_numeric.filter((key) => key !== mapping.y);
+    const z_match = after_xy.find((key) => Z_NAMES.has(key.toLowerCase()));
+    if (z_match && numeric_cols.length >= 3)
+        mapping.z = z_match;
+    // Assign color (first unassigned numeric column)
+    const used = new Set([mapping.x, mapping.y, mapping.z].filter(Boolean));
+    const color_candidate = numeric_cols.find((key) => !used.has(key));
+    if (color_candidate)
+        mapping.color = color_candidate;
+    // Determine plot type
+    let plot_type = `scatter`;
+    if (mapping.z) {
+        plot_type = `scatter3d`;
+    }
+    else if (mapping.x && columns.get(mapping.x)?.type === `string`) {
+        plot_type = `bar`;
+    }
+    else if ((!mapping.x || !mapping.y) && numeric_cols.length >= 1) {
+        plot_type = `histogram`;
+        mapping.x ??= mapping.y ?? numeric_cols[0];
+    }
+    else if (!mapping.x || !mapping.y) {
+        plot_type = `table`;
+    }
+    return { plot_type, mapping };
+}
+// Convert to numbers, preserving array length (non-finite values become NaN)
+const to_numbers = (values) => values.map((val) => (typeof val === `number` && isFinite(val) ? val : NaN));
+// Convert an arbitrary cell value to a display label, JSON-encoding objects so
+// they don't stringify to the useless "[object Object]".
+const to_label = (val) => {
+    if (val == null)
+        return ``;
+    if (typeof val === `string` ||
+        typeof val === `number` ||
+        typeof val === `boolean` ||
+        typeof val === `bigint`)
+        return String(val);
+    return JSON.stringify(val);
+};
+// Look up a column by its mapping key, returning undefined if unmapped or missing
+const get_col = (columns, key) => key ? columns.get(key) : undefined;
+// Optional numeric conversion for color/size channels
+const optional_numbers = (col) => col ? to_numbers(col.values) : undefined;
+// Filter N axis arrays to only include indices where all axes are finite,
+// keeping optional color/size arrays aligned
+function filter_finite(axes, color, size) {
+    const out = axes.map(() => []);
+    const color_values = color ? [] : undefined;
+    const size_values = size ? [] : undefined;
+    for (let idx = 0; idx < axes[0].length; idx++) {
+        if (axes.some((arr) => !isFinite(arr[idx])))
+            continue;
+        for (let dim = 0; dim < axes.length; dim++)
+            out[dim].push(axes[dim][idx]);
+        if (color && color_values)
+            color_values.push(color[idx]);
+        if (size && size_values)
+            size_values.push(size[idx]);
+    }
+    return { axes: out, color_values, size_values };
+}
+export function build_scatter_series(columns, mapping) {
+    const x_col = get_col(columns, mapping.x);
+    const y_col = get_col(columns, mapping.y);
+    if (!x_col || !y_col)
+        return { x: [], y: [] };
+    const { axes: [x, y], color_values, size_values, } = filter_finite([to_numbers(x_col.values), to_numbers(y_col.values)], optional_numbers(get_col(columns, mapping.color)), optional_numbers(get_col(columns, mapping.size)));
+    return {
+        x,
+        y,
+        markers: `points`,
+        color_values,
+        size_values,
+        point_style: { radius: 4, fill: `#4c6ef5`, stroke: `white`, stroke_width: 1 },
+    };
+}
+export function build_scatter3d_series(columns, mapping) {
+    const x_col = get_col(columns, mapping.x);
+    const y_col = get_col(columns, mapping.y);
+    const z_col = get_col(columns, mapping.z);
+    if (!x_col || !y_col || !z_col)
+        return { x: [], y: [], z: [] };
+    const { axes: [x, y, z], color_values, size_values, } = filter_finite([to_numbers(x_col.values), to_numbers(y_col.values), to_numbers(z_col.values)], optional_numbers(get_col(columns, mapping.color)), optional_numbers(get_col(columns, mapping.size)));
+    return { x, y, z, markers: `points`, color_values, size_values };
+}
+export function build_bar_series(columns, mapping) {
+    const x_col = get_col(columns, mapping.x);
+    const y_col = get_col(columns, mapping.y);
+    if (!x_col || !y_col)
+        return { x: [], y: [] };
+    const raw_y = to_numbers(y_col.values);
+    const x = [];
+    const y = [];
+    for (let idx = 0; idx < raw_y.length; idx++) {
+        if (!isFinite(raw_y[idx]))
+            continue;
+        x.push(to_label(x_col.values[idx]));
+        y.push(raw_y[idx]);
+    }
+    return { x, y, color: `#4c6ef5` };
+}
+export function build_histogram_series(columns, mapping) {
+    const col = get_col(columns, mapping.x ?? mapping.y);
+    if (!col)
+        return { x: [], y: [] };
+    const values = to_numbers(col.values).filter(isFinite);
+    return {
+        x: values.map((_, idx) => idx),
+        y: values,
+    };
+}

package/dist/file-viewer/types.d.ts

@@ -0,0 +1,4 @@
+export type ViewType = `trajectory` | `structure` | `fermi_surface` | `isosurface` | `convex_hull` | `phase_diagram` | `json_browser` | `vaspout_electronic`;
+export declare const FERMI_FILE_RE: RegExp;
+export declare const VOLUMETRIC_EXT_RE: RegExp;
+export declare const VOLUMETRIC_VASP_RE: RegExp;

package/dist/file-viewer/types.js

@@ -0,0 +1,5 @@
+// Shared file-viewer types and filename patterns.
+// Filename patterns for specialized file types (shared between extension host and webview)
+export const FERMI_FILE_RE = /\.(?:bxsf|frmsf)$/i;
+export const VOLUMETRIC_EXT_RE = /\.cube$/i;
+export const VOLUMETRIC_VASP_RE = /(?:^|[\\/_.-])(?:chgcar|aeccar[012]?|elfcar|locpot|parchg)(?:[\\/_.-]|$)/i;