matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,861 @@
+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)
+  }
+}