matterviz 0.3.7 → 0.4.1

package/dist/fermi-surface/FermiSurfaceScene.svelte

@@ -1,17 +1,25 @@
 <script lang="ts">
   import type { BrillouinZoneData } from '../brillouin'
-  import { AXIS_COLORS, NEG_AXIS_COLORS } from '../colors'
-  import type { Matrix4Tuple, Vec3 } from '../math'
+  import {
+    cartesian_to_fractional,
+    default_camera_position,
+    k_lattice_inverse,
+    k_space_size,
+    polyhedron_centroid,
+    polyhedron_geometry,
+    ReciprocalVectors,
+  } from '../brillouin'
+  import type { D3InterpolateName } from '../colors'
+  import { get_d3_interpolator } from '../colors'
+  import type { Matrix4Tuple, Vec2, Vec3 } from '../math'
   import * as math from '../math'
-  import type { CameraProjection } from '../settings'
+  import { bind_renderer, build_orbit_props, SceneCamera } from '../scene'
+  import type { SceneControlProps, ThreltePointerEvent } from '../scene'
   import { DEFAULTS } from '../settings'
-  import { Arrow, Cylinder } from '../structure'
-  import { T, useThrelte } from '@threlte/core'
+  import { Cylinder } from '../structure'
+  import { T } from '@threlte/core'
   import * as extras from '@threlte/extras'
-  import * as d3_sc from 'd3-scale-chromatic'
-  import type { ComponentProps } from 'svelte'
   import { SvelteMap } from 'svelte/reactivity'
-  import type { Camera, Scene } from 'three'
   import {
     BackSide,
     BufferAttribute,
@@ -33,9 +41,6 @@
     RepresentationMode,
   } from './types'
 
-  // Threlte pointer event type for mesh interactions
-  type ThreltePointerEvent = { point: Vector3; nativeEvent: PointerEvent }
-
   let {
     fermi_data = $bindable(),
     bz_data = $bindable(),
@@ -75,15 +80,13 @@
     directional_light = DEFAULTS.structure.directional_light,
     gizmo = DEFAULTS.structure.show_gizmo,
     auto_rotate = DEFAULTS.structure.auto_rotate,
-    camera_is_moving = $bindable(false),
     scene = $bindable(),
     camera = $bindable(),
     hover_data = $bindable<FermiHoverData | null>(null),
-  }: {
+  }: SceneControlProps & {
     fermi_data?: FermiSurfaceData
     bz_data?: BrillouinZoneData
     camera_position?: Vec3 | undefined
-    camera_projection?: CameraProjection
     color_property?: ColorProperty
     color_scale?: string
     representation?: RepresentationMode
@@ -101,33 +104,20 @@
     clip_position?: number
     clip_flip?: boolean
     vector_scale?: number
-    rotation_damping?: number
-    max_zoom?: number
-    min_zoom?: number
-    rotate_speed?: number
-    zoom_speed?: number
-    pan_speed?: number
-    zoom_to_cursor?: boolean
-    fov?: number
-    initial_zoom?: number
-    ambient_light?: number
-    directional_light?: number
-    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>
-    auto_rotate?: number
-    camera_is_moving?: boolean
-    scene?: Scene
-    camera?: Camera
     hover_data?: FermiHoverData | null
   } = $props()
 
-  const threlte = useThrelte()
+  const threlte = bind_renderer(
+    (threlte_scene, threlte_camera) => {
+      scene = threlte_scene
+      camera = threlte_camera
+    },
+    // Enable object sorting for proper depth ordering of transparent surfaces
+    (renderer) => (renderer.sortObjects = true),
+  )
 
-  // Compute scene size for clipping (also used for camera positioning later)
-  function get_scene_size(): number {
-    if (!fermi_data?.k_lattice) return 10
-    const mags = fermi_data.k_lattice.map((vec) => Math.hypot(...vec))
-    return mags.reduce((sum, mag) => sum + mag, 0) / 3
-  }
+  // Characteristic scene size, used for clipping and camera positioning
+  const scene_size = $derived(k_space_size(fermi_data?.k_lattice))
 
   // Compute clipping plane based on axis and position
   // Plane equation: dot(normal, point) + constant >= 0 means point is visible
@@ -138,7 +128,7 @@
     const normal_arr: Vec3 = [0, 0, 0]
     normal_arr[axis_idx] = clip_flip ? -1 : 1
 
-    const scaled_position = clip_position * get_scene_size()
+    const scaled_position = clip_position * scene_size
     // constant = -position for normal case (keep points >= position)
     // constant = +position for flipped case (keep points <= position)
     const constant = clip_flip ? scaled_position : -scaled_position
@@ -159,24 +149,8 @@
     }
   })
 
-  $effect(() => {
-    scene = threlte.scene
-    camera = threlte.camera.current
-    if (threlte.renderer) {
-      // Enable object sorting for proper depth ordering of transparent surfaces
-      threlte.renderer.sortObjects = true
-      Object.assign(threlte.renderer.domElement, { __renderer: threlte.renderer })
-    }
-  })
-
   extras.interactivity()
 
-  // Get color interpolator from d3
-  const get_interpolator = (name: string): (t: number) => string => {
-    const fn = d3_sc[name as keyof typeof d3_sc]
-    return typeof fn === `function` ? fn : d3_sc.interpolateViridis
-  }
-
   // Filter surfaces based on selected bands
   let visible_surfaces = $derived(
     fermi_data?.isosurfaces.filter((surface) =>
@@ -216,7 +190,7 @@
   })
 
   // Compute property range for color scaling
-  let property_range = $derived.by((): [number, number] => {
+  let property_range = $derived.by((): Vec2 => {
     if (color_property !== `velocity` && color_property !== `custom`) {
       return [0, 1]
     }
@@ -247,7 +221,7 @@
       const normalized = max_val > min_val
         ? (prop - min_val) / (max_val - min_val)
         : 0.5
-      return get_interpolator(color_scale)(normalized)
+      return get_d3_interpolator(color_scale as D3InterpolateName)(normalized)
     }
     // Spin coloring
     if (color_property === `spin` && surface.spin) {
@@ -377,108 +351,30 @@
     }
   })
 
-  // Compute rotation target from surfaces or BZ
-  const rotation_target = $derived.by((): Vec3 => {
-    if (bz_data?.vertices && bz_data.vertices.length > 0) {
-      const sum = bz_data.vertices.reduce(
-        (acc, vert) => math.add(acc, vert),
-        [0, 0, 0] as Vec3,
-      )
-      return math.scale(sum, 1 / bz_data.vertices.length)
-    }
-    return [0, 0, 0]
-  })
-
-  // Scene size for camera positioning (uses helper function defined earlier)
-  const scene_size = $derived(get_scene_size())
+  // BZ centroid as rotation center
+  const rotation_target = $derived(polyhedron_centroid(bz_data?.vertices))
 
-  const computed_camera_position = $derived.by(
-    () =>
-      camera_position || ([10, 3, 8].map((coord) =>
-        coord * Math.max(1, scene_size)
-      ) as Vec3),
+  const computed_camera_position = $derived(
+    camera_position || default_camera_position(scene_size),
   )
 
-  const gizmo_props = $derived({
-    background: { enabled: false },
-    className: `responsive-gizmo`,
-    ...Object.fromEntries(
-      [...AXIS_COLORS, ...NEG_AXIS_COLORS].map(([axis, color, hover]) => [
-        axis,
-        {
-          color,
-          labelColor: `#111`,
-          opacity: axis.startsWith(`n`) ? 0.9 : 0.8,
-          hover: {
-            color: hover,
-            labelColor: `#222`,
-            opacity: axis.startsWith(`n`) ? 1 : 0.9,
-          },
-        },
-      ]),
-    ),
-    ...(typeof gizmo === `object` ? gizmo : {}),
-    offset: { left: 5, bottom: 5 },
-  })
-
-  const is_ortho = $derived(camera_projection === `orthographic`)
-  const orbit_controls_props = $derived({
-    position: [0, 0, 0],
+  const orbit_controls_props = $derived(build_orbit_props({
+    camera_projection,
     target: rotation_target,
-    enableRotate: rotate_speed > 0,
-    rotateSpeed: rotate_speed,
-    enableZoom: zoom_speed > 0,
-    zoomSpeed: is_ortho ? zoom_speed * 2 : zoom_speed,
-    zoomToCursor: zoom_to_cursor,
-    enablePan: pan_speed > 0,
-    panSpeed: pan_speed,
-    maxZoom: max_zoom,
-    minZoom: min_zoom,
-    autoRotate: Boolean(auto_rotate),
-    autoRotateSpeed: auto_rotate,
-    enableDamping: Boolean(rotation_damping),
-    dampingFactor: rotation_damping,
-    onstart: () => (camera_is_moving = true),
-    onend: () => (camera_is_moving = false),
-  })
-
-  const vector_colors = [`red`, `green`, `blue`]
-  const vector_labels = [`b₁`, `b₂`, `b₃`]
+    rotate_speed,
+    zoom_speed,
+    zoom_to_cursor,
+    pan_speed,
+    max_zoom,
+    min_zoom,
+    auto_rotate,
+    rotation_damping,
+  }))
 
   // Create BZ geometry
-  const bz_geometry = $derived.by(() => {
-    if (!bz_data || bz_data.faces.length === 0) return null
-
-    const positions: number[] = []
-    const normals: number[] = []
-
-    for (const face of bz_data.faces) {
-      if (face.length < 3) continue
-
-      for (let face_idx = 1; face_idx < face.length - 1; face_idx++) {
-        const indices = [face[0], face[face_idx], face[face_idx + 1]]
-        if (indices.some((idx) => idx < 0 || idx >= bz_data.vertices.length)) continue
-        const [v0, v1, v2] = indices.map((idx) => bz_data.vertices[idx])
-        positions.push(...v0, ...v1, ...v2)
-
-        const e1: Vec3 = math.subtract(v1, v0)
-        const e2: Vec3 = math.subtract(v2, v0)
-        const normal_vec = math.cross_3d(e1, e2)
-        const len = Math.hypot(...normal_vec)
-        const norm = len > 1e-10 ? normal_vec.map((coord) => coord / len) : [0, 0, 0]
-        normals.push(...norm, ...norm, ...norm)
-      }
-    }
-
-    const geometry = new BufferGeometry()
-    geometry.setAttribute(
-      `position`,
-      new BufferAttribute(new Float32Array(positions), 3),
-    )
-    geometry.setAttribute(`normal`, new BufferAttribute(new Float32Array(normals), 3))
-    geometry.computeBoundingSphere()
-    return geometry
-  })
+  const bz_geometry = $derived(
+    bz_data ? polyhedron_geometry(bz_data.vertices, bz_data.faces) : null,
+  )
 
   $effect(() => {
     const prev_geometry = bz_geometry
@@ -516,26 +412,12 @@
     return { ...base, color: surface_color }
   }
 
-  // Compute inverse of k_lattice for Cartesian->fractional conversion (cached)
-  const k_lattice_inv = $derived.by(() => {
-    if (!fermi_data?.k_lattice) return null
-    try {
-      return math.matrix_inverse_3x3(fermi_data.k_lattice)
-    } catch {
-      return null
-    }
-  })
+  // Inverse of k_lattice for Cartesian->fractional conversion (cached)
+  const k_lattice_inv = $derived(k_lattice_inverse(fermi_data?.k_lattice))
 
   // Throttle state for pointer move events to avoid O(n) vertex lookups causing jank
   let last_hover_time = 0
 
-  // Convert Cartesian k-coordinates to fractional (reciprocal lattice units)
-  // Returns null if k_lattice is unavailable or inversion failed
-  function cartesian_to_fractional(cart: Vec3): Vec3 | null {
-    if (!k_lattice_inv) return null
-    return math.mat3x3_vec3_multiply(k_lattice_inv, cart)
-  }
-
   // Find index of nearest vertex to a point in a surface
   function find_nearest_vertex(surface: Isosurface, point: Vec3): number {
     let [min_dist, nearest_idx] = [Infinity, 0]
@@ -564,7 +446,7 @@
   ): FermiHoverData {
     // event.point is in world space (after sym_matrix transformation)
     const position_cartesian: Vec3 = [event.point.x, event.point.y, event.point.z]
-    const position_fractional = cartesian_to_fractional(position_cartesian)
+    const position_fractional = cartesian_to_fractional(k_lattice_inv, position_cartesian)
 
     // Transform world-space point to local space for nearest-vertex lookup
     // surface.vertices are in local space (raw geometry before sym_matrix)
@@ -610,26 +492,20 @@
     last_hover_time = now
     hover_data = create_hover_data(event, surface, surface_color, sym_idx, sym_matrix)
   }
+
+  const clear_hover = () => {
+    hover_data = null
+  }
 </script>
 
-{#if camera_projection === `perspective`}
-  <T.PerspectiveCamera makeDefault position={computed_camera_position} {fov}>
-    <extras.OrbitControls {...orbit_controls_props}>
-      {#if gizmo}<extras.Gizmo {...gizmo_props} />{/if}
-    </extras.OrbitControls>
-  </T.PerspectiveCamera>
-{:else}
-  <T.OrthographicCamera
-    makeDefault
-    position={computed_camera_position}
-    zoom={initial_zoom}
-    near={-100}
-  >
-    <extras.OrbitControls {...orbit_controls_props}>
-      {#if gizmo}<extras.Gizmo {...gizmo_props} />{/if}
-    </extras.OrbitControls>
-  </T.OrthographicCamera>
-{/if}
+<SceneCamera
+  {camera_projection}
+  position={computed_camera_position}
+  {fov}
+  zoom={initial_zoom}
+  orbit_props={orbit_controls_props}
+  {gizmo}
+/>
 
 <T.DirectionalLight position={[3, 10, 10]} intensity={directional_light} />
 <T.DirectionalLight position={[-3, -5, -10]} intensity={directional_light * 0.5} />
@@ -657,21 +533,11 @@
 
   <!-- Reciprocal lattice vectors -->
   {#if show_vectors && fermi_data?.k_lattice}
-    {#each fermi_data.k_lattice as vec, idx (idx)}
-      {@const scaled_vec = vec.map((coord) => coord * vector_scale) as Vec3}
-      {@const label_position = scaled_vec.map((coord) => coord * 1.15) as Vec3}
-      <Arrow
-        position={[0, 0, 0]}
-        vector={scaled_vec}
-        color={vector_colors[idx]}
-        scale={1}
-      />
-      <extras.HTML center position={label_position}>
-        <span style:color={vector_colors[idx]} style:font-size="1.2em">
-          {vector_labels[idx]}
-        </span>
-      </extras.HTML>
-    {/each}
+    <ReciprocalVectors
+      k_lattice={fermi_data.k_lattice}
+      {vector_scale}
+      size={scene_size}
+    />
   {/if}
 
   <!-- Fermi surfaces (with optional symmetry tiling) -->
@@ -697,9 +563,7 @@
             {renderOrder}
             onpointermove={(event: ThreltePointerEvent) =>
             handle_pointer_move(event, surface, surface_color, sym_idx, sym_matrix)}
-            onpointerleave={() => {
-              hover_data = null
-            }}
+            onpointerleave={clear_hover}
           >
             <T.MeshBasicMaterial
               color={surface_color}
@@ -720,9 +584,7 @@
             renderOrder={renderOrder * 2}
             onpointermove={(event: ThreltePointerEvent) =>
             handle_pointer_move(event, surface, surface_color, sym_idx, sym_matrix)}
-            onpointerleave={() => {
-              hover_data = null
-            }}
+            onpointerleave={clear_hover}
           >
             <T.MeshStandardMaterial
               {...get_material_props(surface_color, use_vertex_colors, surface_idx, `back`)}
@@ -739,9 +601,7 @@
             renderOrder={renderOrder * 2 + 1}
             onpointermove={(event: ThreltePointerEvent) =>
             handle_pointer_move(event, surface, surface_color, sym_idx, sym_matrix)}
-            onpointerleave={() => {
-              hover_data = null
-            }}
+            onpointerleave={clear_hover}
           >
             <T.MeshStandardMaterial
               {...get_material_props(
@@ -764,9 +624,7 @@
             {renderOrder}
             onpointermove={(event: ThreltePointerEvent) =>
             handle_pointer_move(event, surface, surface_color, sym_idx, sym_matrix)}
-            onpointerleave={() => {
-              hover_data = null
-            }}
+            onpointerleave={clear_hover}
           >
             <T.MeshStandardMaterial
               {...get_material_props(
@@ -785,10 +643,3 @@
     {/if}
   {/each}
 </T.Group>
-
-<style>
-  :global(.fermi-surface .responsive-gizmo) {
-    width: clamp(70px, 18cqmin, 100px) !important;
-    height: clamp(70px, 18cqmin, 100px) !important;
-  }
-</style>

package/dist/fermi-surface/FermiSurfaceScene.svelte.d.ts

@@ -1,15 +1,11 @@
 import type { BrillouinZoneData } from '../brillouin';
 import type { Vec3 } from '../math';
-import type { CameraProjection } from '../settings';
-import * as extras from '@threlte/extras';
-import type { ComponentProps } from 'svelte';
-import type { Camera, Scene } from 'three';
+import type { SceneControlProps } from '../scene';
 import type { ColorProperty, FermiHoverData, FermiSurfaceData, RepresentationMode } from './types';
-type $$ComponentProps = {
+type $$ComponentProps = SceneControlProps & {
     fermi_data?: FermiSurfaceData;
     bz_data?: BrillouinZoneData;
     camera_position?: Vec3 | undefined;
-    camera_projection?: CameraProjection;
     color_property?: ColorProperty;
     color_scale?: string;
     representation?: RepresentationMode;
@@ -27,24 +23,8 @@ type $$ComponentProps = {
     clip_position?: number;
     clip_flip?: boolean;
     vector_scale?: number;
-    rotation_damping?: number;
-    max_zoom?: number;
-    min_zoom?: number;
-    rotate_speed?: number;
-    zoom_speed?: number;
-    pan_speed?: number;
-    zoom_to_cursor?: boolean;
-    fov?: number;
-    initial_zoom?: number;
-    ambient_light?: number;
-    directional_light?: number;
-    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>;
-    auto_rotate?: number;
-    camera_is_moving?: boolean;
-    scene?: Scene;
-    camera?: Camera;
     hover_data?: FermiHoverData | null;
 };
-declare const FermiSurfaceScene: import("svelte").Component<$$ComponentProps, {}, "camera_position" | "camera_projection" | "camera" | "scene" | "camera_is_moving" | "surface_opacity" | "bz_data" | "hover_data" | "fermi_data">;
+declare const FermiSurfaceScene: import("svelte").Component<$$ComponentProps, {}, "scene" | "camera" | "camera_projection" | "camera_position" | "surface_opacity" | "bz_data" | "hover_data" | "fermi_data">;
 type FermiSurfaceScene = ReturnType<typeof FermiSurfaceScene>;
 export default FermiSurfaceScene;

package/dist/fermi-surface/FermiSurfaceTooltip.svelte

@@ -1,14 +1,11 @@
 <script lang="ts">
   // Tooltip component for Fermi surface hover information
   // Displays band index, spin, k-coordinates, and optional property values
-  import { format_num, format_vec3 } from '../labels'
-  import { TooltipContent } from '../tooltip'
+  import { format_num } from '../labels'
+  import { KCoords, TooltipContent } from '../tooltip'
   import type { FermiHoverData, FermiTooltipProp } from './types'
 
-  let {
-    hover_data,
-    tooltip,
-  }: {
+  let { hover_data, tooltip }: {
     hover_data: FermiHoverData
     tooltip?: FermiTooltipProp
   } = $props()
@@ -23,18 +20,10 @@
       {/if}
     </div>
 
-    <div class="coords-section">
-      <div class="coord-row">
-        <span class="coord-label">k (Å⁻¹):</span>
-        <span class="coord-values">{format_vec3(hover_data.position_cartesian)}</span>
-      </div>
-      {#if hover_data.position_fractional}
-        <div class="coord-row">
-          <span class="coord-label">k (frac):</span>
-          <span class="coord-values">{format_vec3(hover_data.position_fractional)}</span>
-        </div>
-      {/if}
-    </div>
+    <KCoords
+      cartesian={hover_data.position_cartesian}
+      fractional={hover_data.position_fractional}
+    />
 
     {#if hover_data.property_value != null}
       <div class="property-row">
@@ -56,7 +45,7 @@
 
 <style>
   .tooltip-content {
-    max-width: var(--tooltip-max-width, 220px);
+    max-width: var(--tooltip-max-width, 250px);
   }
   .tooltip-title {
     display: flex;
@@ -78,21 +67,6 @@
     background: #377eb8;
     color: white;
   }
-  .coords-section {
-    margin: 4px 0;
-  }
-  .coord-row {
-    display: flex;
-    gap: 4px;
-    font-size: 0.9em;
-  }
-  .coord-label {
-    opacity: 0.8;
-    min-width: 55px;
-  }
-  .coord-values {
-    font-family: monospace;
-  }
   .property-row {
     margin-top: 4px;
     font-size: 0.9em;