matterviz 0.4.1 → 0.4.3

package/dist/structure/format-detect.js

@@ -0,0 +1,20 @@
+import { CONFIG_DIRS_REGEX, STRUCT_KEYWORDS_REGEX, STRUCT_KEYWORDS_STRICT_REGEX, STRUCTURE_EXTENSIONS_REGEX, TRAJ_KEYWORDS_REGEX, VASP_FILES_REGEX, XDATCAR_REGEX, XYZ_EXTXYZ_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_REGEX.test(name))
+        return false;
+    if (STRUCTURE_EXTENSIONS_REGEX.test(name) || VASP_FILES_REGEX.test(name))
+        return true;
+    if (XYZ_EXTXYZ_REGEX.test(name))
+        return !TRAJ_KEYWORDS_REGEX.test(name);
+    if (/\.(?:yaml|yml|xml)$/i.test(name) && STRUCT_KEYWORDS_REGEX.test(name))
+        return true;
+    return (/\.json$/i.test(name) &&
+        STRUCT_KEYWORDS_STRICT_REGEX.test(name) &&
+        !TRAJ_KEYWORDS_REGEX.test(name) &&
+        !CONFIG_DIRS_REGEX.test(name));
+}

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';
@@ -18,13 +19,27 @@ 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;
@@ -77,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

@@ -1,5 +1,5 @@
 import { ATOMIC_WEIGHTS } from '../composition/parse';
-import { element_data } from '../element';
+import { element_by_symbol, element_data } from '../element';
 import * as math from '../math';
 export { default as Arrow } from './Arrow.svelte';
 export * from './atom-properties';
@@ -13,11 +13,20 @@ 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) {
@@ -33,21 +42,17 @@ export function get_element_counts(structure) {
 export function format_chemical_formula(structure, sort_fn) {
     // concatenate elements in a structure followed by their amount
     const elements = get_element_counts(structure);
-    const formula = [];
-    for (const element of sort_fn(Object.keys(elements))) {
+    const formula = sort_fn(Object.keys(elements)).map((element) => {
         const amount = elements[element] ?? 0;
-        if (amount === 1)
-            formula.push(element);
-        else
-            formula.push(`${element}<sub>${amount}</sub>`);
-    }
+        return amount === 1 ? element : `${element}<sub>${amount}</sub>`;
+    });
     return formula.join(` `);
 }
 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 = element_by_symbol.get(el1)?.electronegativity ?? 0;
+        const elec_neg2 = element_by_symbol.get(el2)?.electronegativity ?? 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;
@@ -55,6 +56,7 @@ export declare function parse_cif(content: string, wrap_fractional_coords?: bool
 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;
 export declare function parse_any_structure(content: string, filename: string): AnyStructure;
@@ -63,5 +65,4 @@ export declare function parse_optimade_from_raw(raw: unknown): ParsedStructure |
 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`;