matterviz 0.4.0 → 0.4.2

package/dist/structure/InstancedAtoms.svelte

@@ -0,0 +1,114 @@
+<script lang="ts">
+  // All atoms of one visual class (base or ghosted PBC image) in a single
+  // THREE.InstancedMesh: one draw call and zero per-atom Svelte components.
+  // Per-atom colors live in the instanceColor buffer, per-atom position/radius
+  // in the instanceMatrix buffer. Pointer handlers spread onto the mesh receive
+  // threlte intersection events whose `instanceId` indexes into `atoms`.
+  //
+  // This replaces one <extras.Instance> component (plus one scene-graph Group and
+  // one interactivity registration) per atom, which made structure changes on
+  // supercells block the main thread for seconds and hover raycasts O(n²).
+  import type { Vec3 } from '../math'
+  import { T, useThrelte } from '@threlte/core'
+  import { untrack } from 'svelte'
+  import { Color, InstancedMesh, Matrix4, MeshStandardMaterial, SphereGeometry } from 'three'
+
+  type InstancedAtom = {
+    position: Vec3
+    radius: number
+    color?: string
+  }
+
+  let {
+    atoms,
+    sphere_segments = 20,
+    ghost = false,
+    ...pointer_props
+  }: {
+    atoms: InstancedAtom[]
+    sphere_segments?: number
+    // edit-mode PBC image atoms: desaturated + translucent
+    ghost?: boolean
+    // threlte interactivity handlers (onpointerenter, onclick, ...) forwarded to the mesh
+    [key: string]: unknown
+  } = $props()
+
+  const { invalidate } = useThrelte()
+
+  // One material shared across mesh recreations; per-atom colors come from the
+  // instanceColor buffer so the base color stays white.
+  const material = new MeshStandardMaterial()
+  $effect(() => () => material.dispose())
+
+  $effect(() => {
+    material.transparent = ghost
+    material.opacity = ghost ? 0.5 : 1
+    material.needsUpdate = true
+    invalidate()
+  })
+
+  let geometry = $state.raw<SphereGeometry | null>(null)
+  $effect(() => {
+    const geo = new SphereGeometry(0.5, sphere_segments, sphere_segments)
+    geometry = geo
+    return () => geo.dispose()
+  })
+
+  // Recreate the mesh only when capacity must change (instanceMatrix buffer size
+  // is fixed at construction); data updates just rewrite the buffers below.
+  let mesh = $state.raw<InstancedMesh | null>(null)
+  $effect(() => {
+    const count = atoms.length
+    const prev = untrack(() => mesh)
+    if (prev && prev.count === count) return
+    prev?.dispose()
+    if (count === 0) {
+      mesh = null
+      return
+    }
+    const next = new InstancedMesh(untrack(() => geometry) ?? undefined, material, count)
+    next.frustumCulled = false
+    // export.ts reads per-instance colors (instead of the material color) when set
+    next.userData.per_instance_color = true
+    mesh = next
+  })
+  // Unmount-only cleanup (a cleanup on the effect above would dispose the mesh
+  // on every re-run, including runs that keep it; cleanups run untracked)
+  $effect(() => () => mesh?.dispose())
+
+  $effect(() => {
+    if (mesh && geometry && mesh.geometry !== geometry) {
+      mesh.geometry = geometry
+      invalidate()
+    }
+  })
+
+  const scratch_matrix = new Matrix4()
+  const scratch_color = new Color()
+  const gray = new Color(0x999999)
+
+  $effect(() => {
+    const current = mesh
+    if (!current) return
+    const limit = Math.min(atoms.length, current.count)
+    for (let idx = 0; idx < limit; idx++) {
+      const { position, radius, color } = atoms[idx]
+      scratch_matrix
+        .makeScale(radius, radius, radius)
+        .setPosition(position[0], position[1], position[2])
+      current.setMatrixAt(idx, scratch_matrix)
+      scratch_color.set(color ?? gray)
+      if (ghost) scratch_color.lerp(gray, 0.4)
+      current.setColorAt(idx, scratch_color)
+    }
+    current.instanceMatrix.needsUpdate = true
+    if (current.instanceColor) current.instanceColor.needsUpdate = true
+    // keep the whole-mesh bounding sphere in sync so raycasts can early-reject
+    current.computeBoundingSphere()
+    invalidate()
+  })
+</script>
+
+{#if mesh}
+  <T is={mesh} {...pointer_props} />
+{/if}

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

@@ -0,0 +1,15 @@
+import type { Vec3 } from '../math';
+type InstancedAtom = {
+    position: Vec3;
+    radius: number;
+    color?: string;
+};
+type $$ComponentProps = {
+    atoms: InstancedAtom[];
+    sphere_segments?: number;
+    ghost?: boolean;
+    [key: string]: unknown;
+};
+declare const InstancedAtoms: import("svelte").Component<$$ComponentProps, {}, "">;
+type InstancedAtoms = ReturnType<typeof InstancedAtoms>;
+export default InstancedAtoms;

package/dist/structure/Lattice.svelte

@@ -5,15 +5,10 @@
   import * as math from '../math'
   import { DEFAULTS } from '../settings'
   import { CanvasTooltip } from './'
+  import Arrow from './Arrow.svelte'
+  import Cylinder from './Cylinder.svelte'
   import { T } from '@threlte/core'
-  import {
-    BoxGeometry,
-    EdgesGeometry,
-    Euler,
-    Matrix4,
-    Quaternion,
-    Vector3,
-  } from 'three'
+  import { BoxGeometry, EdgesGeometry, Matrix4, Vector3 } from 'three'
 
   let {
     matrix = undefined,
@@ -24,7 +19,7 @@
     cell_surface_opacity = DEFAULTS.structure.cell_surface_opacity,
     show_cell_vectors = true,
     vector_colors = [`red`, `green`, `blue`],
-    vector_origin = [-1, -1, -1] satisfies Vec3,
+    vector_origin = [-1, -1, -1],
     float_fmt = `.2f`,
   }: {
     matrix?: math.Matrix3x3
@@ -40,157 +35,98 @@
   } = $props()
 
   let hovered_idx = $state<number | null>(null) // track hovered vector
-  let lattice_center = $derived(
-    matrix
-      ? (math.scale(math.add(...matrix), 0.5) satisfies Vec3)
-      : ([0, 0, 0] satisfies Vec3),
+  let lattice_center: Vec3 = $derived(
+    matrix ? math.scale(math.add(...matrix), 0.5) : [0, 0, 0],
   )
 
-  // Extract line segments from EdgesGeometry for cylinder-based thick lines
-  function get_edge_segments(edges_geometry: EdgesGeometry): [Vector3, Vector3][] {
-    const positions = edges_geometry.getAttribute(`position`).array as Float32Array
-    const segments: [Vector3, Vector3][] = []
-
-    for (let idx = 0; idx < positions.length; idx += 6) {
-      const start = new Vector3(
-        positions[idx + 0],
-        positions[idx + 1],
-        positions[idx + 2],
-      )
-      const end = new Vector3(
-        positions[idx + 3],
-        positions[idx + 4],
-        positions[idx + 5],
-      )
-      segments.push([start, end])
-    }
-
-    return segments
-  }
-
-  // Calculate cylinder transform for a line segment
-  function get_cylinder_transform(
-    start: Vector3,
-    end: Vector3,
-  ): { position: Vec3; rotation: Vec3; length: number } {
-    const direction = end.clone().sub(start)
-    const length = direction.length()
-    const center = start.clone().add(end).multiplyScalar(0.5)
-
-    if (length === 0) { // Zero-length: no rotation; render a degenerate cylinder
-      return { position: center.toArray(), rotation: [0, 0, 0], length }
+  // Build the sheared box geometry in an effect so the previous one is disposed on
+  // matrix change / unmount (same disposal pattern as the polyhedra in StructureScene).
+  let box_geometry = $state<BoxGeometry | null>(null)
+  $effect(() => {
+    if (!matrix) {
+      box_geometry = null
+      return
     }
-    // Calculate rotation to align cylinder with the line (zero-length guarded above)
-    const quaternion = new Quaternion().setFromUnitVectors(
-      new Vector3(0, 1, 0),
-      direction.normalize(),
+    const shear_matrix = new Matrix4().makeBasis(
+      new Vector3(...matrix[0]),
+      new Vector3(...matrix[1]),
+      new Vector3(...matrix[2]),
     )
-    const euler = new Euler().setFromQuaternion(quaternion)
+    const geo = new BoxGeometry(1, 1, 1).applyMatrix4(shear_matrix)
+    box_geometry = geo
+    return () => geo.dispose()
+  })
 
-    return {
-      position: center.toArray(),
-      rotation: euler.toArray().slice(0, 3) as Vec3,
-      length,
+  // Edge segments (Cartesian endpoint pairs) from the box geometry; the transient
+  // EdgesGeometry is disposed inline since only its extracted positions are kept.
+  let edge_segments = $derived.by<[Vec3, Vec3][]>(() => {
+    if (!box_geometry || !(cell_edge_opacity > 0)) return []
+    const edges_geometry = new EdgesGeometry(box_geometry)
+    const positions = edges_geometry.getAttribute(`position`).array as Float32Array
+    edges_geometry.dispose()
+    const segments: [Vec3, Vec3][] = []
+    // each edge is two consecutive xyz triplets (6 floats)
+    for (let idx = 0; idx < positions.length; idx += 6) {
+      segments.push([
+        [positions[idx], positions[idx + 1], positions[idx + 2]],
+        [positions[idx + 3], positions[idx + 4], positions[idx + 5]],
+      ])
     }
-  }
+    return segments
+  })
 </script>
 
-{#if matrix}
-  {#key matrix}
-    {@const shear_matrix = new Matrix4().makeBasis(
-    new Vector3(...matrix[0]),
-    new Vector3(...matrix[1]),
-    new Vector3(...matrix[2]),
-  )}
-    {@const box_geometry = new BoxGeometry(1, 1, 1).applyMatrix4(shear_matrix)}
-
-    <!-- Render wireframe edges if edge opacity > 0 -->
-    {#if cell_edge_opacity > 0}
-      {@const edges_geometry = new EdgesGeometry(box_geometry)}
-      {@const edge_segments = get_edge_segments(edges_geometry)}
-
-      <!-- Use cylinders for thick wireframe lines -->
-      <T.Group position={lattice_center}>
-        {#each edge_segments as [start, end], idx (idx)}
-          {@const { position, rotation, length } = get_cylinder_transform(start, end)}
-          <T.Mesh {position} {rotation}>
-            <T.CylinderGeometry
-              args={[cell_edge_width * 0.01, cell_edge_width * 0.01, length, 8]}
-            />
-            <T.MeshStandardMaterial
-              color={cell_edge_color}
-              opacity={cell_edge_opacity}
-              transparent
-              depthWrite={false}
-            />
-          </T.Mesh>
-        {/each}
-      </T.Group>
-    {/if}
-
-    <!-- Render transparent surfaces if surface opacity > 0 -->
-    {#if cell_surface_opacity > 0}
-      <T.Mesh geometry={box_geometry} position={lattice_center}>
-        <T.MeshStandardMaterial
-          color={cell_surface_color}
-          opacity={cell_surface_opacity}
-          transparent
-          depthWrite={false}
+{#if matrix && box_geometry}
+  <!-- Wireframe edges (thick lines via cylinders) when edge opacity > 0 -->
+  {#if cell_edge_opacity > 0}
+    <T.Group position={lattice_center}>
+      {#each edge_segments as [start, end], idx (idx)}
+        <Cylinder
+          from={start}
+          to={end}
+          thickness={cell_edge_width * 0.01}
+          color={cell_edge_color}
+          opacity={cell_edge_opacity}
         />
-      </T.Mesh>
-    {/if}
+      {/each}
+    </T.Group>
+  {/if}
 
-    <!-- NOTE below is an untested fix for the lattice vectors being much too small when deployed even though they look correct in local dev -->
-    {#if show_cell_vectors}
-      <T.Group position={vector_origin}>
-        {#each matrix as vec, idx (vec)}
-          {@const shaft_length = Math.hypot(...vec) * 0.85}
-          <!-- Shaft goes to 85% of vector length -->
-          {@const tip_start_position = math.scale(vec, 0.85) as Vec3}
-          <!-- Calculate rotation to align with vector direction -->
-          {@const quaternion = new Quaternion().setFromUnitVectors(
-      new Vector3(0, 1, 0), // Default up direction for cylinder/cone
-      new Vector3(...vec).normalize(),
-    )}
-          {@const rotation = new Euler()
-      .setFromQuaternion(quaternion)
-      .toArray()
-      .slice(0, 3) as Vec3}
-          <!-- Arrow shaft - position at center of shaft length -->
-          {@const shaft_center = math.scale(vec, 0.425) as Vec3}
-          <!-- Center at 42.5% = half of 85% -->
-          <T.Mesh
-            position={shaft_center}
-            {rotation}
-            onpointerenter={() => hovered_idx = idx}
-            onpointerleave={() => hovered_idx = null}
-          >
-            <T.CylinderGeometry args={[0.05, 0.05, shaft_length, 16]} />
-            <T.MeshStandardMaterial color={vector_colors[idx]} />
-          </T.Mesh>
+  <!-- Render transparent surfaces if surface opacity > 0 -->
+  {#if cell_surface_opacity > 0}
+    <T.Mesh geometry={box_geometry} position={lattice_center}>
+      <T.MeshStandardMaterial
+        color={cell_surface_color}
+        opacity={cell_surface_opacity}
+        transparent
+        depthWrite={false}
+      />
+    </T.Mesh>
+  {/if}
 
-          <!-- Arrow tip -->
-          <T.Mesh
-            position={tip_start_position}
-            {rotation}
-            onpointerenter={() => hovered_idx = idx}
-            onpointerleave={() => hovered_idx = null}
-          >
-            <T.ConeGeometry args={[0.175, 0.5, 16]} />
-            <T.MeshStandardMaterial color={vector_colors[idx]} />
-          </T.Mesh>
-        {/each}
-      </T.Group>
+  {#if show_cell_vectors}
+    {#each matrix as vec, idx (vec)}
+      <Arrow
+        position={vector_origin}
+        vector={vec}
+        scale={0.5}
+        color={vector_colors[idx]}
+        shaft_radius={0.1}
+        arrow_head_radius={0.2}
+        arrow_head_length={0.8}
+        onpointerenter={() => (hovered_idx = idx)}
+        onpointerleave={() => (hovered_idx = null)}
+      />
+    {/each}
 
-      <!-- Tooltip for hovered vector -->
-      {#if hovered_idx !== null && matrix}
-        {@const hovered_vec = matrix[hovered_idx]}
-        {@const tooltip_position = math.add(vector_origin, hovered_vec)}
-        <CanvasTooltip position={tooltip_position}>
-          <strong>{[`A`, `B`, `C`][hovered_idx]}</strong>
-          ({hovered_vec.map((coord) => format_num(coord, float_fmt)).join(`, `)}) Å
-        </CanvasTooltip>
-      {/if}
+    <!-- Tooltip for hovered vector -->
+    {#if hovered_idx !== null && matrix}
+      {@const hovered_vec = matrix[hovered_idx]}
+      {@const tooltip_position = math.add(vector_origin, hovered_vec)}
+      <CanvasTooltip position={tooltip_position}>
+        <strong>{[`A`, `B`, `C`][hovered_idx]}</strong>
+        ({hovered_vec.map((coord) => format_num(coord, float_fmt)).join(`, `)}) Å
+      </CanvasTooltip>
     {/if}
-  {/key}
+  {/if}
 {/if}

package/dist/structure/SiteLabels.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+  // Single overlay for all site labels: one portaled DOM container plus one
+  // per-frame position pass. Replaces per-label threlte <HTML> components (each
+  // of which carries its own portal, per-frame task and matrix updates), which
+  // made labels on large structures/supercells unusable.
+  import type { Vec3 } from '../math'
+  import { T, useTask, useThrelte } from '@threlte/core'
+  import type { Snippet } from 'svelte'
+  import { Group } from 'three'
+  import { type LabelPlacement, LabelProjector } from './atom-label-placement'
+
+  type SiteLabelEntry = {
+    site_idx: number
+    position: Vec3 // in the local space of the surrounding rotation groups
+    radius: number // visual atom scale (SphereGeometry(0.5) scale factor)
+  }
+
+  let {
+    entries,
+    get_offset,
+    screen_margin,
+    label,
+  }: {
+    entries: SiteLabelEntry[]
+    get_offset: (site_idx: number) => Vec3
+    screen_margin: number
+    label: Snippet<[{ site_idx: number }]>
+  } = $props()
+
+  const { camera, size, dom, renderStage } = useThrelte()
+
+  // Anchor object inside the scene's rotation groups so label positions follow
+  // the same transform as the atoms they annotate.
+  const anchor = new Group()
+  let container = $state<HTMLDivElement>()
+
+  const projector = new LabelProjector()
+  const placement: LabelPlacement = { x: 0, y: 0, visible: false }
+  // Cache last-applied transform per label to skip redundant style writes
+  let last_transforms: string[] = []
+
+  function update_positions() {
+    const cam = camera.current
+    if (!container || !cam) return
+    cam.updateMatrixWorld()
+    anchor.updateWorldMatrix(true, false)
+    projector.update(cam, anchor.matrixWorld, size.current, screen_margin)
+    // Read reactive props once, not per label (prop getters cross a component
+    // boundary and would otherwise run 2-3x per label per frame)
+    const items = entries
+    const offset_of = get_offset
+    const kids = container.children
+    for (let idx = 0; idx < items.length; idx++) {
+      const el = kids[idx] as HTMLElement | undefined
+      if (!el) break
+      const entry = items[idx]
+      projector.place(entry.position, offset_of(entry.site_idx), entry.radius * 0.5, placement)
+      // Hide labels behind the camera (same check as threlte's <HTML>)
+      if (!placement.visible) {
+        if (el.style.display !== `none`) el.style.display = `none`
+        continue
+      }
+      if (el.style.display === `none`) el.style.display = ``
+      const transform = `translate(-50%, -50%) translate3d(${placement.x.toFixed(1)}px, ${placement.y.toFixed(
+        1,
+      )}px, 0)`
+      if (last_transforms[idx] !== transform) {
+        last_transforms[idx] = transform
+        el.style.transform = transform
+      }
+    }
+  }
+
+  // Follow camera motion (runs only on rendered frames, like threlte's <HTML>)
+  useTask(update_positions, { stage: renderStage, autoInvalidate: false })
+
+  // Immediate repositioning when label data, offsets or viewport size changes.
+  // update_positions is deliberately tracked: it reads entries, screen_margin and
+  // (via get_offset) the scene's offset state, so offset changes re-run this
+  // effect even when no frame is scheduled.
+  $effect(() => {
+    void $size
+    last_transforms = []
+    update_positions()
+  })
+
+  const portal_action = (el: HTMLElement) => {
+    if (!dom) return
+    dom.append(el)
+    return { destroy: () => el.remove() }
+  }
+</script>
+
+<T is={anchor} />
+
+<div bind:this={container} class="site-labels-overlay" use:portal_action>
+  {#each entries as entry (entry.site_idx)}
+    <div class="site-label">
+      {@render label({ site_idx: entry.site_idx })}
+    </div>
+  {/each}
+</div>
+
+<style>
+  .site-labels-overlay {
+    position: absolute;
+    top: 0;
+    left: 0;
+    pointer-events: none;
+  }
+  .site-label {
+    position: absolute;
+    top: 0;
+    left: 0;
+    pointer-events: auto;
+    white-space: nowrap;
+    /* measured A/B (888 labels, 2x2x2 supercell, auto-rotating, dpr 2): 60fps
+      with will-change vs ~34fps without - promoting labels to their own layers
+      avoids repaints when only transforms change */
+    will-change: transform;
+  }
+</style>

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

@@ -0,0 +1,18 @@
+import type { Vec3 } from '../math';
+import type { Snippet } from 'svelte';
+type SiteLabelEntry = {
+    site_idx: number;
+    position: Vec3;
+    radius: number;
+};
+type $$ComponentProps = {
+    entries: SiteLabelEntry[];
+    get_offset: (site_idx: number) => Vec3;
+    screen_margin: number;
+    label: Snippet<[{
+        site_idx: number;
+    }]>;
+};
+declare const SiteLabels: import("svelte").Component<$$ComponentProps, {}, "">;
+type SiteLabels = ReturnType<typeof SiteLabels>;
+export default SiteLabels;