matterviz 0.3.1 → 0.3.2

package/dist/structure/StructureScene.svelte

@@ -6,9 +6,10 @@ import { format_num } from '../labels';
 import * as math from '../math';
 import { DEFAULTS } from '../settings';
 import { colors } from '../state.svelte';
-import { Arrow, atomic_radii, Cylinder, get_center_of_mass, Lattice, } from './';
+import { Arrow, atomic_radii, Cylinder, get_center_of_mass, get_site_vector_info, Lattice, } from './';
 import { get_orig_site_idx, get_property_colors, } from './atom-properties';
 import * as measure from './measure';
+import { compute_slice_geometry, merge_split_partial_sites, PARTIAL_OCCUPANCY_CAP_ARC, } from './partial-occupancy';
 import { T, useThrelte } from '@threlte/core';
 import * as extras from '@threlte/extras';
 import { untrack } from 'svelte';
@@ -35,7 +36,7 @@ $effect(() => {
     frame_id = requestAnimationFrame(animate);
     return () => cancelAnimationFrame(frame_id);
 });
-let { structure = undefined, base_structure = undefined, atom_radius = DEFAULTS.structure.atom_radius, same_size_atoms = false, camera_position = DEFAULTS.structure.camera_position, camera_projection = DEFAULTS.structure.camera_projection, rotation_damping = DEFAULTS.structure.rotation_damping, max_zoom = DEFAULTS.structure.max_zoom, min_zoom = DEFAULTS.structure.min_zoom, rotate_speed = DEFAULTS.structure.rotate_speed, zoom_speed = DEFAULTS.structure.zoom_speed, pan_speed = DEFAULTS.structure.pan_speed, zoom_to_cursor = DEFAULTS.structure.zoom_to_cursor, show_atoms = DEFAULTS.structure.show_atoms, show_bonds = DEFAULTS.structure.show_bonds, show_site_labels = DEFAULTS.structure.show_site_labels, show_site_indices = DEFAULTS.structure.show_site_indices, site_label_size = DEFAULTS.structure.site_label_size, site_label_offset = $bindable(DEFAULTS.structure.site_label_offset), site_label_bg_color = `color-mix(in srgb, #000000 0%, transparent)`, site_label_color = `#ffffff`, site_label_padding = 3, show_force_vectors = DEFAULTS.structure.show_force_vectors, force_scale = DEFAULTS.structure.force_scale, force_color = DEFAULTS.structure.force_color, gizmo = DEFAULTS.structure.show_gizmo, hovered_idx = $bindable(null), hovered_site = $bindable(null), float_fmt = `.3~f`, auto_rotate = DEFAULTS.structure.auto_rotate, bond_thickness = DEFAULTS.structure.bond_thickness, bond_color = DEFAULTS.structure.bond_color, bonding_strategy = DEFAULTS.structure.bonding_strategy, bonding_options = {}, fov = DEFAULTS.structure.fov, initial_zoom = DEFAULTS.structure.initial_zoom, ambient_light = DEFAULTS.structure.ambient_light, directional_light = DEFAULTS.structure.directional_light, sphere_segments = DEFAULTS.structure.sphere_segments, lattice_props = {}, atom_label, camera_is_moving = $bindable(false), width = 0, height = 0, measure_mode = `distance`, selected_sites = $bindable([]), measured_sites = $bindable([]), added_bonds = $bindable([]), removed_bonds = $bindable([]), selection_highlight_color = `#6cf0ff`, 
+let { structure = undefined, base_structure = undefined, atom_radius = DEFAULTS.structure.atom_radius, same_size_atoms = false, camera_position = DEFAULTS.structure.camera_position, camera_target = undefined, camera_projection = DEFAULTS.structure.camera_projection, rotation_damping = DEFAULTS.structure.rotation_damping, max_zoom = DEFAULTS.structure.max_zoom, min_zoom = DEFAULTS.structure.min_zoom, rotate_speed = DEFAULTS.structure.rotate_speed, zoom_speed = DEFAULTS.structure.zoom_speed, pan_speed = DEFAULTS.structure.pan_speed, zoom_to_cursor = DEFAULTS.structure.zoom_to_cursor, show_atoms = DEFAULTS.structure.show_atoms, show_bonds = DEFAULTS.structure.show_bonds, show_site_labels = DEFAULTS.structure.show_site_labels, show_site_indices = DEFAULTS.structure.show_site_indices, site_label_size = DEFAULTS.structure.site_label_size, site_label_offset = $bindable(DEFAULTS.structure.site_label_offset), site_label_bg_color = `color-mix(in srgb, #000000 0%, transparent)`, site_label_color = `#ffffff`, site_label_padding = 3, show_force_vectors = DEFAULTS.structure.show_force_vectors, force_scale = DEFAULTS.structure.force_scale, force_color = DEFAULTS.structure.force_color, gizmo = DEFAULTS.structure.show_gizmo, hovered_idx = $bindable(null), hovered_site = $bindable(null), float_fmt = `.3~f`, auto_rotate = DEFAULTS.structure.auto_rotate, bond_thickness = DEFAULTS.structure.bond_thickness, bond_color = DEFAULTS.structure.bond_color, bonding_strategy = DEFAULTS.structure.bonding_strategy, bonding_options = {}, fov = DEFAULTS.structure.fov, initial_zoom = DEFAULTS.structure.initial_zoom, ambient_light = DEFAULTS.structure.ambient_light, directional_light = DEFAULTS.structure.directional_light, sphere_segments = DEFAULTS.structure.sphere_segments, lattice_props = {}, atom_label, camera_is_moving = $bindable(false), width = 0, height = 0, measure_mode = `distance`, selected_sites = $bindable([]), measured_sites = $bindable([]), added_bonds = $bindable([]), removed_bonds = $bindable([]), selection_highlight_color = `#6cf0ff`, 
 // Active highlight group with different color
 active_sites = $bindable([]), active_highlight_color = `var(--struct-active-highlight-color, #2563eb)`, rotation = DEFAULTS.structure.rotation, scene = $bindable(), camera = $bindable(), orbit_controls = $bindable(), rotation_target_ref = $bindable(), initial_computed_zoom = $bindable(), hidden_elements = $bindable(new SvelteSet()), hidden_prop_vals = $bindable(new SvelteSet()), element_radius_overrides = $bindable({}), site_radius_overrides = $bindable(new SvelteMap()), atom_color_config = {
     mode: DEFAULTS.structure.atom_color_mode,
@@ -49,9 +50,7 @@ $effect(() => {
     scene = threlte.scene;
     camera = threlte.camera.current;
     if (threlte.renderer) {
-        Object.assign(threlte.renderer.domElement, {
-            __renderer: threlte.renderer,
-        });
+        Object.assign(threlte.renderer.domElement, { __renderer: threlte.renderer });
     }
 });
 // Expose rotation target for external reset
@@ -119,12 +118,10 @@ function toggle_bond(site_1, site_2) {
     }
     // bond_pairs may not be sorted, so use get_bond_key for comparison
     const key = `${idx_i}-${idx_j}`;
-    if (bond_pairs.some((bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2) === key)) {
+    if (bond_pairs.some((bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2) === key))
         removed_bonds = [...removed_bonds, [idx_i, idx_j]];
-    }
-    else {
+    else
         added_bonds = [...added_bonds, [idx_i, idx_j]];
-    }
 }
 // Deduplicate clicks: when a highlight sphere and the underlying atom both
 // intercept the same native click, only the first intersection should fire.
@@ -132,11 +129,13 @@ function toggle_bond(site_1, site_2) {
 let last_native_event = null;
 function toggle_selection(site_index, evt) {
     evt?.stopPropagation?.();
-    const native = evt?.nativeEvent;
-    if (native && native === last_native_event)
-        return;
-    if (native)
-        last_native_event = native;
+    const native_event = evt
+        ?.nativeEvent;
+    if (native_event instanceof Event) {
+        if (native_event === last_native_event)
+            return;
+        last_native_event = native_event;
+    }
     if (measure_mode === `edit-bonds`) {
         // In edit-bonds mode, select atoms to add/remove bonds between them
         const new_sites = measured_sites.includes(site_index)
@@ -232,7 +231,7 @@ $effect(() => {
     computed_zoom = new_zoom;
 });
 $effect.pre(() => {
-    if (camera_position.every((v) => v === 0) && structure) {
+    if (camera_position.every((val) => val === 0) && structure) {
         const distance = Math.max(1, structure_size) * (60 / fov);
         camera_position = [distance, distance * 0.3, distance * 0.8];
     }
@@ -268,7 +267,8 @@ const calc_weighted_radius = (site) => {
 let atom_data = $derived.by(() => {
     if (!show_atoms || !structure?.sites)
         return [];
-    return structure.sites.flatMap((site, site_idx) => {
+    const render_sites = merge_split_partial_sites(structure.sites, hidden_elements);
+    return render_sites.flatMap(({ site_idx, site, is_image_atom }) => {
         const orig_idx = get_orig_site_idx(site, site_idx);
         // Skip sites with hidden property values
         const prop_val = property_colors?.values[orig_idx];
@@ -283,23 +283,25 @@ let atom_data = $derived.by(() => {
         // Use property color if available (e.g. coordination number, Wyckoff position)
         // Otherwise, each species gets its own element color (important for disordered sites)
         const site_property_color = property_colors?.colors[orig_idx];
-        // Detect image atoms by presence of orig_site_idx property (set by get_pbc_image_sites)
-        const is_image_atom = site.properties?.orig_site_idx != null;
-        let start_angle = 0;
-        return site.species
-            .filter(({ element }) => !hidden_elements.has(element))
-            .map(({ element, occu }) => ({
-            site_idx,
-            element,
-            occupancy: occu,
-            position: site.xyz,
-            radius,
-            color: site_property_color ?? colors.element?.[element],
-            has_partial_occupancy: occu < 1,
-            start_phi: 2 * Math.PI * start_angle,
-            end_phi: 2 * Math.PI * (start_angle += occu),
-            is_image_atom,
-        }));
+        const visible_species = site.species.filter(({ element }) => !hidden_elements.has(element));
+        const slice_geometry = compute_slice_geometry(visible_species);
+        return slice_geometry.map((slice_data) => {
+            return {
+                site_idx,
+                element: slice_data.element,
+                occupancy: slice_data.occupancy,
+                position: site.xyz,
+                radius,
+                color: site_property_color ?? colors.element?.[slice_data.element],
+                has_partial_occupancy: slice_data.occupancy < 1,
+                start_phi: slice_data.start_phi,
+                end_phi: slice_data.end_phi,
+                phi_length: slice_data.phi_length,
+                render_start_cap: slice_data.render_start_cap,
+                render_end_cap: slice_data.render_end_cap,
+                is_image_atom,
+            };
+        });
     });
 });
 let filtered_bond_pairs = $derived.by(() => {
@@ -389,21 +391,47 @@ const get_site_radius = (site, site_idx) => {
     const base_radius = same_size_atoms ? 1 : override ?? calc_weighted_radius(site);
     return base_radius * atom_radius;
 };
-let force_data = $derived.by(() => show_force_vectors && structure?.sites
-    ? structure?.sites
+// Interpolate between spin-down (#3498db blue) and spin-up (#e74c3c red)
+// based on the z-component direction of a magnetic vector
+function spin_direction_color(vec) {
+    const mag = Math.hypot(...vec);
+    const z_frac = mag > 1e-10 ? (vec[2] / mag + 1) / 2 : 0.5; // 0=down, 1=up
+    const red = Math.round(52 + (231 - 52) * z_frac);
+    const grn = Math.round(152 + (76 - 152) * z_frac);
+    const blu = Math.round(219 + (60 - 219) * z_frac);
+    return `#${red.toString(16).padStart(2, `0`)}${grn.toString(16).padStart(2, `0`)}${blu.toString(16).padStart(2, `0`)}`;
+}
+// Extract per-site vectors from force, magmom, or spin properties.
+// For magmom/spin, color interpolates between spin-up (red) and spin-down (blue).
+let force_data = $derived.by(() => {
+    if (!show_force_vectors || !structure?.sites)
+        return [];
+    return structure.sites
         .map((site) => {
-        if (!site.properties?.force || !Array.isArray(site.properties.force))
+        const info = get_site_vector_info(site);
+        if (!info)
             return null;
-        const majority_element = site.species.reduce((max, spec) => spec.occu > max.occu ? spec : max).element;
+        let arrow_color;
+        if (info.key !== `force`) {
+            arrow_color = spin_direction_color(info.vec);
+        }
+        else {
+            const majority_element = site.species.length > 0
+                ? site.species.reduce((max, spec) => spec.occu > max.occu ? spec : max)
+                    .element
+                : undefined;
+            arrow_color = (majority_element && colors.element?.[majority_element]) ||
+                force_color;
+        }
         return {
             position: site.xyz,
-            vector: site.properties.force,
+            vector: info.vec,
             scale: force_scale,
-            color: colors.element?.[majority_element] || force_color,
+            color: arrow_color,
         };
     })
-        .filter((item) => item !== null)
-    : []);
+        .filter((item) => item !== null);
+});
 let instanced_atom_groups = $derived(Object.values(atom_data
     .filter((atom) => !atom.has_partial_occupancy)
     .reduce((groups, atom) => {
@@ -452,7 +480,7 @@ let orbit_controls_props = $derived({
     zoomToCursor: zoom_to_cursor,
     enablePan: pan_speed > 0,
     panSpeed: pan_speed,
-    target: rotation_target,
+    target: camera_target ?? rotation_target,
     maxZoom: max_zoom,
     minZoom: min_zoom,
     autoRotate: Boolean(auto_rotate),
@@ -498,27 +526,17 @@ let measure_line_color = $derived.by(() => {
         style:padding="{site_label_padding}px"
         style:color={site_label_color}
       >
-        {#if show_site_labels && show_site_indices}
+        {#if show_site_labels}
           {#if site.species.length === 1}
-            {site.species[0].element}-{site_idx + 1}
+            {site.species[0].element}{#if show_site_indices}-{site_idx + 1}{/if}
           {:else}
             {@html site.species.map((spec) =>
         `${spec.element}<sub>${
           format_num(spec.occu, `.3~`).replace(`0.`, `.`)
         }</sub>`
-      ).join(``)}-{
-              site_idx + 1
-            }
-          {/if}
-        {:else if show_site_labels}
-          {#if site.species.length === 1}
-            {site.species[0].element}
-          {:else}
-            {@html site.species.map((spec) =>
-        `${spec.element}<sub>${
-          format_num(spec.occu, `.3~`).replace(`0.`, `.`)
-        }</sub>`
-      ).join(``)}
+      ).join(``)}{#if show_site_indices}-{
+                site_idx + 1
+              }{/if}
           {/if}
         {:else if show_site_indices}
           {site_idx + 1}
@@ -637,7 +655,7 @@ let measure_line_color = $derived.by(() => {
                   sphere_segments,
                   sphere_segments,
                   atom.start_phi,
-                  2 * Math.PI * atom.occupancy,
+                  atom.phi_length,
                 ]}
               />
               <T.MeshStandardMaterial
@@ -647,9 +665,16 @@ let measure_line_color = $derived.by(() => {
               />
             </T.Mesh>
 
-            {#if atom.has_partial_occupancy}
+            {#if atom.has_partial_occupancy && atom.render_start_cap}
               <T.Mesh rotation={[0, atom.start_phi, 0]}>
-                <T.CircleGeometry args={[0.5, sphere_segments]} />
+                <T.CircleGeometry
+                  args={[
+                    0.5,
+                    sphere_segments,
+                    PARTIAL_OCCUPANCY_CAP_ARC.start_cap_arc_start,
+                    PARTIAL_OCCUPANCY_CAP_ARC.arc_length,
+                  ]}
+                />
                 <T.MeshStandardMaterial
                   color={partial_color}
                   side={2}
@@ -657,8 +682,17 @@ let measure_line_color = $derived.by(() => {
                   transparent={partial_edit_image}
                 />
               </T.Mesh>
+            {/if}
+            {#if atom.has_partial_occupancy && atom.render_end_cap}
               <T.Mesh rotation={[0, atom.end_phi, 0]}>
-                <T.CircleGeometry args={[0.5, sphere_segments]} />
+                <T.CircleGeometry
+                  args={[
+                    0.5,
+                    sphere_segments,
+                    PARTIAL_OCCUPANCY_CAP_ARC.end_cap_arc_start,
+                    PARTIAL_OCCUPANCY_CAP_ARC.arc_length,
+                  ]}
+                />
                 <T.MeshStandardMaterial
                   color={partial_color}
                   side={2}
@@ -806,8 +840,12 @@ let measure_line_color = $derived.by(() => {
 
       <!-- hovered site tooltip -->
       {#if hovered_site && !camera_is_moving && active_tooltip === `atom`}
-        {@const abc = hovered_site.abc.map((x) => format_num(x, float_fmt)).join(`, `)}
-        {@const xyz = hovered_site.xyz.map((x) => format_num(x, float_fmt)).join(`, `)}
+        {@const abc = hovered_site.abc.map((val) => format_num(val, float_fmt)).join(
+          `, `,
+        )}
+        {@const xyz = hovered_site.xyz.map((val) => format_num(val, float_fmt)).join(
+          `, `,
+        )}
         {@const bond_neighbors = (() => {
           if (hovered_idx == null || !structure?.sites) return []
           return filtered_bond_pairs
@@ -874,7 +912,7 @@ let measure_line_color = $derived.by(() => {
           structure?.sites}
         {@const selected_atoms = selected_sites
           .map((idx) => structure?.sites?.[idx])
-          .filter(Boolean) as Site[]}
+          .filter((site): site is Site => site != null)}
         {#if selected_atoms.length > 0}
           {@const avg = (dim: number) =>
           selected_atoms.reduce((sum, atom) => sum + atom.xyz[dim], 0) /
@@ -994,12 +1032,12 @@ let measure_line_color = $derived.by(() => {
         {:else if measure_mode === `angle` && measured_sites.length >= 3}
           {#each measured_sites as idx_center (idx_center)}
             {@const center = structure.sites[idx_center]}
-            {#each measured_sites.filter((x) => x !== idx_center) as
+            {#each measured_sites.filter((idx) => idx !== idx_center) as
               idx_a,
               loop_idx
               (idx_center + `-` + idx_a)
             }
-              {#each measured_sites.filter((x) => x !== idx_center).slice(loop_idx + 1) as
+              {#each measured_sites.filter((idx) => idx !== idx_center).slice(loop_idx + 1) as
                 idx_b
                 (idx_center + `-` + idx_a + `-` + idx_b)
               }

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

@@ -18,6 +18,7 @@ type $$ComponentProps = {
     atom_radius?: number;
     same_size_atoms?: boolean;
     camera_position?: [x: number, y: number, z: number];
+    camera_target?: Vec3;
     camera_projection?: CameraProjection;
     rotation_damping?: number;
     max_zoom?: number;
@@ -90,6 +91,6 @@ type $$ComponentProps = {
     volumetric_data?: VolumetricData;
     isosurface_settings?: IsosurfaceSettings;
 };
-declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "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" | "scene" | "camera" | "orbit_controls" | "rotation_target_ref" | "initial_computed_zoom" | "add_atom_mode" | "add_element" | "dragging_atoms">;
+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">;
 type StructureScene = ReturnType<typeof StructureScene>;
 export default StructureScene;

package/dist/structure/atom-properties.d.ts

@@ -1,6 +1,6 @@
-import type { AnyStructure, Site } from './';
 import type { ColorScaleType, D3InterpolateName } from '../colors';
 import type { AtomColorMode } from '../settings';
+import type { AnyStructure, Site } from './';
 import type { BondingStrategy } from './bonding';
 import type { MoyoDataset } from '@spglib/moyo-wasm';
 export interface AtomColorConfig {
@@ -16,6 +16,9 @@ export interface AtomPropertyColors {
     max_value?: number;
     unique_values?: (number | string)[];
 }
+type SymmetryDataWithOrigMap = MoyoDataset & {
+    orig_site_indices_by_std_idx?: number[][];
+};
 export declare const get_d3_color_scales: () => string[];
 export declare function apply_color_scale(vals: number[], scale?: string, type?: ColorScaleType): {
     colors: string[];
@@ -27,7 +30,8 @@ export declare const apply_categorical_color_scale: (vals: string[], scale?: str
 };
 export declare const get_orig_site_idx: (site: Site | undefined, site_idx: number) => number;
 export declare function get_coordination_colors(structure: AnyStructure, strategy?: BondingStrategy, scale?: string, type?: ColorScaleType): AtomPropertyColors;
-export declare function get_wyckoff_colors(structure: AnyStructure, sym_data: MoyoDataset | null, scale?: string): AtomPropertyColors;
+export declare function get_wyckoff_colors(structure: AnyStructure, sym_data: SymmetryDataWithOrigMap | null, scale?: string): AtomPropertyColors;
 export declare function get_custom_colors(structure: AnyStructure, fn: (site: Site, idx: number) => number | string, scale?: string, type?: ColorScaleType): AtomPropertyColors;
 export declare function get_atom_colors(structure: AnyStructure, config: Partial<AtomColorConfig>, bonding_strategy?: BondingStrategy, sym_data?: MoyoDataset | null): AtomPropertyColors;
 export declare function get_property_colors(structure: AnyStructure | undefined, config: Partial<AtomColorConfig>, bonding_strategy: BondingStrategy, sym_data: MoyoDataset | null): AtomPropertyColors | null;
+export {};

package/dist/structure/atom-properties.js

@@ -15,6 +15,25 @@ 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 img_abc = [
+        site.abc[0] + offset[0],
+        site.abc[1] + offset[1],
+        site.abc[2] + offset[2],
+    ];
+    return {
+        ...site,
+        abc: img_abc,
+        xyz: math.mat3x3_vec3_multiply(lattice_T, img_abc),
+        properties: { ...site.properties, orig_site_idx: orig_idx },
+    };
+};
+const get_all_offsets = (pbc) => [-1, 0, 1]
+    .flatMap((dx) => [-1, 0, 1].flatMap((dy) => [-1, 0, 1].map((dz) => [dx, dy, dz])))
+    .filter(([dx, dy, dz]) => !(dx === 0 && dy === 0 && dz === 0) &&
+    (pbc[0] || dx === 0) &&
+    (pbc[1] || dy === 0) &&
+    (pbc[2] || dz === 0));
 const make_categorical = (vals, scale, sort_fn) => {
     const interp_fn = get_interpolator(scale);
     const uniq = sort_fn ? [...new Set(vals)].sort(sort_fn) : [...new Set(vals)].sort();
@@ -68,24 +87,10 @@ function expand_structure_for_pbc(structure) {
     const { sites, lattice } = structure;
     const lattice_T = math.transpose_3x3_matrix(lattice.matrix);
     const pbc = lattice.pbc ?? [true, true, true];
-    // All valid image offsets respecting PBC
-    const all_offsets = [-1, 0, 1]
-        .flatMap((dx) => [-1, 0, 1].flatMap((dy) => [-1, 0, 1].map((dz) => [dx, dy, dz])))
-        .filter(([dx, dy, dz]) => !(dx === 0 && dy === 0 && dz === 0) &&
-        (pbc[0] || dx === 0) &&
-        (pbc[1] || dy === 0) &&
-        (pbc[2] || dz === 0));
+    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(([dx, dy, dz]) => {
-            const img_abc = [site.abc[0] + dx, site.abc[1] + dy, site.abc[2] + dz];
-            return {
-                ...site,
-                abc: img_abc,
-                xyz: math.mat3x3_vec3_multiply(lattice_T, img_abc),
-                properties: { ...site.properties, orig_site_idx: orig_idx },
-            };
-        }));
+        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map((offset) => build_image_site(site, lattice_T, offset, orig_idx)));
         return { ...structure, sites: [...sites, ...image_sites] };
     }
     // Large structures: only expand atoms near boundaries (within 5Å bond distance)
@@ -96,15 +101,7 @@ function expand_structure_for_pbc(structure) {
             .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(([dx, dy, dz]) => {
-            const img_abc = [site.abc[0] + dx, site.abc[1] + dy, site.abc[2] + dz];
-            return {
-                ...site,
-                abc: img_abc,
-                xyz: math.mat3x3_vec3_multiply(lattice_T, img_abc),
-                properties: { ...site.properties, orig_site_idx: orig_idx },
-            };
-        });
+            .map((offset) => build_image_site(site, lattice_T, offset, orig_idx));
     });
     return { ...structure, sites: [...sites, ...image_sites] };
 }
@@ -135,9 +132,25 @@ export function get_wyckoff_colors(structure, sym_data, scale = DEFAULT_COLOR_SC
             unique_values: [`unknown`],
         };
     }
+    const wyckoff_by_orig_idx = new Map();
+    const mapping_by_std_idx = sym_data.orig_site_indices_by_std_idx;
+    if (mapping_by_std_idx) {
+        for (let std_idx = 0; std_idx < sym_data.wyckoffs.length; std_idx += 1) {
+            const wyckoff = sym_data.wyckoffs[std_idx];
+            for (const orig_idx of mapping_by_std_idx[std_idx] ?? []) {
+                if (!wyckoff_by_orig_idx.has(orig_idx))
+                    wyckoff_by_orig_idx.set(orig_idx, wyckoff);
+            }
+        }
+    }
     // Create unique orbit identifiers: Wyckoff position + element symbol
     const orbit_ids = structure.sites.map((site, idx) => {
         const sym_idx = get_orig_site_idx(site, idx);
+        const mapped_wyckoff = wyckoff_by_orig_idx.get(sym_idx);
+        if (mapped_wyckoff !== undefined) {
+            const element = site.species[0]?.element ?? `?`;
+            return mapped_wyckoff ? `${mapped_wyckoff}|${element}` : `unknown`;
+        }
         if (sym_idx >= sym_data.wyckoffs.length) {
             console.error(`[get_wyckoff_colors] Site ${idx} (maps to ${sym_idx}) has no Wyckoff data. ` +
                 `Structure has ${n} sites but symmetry data only has ${sym_data.wyckoffs.length}.`);

package/dist/structure/export.js

@@ -10,13 +10,16 @@ export function has_color_property(mat) {
     if (!(`color` in mat))
         return false;
     const color = mat.color;
-    // Check for Color-like object with r, g, b properties (duck typing)
-    return (color !== null &&
-        typeof color === `object` &&
-        `r` in color &&
-        `g` in color &&
-        `b` in color &&
-        typeof color.r === `number`);
+    if (!color || typeof color !== `object`)
+        return false;
+    // Check for Color-like object with numeric r/g/b channels (duck typing)
+    const color_obj = color;
+    const red_channel = color_obj.r;
+    const green_channel = color_obj.g;
+    const blue_channel = color_obj.b;
+    return typeof red_channel === `number` &&
+        typeof green_channel === `number` &&
+        typeof blue_channel === `number`;
 }
 // Extract color from a ShaderMaterial by checking common color uniform patterns
 function extract_shader_color(shader_mat) {

package/dist/structure/ferrox-wasm-types.d.ts

@@ -1,3 +1,4 @@
+import type { Vec3 } from '../math';
 export type WasmResult<T> = {
     ok: T;
 } | {
@@ -14,7 +15,7 @@ export declare function unwrap_or<T>(result: WasmResult<T>, default_value: T): T
 export interface NeighborListResult {
     center_indices: number[];
     neighbor_indices: number[];
-    image_offsets: [number, number, number][];
+    image_offsets: Vec3[];
     distances: number[];
 }
 export interface MatcherOptions {
@@ -28,7 +29,7 @@ export interface MatcherOptions {
 export type StructureFormat = `cif` | `poscar` | `json`;
 export type ReductionAlgorithm = `niggli` | `lll`;
 export interface HklInfo {
-    hkl: [number, number, number];
+    hkl: Vec3;
     multiplicity: number;
 }
 export interface XrdPattern {

package/dist/structure/ferrox-wasm-types.js

@@ -1,6 +1,3 @@
-// Pure type definitions and utility functions for ferrox-wasm results.
-// This module has no WASM side effects, making it safe to import in tests
-// without triggering WASM resolution.
 // Type guard to check if result is successful
 export function is_ok(result) {
     return `ok` in result;

package/dist/structure/ferrox-wasm.d.ts

@@ -1,3 +1,4 @@
+import type { Vec3 } from '../math';
 import type { Crystal } from './';
 import type { MatcherOptions, NeighborListResult, ReductionAlgorithm, StructureFormat, WasmResult, XrdOptions, XrdPattern } from './ferrox-wasm-types';
 export * from './ferrox-wasm-types';
@@ -81,8 +82,8 @@ export declare function interpolate_structures(start: Crystal, end: Crystal, n_i
 }): Promise<WasmResult<Crystal[]>>;
 export declare function copy_structure(structure: Crystal, sanitize?: boolean): Promise<WasmResult<Crystal>>;
 export declare function wrap_to_unit_cell(structure: Crystal): Promise<WasmResult<Crystal>>;
-export declare function create_supercell_matrix(structure: Crystal, matrix: [[number, number, number], [number, number, number], [number, number, number]]): Promise<WasmResult<Crystal>>;
-export declare function translate_sites(structure: Crystal, indices: number[], vector: [number, number, number], frac_coords?: boolean): Promise<WasmResult<Crystal>>;
+export declare function create_supercell_matrix(structure: Crystal, matrix: [Vec3, Vec3, Vec3]): Promise<WasmResult<Crystal>>;
+export declare function translate_sites(structure: Crystal, indices: number[], vector: Vec3, frac_coords?: boolean): Promise<WasmResult<Crystal>>;
 export declare function perturb_structure(structure: Crystal, distance: number, options?: {
     min_distance?: number;
     seed?: number;

package/dist/structure/ferrox-wasm.js

@@ -25,8 +25,7 @@ export function ensure_ferrox_wasm_ready() {
         init_promise = (async () => {
             try {
                 // Dynamic import to avoid loading WASM until needed
-                const { default: init } = (await import(
-                /* @vite-ignore */ `matterviz-wasm`));
+                const { default: init } = (await import(`matterviz-wasm`));
                 // Initialize WASM module (the package handles WASM loading internally)
                 wasm_module = await init();
                 return wasm_module;

package/dist/structure/index.d.ts

@@ -67,6 +67,11 @@ 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): {
+    vec: Vec3;
+    key: string;
+} | null;
+export declare function get_site_vector(site: Site): Vec3 | null;
 export interface StructureHandlerData {
     structure?: AnyStructure;
     filename?: string;
@@ -75,6 +80,7 @@ export interface StructureHandlerData {
     error_msg?: string;
     fullscreen?: boolean;
     camera_position?: Vec3;
+    camera_target?: Vec3;
     camera_has_moved?: boolean;
     color_scheme?: string;
     performance_mode?: `quality` | `speed`;

package/dist/structure/index.js

@@ -84,3 +84,25 @@ 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) {
+    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 null;
+}
+// Convenience wrapper returning just the vector (preserves existing API)
+export function get_site_vector(site) {
+    return get_site_vector_info(site)?.vec ?? null;
+}