matterviz 0.3.6 → 0.4.0

package/dist/src/lib/structure/export.ts

@@ -1,861 +0,0 @@
-import { get_electro_neg_formula } from '$lib/composition'
-import { download } from '$lib/io/fetch'
-import type { Vec3 } from '$lib/math'
-import * as math from '$lib/math'
-import type { AnyStructure } from '$lib/structure'
-import type { BufferGeometry, InstancedMesh, Material, Object3D, Scene } from 'three'
-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)
-export function has_color_property(mat: Material): mat is Material & { color: Color } {
-  if (!(`color` in mat)) return false
-  const color = (mat as { color: unknown }).color
-  if (!color || typeof color !== `object`) return false
-  // Check for Color-like object with numeric r/g/b channels (duck typing)
-  const color_obj = color as { r?: unknown; g?: unknown; b?: unknown }
-  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: ShaderMaterial): Color | null {
-  const uniforms = shader_mat.uniforms
-  if (!uniforms) return null
-
-  // Check for common color uniform names
-  for (const key of [`color`, `diffuse`, `baseColor`, `uColor`]) {
-    if (uniforms[key]?.value instanceof Color) {
-      return uniforms[key].value.clone()
-    }
-  }
-
-  // For gradient bonds, try to extract midpoint color from instanceColorStart/End attributes
-  // These are set as geometry attributes, not uniforms, so we return a default gray
-  return null
-}
-
-// Convert ShaderMaterial to MeshStandardMaterial for export compatibility
-function convert_shader_to_standard(shader_mat: ShaderMaterial): MeshStandardMaterial {
-  const extracted_color = extract_shader_color(shader_mat)
-  const standard_mat = new MeshStandardMaterial({
-    color: extracted_color ?? new Color(0.5, 0.5, 0.5),
-    metalness: 0.1,
-    roughness: 0.5,
-  })
-  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
-export function extract_bond_color_for_instance(
-  geometry: BufferGeometry,
-  instance_idx: number,
-): Color | null {
-  const color_start_attr = geometry.getAttribute(`instanceColorStart`)
-  const color_end_attr = geometry.getAttribute(`instanceColorEnd`)
-
-  if (!color_start_attr || !color_end_attr) return null
-  if (instance_idx < 0 || instance_idx >= color_start_attr.count) return null
-
-  // Get RGB values for this instance and compute midpoint color
-  const start_rgb: Vec3 = [
-    color_start_attr.getX(instance_idx),
-    color_start_attr.getY(instance_idx),
-    color_start_attr.getZ(instance_idx),
-  ]
-  const end_rgb: Vec3 = [
-    color_end_attr.getX(instance_idx),
-    color_end_attr.getY(instance_idx),
-    color_end_attr.getZ(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
-export function clean_geometry_for_export(geometry: BufferGeometry): void {
-  const standard_attrs = new Set([
-    `position`,
-    `normal`,
-    `tangent`,
-    `uv`,
-    `uv1`,
-    `uv2`,
-    `uv3`,
-    `color`,
-    `skinIndex`,
-    `skinWeight`,
-  ])
-
-  const attrs_to_remove: string[] = []
-  for (const attr_name of Object.keys(geometry.attributes)) {
-    // Keep standard attributes and those starting with underscore (GLTF custom)
-    // But remove instance-specific attributes that cause accessor count mismatches
-    const lower_name = attr_name.toLowerCase()
-    if (
-      lower_name.includes(`instance`) ||
-      (lower_name.includes(`color`) && !standard_attrs.has(lower_name))
-    )
-      attrs_to_remove.push(attr_name)
-  }
-
-  for (const attr_name of attrs_to_remove) {
-    geometry.deleteAttribute(attr_name)
-  }
-}
-
-// Generate MTL (Wavefront Material) content from scene materials
-export function generate_mtl_content(scene: Scene): string {
-  const lines: string[] = [`# MTL file generated by MatterViz`, ``]
-  const processed_materials = new Set<string>()
-
-  scene.traverse((object) => {
-    if (!(object instanceof Mesh)) return
-
-    const materials = Array.isArray(object.material) ? object.material : [object.material]
-    for (const mat of materials) {
-      // Skip if already processed or no name
-      const mat_name = mat.name || `default_material`
-      if (processed_materials.has(mat_name)) continue
-      processed_materials.add(mat_name)
-
-      lines.push(`newmtl ${mat_name}`)
-
-      // 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)}`)
-        // 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)}`,
-        )
-      } else {
-        // Default white if no color
-        lines.push(`Kd 1.000000 1.000000 1.000000`)
-        lines.push(`Ka 0.200000 0.200000 0.200000`)
-      }
-
-      // Specular properties
-      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
-      lines.push(`d ${opacity.toFixed(6)}`)
-
-      // Illumination model (2 = highlight on)
-      lines.push(`illum 2`)
-      lines.push(``)
-    }
-  })
-
-  return lines.join(`\n`)
-}
-
-// Extract color from material, returning RGB values or null if not found
-function extract_material_color(mat: Material): { r: number; g: number; b: number } | null {
-  if (has_color_property(mat)) {
-    return { r: mat.color.r, g: mat.color.g, b: mat.color.b }
-  }
-  return null
-}
-
-// Helper function to convert InstancedMesh to regular Mesh objects for export
-// 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: Object3D): obj is InstancedMesh =>
-  (obj as InstancedMesh).isInstancedMesh || obj.type === `InstancedMesh`
-
-function convert_instanced_meshes_to_regular(scene: Scene): 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<string, { r: number; g: number; b: number }>()
-  const bond_colors_map = new Map<string, Map<number, Color>>()
-
-  scene.traverse((object) => {
-    const is_instanced = is_instanced_mesh(object)
-    if (!is_instanced) return
-
-    const instanced_mesh = object
-    const mesh_id = instanced_mesh.uuid
-
-    // Check if this is a shader material (bonds)
-    const mat = instanced_mesh.material
-    const is_shader = Array.isArray(mat)
-      ? mat.some((material) => material instanceof ShaderMaterial)
-      : mat instanceof ShaderMaterial
-
-    if (is_shader) {
-      // Extract bond colors for each instance from geometry attributes
-      const instance_colors = new Map<number, Color>()
-      for (let idx = 0; idx < instanced_mesh.count; idx++) {
-        const bond_color = extract_bond_color_for_instance(instanced_mesh.geometry, idx)
-        if (bond_color) {
-          instance_colors.set(idx, bond_color)
-        }
-      }
-      bond_colors_map.set(mesh_id, instance_colors)
-    } else {
-      // Extract shared material color for atoms
-      const single_mat = Array.isArray(mat) ? mat[0] : mat
-      const color = extract_material_color(single_mat)
-      if (color) {
-        material_colors.set(mesh_id, color)
-      }
-    }
-  })
-
-  // STEP 2: Clone the scene
-  const cloned_scene = scene.clone()
-
-  // STEP 3: Find all InstancedMesh objects in the cloned scene and build uuid mapping
-  const original_meshes: InstancedMesh[] = []
-  const cloned_meshes: InstancedMesh[] = []
-
-  scene.traverse((object) => {
-    if (is_instanced_mesh(object)) original_meshes.push(object)
-  })
-
-  cloned_scene.traverse((object) => {
-    if (is_instanced_mesh(object)) cloned_meshes.push(object)
-  })
-
-  // STEP 4: Convert each InstancedMesh to individual Mesh objects
-  for (let mesh_idx = 0; mesh_idx < cloned_meshes.length; mesh_idx++) {
-    const instanced_mesh = cloned_meshes[mesh_idx]
-    const original_mesh = original_meshes[mesh_idx]
-    const original_uuid = original_mesh?.uuid || instanced_mesh.uuid
-
-    const parent = instanced_mesh.parent
-    if (!parent || !instanced_mesh.instanceMatrix) continue
-
-    // Create a group to hold all the individual meshes
-    const group = new Group()
-    group.name = instanced_mesh.name
-
-    // Get the base transform from the InstancedMesh
-    const base_matrix = new Matrix4()
-    base_matrix.copy(instanced_mesh.matrix)
-
-    // Get stored colors for this mesh
-    const stored_color = material_colors.get(original_uuid)
-    const stored_bond_colors = bond_colors_map.get(original_uuid)
-
-    // Check if material is a ShaderMaterial
-    const original_material = instanced_mesh.material
-    const has_shader = Array.isArray(original_material)
-      ? original_material.some((mat) => mat instanceof ShaderMaterial)
-      : original_material instanceof ShaderMaterial
-
-    // Create individual meshes for each instance
-    const instance_matrix = new Matrix4()
-    for (let idx = 0; idx < instanced_mesh.count; idx++) {
-      instanced_mesh.getMatrixAt(idx, instance_matrix)
-
-      // Clone geometry
-      const cloned_geometry = instanced_mesh.geometry.clone()
-
-      // Clean up custom attributes from shader-based geometries
-      if (has_shader) {
-        clean_geometry_for_export(cloned_geometry)
-      }
-
-      // Create material - always create fresh MeshStandardMaterial for reliability
-      const new_material = new MeshStandardMaterial({
-        metalness: 0.1,
-        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
-
-      const mesh = new Mesh(cloned_geometry, new_material)
-
-      // Combine base transform with instance transform
-      const combined_matrix = new Matrix4()
-      combined_matrix.multiplyMatrices(base_matrix, instance_matrix)
-      mesh.applyMatrix4(combined_matrix)
-
-      group.add(mesh)
-    }
-
-    // Replace the InstancedMesh with the Group in the parent
-    parent.remove(instanced_mesh)
-    parent.add(group)
-
-    // Update world matrices after scene graph modification
-    group.updateMatrixWorld(true)
-  }
-
-  // Update all world matrices in the modified scene
-  cloned_scene.updateMatrixWorld(true)
-
-  // Convert any remaining ShaderMaterials to standard materials (e.g. non-instanced bonds)
-  // Also clean up custom geometry attributes that cause export validation errors
-  cloned_scene.traverse((object) => {
-    if (object instanceof Mesh) {
-      let has_shader_material = false
-      if (object.material instanceof ShaderMaterial) {
-        object.material = convert_shader_to_standard(object.material)
-        has_shader_material = true
-      } else if (Array.isArray(object.material)) {
-        has_shader_material = object.material.some((mat) => mat instanceof ShaderMaterial)
-        object.material = object.material.map((mat) =>
-          mat instanceof ShaderMaterial ? convert_shader_to_standard(mat) : mat,
-        )
-      }
-      // Clean up custom attributes from geometries that had shader materials
-      if (has_shader_material && object.geometry) {
-        clean_geometry_for_export(object.geometry)
-      }
-    }
-  })
-
-  return cloned_scene
-}
-
-// Generate a filename for structure exports based on structure metadata
-// Sanitize string for use in filenames by removing problematic characters.
-const sanitize_filename_part = (text: string): string =>
-  text
-    .replace(/<\/?[^>]+>/g, ``) // strip HTML tags
-    .replace(/[/\\:*?"<>|]/g, `_`) // replace filesystem-invalid chars
-    .replace(/_+/g, `_`) // condense consecutive underscores
-    .replace(/^_|_$/g, ``) // remove leading/trailing underscores
-
-export function create_structure_filename(
-  structure: AnyStructure | undefined,
-  extension: string,
-): string {
-  if (!structure) return `structure.${extension}`
-
-  const parts: string[] = []
-  // Helper to sanitize and push non-empty parts
-  const safe_push = (value: string | undefined) => {
-    const sanitized = value ? sanitize_filename_part(value) : ``
-    if (sanitized) parts.push(sanitized)
-  }
-  safe_push(structure.id)
-
-  // Add formula (plain text to avoid HTML in filenames)
-  const formula = get_electro_neg_formula(structure, true)
-  if (formula && formula !== `Unknown`) {
-    safe_push(formula.replaceAll(` `, ``))
-  }
-
-  // Add space group if available
-  if (
-    `symmetry` in structure &&
-    structure.symmetry &&
-    typeof structure.symmetry === `object` &&
-    `space_group_symbol` in structure.symmetry
-  ) {
-    const space_group = structure.symmetry.space_group_symbol
-    if (space_group && typeof space_group === `string`) {
-      safe_push(space_group.replaceAll(` `, ``))
-    }
-  }
-
-  // Add lattice system if available
-  if (
-    `lattice` in structure &&
-    structure.lattice &&
-    typeof structure.lattice === `object` &&
-    `lattice_system` in structure.lattice
-  ) {
-    const lattice_system = structure.lattice.lattice_system
-    if (lattice_system && typeof lattice_system === `string`) {
-      safe_push(lattice_system)
-    }
-  }
-
-  // Add number of sites
-  if (structure.sites?.length) parts.push(`${structure.sites.length}sites`)
-
-  const base_name = parts.length > 0 ? parts.join(`-`) : `structure`
-  return `${base_name}.${extension}`
-}
-
-// Generate XYZ content string without saving
-export function structure_to_xyz_str(structure?: AnyStructure): string {
-  if (!structure?.sites) throw new Error(`No structure or sites to export`)
-
-  const lines: string[] = []
-
-  // First line: number of atoms
-  lines.push(String(structure.sites.length))
-
-  // Second line: comment (structure ID, formula, or default)
-  const comment_parts: string[] = []
-  if (structure.id) comment_parts.push(structure.id)
-  const formula = get_electro_neg_formula(structure, true)
-  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) {
-    const lattice_values = structure.lattice.matrix
-      .flat()
-      .map((value: number) => (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
-
-  // 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
-    }
-
-    // Get coordinates - prefer xyz; fallback to abc (converted to cartesian if lattice available)
-    let coords: number[]
-    if (site.xyz && Array.isArray(site.xyz) && site.xyz.length >= 3) {
-      coords = site.xyz.slice(0, 3)
-    } else if (site.abc?.length >= 3 && frac_to_cart) {
-      coords = frac_to_cart(site.abc)
-    } else coords = [0, 0, 0] // fallback
-
-    // Format coordinates to reasonable precision
-    const [x, y, z] = coords.map((coord) => coord.toFixed(6))
-    lines.push(`${element_symbol} ${x} ${y} ${z}`)
-  }
-
-  return lines.join(`\n`)
-}
-
-// Generate a valid CIF data block name from structure formula
-// CIF block names can contain alphanumerics, underscores, but no spaces or special chars
-function get_cif_block_name(structure: AnyStructure): string {
-  try {
-    // Count atoms per element (rounded to nearest integer for occupancy)
-    const element_counts: Record<string, number> = {}
-    for (const site of structure.sites) {
-      if (!site.species || !Array.isArray(site.species)) continue
-      for (const species of site.species) {
-        if (!species.element) continue
-        const count = species.occu ?? 1
-        element_counts[species.element] = (element_counts[species.element] ?? 0) + count
-      }
-    }
-
-    // Sort elements alphabetically and build formula string
-    const elements = Object.keys(element_counts).sort()
-    if (elements.length === 0) throw new Error(`No elements found`)
-
-    const formula = elements
-      .map((el) => {
-        const count = Math.round(element_counts[el])
-        if (count === 0) return null // filter out near-zero occupancies
-        return count === 1 ? el : `${el}${count}`
-      })
-      .filter((part): part is string => part !== null)
-      .join(``)
-
-    if (!formula) throw new Error(`All occupancies round to zero`)
-    return formula
-  } catch {
-    // Fall back to structure.id (sanitized) or generic name
-    if (structure.id) {
-      // Remove invalid CIF characters (keep alphanumerics and underscores)
-      // and condense consecutive underscores for cleaner block names
-      return structure.id.replace(/[^a-zA-Z0-9_]/g, `_`).replace(/_+/g, `_`)
-    }
-    return `structure`
-  }
-}
-
-// Generate CIF content string without saving
-export function structure_to_cif_str(structure?: AnyStructure): string {
-  if (!structure?.sites) throw new Error(`No structure or sites to export`)
-  if (!(`lattice` in structure) || !structure.lattice) {
-    throw new Error(`No lattice information for CIF export`)
-  }
-
-  const lines: string[] = []
-
-  // CIF header with data block (required by pymatgen and CIF spec)
-  lines.push(`# CIF file generated by MatterViz`)
-  const block_name = get_cif_block_name(structure)
-  lines.push(`data_${block_name}`)
-  lines.push(``)
-
-  // Cell parameters
-  const lattice = structure.lattice
-  if (lattice.a && lattice.b && lattice.c) {
-    lines.push(`_cell_length_a ${lattice.a.toFixed(6)}`)
-    lines.push(`_cell_length_b ${lattice.b.toFixed(6)}`)
-    lines.push(`_cell_length_c ${lattice.c.toFixed(6)}`)
-  }
-  if (lattice.alpha && lattice.beta && lattice.gamma) {
-    lines.push(`_cell_angle_alpha ${lattice.alpha.toFixed(6)}`)
-    lines.push(`_cell_angle_beta ${lattice.beta.toFixed(6)}`)
-    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 as Record<string, unknown>
-    const { space_group_number, space_group_symbol } = symmetry
-    if (typeof space_group_symbol === `string` && space_group_symbol) {
-      lines.push(`_space_group_name_H-M_alt ${space_group_symbol}`)
-    }
-    if (
-      (typeof space_group_number === `number` || typeof space_group_number === `string`) &&
-      space_group_number
-    ) {
-      lines.push(`_space_group_IT_number ${space_group_number}`)
-    }
-  }
-
-  lines.push(``)
-
-  // Atom site loop header
-  lines.push(`loop_`)
-  lines.push(`_atom_site_label`)
-  lines.push(`_atom_site_type_symbol`)
-  lines.push(`_atom_site_fract_x`)
-  lines.push(`_atom_site_fract_y`)
-  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
-
-  // Atom sites
-  for (let idx = 0; idx < structure.sites.length; idx++) {
-    const site = structure.sites[idx]
-    if (!site) continue // Skip if site is undefined
-
-    // 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) {
-      const first_species = site.species[0]
-      if (first_species && `element` in first_species && first_species.element) {
-        element_symbol = first_species.element
-        occupancy = first_species?.occu ?? 1
-      }
-    }
-
-    // Get fractional coordinates
-    let frac_coords: number[]
-    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)
-    } else throw new Error(`No valid coordinates found for site ${idx}`)
-
-    // Format: label element_symbol x y z
-    const label = site.label || `${element_symbol}${idx + 1}`
-    lines.push(
-      `${label} ${element_symbol} ${frac_coords[0].toFixed(8)} ${frac_coords[1].toFixed(
-        8,
-      )} ${frac_coords[2].toFixed(8)} ${occupancy.toFixed(8)}`,
-    )
-  }
-
-  return lines.join(`\n`)
-}
-
-// Generate VASP POSCAR content string without saving
-export function structure_to_poscar_str(structure?: AnyStructure): string {
-  if (!structure?.sites) throw new Error(`No structure or sites to export`)
-  if (!(`lattice` in structure) || !structure.lattice) {
-    throw new Error(`No lattice information for POSCAR export`)
-  }
-  const lines: string[] = []
-
-  // Use plain text formula for POSCAR title to avoid HTML tags
-  const formula = get_electro_neg_formula(structure, true)
-  const title =
-    structure.id ||
-    (formula && formula !== `Unknown` ? formula : null) ||
-    `Generated from structure`
-  lines.push(title)
-  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)}`,
-    )
-  } else {
-    throw new Error(`No valid lattice matrix for POSCAR export`)
-  }
-
-  // Count atoms by element
-  const element_counts = new Map<string, number>()
-  const element_symbols: string[] = []
-
-  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)
-  }
-
-  // Element symbols line
-  lines.push(element_symbols.join(` `))
-
-  // Atom counts line
-  lines.push(element_symbols.map((el) => element_counts.get(el)).join(` `))
-
-  // Check if any site has selective dynamics
-  const has_selective_dynamics = structure.sites.some(
-    (site) => site.properties?.selective_dynamics,
-  )
-  if (has_selective_dynamics) {
-    lines.push(`Selective dynamics`)
-  }
-
-  // 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
-
-  // 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: number[]
-        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) as Vec3)
-        } 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,
-          ]) as boolean[]
-          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`)
-}
-
-// Generate JSON content string without saving
-export function structure_to_json_str(structure?: AnyStructure): string {
-  if (!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?: AnyStructure): void {
-  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?: AnyStructure): void {
-  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?: AnyStructure): void {
-  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?: AnyStructure): void {
-  try {
-    const data = structure_to_json_str(structure)
-    const filename = create_structure_filename(structure, `json`)
-    download(data, filename, `application/json`)
-  } catch (error) {
-    console.error(`Error exporting JSON:`, error)
-  }
-}
-
-// Export Three.js scene as GLB (binary GLTF) file
-// GLB preserves materials and colors, making it ideal for element visualization
-export function export_structure_as_glb(
-  scene: Scene | null,
-  structure: AnyStructure | undefined,
-): void {
-  try {
-    if (!scene) {
-      console.warn(`No scene available for GLB export`)
-      return
-    }
-
-    // Convert instanced meshes to regular meshes for export
-    const export_scene = convert_instanced_meshes_to_regular(scene)
-
-    const exporter = new GLTFExporter()
-    const filename = create_structure_filename(structure, `glb`)
-
-    // Export as binary GLB format
-    exporter.parse(
-      export_scene,
-      (result) => {
-        if (result instanceof ArrayBuffer) {
-          const blob = new Blob([result], { type: `model/gltf-binary` })
-          download(blob, filename, `model/gltf-binary`)
-        } else {
-          console.error(`GLB export returned unexpected format`)
-        }
-      },
-      (error) => {
-        console.error(`GLB export failed:`, error)
-      },
-      { binary: true },
-    )
-  } catch (error) {
-    console.error(`Error exporting GLB:`, error)
-  }
-}
-
-// Export Three.js scene as OBJ (Wavefront Object) file with accompanying MTL file for materials
-// OBJ exports geometry with material references, MTL contains color definitions
-export function export_structure_as_obj(
-  scene: Scene | null,
-  structure: AnyStructure | undefined,
-): void {
-  try {
-    if (!scene) {
-      console.warn(`No scene available for OBJ export`)
-      return
-    }
-
-    // Convert instanced meshes to regular meshes for export
-    const export_scene = convert_instanced_meshes_to_regular(scene)
-
-    const obj_exporter = new OBJExporter()
-
-    const base_filename = create_structure_filename(structure, ``).replace(/\.$/, ``)
-    const obj_filename = `${base_filename}.obj`
-    const mtl_filename = `${base_filename}.mtl`
-
-    // Generate OBJ content with material library reference
-    let obj_content = obj_exporter.parse(export_scene)
-    // Add material library reference at the beginning of the OBJ file
-    obj_content = `mtllib ${mtl_filename}\n${obj_content}`
-
-    // Generate MTL content with material color definitions
-    const mtl_content = generate_mtl_content(export_scene)
-
-    // Download both files
-    const obj_blob = new Blob([obj_content], { type: `text/plain` })
-    const mtl_blob = new Blob([mtl_content], { type: `text/plain` })
-
-    download(obj_blob, obj_filename, `text/plain`)
-    // Small delay to prevent some browsers from blocking rapid successive downloads as potential abuse.
-    // A more robust solution might be to zip both files together.
-    setTimeout(() => download(mtl_blob, mtl_filename, `text/plain`), 100)
-  } catch (error) {
-    console.error(`Error exporting OBJ:`, error)
-  }
-}