matterviz 0.3.2 → 0.3.4

package/dist/structure/StructureScene.svelte.d.ts

@@ -1,14 +1,14 @@
+import type { D3InterpolateName } from '../colors';
 import type { ElementSymbol } from '../element';
 import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types';
 import type { Vec3 } from '../math';
-import { type CameraProjection, type ShowBonds } from '../settings';
+import type { CameraProjection, ShowBonds, VectorColorMode, VectorLayerConfig } from '../settings';
 import type { AnyStructure, MeasureMode, Site } from './';
 import { Lattice } from './';
 import type { AtomColorConfig } from './atom-properties';
 import type { MoyoDataset } from '@spglib/moyo-wasm';
 import * as extras from '@threlte/extras';
-import type { ComponentProps } from 'svelte';
-import { type Snippet } from 'svelte';
+import { type ComponentProps, type Snippet } from 'svelte';
 import { SvelteMap } from 'svelte/reactivity';
 import { type Camera, type Scene } from 'three';
 import type { BondingStrategy } from './bonding';
@@ -31,9 +31,17 @@ type $$ComponentProps = {
     show_bonds?: ShowBonds;
     show_site_labels?: boolean;
     show_site_indices?: boolean;
-    show_force_vectors?: boolean;
-    force_scale?: number;
-    force_color?: string;
+    vector_configs?: Record<string, VectorLayerConfig>;
+    vector_scale?: number;
+    vector_color?: string;
+    vector_color_mode?: VectorColorMode;
+    vector_color_scale?: D3InterpolateName;
+    vector_normalize?: boolean;
+    vector_uniform_thickness?: boolean;
+    vector_origin_gap?: number;
+    vector_shaft_radius?: number;
+    vector_arrow_head_radius?: number;
+    vector_arrow_head_length?: number;
     gizmo?: boolean | ComponentProps<typeof extras.Gizmo>;
     hovered_idx?: number | null;
     hovered_site?: Site | null;
@@ -91,6 +99,6 @@ type $$ComponentProps = {
     volumetric_data?: VolumetricData;
     isosurface_settings?: IsosurfaceSettings;
 };
-declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "scene" | "camera" | "orbit_controls" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "selected_sites" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "measured_sites" | "added_bonds" | "removed_bonds" | "active_sites" | "rotation_target_ref" | "initial_computed_zoom" | "add_atom_mode" | "add_element" | "dragging_atoms">;
+declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "vector_configs" | "camera" | "scene" | "orbit_controls" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "site_radius_overrides" | "selected_sites" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "measured_sites" | "added_bonds" | "removed_bonds" | "active_sites" | "rotation_target_ref" | "initial_computed_zoom" | "add_atom_mode" | "add_element" | "dragging_atoms">;
 type StructureScene = ReturnType<typeof StructureScene>;
 export default StructureScene;

package/dist/structure/atom-properties.js

@@ -1,6 +1,7 @@
 // Utility functions for computing atom properties and applying color scales
 import { calc_coordination_nums } from '../coordination';
 import * as math from '../math';
+import { wrap_to_unit_cell } from './pbc';
 import { rgb } from 'd3-color';
 import * as d3_sc from 'd3-scale-chromatic';
 const GRAY = `#808080`;
@@ -15,7 +16,7 @@ const get_interpolator = (scale) => {
     return interp_fn;
 };
 const to_hex = (interp_fn, t) => rgb(interp_fn(t)).formatHex();
-const build_image_site = (site, lattice_T, offset, orig_idx) => {
+const build_image_site = (site, frac_to_cart, offset, orig_idx) => {
     const img_abc = [
         site.abc[0] + offset[0],
         site.abc[1] + offset[1],
@@ -24,7 +25,7 @@ const build_image_site = (site, lattice_T, offset, orig_idx) => {
     return {
         ...site,
         abc: img_abc,
-        xyz: math.mat3x3_vec3_multiply(lattice_T, img_abc),
+        xyz: frac_to_cart(img_abc),
         properties: { ...site.properties, orig_site_idx: orig_idx },
     };
 };
@@ -85,23 +86,23 @@ function expand_structure_for_pbc(structure) {
         return structure;
     }
     const { sites, lattice } = structure;
-    const lattice_T = math.transpose_3x3_matrix(lattice.matrix);
+    const frac_to_cart = math.create_frac_to_cart(lattice.matrix);
     const pbc = lattice.pbc ?? [true, true, true];
     const all_offsets = get_all_offsets(pbc);
     // Small structures: expand all atoms
     if (sites.length < 20 || !pbc.some((periodic) => periodic)) {
-        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map((offset) => build_image_site(site, lattice_T, offset, orig_idx)));
+        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx)));
         return { ...structure, sites: [...sites, ...image_sites] };
     }
     // Large structures: only expand atoms near boundaries (within 5Å bond distance)
     const cutoff = [5.0 / lattice.a, 5.0 / lattice.b, 5.0 / lattice.c];
     const image_sites = sites.flatMap((site, orig_idx) => {
-        const norm = site.abc.map((coord) => coord - Math.floor(coord));
+        const norm = wrap_to_unit_cell(site.abc);
         return all_offsets
             .filter(([dx, dy, dz]) => (dx === 0 || (dx === -1 ? norm[0] <= cutoff[0] : norm[0] >= 1 - cutoff[0])) &&
             (dy === 0 || (dy === -1 ? norm[1] <= cutoff[1] : norm[1] >= 1 - cutoff[1])) &&
             (dz === 0 || (dz === -1 ? norm[2] <= cutoff[2] : norm[2] >= 1 - cutoff[2])))
-            .map((offset) => build_image_site(site, lattice_T, offset, orig_idx));
+            .map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx));
     });
     return { ...structure, sites: [...sites, ...image_sites] };
 }
@@ -110,8 +111,7 @@ export function get_coordination_colors(structure, strategy = `electroneg_ratio`
     // Check if structure has periodic boundary conditions
     const has_lattice = `lattice` in structure && structure.lattice !== undefined;
     const pbc = has_lattice ? structure.lattice.pbc : undefined;
-    const has_pbc = has_lattice &&
-        (pbc === undefined || pbc.some((is_periodic) => is_periodic));
+    const has_pbc = has_lattice && (pbc === undefined || pbc.some((is_periodic) => is_periodic));
     // For PBC structures, expand with images from neighboring cells for accurate coordination
     const coord_structure = has_pbc ? expand_structure_for_pbc(structure) : structure;
     // Calculate coordination numbers on the (potentially expanded) structure

package/dist/structure/bonding.js

@@ -2,7 +2,9 @@
 import { element_data } from '../element';
 import * as math from '../math';
 const element_lookup = new Map(element_data.map((el) => [el.symbol, el]));
-const covalent_radii = new Map(element_data.filter((el) => el.covalent_radius !== null).map((el) => [el.symbol, el.covalent_radius]));
+const covalent_radii = new Map(element_data
+    .filter((el) => el.covalent_radius !== null)
+    .map((el) => [el.symbol, el.covalent_radius]));
 // Get the species with highest occupancy from a site.
 const get_majority_species = (site) => (site.species ?? []).reduce((max_species, species) => (species.occu > max_species.occu ? species : max_species), site.species?.[0] ?? { element: ``, occu: -1 });
 // Helper to extract numeric index from site properties
@@ -67,6 +69,7 @@ export function compute_bond_transform(pos_1, pos_2) {
         (pos_1[2] + pos_2[2]) / 2,
     ];
     return new Float32Array([
+        // Return flattened column-major 4x4 matrix for Three.js
         ...[m00, m10, m20, 0],
         ...[m01 * height, m11 * height, m21 * height, 0],
         ...[m02, m12, m22, 0],
@@ -263,17 +266,13 @@ export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area =
     for (let idx_a = 0; idx_a < sites.length - 1; idx_a++) {
         const [x1, y1, z1] = sites[idx_a].xyz;
         const majority_a = get_majority_species(sites[idx_a]);
-        const radius_a = majority_a.element
-            ? covalent_radii.get(majority_a.element)
-            : undefined;
+        const radius_a = majority_a.element ? covalent_radii.get(majority_a.element) : undefined;
         for (const idx_b of get_candidates(sites[idx_a].xyz, sites, spatial)) {
             if (idx_b <= idx_a)
                 continue;
             const [x2, y2, z2] = sites[idx_b].xyz;
             const majority_b = get_majority_species(sites[idx_b]);
-            const radius_b = majority_b.element
-                ? covalent_radii.get(majority_b.element)
-                : undefined;
+            const radius_b = majority_b.element ? covalent_radii.get(majority_b.element) : undefined;
             const [dx, dy, dz] = [x2 - x1, y2 - y1, z2 - z1];
             const dist_sq = dx * dx + dy * dy + dz * dz;
             const dist = Math.sqrt(dist_sq);

package/dist/structure/export.js

@@ -17,9 +17,9 @@ export function has_color_property(mat) {
     const red_channel = color_obj.r;
     const green_channel = color_obj.g;
     const blue_channel = color_obj.b;
-    return typeof red_channel === `number` &&
+    return (typeof red_channel === `number` &&
         typeof green_channel === `number` &&
-        typeof blue_channel === `number`;
+        typeof blue_channel === `number`);
 }
 // Extract color from a ShaderMaterial by checking common color uniform patterns
 function extract_shader_color(shader_mat) {
@@ -129,9 +129,7 @@ export function generate_mtl_content(scene) {
             lines.push(`Ks 0.500000 0.500000 0.500000`);
             lines.push(`Ns 96.078431`); // Specular exponent
             // Transparency (d = 1.0 is fully opaque)
-            const opacity = `opacity` in mat && typeof mat.opacity === `number`
-                ? mat.opacity
-                : 1.0;
+            const opacity = `opacity` in mat && typeof mat.opacity === `number` ? mat.opacity : 1.0;
             lines.push(`d ${opacity.toFixed(6)}`);
             // Illumination model (2 = highlight on)
             lines.push(`illum 2`);
@@ -151,7 +149,7 @@ function extract_material_color(mat) {
 // This is necessary because GLB/OBJ exporters don't handle InstancedMesh properly
 // 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 === true || obj.type === `InstancedMesh`;
+const is_instanced_mesh = (obj) => obj.isInstancedMesh || obj.type === `InstancedMesh`;
 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
@@ -357,16 +355,14 @@ export function structure_to_xyz_str(structure) {
     if (formula && formula !== `Unknown`)
         comment_parts.push(formula);
     // Include extended XYZ lattice information when available so round-trips preserve lattice
-    if ((`lattice` in structure) && structure.lattice?.matrix?.length === 3) {
+    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))
             .join(` `);
         comment_parts.push(`Lattice="${lattice_values}"`);
     }
-    const comment = comment_parts.length > 0
-        ? comment_parts.join(` `)
-        : `Generated from structure`;
+    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
@@ -376,9 +372,7 @@ export function structure_to_xyz_str(structure) {
     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) {
+        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)
@@ -469,7 +463,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 &&
+    if (`symmetry` in structure &&
+        structure.symmetry &&
         typeof structure.symmetry === `object`) {
         const symmetry = structure.symmetry;
         if (`space_group_symbol` in symmetry && symmetry.space_group_symbol) {
@@ -489,9 +484,7 @@ export function structure_to_cif_str(structure) {
     lines.push(`_atom_site_fract_z`);
     lines.push(`_atom_site_occupancy`);
     // 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;
+    const cart_to_frac = lattice.matrix?.length === 3 ? math.create_cart_to_frac(lattice.matrix) : null;
     // Atom sites
     for (let idx = 0; idx < structure.sites.length; idx++) {
         const site = structure.sites[idx];
@@ -500,9 +493,7 @@ export function structure_to_cif_str(structure) {
         // Extract element symbol from species
         let element_symbol = `X`; // default fallback
         let occupancy = 1;
-        if (site.species &&
-            Array.isArray(site.species) &&
-            site.species.length > 0) {
+        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;
@@ -556,9 +547,7 @@ export function structure_to_poscar_str(structure) {
     const element_symbols = [];
     for (const site of structure.sites) {
         let element_symbol = `X`; // default fallback
-        if (site.species &&
-            Array.isArray(site.species) &&
-            site.species.length > 0) {
+        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;
@@ -582,16 +571,12 @@ export function structure_to_poscar_str(structure) {
     // Coordinate mode (Direct = fractional coordinates)
     lines.push(`Direct`);
     // 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;
+    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) {
+            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;

package/dist/structure/ferrox-wasm.js

@@ -33,7 +33,7 @@ export function ensure_ferrox_wasm_ready() {
             catch (err) {
                 // Clear the promise on failure so retry is possible
                 init_promise = null;
-                throw new Error(`Failed to load matterviz-wasm. Install with: pnpm add matterviz-wasm. Original error: ${err}`);
+                throw new Error(`Failed to load matterviz-wasm. Install with: npm add matterviz-wasm. Original error: ${err}`, { cause: err });
             }
         })();
     }

package/dist/structure/index.d.ts

@@ -67,11 +67,21 @@ export declare function format_formula_by_electronegativity(structure: AnyStruct
 export declare const atomic_radii: CompositionType;
 export declare function get_density(structure: Crystal): number;
 export declare function get_center_of_mass(structure: AnyStructure): Vec3;
-export declare function get_site_vector_info(site: Site): {
+export declare const VECTOR_KEY_PREFIXES: readonly ["force", "forces", "magmom", "magmoms", "spin", "spins"];
+export declare function is_vector_key(key: string): boolean;
+export declare const VECTOR_PALETTE: readonly ["#e74c3c", "#3498db", "#2ecc71", "#f39c12", "#9b59b6", "#1abc9c"];
+export declare const default_vector_configs: (keys: string[]) => {
+    [k: string]: {
+        visible: boolean;
+        color: "#e74c3c" | "#3498db" | "#2ecc71" | "#f39c12" | "#9b59b6" | "#1abc9c" | null;
+        scale: null;
+    };
+};
+export declare function get_all_site_vectors(site: Site): {
     vec: Vec3;
     key: string;
-} | null;
-export declare function get_site_vector(site: Site): Vec3 | null;
+}[];
+export declare function get_structure_vector_keys(structure: AnyStructure): string[];
 export interface StructureHandlerData {
     structure?: AnyStructure;
     filename?: string;

package/dist/structure/index.js

@@ -42,16 +42,14 @@ export function format_chemical_formula(structure, sort_fn) {
 }
 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;
+    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;
         // Sort by electronegativity (ascending), then alphabetically for ties
         if (elec_neg1 !== elec_neg2)
             return elec_neg1 - elec_neg2;
         return el1.localeCompare(el2);
-    })));
+    }));
 }
 // Atomic radii in Angstroms (used for relative sizing, not absolute rendering scale)
 export const atomic_radii = Object.fromEntries(element_data.map((el) => [el.symbol, el.atomic_radius ?? 1]));
@@ -84,25 +82,87 @@ export function get_center_of_mass(structure) {
     }
     return math.scale(center, 1 / total_weight);
 }
-// Property keys checked for per-site vector data (force, magnetic moment, spin)
-const VECTOR_PROPERTY_KEYS = [`force`, `magmom`, `spin`];
-// Extract a vector and its source key from a site's properties. Checks force, magmom,
-// and spin in priority order. Scalar values are converted to z-directed vectors [0, 0, val].
-export function get_site_vector_info(site) {
+// Recognized prefixes for per-site vector data (force, magnetic moment, spin).
+// Both singular and plural forms are accepted. Keys matching exactly or starting
+// with one of these followed by `_` (e.g. `force_DFT`) are treated as vectors.
+export const VECTOR_KEY_PREFIXES = [
+    `force`,
+    `forces`,
+    `magmom`,
+    `magmoms`,
+    `spin`,
+    `spins`,
+];
+export function is_vector_key(key) {
+    return VECTOR_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}_`));
+}
+// Default color palette for distinguishing multiple vector layers
+export const VECTOR_PALETTE = [
+    `#e74c3c`,
+    `#3498db`,
+    `#2ecc71`,
+    `#f39c12`,
+    `#9b59b6`,
+    `#1abc9c`,
+];
+// Single key → null color (semantic coloring); multiple keys → palette colors.
+export const default_vector_configs = (keys) => Object.fromEntries(keys.map((key, idx) => [
+    key,
+    {
+        visible: true,
+        color: keys.length > 1 ? VECTOR_PALETTE[idx % VECTOR_PALETTE.length] : null,
+        scale: null,
+    },
+]));
+function try_parse_vec3(val) {
+    if (Array.isArray(val) &&
+        val.length === 3 &&
+        val.every((elem) => typeof elem === `number` && isFinite(elem)))
+        return val;
+    if (typeof val === `number` && isFinite(val))
+        return [0, 0, val];
+    return null;
+}
+// Priority index for ordering: bare names first in VECTOR_KEY_PREFIXES order,
+// then prefixed keys in the same prefix order, alphabetically within each prefix group.
+function vector_key_sort_order(key) {
+    for (const [prefix_idx, prefix] of VECTOR_KEY_PREFIXES.entries()) {
+        if (key === prefix)
+            return [prefix_idx, 0, ``];
+        if (key.startsWith(`${prefix}_`))
+            return [prefix_idx, 1, key];
+    }
+    return [VECTOR_KEY_PREFIXES.length, 0, key];
+}
+function compare_vector_keys(left, right) {
+    const ord_l = vector_key_sort_order(left);
+    const ord_r = vector_key_sort_order(right);
+    return ord_l[0] - ord_r[0] || ord_l[1] - ord_r[1] || ord_l[2].localeCompare(ord_r[2]);
+}
+// Extract ALL vector properties from a site (not just the first match).
+// Returns entries for every key that is_vector_key() and has a valid 3D vector value.
+// Ordered by VECTOR_KEY_PREFIXES priority, then alphabetically for prefixed keys.
+export function get_all_site_vectors(site) {
     const props = site.properties;
     if (!props)
-        return null;
-    for (const key of VECTOR_PROPERTY_KEYS) {
-        const val = props[key];
-        if (Array.isArray(val) && val.length === 3 &&
-            val.every((elem) => typeof elem === `number` && isFinite(elem)))
-            return { vec: val, key };
-        if (typeof val === `number` && isFinite(val))
-            return { vec: [0, 0, val], key };
+        return [];
+    const results = [];
+    for (const key of Object.keys(props)) {
+        if (!is_vector_key(key))
+            continue;
+        const vec = try_parse_vec3(props[key]);
+        if (vec)
+            results.push({ vec, key });
     }
-    return null;
+    return results.sort((left, right) => compare_vector_keys(left.key, right.key));
 }
-// Convenience wrapper returning just the vector (preserves existing API)
-export function get_site_vector(site) {
-    return get_site_vector_info(site)?.vec ?? null;
+// Collect the union of all vector property keys across all sites in a structure,
+// preserving VECTOR_KEY_PREFIXES priority order.
+export function get_structure_vector_keys(structure) {
+    const seen = new Set();
+    for (const site of structure.sites) {
+        for (const { key } of get_all_site_vectors(site))
+            seen.add(key);
+    }
+    return [...seen].sort(compare_vector_keys);
 }

package/dist/structure/measure.d.ts

@@ -1,6 +1,6 @@
-import type { Matrix3x3, Vec3 } from '../math';
+import type { LatticeConverters, Matrix3x3, Vec3 } from '../math';
 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, lattice_inv?: Matrix3x3): Vec3;
+export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, converters?: LatticeConverters): Vec3;
 export declare function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3): number;
 export declare function angle_between_vectors(v1: Vec3, v2: Vec3, mode?: AngleMode): number;

package/dist/structure/measure.js

@@ -1,55 +1,15 @@
 // functions for measuring distances and angles between structure sites
-import { mat3x3_vec3_multiply, matrix_inverse_3x3, subtract } from '../math';
+import { min_image_displacement, subtract } 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
-export function displacement_pbc(from, to, lattice_matrix, lattice_inv) {
-    // For non-periodic structures, return direct displacement
+export function displacement_pbc(from, to, lattice_matrix, converters) {
     if (!lattice_matrix)
         return subtract(to, from);
-    const inv_mat = lattice_inv ?? matrix_inverse_3x3(lattice_matrix);
-    const frac_from = mat3x3_vec3_multiply(inv_mat, from);
-    const frac_to = mat3x3_vec3_multiply(inv_mat, to);
-    // Wrap fractional coordinates to [0,1) for easier boundary checking
-    const frac_from_wrapped = [
-        frac_from[0] - Math.floor(frac_from[0]),
-        frac_from[1] - Math.floor(frac_from[1]),
-        frac_from[2] - Math.floor(frac_from[2]),
-    ];
-    const frac_to_wrapped = [
-        frac_to[0] - Math.floor(frac_to[0]),
-        frac_to[1] - Math.floor(frac_to[1]),
-        frac_to[2] - Math.floor(frac_to[2]),
-    ];
-    // Find minimum image by testing all nearby lattice translations
-    let min_dist_sq = Infinity;
-    let best_displacement = [0, 0, 0];
-    // Test lattice images in a 3x3x3 neighborhood (sufficient for minimum image)
-    for (let ii = -1; ii <= 1; ii++) {
-        for (let jj = -1; jj <= 1; jj++) {
-            for (let kk = -1; kk <= 1; kk++) {
-                // Fractional displacement with lattice translation
-                const frac_diff = [
-                    frac_to_wrapped[0] - frac_from_wrapped[0] + ii,
-                    frac_to_wrapped[1] - frac_from_wrapped[1] + jj,
-                    frac_to_wrapped[2] - frac_from_wrapped[2] + kk,
-                ];
-                // Convert to cartesian
-                const cart_diff = mat3x3_vec3_multiply(lattice_matrix, frac_diff);
-                const dist_sq = cart_diff[0] ** 2 + cart_diff[1] ** 2 + cart_diff[2] ** 2;
-                // Keep the shortest displacement
-                if (dist_sq < min_dist_sq) {
-                    min_dist_sq = dist_sq;
-                    best_displacement = cart_diff;
-                }
-            }
-        }
-    }
-    return best_displacement;
+    return min_image_displacement(from, to, lattice_matrix, converters);
 }
 export function distance_pbc(a, b, lattice_matrix) {
-    const inv_mat = matrix_inverse_3x3(lattice_matrix);
-    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix, inv_mat);
+    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix);
     return Math.hypot(dx, dy, dz);
 }
 export function angle_between_vectors(v1, v2, mode = `degrees`) {