matterviz 0.4.0 → 0.4.1

package/dist/structure/export.js

@@ -1,11 +1,13 @@
 import { get_electro_neg_formula } from '../composition';
 import { download } from '../io/fetch';
 import * as math from '../math';
+import { is_plain_object } from '../utils';
 import { Color, Group, Matrix4, Mesh, MeshStandardMaterial, ShaderMaterial } from 'three';
 import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
 import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js';
-// Type guard to check if a material has a color property (duck typing for bundler compatibility)
-// Uses duck typing to work across different Three.js instances (Threlte vs vanilla Three.js)
+// @internal exported only for tests - not part of the public API.
+// Type guard to check if a material has a color property (duck typing for bundler
+// compatibility across different Three.js instances - Threlte vs vanilla Three.js).
 export function has_color_property(mat) {
     if (!(`color` in mat))
         return false;
@@ -47,8 +49,9 @@ function convert_shader_to_standard(shader_mat) {
     standard_mat.name = shader_mat.name || `converted_shader_material`;
     return standard_mat;
 }
-// Extract bond gradient colors from geometry attributes for a specific instance
-// Returns midpoint color between start and end colors for the bond
+// @internal exported only for tests - not part of the public API.
+// Extract bond gradient colors from geometry attributes for a specific instance.
+// Returns midpoint color between start and end colors for the bond.
 export function extract_bond_color_for_instance(geometry, instance_idx) {
     const color_start_attr = geometry.getAttribute(`instanceColorStart`);
     const color_end_attr = geometry.getAttribute(`instanceColorEnd`);
@@ -70,8 +73,10 @@ export function extract_bond_color_for_instance(geometry, instance_idx) {
     const [mid_r, mid_g, mid_b] = math.scale(math.add(start_rgb, end_rgb), 0.5);
     return new Color(mid_r, mid_g, mid_b);
 }
-// Remove custom/non-standard attributes from geometry that cause export issues
-// Standard GLTF attributes: position, normal, tangent, texcoord_N, color_N, joints_N, weights_N
+// @internal exported only for tests - not part of the public API.
+// Remove custom/non-standard attributes from geometry that cause export issues.
+// Standard GLTF attributes: position, normal, tangent, texcoord_N, color_N, joints_N,
+// weights_N.
 export function clean_geometry_for_export(geometry) {
     const standard_attrs = new Set([
         `position`,
@@ -98,7 +103,8 @@ export function clean_geometry_for_export(geometry) {
         geometry.deleteAttribute(attr_name);
     }
 }
-// Generate MTL (Wavefront Material) content from scene materials
+// @internal exported only for tests - not part of the public API.
+// Generate MTL (Wavefront Material) content from scene materials.
 export function generate_mtl_content(scene) {
     const lines = [`# MTL file generated by MatterViz`, ``];
     const processed_materials = new Set();
@@ -341,6 +347,17 @@ export function create_structure_filename(structure, extension) {
     const base_name = parts.length > 0 ? parts.join(`-`) : `structure`;
     return `${base_name}.${extension}`;
 }
+// First species' element of a site, or `X` when the site has no species
+const site_element = (site) => site.species?.[0]?.element || `X`;
+// Fractional coordinates from abc, falling back to converting xyz; throws when neither
+// is available. idx (when given) is included in the error message.
+function get_frac_coords(site, cart_to_frac, idx) {
+    if (Array.isArray(site.abc) && site.abc.length >= 3)
+        return site.abc.slice(0, 3);
+    if (site.xyz?.length >= 3 && cart_to_frac)
+        return cart_to_frac(site.xyz.slice(0, 3));
+    throw new Error(`No valid coordinates found for site${idx === undefined ? `` : ` ${idx}`}`);
+}
 // Generate XYZ content string without saving
 export function structure_to_xyz_str(structure) {
     if (!structure?.sites)
@@ -358,8 +375,7 @@ export function structure_to_xyz_str(structure) {
     // Include extended XYZ lattice information when available so round-trips preserve lattice
     if (`lattice` in structure && structure.lattice?.matrix?.length === 3) {
         const lattice_values = structure.lattice.matrix
-            .flat()
-            .map((value) => (Number.isFinite(value) ? value : 0).toFixed(8))
+            .flatMap((row) => row.map((value) => (Number.isFinite(value) ? value : 0).toFixed(8)))
             .join(` `);
         comment_parts.push(`Lattice="${lattice_values}"`);
     }
@@ -371,14 +387,7 @@ export function structure_to_xyz_str(structure) {
         : null;
     // Atom lines: element symbol followed by x, y, z coordinates
     for (const site of structure.sites) {
-        // Extract element symbol from species
-        let element_symbol = `X`; // default fallback
-        if (site.species && Array.isArray(site.species) && site.species.length > 0) {
-            // species is an array of Species objects with element property
-            const first_species = site.species[0];
-            if (first_species && `element` in first_species && first_species.element)
-                element_symbol = first_species.element;
-        }
+        const element_symbol = site_element(site);
         // Get coordinates - prefer xyz; fallback to abc (converted to cartesian if lattice available)
         let coords;
         if (site.xyz && Array.isArray(site.xyz) && site.xyz.length >= 3) {
@@ -464,11 +473,8 @@ export function structure_to_cif_str(structure) {
         lines.push(`_cell_angle_gamma ${lattice.gamma.toFixed(6)}`);
     }
     // Space group information
-    if (`symmetry` in structure &&
-        structure.symmetry &&
-        typeof structure.symmetry === `object`) {
-        const symmetry = structure.symmetry;
-        const { space_group_number, space_group_symbol } = symmetry;
+    if (`symmetry` in structure && is_plain_object(structure.symmetry)) {
+        const { space_group_number, space_group_symbol } = structure.symmetry;
         if (typeof space_group_symbol === `string` && space_group_symbol) {
             // Quote H-M symbols: their spaces (e.g. 'F m -3 m') would break CIF tokenization
             lines.push(`_space_group_name_H-M_alt '${space_group_symbol}'`);
@@ -498,16 +504,7 @@ export function structure_to_cif_str(structure) {
         const site = structure.sites[idx];
         if (!site)
             continue; // Skip if site is undefined
-        // Get fractional coordinates
-        let frac_coords;
-        if (Array.isArray(site.abc) && site.abc.length >= 3) {
-            frac_coords = site.abc.slice(0, 3);
-        }
-        else if (site.xyz?.length >= 3 && cart_to_frac) {
-            frac_coords = cart_to_frac(site.xyz);
-        }
-        else
-            throw new Error(`No valid coordinates found for site ${idx}`);
+        const frac_coords = get_frac_coords(site, cart_to_frac, idx);
         const coords_str = frac_coords.map((coord) => coord.toFixed(8)).join(` `);
         const species_list = site.species?.length ? site.species : [{ element: `X`, occu: 1 }];
         for (const [spec_idx, species] of species_list.entries()) {
@@ -548,27 +545,20 @@ export function structure_to_poscar_str(structure) {
     else {
         throw new Error(`No valid lattice matrix for POSCAR export`);
     }
-    // Count atoms by element
-    const element_counts = new Map();
-    const element_symbols = [];
+    // Group sites by element in one pass, preserving first-appearance element order
+    const sites_by_element = new Map();
     for (const site of structure.sites) {
-        let element_symbol = `X`; // default fallback
-        if (site.species && Array.isArray(site.species) && site.species.length > 0) {
-            const first_species = site.species[0];
-            if (first_species && `element` in first_species && first_species.element) {
-                element_symbol = first_species.element;
-            }
-        }
-        if (!element_counts.has(element_symbol)) {
-            element_counts.set(element_symbol, 0);
-            element_symbols.push(element_symbol);
-        }
-        element_counts.set(element_symbol, Number(element_counts.get(element_symbol)) + 1);
+        const element_symbol = site_element(site);
+        const group = sites_by_element.get(element_symbol);
+        if (group)
+            group.push(site);
+        else
+            sites_by_element.set(element_symbol, [site]);
     }
     // Element symbols line
-    lines.push(element_symbols.join(` `));
+    lines.push([...sites_by_element.keys()].join(` `));
     // Atom counts line
-    lines.push(element_symbols.map((el) => element_counts.get(el)).join(` `));
+    lines.push([...sites_by_element.values()].map((group) => group.length).join(` `));
     // Check if any site has selective dynamics
     const has_selective_dynamics = structure.sites.some((site) => site.properties?.selective_dynamics);
     if (has_selective_dynamics) {
@@ -579,38 +569,19 @@ export function structure_to_poscar_str(structure) {
     // Cache inverse transpose for Cartesian→fractional conversion (avoids recomputing per site)
     const cart_to_frac = lattice.matrix?.length === 3 ? math.create_cart_to_frac(lattice.matrix) : null;
     // Atom coordinates grouped by element
-    for (const element_symbol of element_symbols) {
-        for (const site of structure.sites) {
-            let site_element = `X`;
-            if (site.species && Array.isArray(site.species) && site.species.length > 0) {
-                const first_species = site.species[0];
-                if (first_species && `element` in first_species && first_species.element) {
-                    site_element = first_species.element;
-                }
-            }
-            if (site_element === element_symbol) {
-                // Get fractional coordinates
-                let frac_coords;
-                if (site.abc && Array.isArray(site.abc) && site.abc.length >= 3) {
-                    frac_coords = site.abc.slice(0, 3);
-                }
-                else if (site.xyz?.length >= 3 && cart_to_frac) {
-                    frac_coords = cart_to_frac(site.xyz.slice(0, 3));
-                }
-                else {
-                    throw new Error(`No valid coordinates found for site`);
-                }
-                let selective_dynamics_str = ``;
-                if (has_selective_dynamics) {
-                    const sel_dyn = (site.properties?.selective_dynamics ?? [
-                        true,
-                        true,
-                        true,
-                    ]);
-                    selective_dynamics_str = ` ${sel_dyn[0] ? `T` : `F`} ${sel_dyn[1] ? `T` : `F`} ${sel_dyn[2] ? `T` : `F`}`;
-                }
-                lines.push(`${frac_coords[0].toFixed(8)} ${frac_coords[1].toFixed(8)} ${frac_coords[2].toFixed(8)}${selective_dynamics_str}`);
+    for (const group of sites_by_element.values()) {
+        for (const site of group) {
+            const frac_coords = get_frac_coords(site, cart_to_frac);
+            let selective_dynamics_str = ``;
+            if (has_selective_dynamics) {
+                const sel_dyn = (site.properties?.selective_dynamics ?? [
+                    true,
+                    true,
+                    true,
+                ]);
+                selective_dynamics_str = ` ${sel_dyn[0] ? `T` : `F`} ${sel_dyn[1] ? `T` : `F`} ${sel_dyn[2] ? `T` : `F`}`;
             }
+            lines.push(`${frac_coords[0].toFixed(8)} ${frac_coords[1].toFixed(8)} ${frac_coords[2].toFixed(8)}${selective_dynamics_str}`);
         }
     }
     return lines.join(`\n`);
@@ -621,51 +592,22 @@ export function structure_to_json_str(structure) {
         throw new Error(`No structure to export`);
     return JSON.stringify(structure, null, 2);
 }
-// Export structure as CIF format
-export function export_structure_as_cif(structure) {
-    try {
-        const content = structure_to_cif_str(structure);
-        const filename = create_structure_filename(structure, `cif`);
-        download(content, filename, `chemical/x-cif`);
-    }
-    catch (error) {
-        console.error(`Failed to export CIF:`, error);
-    }
-}
-// Export structure as VASP POSCAR format
-export function export_structure_as_poscar(structure) {
-    try {
-        const content = structure_to_poscar_str(structure);
-        const filename = create_structure_filename(structure, `poscar`);
-        download(content, filename, `text/plain`);
-    }
-    catch (error) {
-        console.error(`Failed to export POSCAR:`, error);
-    }
-}
-// Export structure as XYZ format. Format specification:
-// - Line 1: Number of atoms
-// - Line 2: Comment line (structure ID, formula, etc.)
-// - Remaining lines: Element symbol followed by x, y, z coordinates (in Angstrom)
-export function export_structure_as_xyz(structure) {
-    try {
-        const xyz_content = structure_to_xyz_str(structure);
-        const filename = create_structure_filename(structure, `xyz`);
-        download(xyz_content, filename, `text/plain`);
-    }
-    catch (error) {
-        console.error(`Error exporting XYZ:`, error);
-    }
-}
-// Export structure in pymatgen JSON format
-export function export_structure_as_json(structure) {
+// Text export formats: serializer + file extension + MIME type per format
+export const STRUCT_TEXT_FORMATS = {
+    json: { to_str: structure_to_json_str, ext: `json`, mime: `application/json` },
+    xyz: { to_str: structure_to_xyz_str, ext: `xyz`, mime: `text/plain` },
+    cif: { to_str: structure_to_cif_str, ext: `cif`, mime: `chemical/x-cif` },
+    poscar: { to_str: structure_to_poscar_str, ext: `poscar`, mime: `text/plain` },
+};
+// Serialize structure in the given text format and trigger a browser download
+export function export_structure_as(fmt, structure) {
+    const { to_str, ext, mime } = STRUCT_TEXT_FORMATS[fmt];
     try {
-        const data = structure_to_json_str(structure);
-        const filename = create_structure_filename(structure, `json`);
-        download(data, filename, `application/json`);
+        const content = to_str(structure);
+        download(content, create_structure_filename(structure, ext), mime);
     }
     catch (error) {
-        console.error(`Error exporting JSON:`, error);
+        console.error(`Failed to export ${fmt.toUpperCase()}:`, error);
     }
 }
 // Export Three.js scene as GLB (binary GLTF) file

package/dist/structure/index.d.ts

@@ -15,6 +15,8 @@ export { default as CanvasTooltip } from './CanvasTooltip.svelte';
 export { default as Cylinder } from './Cylinder.svelte';
 export { default as Lattice } from './Lattice.svelte';
 export * from './pbc';
+export * from './polyhedra';
+export * from './site';
 export { default as Structure } from './Structure.svelte';
 export { default as StructureControls } from './StructureControls.svelte';
 export { default as StructureExportPane } from './StructureExportPane.svelte';

package/dist/structure/index.js

@@ -10,6 +10,8 @@ export { default as CanvasTooltip } from './CanvasTooltip.svelte';
 export { default as Cylinder } from './Cylinder.svelte';
 export { default as Lattice } from './Lattice.svelte';
 export * from './pbc';
+export * from './polyhedra';
+export * from './site';
 export { default as Structure } from './Structure.svelte';
 export { default as StructureControls } from './StructureControls.svelte';
 export { default as StructureExportPane } from './StructureExportPane.svelte';

package/dist/structure/parse.d.ts

@@ -54,9 +54,10 @@ export declare function parse_xyz(content: string): ParsedStructure | null;
 export declare function parse_cif(content: string, wrap_fractional_coords?: boolean, strict?: boolean): ParsedStructure | null;
 export type CellType = `primitive_cell` | `unit_cell` | `supercell` | `phonon_primitive_cell` | `phonon_supercell` | `auto`;
 export declare function parse_phonopy_yaml(content: string, cell_type?: CellType): ParsedStructure | null;
+export declare function is_parsed_structure(obj: unknown): obj is ParsedStructure;
 export declare function normalize_fractional_coords(structure: ParsedStructure): ParsedStructure;
-export declare function parse_structure_file(content: string, filename?: string): ParsedStructure | null;
-export declare function parse_any_structure(content: string, filename: string): AnyStructure | null;
+export declare function parse_structure_file(content: string, filename?: string): ParsedStructure;
+export declare function parse_any_structure(content: string, filename: string): AnyStructure;
 export declare function parse_optimade_json(content: string): ParsedStructure | null;
 export declare function parse_optimade_from_raw(raw: unknown): ParsedStructure | null;
 export declare function is_optimade_json(content: string): boolean;