matterviz 0.4.0 → 0.4.2

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();
@@ -117,9 +123,10 @@ export function generate_mtl_content(scene) {
             // Get diffuse color (main color)
             if (has_color_property(mat)) {
                 const color = mat.color;
-                lines.push(`Kd ${color.r.toFixed(6)} ${color.g.toFixed(6)} ${color.b.toFixed(6)}`);
+                const fmt = (val) => val.toFixed(6);
+                lines.push(`Kd ${fmt(color.r)} ${fmt(color.g)} ${fmt(color.b)}`);
                 // Ambient is typically a fraction of diffuse
-                lines.push(`Ka ${(color.r * 0.2).toFixed(6)} ${(color.g * 0.2).toFixed(6)} ${(color.b * 0.2).toFixed(6)}`);
+                lines.push(`Ka ${fmt(color.r * 0.2)} ${fmt(color.g * 0.2)} ${fmt(color.b * 0.2)}`);
             }
             else {
                 // Default white if no color
@@ -151,7 +158,28 @@ function extract_material_color(mat) {
 // Note: Threlte's InstancedMesh sets isInstancedMesh=true but type remains "Mesh"
 // Type guard for InstancedMesh (Three.js uses isInstancedMesh property, not exposed in Object3D type)
 const is_instanced_mesh = (obj) => obj.isInstancedMesh || obj.type === `InstancedMesh`;
-function convert_instanced_meshes_to_regular(scene) {
+// Resolve the export color for one instance of an InstancedMesh. Precedence:
+// gradient bond midpoints (shader bonds), then per-instance colors on meshes
+// flagged userData.per_instance_color (atoms/arrows keep a white base material
+// and store real colors in the instanceColor buffer), then the shared material
+// color (legacy threlte-instanced meshes carry an all-white instanceColor that
+// must NOT win), then instanceColor as a last resort. null = keep default.
+function resolve_instance_material_color(instanced_mesh, instance_idx, bond_colors, stored_color) {
+    const bond_color = bond_colors?.get(instance_idx);
+    if (bond_color)
+        return bond_color;
+    const { instanceColor } = instanced_mesh;
+    const per_instance = instanceColor
+        ? new Color(instanceColor.getX(instance_idx), instanceColor.getY(instance_idx), instanceColor.getZ(instance_idx))
+        : null;
+    if (instanced_mesh.userData.per_instance_color && per_instance)
+        return per_instance;
+    if (stored_color)
+        return new Color(stored_color.r, stored_color.g, stored_color.b);
+    return per_instance;
+}
+// @internal exported only for tests - not part of the public API.
+export function convert_instanced_meshes_to_regular(scene) {
     // STEP 1: Collect material colors from ORIGINAL scene BEFORE cloning
     // This is crucial because scene.clone() may not properly preserve Threlte's material colors
     const material_colors = new Map();
@@ -238,24 +266,10 @@ function convert_instanced_meshes_to_regular(scene) {
                 roughness: 0.5,
             });
             new_material.name = `material_${mesh_idx}_${idx}`;
-            // Apply the correct color
-            const bond_color = stored_bond_colors?.get(idx);
-            if (bond_color) {
-                // Bond with gradient color - use stored midpoint color
-                new_material.color.copy(bond_color);
-            }
-            else if (stored_color) {
-                // Atom with shared material color
-                new_material.color.setRGB(stored_color.r, stored_color.g, stored_color.b);
-            }
-            else if (instanced_mesh.instanceColor) {
-                // Fallback: per-instance colors from instanceColor attribute
-                const color_r = instanced_mesh.instanceColor.getX(idx);
-                const color_g = instanced_mesh.instanceColor.getY(idx);
-                const color_b = instanced_mesh.instanceColor.getZ(idx);
-                new_material.color.setRGB(color_r, color_g, color_b);
-            }
-            // If no color found, material stays default white
+            // Apply the correct color (null = no color found, material stays default white)
+            const resolved_color = resolve_instance_material_color(instanced_mesh, idx, stored_bond_colors, stored_color);
+            if (resolved_color)
+                new_material.color.copy(resolved_color);
             const mesh = new Mesh(cloned_geometry, new_material);
             // Combine base transform with instance transform
             const combined_matrix = new Matrix4();
@@ -341,6 +355,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)
@@ -355,30 +380,23 @@ export function structure_to_xyz_str(structure) {
     const formula = get_electro_neg_formula(structure, true);
     if (formula && formula !== `Unknown`)
         comment_parts.push(formula);
+    const lattice_matrix = `lattice` in structure && structure.lattice?.matrix?.length === 3
+        ? structure.lattice.matrix
+        : null;
     // 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))
+    if (lattice_matrix) {
+        const lattice_values = lattice_matrix
+            .flatMap((row) => row.map((value) => (Number.isFinite(value) ? value : 0).toFixed(8)))
             .join(` `);
         comment_parts.push(`Lattice="${lattice_values}"`);
     }
     const comment = comment_parts.length > 0 ? comment_parts.join(` `) : `Generated from structure`;
     lines.push(comment);
     // Cache converter for fractional→Cartesian (if lattice available)
-    const frac_to_cart = `lattice` in structure && structure.lattice?.matrix?.length === 3
-        ? math.create_frac_to_cart(structure.lattice.matrix)
-        : null;
+    const frac_to_cart = lattice_matrix ? math.create_frac_to_cart(lattice_matrix) : 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 +482,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 +513,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()) {
@@ -539,36 +545,28 @@ export function structure_to_poscar_str(structure) {
     lines.push(`1.0`); // Scale factor (1.0 for direct coordinates)
     const lattice = structure.lattice;
     if (lattice.matrix && Array.isArray(lattice.matrix) && lattice.matrix.length >= 3) {
-        // Convert 3x3 matrix to 3 vectors
-        const matrix = lattice.matrix;
-        lines.push(`${matrix[0][0].toFixed(8)} ${matrix[0][1].toFixed(8)} ${matrix[0][2].toFixed(8)}`);
-        lines.push(`${matrix[1][0].toFixed(8)} ${matrix[1][1].toFixed(8)} ${matrix[1][2].toFixed(8)}`);
-        lines.push(`${matrix[2][0].toFixed(8)} ${matrix[2][1].toFixed(8)} ${matrix[2][2].toFixed(8)}`);
+        // One line per lattice vector, exactly 3 components at 8-decimal fixed precision
+        for (const vec of lattice.matrix.slice(0, 3)) {
+            lines.push([vec[0], vec[1], vec[2]].map((coord) => coord.toFixed(8)).join(` `));
+        }
     }
     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 +577,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 +600,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/format-detect.d.ts

@@ -0,0 +1 @@
+export declare function is_structure_file(filename: string): boolean;

package/dist/structure/format-detect.js

@@ -0,0 +1,22 @@
+import { CONFIG_DIRS_REGEX, STRUCT_KEYWORDS_REGEX, STRUCT_KEYWORDS_STRICT_REGEX, STRUCTURE_EXTENSIONS_REGEX, TRAJ_KEYWORDS_REGEX, VASP_FILES_REGEX, } from '../constants';
+import { strip_compression_extensions } from '../io/decompress';
+// Filename-only detection lives apart from the parsers so lightweight callers
+// (desktop recents, file pickers) do not load YAML, structure math, and element
+// data just to choose an icon.
+export function is_structure_file(filename) {
+    const name = strip_compression_extensions(filename);
+    if (/\.(?:traj|xtc|h5|hdf5)$/i.test(name) || /xdatcar/i.test(name))
+        return false;
+    if (STRUCTURE_EXTENSIONS_REGEX.test(name) || VASP_FILES_REGEX.test(name))
+        return true;
+    if (/\.(?:xyz|extxyz)$/i.test(name))
+        return !TRAJ_KEYWORDS_REGEX.test(name);
+    if (/\.(?:yaml|yml|xml)$/i.test(name) && STRUCT_KEYWORDS_REGEX.test(name))
+        return true;
+    if (/\.json$/i.test(name) &&
+        STRUCT_KEYWORDS_STRICT_REGEX.test(name) &&
+        !TRAJ_KEYWORDS_REGEX.test(name) &&
+        !CONFIG_DIRS_REGEX.test(name))
+        return true;
+    return false;
+}

package/dist/structure/geometry.d.ts

@@ -0,0 +1,9 @@
+import { type Vec3 } from '../math';
+import { Quaternion } from 'three';
+export declare function quaternion_from_direction(direction: Vec3): Quaternion;
+export declare function rotation_from_direction(direction: Vec3): Vec3;
+export declare function cylinder_between(start: Vec3, end: Vec3): {
+    position: Vec3;
+    rotation: Vec3;
+    length: number;
+};

package/dist/structure/geometry.js

@@ -0,0 +1,27 @@
+// Three.js orientation helpers shared by 3D components (Arrow, Cylinder, Lattice,
+// SymmetryElements). Kept out of $lib/math, which is pure TS with no three.js dependency.
+import { add, EPS, scale, subtract } from '../math';
+import { Euler, Quaternion, Vector3 } from 'three';
+const UP = new Vector3(0, 1, 0);
+// Quaternion rotating the +Y axis onto `direction` (zero-length → identity). Cylinder and
+// cone geometries run along +Y, so this orients them toward an arbitrary direction.
+export function quaternion_from_direction(direction) {
+    const vec = new Vector3(...direction);
+    if (vec.lengthSq() < EPS * EPS)
+        return new Quaternion(); // ~zero length → no rotation
+    return new Quaternion().setFromUnitVectors(UP, vec.normalize());
+}
+// Same orientation as an Euler rotation tuple, for Threlte `rotation` props
+export function rotation_from_direction(direction) {
+    const { x, y, z } = new Euler().setFromQuaternion(quaternion_from_direction(direction));
+    return [x, y, z];
+}
+// Transform placing a +Y-aligned cylinder so it spans start→end: midpoint position,
+// orientation, and length (coincident points → length 0, identity rotation).
+export function cylinder_between(start, end) {
+    const delta = subtract(end, start);
+    const position = add(start, scale(delta, 0.5));
+    const rotation = rotation_from_direction(delta);
+    const length = Math.hypot(...delta);
+    return { position, rotation, length };
+}

package/dist/structure/index.d.ts

@@ -2,6 +2,7 @@ import type { CompositionType } from '../composition';
 import type { ElementSymbol } from '../element';
 import type { Vec3 } from '../math';
 import * as math from '../math';
+import type { CameraProjection } from '../settings';
 import type { ComponentProps } from 'svelte';
 import type LatticeComponent from './Lattice.svelte';
 import type { Pbc } from './pbc';
@@ -15,14 +16,30 @@ 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 StructureCarousel } from './StructureCarousel.svelte';
+export type StructureCarouselItem = {
+    id: string;
+    label: string;
+    subtitle?: string;
+    structure: AnyStructure;
+};
 export { default as StructureControls } from './StructureControls.svelte';
 export { default as StructureExportPane } from './StructureExportPane.svelte';
 export { default as StructureInfoPane } from './StructureInfoPane.svelte';
 export { default as StructureScene } from './StructureScene.svelte';
+export { default as StructureViewport } from './StructureViewport.svelte';
 export * from './supercell';
 export type MeasureMode = `distance` | `angle` | `edit-bonds` | `edit-atoms`;
 export type BondEditMode = `add` | `delete`;
+export type StructureView = {
+    label?: string;
+    projection?: CameraProjection;
+    direction?: Vec3;
+};
+export declare const DEFAULT_STRUCTURE_VIEWS: StructureView[];
 export type Species = {
     element: ElementSymbol;
     occu: number;
@@ -75,7 +92,7 @@ export type BondPair = {
 };
 export type { PerceivedBond, PerceptionOptions } from './bond-order-perception';
 export { compose_perceived_bonds, perceive_bond_orders, } from './bond-order-perception';
-export declare function get_element_counts(structure: AnyStructure): Partial<Record<"S" | "K" | "B" | "H" | "He" | "Li" | "Be" | "C" | "N" | "O" | "F" | "Ne" | "Na" | "Mg" | "Al" | "Si" | "P" | "Cl" | "Ar" | "Ca" | "Sc" | "Ti" | "V" | "Cr" | "Mn" | "Fe" | "Co" | "Ni" | "Cu" | "Zn" | "Ga" | "Ge" | "As" | "Se" | "Br" | "Kr" | "Rb" | "Sr" | "Y" | "Zr" | "Nb" | "Mo" | "Tc" | "Ru" | "Rh" | "Pd" | "Ag" | "Cd" | "In" | "Sn" | "Sb" | "Te" | "I" | "Xe" | "Cs" | "Ba" | "La" | "Ce" | "Pr" | "Nd" | "Pm" | "Sm" | "Eu" | "Gd" | "Tb" | "Dy" | "Ho" | "Er" | "Tm" | "Yb" | "Lu" | "Hf" | "Ta" | "W" | "Re" | "Os" | "Ir" | "Pt" | "Au" | "Hg" | "Tl" | "Pb" | "Bi" | "Po" | "At" | "Rn" | "Fr" | "Ra" | "Ac" | "Th" | "Pa" | "U" | "Np" | "Pu" | "Am" | "Cm" | "Bk" | "Cf" | "Es" | "Fm" | "Md" | "No" | "Lr" | "Rf" | "Db" | "Sg" | "Bh" | "Hs" | "Mt" | "Ds" | "Rg" | "Cn" | "Nh" | "Fl" | "Mc" | "Lv" | "Ts" | "Og", number>>;
+export declare function get_element_counts(structure: AnyStructure): Partial<Record<"Ac" | "Ag" | "Al" | "Am" | "Ar" | "As" | "At" | "Au" | "B" | "Ba" | "Be" | "Bh" | "Bi" | "Bk" | "Br" | "C" | "Ca" | "Cd" | "Ce" | "Cf" | "Cl" | "Cm" | "Co" | "Cr" | "Cs" | "Cu" | "Db" | "Dy" | "Er" | "Es" | "Eu" | "F" | "Fe" | "Fm" | "Fr" | "Ga" | "Gd" | "Ge" | "H" | "He" | "Hf" | "Hg" | "Ho" | "Hs" | "I" | "In" | "Ir" | "K" | "Kr" | "La" | "Li" | "Lr" | "Lu" | "Md" | "Mg" | "Mn" | "Mo" | "Mt" | "N" | "Na" | "Nb" | "Nd" | "Ne" | "Ni" | "No" | "Np" | "O" | "Os" | "P" | "Pa" | "Pb" | "Pd" | "Pm" | "Po" | "Pr" | "Pt" | "Pu" | "Ra" | "Rb" | "Re" | "Rf" | "Rh" | "Rn" | "Ru" | "S" | "Sb" | "Sc" | "Se" | "Sg" | "Si" | "Sm" | "Sn" | "Sr" | "Ta" | "Tb" | "Tc" | "Te" | "Th" | "Ti" | "Tl" | "Tm" | "U" | "V" | "W" | "Xe" | "Y" | "Yb" | "Zn" | "Zr" | "Ds" | "Rg" | "Cn" | "Nh" | "Fl" | "Mc" | "Lv" | "Ts" | "Og", number>>;
 export declare function format_chemical_formula(structure: AnyStructure, sort_fn: (symbols: ElementSymbol[]) => ElementSymbol[]): string;
 export declare function format_formula_by_electronegativity(structure: AnyStructure): string;
 export declare const atomic_radii: CompositionType;

package/dist/structure/index.js

@@ -10,12 +10,23 @@ 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 StructureCarousel } from './StructureCarousel.svelte';
 export { default as StructureControls } from './StructureControls.svelte';
 export { default as StructureExportPane } from './StructureExportPane.svelte';
 export { default as StructureInfoPane } from './StructureInfoPane.svelte';
 export { default as StructureScene } from './StructureScene.svelte';
+export { default as StructureViewport } from './StructureViewport.svelte';
 export * from './supercell';
+// Ovito-like default 2x2 view set: one perspective + three orthographic axis views.
+export const DEFAULT_STRUCTURE_VIEWS = [
+    { label: `Perspective`, projection: `perspective`, direction: [1, 0.3, 0.8] },
+    { label: `Front`, projection: `orthographic`, direction: [0, 0, 1] },
+    { label: `Top`, projection: `orthographic`, direction: [0, 1, 0] },
+    { label: `Right`, projection: `orthographic`, direction: [1, 0, 0] },
+];
 export const LATTICE_PARAM_KEYS = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`];
 export { compose_perceived_bonds, perceive_bond_orders, } from './bond-order-perception';
 export function get_element_counts(structure) {
@@ -41,11 +52,13 @@ export function format_chemical_formula(structure, sort_fn) {
     }
     return formula.join(` `);
 }
+// Electronegativity by element symbol (0 when missing), for O(1) sort comparisons
+const electronegativity_by_symbol = new Map(element_data.map((el) => [el.symbol, el.electronegativity ?? 0]));
 export function format_formula_by_electronegativity(structure) {
     // concatenate elements in a structure followed by their amount sorted by electronegativity
     return format_chemical_formula(structure, (symbols) => symbols.sort((el1, el2) => {
-        const elec_neg1 = element_data.find((el) => el.symbol === el1)?.electronegativity ?? 0;
-        const elec_neg2 = element_data.find((el) => el.symbol === el2)?.electronegativity ?? 0;
+        const elec_neg1 = electronegativity_by_symbol.get(el1) ?? 0;
+        const elec_neg2 = electronegativity_by_symbol.get(el2) ?? 0;
         // Sort by electronegativity (ascending), then alphabetically for ties
         if (elec_neg1 !== elec_neg2)
             return elec_neg1 - elec_neg2;

package/dist/structure/measure.d.ts

@@ -3,5 +3,5 @@ import type { Pbc } from './pbc';
 export type AngleMode = `degrees` | `radians`;
 export declare const MAX_SELECTED_SITES = 8;
 export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, converters?: LatticeConverters, pbc?: Pbc): Vec3;
-export declare function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3, converters?: LatticeConverters, pbc?: Pbc): number;
+export { pbc_dist as distance_pbc } from '../math';
 export declare function angle_between_vectors(v1: Vec3, v2: Vec3, mode?: AngleMode): number;

package/dist/structure/measure.js

@@ -1,5 +1,5 @@
 // functions for measuring distances and angles between structure sites
-import { min_image_displacement, subtract } from '../math';
+import { dot, min_image_displacement, subtract, to_degrees } from '../math';
 export const MAX_SELECTED_SITES = 8;
 // Calculate minimum image displacement between two points under PBC
 // If lattice_matrix is null/undefined, returns Euclidean displacement.
@@ -9,22 +9,16 @@ export function displacement_pbc(from, to, lattice_matrix, converters, pbc) {
         return subtract(to, from);
     return min_image_displacement(from, to, lattice_matrix, converters, pbc);
 }
-export function distance_pbc(a, b, lattice_matrix, converters, pbc) {
-    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix, converters, pbc);
-    return Math.hypot(dx, dy, dz);
-}
+// Minimum-image distance between two Cartesian points
+export { pbc_dist as distance_pbc } from '../math';
 export function angle_between_vectors(v1, v2, mode = `degrees`) {
     const n1 = Math.hypot(v1[0], v1[1], v1[2]);
     const n2 = Math.hypot(v2[0], v2[1], v2[2]);
     if (n1 === 0 || n2 === 0)
         return 0;
-    // Dot product of vectors
-    const dot = v1[0] * v2[0] + v1[1] * v2[1] + v1[2] * v2[2];
-    // Normalize dot product to get cosine
-    const cos_angle = dot / (n1 * n2);
-    // Clamp to [-1, 1] to avoid numerical errors with acos
+    // Normalize dot product to get cosine, clamped to [-1, 1] to avoid acos NaN
+    const cos_angle = dot(v1, v2) / (n1 * n2);
     const clamped = Math.max(-1, Math.min(1, cos_angle));
-    // Compute angle using arccos
     const ang = Math.acos(clamped);
-    return mode === `degrees` ? (ang * 180) / Math.PI : ang;
+    return mode === `degrees` ? to_degrees(ang) : ang;
 }

package/dist/structure/parse.d.ts

@@ -2,6 +2,7 @@ import type { OptimadeStructure } from '../api/optimade';
 import * as math from '../math';
 import type { AnyStructure, Crystal, Site, StructureProperties } from './';
 import type { Pbc } from './pbc';
+export { is_structure_file } from './format-detect';
 export interface ParsedStructure {
     sites: Site[];
     properties?: StructureProperties;
@@ -54,13 +55,14 @@ 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 ensure_lattice_params(structure: ParsedStructure): 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;
 export declare const is_optimade_raw: (raw: unknown) => boolean;
 export declare function optimade_to_crystal(optimade_structure: OptimadeStructure): Crystal | null;
-export declare function is_structure_file(filename: string): boolean;
 export declare const detect_structure_type: (filename: string, content: string) => `crystal` | `molecule` | `unknown`;