matterviz 0.3.1 → 0.3.3

package/dist/io/export.js

@@ -1,171 +1,161 @@
 import { download } from './fetch';
 import { create_structure_filename } from '../structure/export';
 import { Vector2 } from 'three';
-// Export structure as PNG image from canvas
-export function export_canvas_as_png(canvas, structure_or_filename, png_dpi = 150, scene = null, camera = null) {
-    try {
-        if (!canvas) {
-            if (typeof window !== `undefined`) {
-                console.warn(`Canvas not found for PNG export`);
-            }
-            return;
-        }
-        // Determine filename from either structure or direct filename
-        let filename = typeof structure_or_filename === `string`
-            ? structure_or_filename
-            : create_structure_filename(structure_or_filename, `png`);
-        // Inject DPI into filename
-        const suffix = `-${Math.round(png_dpi)}dpi`;
-        if (filename.toLowerCase().endsWith(`.png`)) {
-            filename = filename.replace(/\.png$/i, `${suffix}.png`);
-        }
-        else {
-            filename = `${filename}${suffix}.png`;
-        }
-        // Convert DPI to multiplier (72 DPI is baseline web resolution)
-        // Cap to a reasonable upper bound to avoid excessive memory use
-        const resolution_multiplier = Math.min(png_dpi / 72, 10);
-        const renderer = canvas.__renderer;
-        // Force render to populate buffer
+function is_webgl_renderer_like(value) {
+    if (typeof value !== `object` || !value)
+        return false;
+    const renderer_obj = value;
+    return (typeof renderer_obj.render === `function` &&
+        typeof renderer_obj.getPixelRatio === `function` &&
+        typeof renderer_obj.setPixelRatio === `function` &&
+        typeof renderer_obj.getSize === `function` &&
+        typeof renderer_obj.setSize === `function`);
+}
+// Capture a WebGL canvas as a PNG Blob at the given DPI.
+// Temporarily adjusts renderer pixel ratio for high-res capture, then restores.
+// Returns data directly (no browser download), suitable for programmatic capture
+// in test suites, server-side rendering, or Python widget integration via anywidget.
+// DPI is converted to a resolution multiplier relative to 72 DPI baseline, capped at 10x.
+export function canvas_to_png_blob(canvas, png_dpi = 150, scene = null, camera = null) {
+    const resolution_multiplier = Math.min(png_dpi / 72, 10);
+    const renderer_val = canvas.__renderer;
+    const renderer = is_webgl_renderer_like(renderer_val) ? renderer_val : undefined;
+    if (resolution_multiplier <= 1.1 || !renderer) {
         if (renderer && scene && camera)
             renderer.render(scene, camera);
-        if (resolution_multiplier <= 1.1 || !renderer) {
-            // Direct capture at current resolution (if DPI is close to 72 or renderer not available)
+        return new Promise((resolve, reject) => {
             try {
                 canvas.toBlob((blob) => {
-                    if (blob) {
-                        download(blob, filename, `image/png`);
-                    }
-                    else {
-                        if (typeof window !== `undefined`) {
-                            console.warn(`Failed to generate PNG - canvas may be empty`);
-                        }
-                    }
+                    if (blob)
+                        resolve(blob);
+                    else
+                        reject(new Error(`Failed to generate PNG - canvas may be empty`));
                 }, `image/png`);
             }
             catch (error) {
-                console.error(`Error during PNG export:`, error);
+                reject(error);
             }
-            return;
-        }
-        // Temporarily modify the renderer's pixel ratio for high-res capture
-        const orig_pixel_ratio = renderer.getPixelRatio();
-        const orig_size = renderer.getSize(new Vector2());
+        });
+    }
+    // Temporarily modify the renderer's pixel ratio for high-res capture
+    const orig_pixel_ratio = renderer.getPixelRatio();
+    const orig_size = renderer.getSize(new Vector2());
+    const restore = () => {
+        renderer.setPixelRatio(orig_pixel_ratio);
+        renderer.setSize(orig_size.width, orig_size.height, false);
+    };
+    renderer.setPixelRatio(resolution_multiplier);
+    renderer.setSize(orig_size.width, orig_size.height, false);
+    if (scene && camera)
+        renderer.render(scene, camera);
+    return new Promise((resolve, reject) => {
         try {
-            // Set higher pixel ratio to increase rendering resolution
-            renderer.setPixelRatio(resolution_multiplier);
-            // Force the canvas to update its resolution
-            renderer.setSize(orig_size.width, orig_size.height, false);
-            if (scene && camera) {
-                renderer.render(scene, camera);
-            }
-            // Capture the high-resolution render after paint completion
             canvas.toBlob((blob) => {
-                // Restore original settings immediately
-                renderer.setPixelRatio(orig_pixel_ratio);
-                renderer.setSize(orig_size.width, orig_size.height, false);
-                if (blob) {
-                    download(blob, filename, `image/png`);
-                }
-                else {
-                    if (typeof window !== `undefined`) {
-                        console.warn(`Failed to generate high-resolution PNG`);
-                    }
-                }
+                restore();
+                if (blob)
+                    resolve(blob);
+                else
+                    reject(new Error(`Failed to generate high-resolution PNG`));
             }, `image/png`);
         }
         catch (error) {
-            console.error(`Error during high-res rendering:`, error);
-            // Restore original settings
-            renderer.setPixelRatio(orig_pixel_ratio);
-            renderer.setSize(orig_size.width, orig_size.height, false);
-            if (typeof window !== `undefined`) {
-                console.warn(`Failed to render at high resolution: ${error instanceof Error ? error.message : String(error)}`);
-            }
+            restore();
+            reject(error);
         }
+    });
+}
+// Export structure as PNG image from canvas (triggers browser download)
+export function export_canvas_as_png(canvas, structure_or_filename, png_dpi = 150, scene = null, camera = null) {
+    if (!canvas) {
+        if (typeof window !== `undefined`)
+            console.warn(`Canvas not found for PNG export`);
+        return;
     }
-    catch (error) {
-        console.error(`Error exporting PNG:`, error);
+    let filename = typeof structure_or_filename === `string`
+        ? structure_or_filename
+        : create_structure_filename(structure_or_filename, `png`);
+    const suffix = `-${Math.round(png_dpi)}dpi`;
+    if (filename.toLowerCase().endsWith(`.png`)) {
+        filename = filename.replace(/\.png$/i, `${suffix}.png`);
+    }
+    else {
+        filename = `${filename}${suffix}.png`;
     }
+    canvas_to_png_blob(canvas, png_dpi, scene, camera)
+        .then((blob) => download(blob, filename, `image/png`))
+        .catch((error) => console.error(`Error exporting PNG:`, error));
 }
 // Helper to ensure font-family is set on SVG root
 function set_svg_font_family(svg) {
     const style = svg.getAttribute(`style`) || ``;
     if (!/font-family/.test(style)) {
-        svg.setAttribute(`style`, `${style};font-family:sans-serif;`);
+        svg.setAttribute(`style`, `${style}${style ? `;` : ``}font-family:sans-serif;`);
     }
     // Also set as attribute for extra robustness
     svg.setAttribute(`font-family`, `sans-serif`);
 }
-// Export SVG element as SVG file
+// Serialize an SVG element to a standalone SVG string with proper XML headers.
+// Clones the element to avoid mutation, sets font-family/xmlns, and
+// prepends XML declaration + SVG DOCTYPE. Returns a complete SVG document string
+// suitable for saving to file or further processing.
+export function svg_to_svg_string(svg_element) {
+    const cloned_svg = svg_element.cloneNode(true);
+    set_svg_font_family(cloned_svg);
+    if (!cloned_svg.hasAttribute(`xmlns`)) {
+        cloned_svg.setAttribute(`xmlns`, `http://www.w3.org/2000/svg`);
+    }
+    const svg_string = new XMLSerializer().serializeToString(cloned_svg);
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">\n${svg_string}`;
+}
+// Export SVG element as SVG file (triggers browser download)
 export function export_svg_as_svg(svg_element, filename) {
+    if (!svg_element) {
+        console.warn(`SVG element not found for export`);
+        return;
+    }
     try {
-        if (!svg_element) {
-            console.warn(`SVG element not found for export`);
-            return;
-        }
-        // Clone the SVG to avoid modifying the original
-        const cloned_svg = svg_element.cloneNode(true);
-        // Ensure the SVG has proper dimensions and viewBox
-        const viewBox = svg_element.getAttribute(`viewBox`);
-        if (viewBox)
-            cloned_svg.setAttribute(`viewBox`, viewBox);
-        // Ensure font-family is set
-        set_svg_font_family(cloned_svg);
-        // Ensure xmlns is set
-        if (!cloned_svg.hasAttribute(`xmlns`)) {
-            cloned_svg.setAttribute(`xmlns`, `http://www.w3.org/2000/svg`);
-        }
-        // Convert SVG to string
-        const svg_string = new XMLSerializer().serializeToString(cloned_svg);
-        // Add XML declaration and DOCTYPE for proper SVG format
-        const svg_content = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">\n${svg_string}`;
+        const svg_content = svg_to_svg_string(svg_element);
         download(svg_content, filename, `image/svg+xml;charset=utf-8`);
     }
     catch (error) {
         console.error(`Error exporting SVG:`, error);
     }
 }
-// Export SVG element as PNG by converting to canvas
-export function export_svg_as_png(svg_element, filename, png_dpi = 150) {
-    try {
-        if (!svg_element) {
-            console.warn(`SVG element not found for PNG export`);
-            return;
-        }
-        // Get SVG dimensions
-        const viewBox = svg_element.getAttribute(`viewBox`);
-        if (!viewBox) {
-            console.warn(`SVG viewBox not found for PNG export`);
-            return;
-        }
-        const [, , width, height] = viewBox.split(` `).map(Number);
-        if (!width || !height) {
-            console.warn(`Invalid SVG dimensions for PNG export`);
-            return;
-        }
-        // Convert DPI to pixel dimensions
-        const resolution_multiplier = Math.min(png_dpi / 72, 10);
-        const pixel_width = Math.round(width * resolution_multiplier);
-        const pixel_height = Math.round(height * resolution_multiplier);
-        // Create a canvas for rendering
-        const canvas = document.createElement(`canvas`);
-        const ctx = canvas.getContext(`2d`);
-        if (!ctx) {
-            console.warn(`Canvas 2D context not available for PNG export`);
-            return;
-        }
-        // Set canvas dimensions
-        canvas.width = pixel_width;
-        canvas.height = pixel_height;
-        // Clone and patch SVG for font-family
-        const cloned_svg = svg_element.cloneNode(true);
-        set_svg_font_family(cloned_svg);
-        // Create an object URL from SVG Blob
-        const svg_string = new XMLSerializer().serializeToString(cloned_svg);
-        const svg_blob = new Blob([svg_string], { type: `image/svg+xml;charset=utf-8` });
-        const svg_data_url = URL.createObjectURL(svg_blob);
-        // Create an image element to load the SVG
+// Rasterize an SVG element to a PNG Blob at the given DPI.
+// Creates an offscreen canvas at the scaled resolution, draws the SVG via an
+// Image element, and returns the resulting PNG Blob. Rejects if viewBox is
+// missing or dimensions are invalid (zero width/height).
+// DPI is converted to a resolution multiplier relative to 72 DPI baseline, capped at 10x.
+export function svg_to_png_blob(svg_element, png_dpi = 150) {
+    const viewBox = svg_element.getAttribute(`viewBox`)?.trim();
+    if (!viewBox)
+        return Promise.reject(new Error(`SVG viewBox not found for PNG export`));
+    const parts = viewBox.split(/[\s,]+/).map(Number);
+    if (parts.length < 4 || !parts.every(Number.isFinite)) {
+        return Promise.reject(new Error(`Invalid SVG dimensions for PNG export`));
+    }
+    const [, , width, height] = parts;
+    if (!(width > 0) || !(height > 0)) {
+        return Promise.reject(new Error(`Invalid SVG dimensions for PNG export`));
+    }
+    if (!Number.isFinite(png_dpi) || png_dpi <= 0) {
+        return Promise.reject(new Error(`Invalid PNG DPI for export`));
+    }
+    const resolution_multiplier = Math.min(png_dpi / 72, 10);
+    const pixel_width = Math.round(width * resolution_multiplier);
+    const pixel_height = Math.round(height * resolution_multiplier);
+    const canvas = document.createElement(`canvas`);
+    const ctx = canvas.getContext(`2d`);
+    if (!ctx)
+        return Promise.reject(new Error(`Canvas 2D context not available`));
+    canvas.width = pixel_width;
+    canvas.height = pixel_height;
+    const cloned_svg = svg_element.cloneNode(true);
+    set_svg_font_family(cloned_svg);
+    const serialized = new XMLSerializer().serializeToString(cloned_svg);
+    const svg_blob = new Blob([serialized], { type: `image/svg+xml;charset=utf-8` });
+    const svg_data_url = URL.createObjectURL(svg_blob);
+    return new Promise((resolve, reject) => {
         const img = new Image();
         img.onload = () => {
             try {
@@ -173,27 +163,34 @@ export function export_svg_as_png(svg_element, filename, png_dpi = 150) {
                 ctx.drawImage(img, 0, 0, pixel_width, pixel_height);
                 canvas.toBlob((blob) => {
                     if (blob)
-                        download(blob, filename, `image/png`);
+                        resolve(blob);
                     else
-                        console.warn(`Failed to generate PNG blob`);
+                        reject(new Error(`Failed to generate PNG blob`));
                 }, `image/png`, 1);
             }
             catch (error) {
-                console.error(`Error during PNG generation:`, error);
+                reject(error);
             }
             finally {
                 URL.revokeObjectURL(svg_data_url);
             }
         };
         img.onerror = () => {
-            console.error(`Failed to load SVG for PNG export`);
             URL.revokeObjectURL(svg_data_url);
+            reject(new Error(`Failed to load SVG for PNG export`));
         };
         img.src = svg_data_url;
+    });
+}
+// Export SVG element as PNG (triggers browser download)
+export function export_svg_as_png(svg_element, filename, png_dpi = 150) {
+    if (!svg_element) {
+        console.warn(`SVG element not found for PNG export`);
+        return;
     }
-    catch (error) {
-        console.error(`Error exporting PNG:`, error);
-    }
+    svg_to_png_blob(svg_element, png_dpi)
+        .then((blob) => download(blob, filename, `image/png`))
+        .catch((error) => console.error(`Error exporting PNG:`, error));
 }
 // Generate FFmpeg command for WebM to MP4 conversion
 export function get_ffmpeg_conversion_command(input_filename) {
@@ -208,7 +205,8 @@ export async function export_trajectory_video(canvas, filename, options = {}) {
         typeof MediaRecorder === `undefined` ||
         !MediaRecorder.isTypeSupported(`video/webm;codecs=vp9`))
         throw new Error(`WebM video recording not supported in this browser`);
-    const renderer = canvas.__renderer;
+    const renderer_val = canvas.__renderer;
+    const renderer = is_webgl_renderer_like(renderer_val) ? renderer_val : undefined;
     // Store original renderer settings if changing resolution
     let orig_pixel_ratio;
     let orig_size;

package/dist/io/file-drop.d.ts

@@ -0,0 +1,7 @@
+export interface FileDropOptions {
+    allow: () => boolean;
+    on_drop: (content: string | ArrayBuffer, filename: string) => void | Promise<void>;
+    on_error?: (msg: string) => void;
+    set_loading?: (loading: boolean) => void;
+}
+export declare function create_file_drop_handler(opts: FileDropOptions): (event: DragEvent) => Promise<void>;

package/dist/io/file-drop.js

@@ -0,0 +1,43 @@
+// Shared file-drop handler composable for drag-and-drop file loading.
+import { decompress_file } from './decompress';
+import { handle_url_drop } from './url-drop';
+// Handles URL drops (from FilePicker), direct file drops with decompression,
+// loading state, and error reporting.
+export function create_file_drop_handler(opts) {
+    return async (event) => {
+        event.preventDefault();
+        if (!opts.allow())
+            return;
+        opts.set_loading?.(true);
+        let drop_filename = ``;
+        try {
+            let url_error;
+            const handled = await handle_url_drop(event, opts.on_drop).catch((exc) => {
+                url_error = exc instanceof Error ? exc.message : String(exc);
+                return false;
+            });
+            if (handled)
+                return;
+            const file = event.dataTransfer?.files[0];
+            if (!file) {
+                if (url_error)
+                    opts.on_error?.(`Failed to load from URL: ${url_error}`);
+                return;
+            }
+            drop_filename = file.name;
+            const { content, filename } = await decompress_file(file);
+            if (content)
+                await opts.on_drop(content, filename);
+        }
+        catch (exc) {
+            const detail = exc instanceof Error ? exc.message : String(exc);
+            const msg = drop_filename
+                ? `Failed to load file ${drop_filename}: ${detail}`
+                : `Failed to load file: ${detail}`;
+            opts.on_error?.(msg);
+        }
+        finally {
+            opts.set_loading?.(false);
+        }
+    };
+}

package/dist/io/index.d.ts

@@ -1,7 +1,7 @@
 export * from './decompress';
 export * from './export';
 export * from './fetch';
+export * from './file-drop';
 export * from './is-binary';
 export * from './types';
-export declare function handle_url_drop(drag_event: DragEvent, callback: (content: string | ArrayBuffer, filename: string) => Promise<void> | void): Promise<boolean>;
-export declare function load_from_url(url: string, callback: (content: string | ArrayBuffer, filename: string) => Promise<void> | void): Promise<void>;
+export * from './url-drop';

package/dist/io/index.js

@@ -1,117 +1,7 @@
-import { load_binary_traj } from '../trajectory/parse';
 export * from './decompress';
 export * from './export';
 export * from './fetch';
+export * from './file-drop';
 export * from './is-binary';
 export * from './types';
-// 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;
-    const file_info = JSON.parse(json_data);
-    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() || ``;
-    const extract_filename = (headers) => {
-        const fallback = url_basename;
-        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;
-    };
-    // Check for known binary file extensions
-    const known_bin_extensions = `h5 hdf5 traj npz pkl dat gz gzip zip bz2 xz brml`.split(` `);
-    if (known_bin_extensions.includes(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);
-        // 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 ([`h5`, `hdf5`].includes(ext)) {
-            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, extract_filename(resp.headers));
-        }
-        // 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, extract_filename(resp.headers));
-        }
-        if (resp.headers.get(`content-encoding`) === `gzip`) {
-            return callback(await resp.text(), extract_filename(resp.headers));
-        }
-        return callback(await resp.arrayBuffer(), extract_filename(resp.headers));
-    }
-    // Skip Range requests for known text formats to avoid production server issues
-    const known_text_extensions = `xyz extxyz json cif poscar yaml yml txt md py js ts css html xml`.split(` `);
-    // Include VASP files that don't have extensions (POSCAR, XDATCAR, CONTCAR)
-    const is_known_text = known_text_extensions.includes(ext) ||
-        url_basename.toLowerCase().match(/^(poscar|xdatcar|contcar)$/i);
-    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));
-                }
-            }
-        }
-        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));
-}
+export * from './url-drop';

package/dist/io/is-binary.js

@@ -1,6 +1,5 @@
 // Simplified binary detection
 export const is_binary = (content) => content.includes(`\0`) ||
-    // deno-lint-ignore no-control-regex
-    (content.match(/[\u0000-\u0008\u000E-\u001F\u007F-\u00FF]/g) || []).length /
-        content.length > 0.1 ||
+    (content.match(/[\u0000-\u0008\u000E-\u001F\u007F-\u00FF]/g) || []).length / content.length >
+        0.1 ||
     (content.match(/[\u0020-\u007E]/g) || []).length / content.length < 0.7;

package/dist/io/types.d.ts

@@ -1,6 +1,7 @@
 export interface FileInfo {
     name: string;
     url: string;
+    label?: string;
     type?: string;
     category?: string;
     category_icon?: string;

package/dist/io/url-drop.d.ts

@@ -0,0 +1,2 @@
+export declare function handle_url_drop(drag_event: DragEvent, callback: (content: string | ArrayBuffer, filename: string) => Promise<void> | void): Promise<boolean>;
+export declare function load_from_url(url: string, callback: (content: string | ArrayBuffer, filename: string) => Promise<void> | void): Promise<void>;