matterviz 0.4.0 → 0.4.2

package/dist/brillouin/BrillouinZoneScene.svelte

@@ -1,20 +1,23 @@
 <script lang="ts">
-  import { AXIS_COLORS, NEG_AXIS_COLORS } from '../colors'
   import type { Vec3 } from '../math'
   import * as math from '../math'
-  import { type CameraProjection, DEFAULTS } from '../settings'
-  import Arrow from '../structure/Arrow.svelte'
+  import { bind_renderer, build_orbit_props, SceneCamera } from '../scene'
+  import type { SceneControlProps, ThreltePointerEvent } from '../scene'
+  import { DEFAULTS } from '../settings'
   import Cylinder from '../structure/Cylinder.svelte'
-  import { T, useThrelte } from '@threlte/core'
+  import { T } from '@threlte/core'
   import * as extras from '@threlte/extras'
-  import type { ComponentProps } from 'svelte'
-  import type { Camera, Scene } from 'three'
-  import { BufferAttribute, BufferGeometry, Vector3 } from 'three'
+  import {
+    cartesian_to_fractional,
+    default_camera_position,
+    k_lattice_inverse,
+    k_space_size,
+    polyhedron_centroid,
+    polyhedron_geometry,
+  } from './geometry'
+  import ReciprocalVectors from './ReciprocalVectors.svelte'
   import type { BrillouinZoneData, BZHoverData, IrreducibleBZData } from './types'
 
-  // Threlte pointer event type for mesh interactions
-  type ThreltePointerEvent = { point: Vector3; nativeEvent: PointerEvent }
-
   let {
     bz_data = $bindable(),
     camera_position = $bindable(),
@@ -22,7 +25,7 @@
     surface_color = $bindable(`#4488ff`),
     surface_opacity = $bindable(0.3),
     edge_color = $bindable(`#000000`),
-    edge_width = $bindable(0.05),
+    edge_width = $bindable(0.002),
     show_vectors = $bindable(true),
     vector_scale = $bindable(1.0),
     // Irreducible BZ options
@@ -43,7 +46,6 @@
     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(),
     k_path_points = [],
@@ -52,10 +54,9 @@
     hovered_qpoint_index = null,
     hover_data = $bindable<BZHoverData | null>(null),
     on_kpath_hover,
-  }: {
+  }: SceneControlProps & {
     bz_data?: BrillouinZoneData
     camera_position?: Vec3 | undefined
-    camera_projection?: CameraProjection
     surface_color?: string
     surface_opacity?: number
     edge_color?: string
@@ -67,22 +68,6 @@
     ibz_data?: IrreducibleBZData | null
     ibz_color?: string
     ibz_opacity?: 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
     k_path_points?: Vec3[]
     k_path_labels?: { position: Vec3; label: string | null }[]
     hovered_k_point?: Vec3 | null
@@ -91,87 +76,38 @@
     on_kpath_hover?: (qpoint_index: number | null) => void
   } = $props()
 
-  const threlte = useThrelte()
-  $effect(() => {
-    scene = threlte.scene
-    camera = threlte.camera.current
-    if (threlte.renderer) {
-      Object.assign(threlte.renderer.domElement, { __renderer: threlte.renderer })
-    }
+  bind_renderer((threlte_scene, threlte_camera) => {
+    scene = threlte_scene
+    camera = threlte_camera
   })
 
   extras.interactivity()
 
-  // Compute centroid of BZ vertices for proper rotation center
-  const rotation_target = $derived.by((): Vec3 => {
-    if (!bz_data?.vertices || bz_data.vertices.length === 0) return [0, 0, 0]
-    const sum = bz_data.vertices.reduce(
-      (acc, v) => math.add(acc, v),
-      [0, 0, 0] as Vec3,
-    )
-    return math.scale(sum, 1 / bz_data.vertices.length)
-  })
-
-  // BZ size for camera positioning: average magnitude of k-vectors
-  const bz_size = $derived.by(() => {
-    if (!bz_data?.k_lattice) return 10
-    const mags = bz_data.k_lattice.map((vec) => Math.hypot(...vec))
-    return mags.reduce((sum, mag) => sum + mag, 0) / 3
-  })
-
-  const computed_camera_position = $derived.by(() =>
-    camera_position || ([10, 3, 8].map((coord) => coord * Math.max(1, bz_size)) as Vec3)
+  // BZ centroid as rotation center; mean k-vector magnitude for camera positioning
+  const rotation_target = $derived(polyhedron_centroid(bz_data?.vertices))
+  const bz_size = $derived(k_space_size(bz_data?.k_lattice))
+  const computed_camera_position = $derived(
+    camera_position || default_camera_position(bz_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],
-    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₃`]
+  const orbit_controls_props = $derived(
+    build_orbit_props({
+      camera_projection,
+      target: rotation_target,
+      rotate_speed,
+      zoom_speed,
+      zoom_to_cursor,
+      pan_speed,
+      max_zoom,
+      min_zoom,
+      auto_rotate,
+      rotation_damping,
+    }),
+  )
 
   // K-path styling. The invisible hover proxy is twice the visible thickness so the cursor
   // snaps to the path even when it isn't directly over the thin visible segment.
-  const KPATH_THICKNESS = 0.12
+  const KPATH_THICKNESS = 0.012
   const KPATH_HOVER_THICKNESS = KPATH_THICKNESS * 2
 
   // Threshold for skipping k-path segments that bridge a path discontinuity (e.g. `U|K`).
@@ -186,50 +122,11 @@
     return lens[Math.floor(lens.length / 2)] * 10
   })
 
-  // Create mesh geometry from faces with fan triangulation
-  function create_mesh_geometry(
-    vertices: Vec3[],
-    faces: number[][],
-  ): BufferGeometry | null {
-    if (faces.length === 0) return null
-
-    const positions: number[] = []
-    const normals: number[] = []
-
-    for (const face of 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 >= vertices.length)) continue
-        const [v0, v1, v2] = indices.map((idx) => 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 ? create_mesh_geometry(bz_data.vertices, bz_data.faces) : null,
+    bz_data ? polyhedron_geometry(bz_data.vertices, bz_data.faces) : null,
   )
   const ibz_geometry = $derived(
-    show_ibz && ibz_data
-      ? create_mesh_geometry(ibz_data.vertices, ibz_data.faces)
-      : null,
+    show_ibz && ibz_data ? polyhedron_geometry(ibz_data.vertices, ibz_data.faces) : null,
   )
 
   // Separate effects to avoid disposing one geometry when only the other changes
@@ -242,21 +139,8 @@
     return () => prev?.dispose()
   })
 
-  // Compute inverse of k_lattice for Cartesian->fractional conversion
-  const k_lattice_inv = $derived.by(() => {
-    if (!bz_data?.k_lattice) return null
-    try {
-      return math.matrix_inverse_3x3(bz_data.k_lattice)
-    } catch {
-      return null
-    }
-  })
-
-  // Convert Cartesian k-coordinates to fractional (reciprocal lattice units)
-  function cartesian_to_fractional(cart: Vec3): Vec3 | null {
-    if (!k_lattice_inv) return null
-    return math.mat3x3_vec3_multiply(k_lattice_inv, cart)
-  }
+  // Inverse of k_lattice for Cartesian->fractional conversion
+  const k_lattice_inv = $derived(k_lattice_inverse(bz_data?.k_lattice))
 
   // Throttle state for pointer move events
   let last_hover_time = 0
@@ -282,21 +166,17 @@
   })
 
   // Create hover data from pointer event
-  function create_hover_data(
-    event: ThreltePointerEvent,
-    is_ibz: boolean,
-  ): BZHoverData | null {
+  function create_hover_data(event: ThreltePointerEvent, is_ibz: boolean): BZHoverData | null {
     if (!bz_data) return null
 
     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)
 
     const { clientX, clientY } = event.nativeEvent
     const ibz_vol = ibz_data?.volume ?? null
     // Round to nearest integer since symmetry multiplicity is the point group order
-    const symmetry_multiplicity = ibz_vol != null && ibz_vol > 0
-      ? Math.round(bz_data.volume / ibz_vol)
-      : null
+    const symmetry_multiplicity =
+      ibz_vol != null && ibz_vol > 0 ? Math.round(bz_data.volume / ibz_vol) : null
 
     return {
       position_cartesian,
@@ -342,24 +222,14 @@
   }
 </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.AmbientLight intensity={ambient_light} />
@@ -370,7 +240,7 @@
     {#if bz_geometry}
       <T.Mesh
         geometry={bz_geometry}
-        onpointermove={(e: ThreltePointerEvent) => handle_hover(e, false)}
+        onpointermove={(event: ThreltePointerEvent) => handle_hover(event, false)}
         onpointerleave={() => handle_leave(false)}
       >
         <T.MeshStandardMaterial
@@ -393,7 +263,7 @@
     {#if show_ibz && ibz_geometry}
       <T.Mesh
         geometry={ibz_geometry}
-        onpointermove={(e: ThreltePointerEvent) => handle_hover(e, true)}
+        onpointermove={(event: ThreltePointerEvent) => handle_hover(event, true)}
         onpointerleave={() => handle_leave(true)}
       >
         <T.MeshStandardMaterial
@@ -416,43 +286,17 @@
 
     <!-- Reciprocal lattice vectors -->
     {#if show_vectors && bz_data.k_lattice}
-      {#each bz_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}
-          shaft_radius={bz_size * 0.008}
-          arrow_head_radius={bz_size * 0.028}
-          arrow_head_length={-0.1}
-        />
-        <!-- Vector label beyond tip -->
-        <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={bz_data.k_lattice} {vector_scale} size={bz_size} />
     {/if}
 
     <!-- K-path visualization -->
     {#if k_path_points && k_path_points.length > 1}
-      {#each k_path_points.slice(0, -1) as
-        from_point,
-        idx
-        (`${from_point}-${k_path_points[idx + 1]}#${idx}`)
-      }
+      {#each k_path_points.slice(0, -1) as from_point, idx (`${from_point}-${k_path_points[idx + 1]}#${idx}`)}
         {@const to_point = k_path_points[idx + 1]}
-        {@const seg_len = Math.hypot(
-      ...math.subtract(to_point as Vec3, from_point as Vec3),
-    )}
-        {@const is_hovered = hovered_qpoint_index !== null &&
-      (idx === hovered_qpoint_index || idx === hovered_qpoint_index - 1)}
+        {@const seg_len = Math.hypot(...math.subtract(to_point as Vec3, from_point as Vec3))}
+        {@const is_hovered =
+          hovered_qpoint_index !== null &&
+          (idx === hovered_qpoint_index || idx === hovered_qpoint_index - 1)}
         {#if seg_len <= k_path_seg_cutoff}
           <Cylinder
             from={from_point as Vec3}
@@ -504,19 +348,8 @@
     {#if hovered_k_point}
       <T.Mesh position={hovered_k_point}>
         <T.SphereGeometry args={[0.03, 16, 16]} />
-        <T.MeshStandardMaterial
-          color="#ff0000"
-          emissive="#ff0000"
-          emissiveIntensity={1.2}
-        />
+        <T.MeshStandardMaterial color="#ff0000" emissive="#ff0000" emissiveIntensity={1.2} />
       </T.Mesh>
     {/if}
   {/if}
 </T.Group>
-
-<style>
-  :global(.brillouin-zone .responsive-gizmo) {
-    width: clamp(70px, 18cqmin, 100px) !important;
-    height: clamp(70px, 18cqmin, 100px) !important;
-  }
-</style>

package/dist/brillouin/BrillouinZoneScene.svelte.d.ts

@@ -1,13 +1,9 @@
 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 { BrillouinZoneData, BZHoverData, IrreducibleBZData } from './types';
-type $$ComponentProps = {
+type $$ComponentProps = SceneControlProps & {
     bz_data?: BrillouinZoneData;
     camera_position?: Vec3 | undefined;
-    camera_projection?: CameraProjection;
     surface_color?: string;
     surface_opacity?: number;
     edge_color?: string;
@@ -18,22 +14,6 @@ type $$ComponentProps = {
     ibz_data?: IrreducibleBZData | null;
     ibz_color?: string;
     ibz_opacity?: 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;
     k_path_points?: Vec3[];
     k_path_labels?: {
         position: Vec3;
@@ -44,6 +24,6 @@ type $$ComponentProps = {
     hover_data?: BZHoverData | null;
     on_kpath_hover?: (qpoint_index: number | null) => void;
 };
-declare const BrillouinZoneScene: import("svelte").Component<$$ComponentProps, {}, "camera_position" | "camera_projection" | "vector_scale" | "camera" | "scene" | "camera_is_moving" | "surface_color" | "surface_opacity" | "edge_color" | "edge_width" | "show_vectors" | "bz_data" | "hover_data">;
+declare const BrillouinZoneScene: import("svelte").Component<$$ComponentProps, {}, "camera" | "camera_projection" | "camera_position" | "vector_scale" | "scene" | "surface_color" | "surface_opacity" | "edge_color" | "edge_width" | "show_vectors" | "bz_data" | "hover_data">;
 type BrillouinZoneScene = ReturnType<typeof BrillouinZoneScene>;
 export default BrillouinZoneScene;

package/dist/brillouin/ReciprocalVectors.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+  // Reciprocal lattice vector arrows (b₁, b₂, b₃) with HTML labels beyond the tips, shared by BrillouinZoneScene and FermiSurfaceScene
+  import type { Matrix3x3, Vec3 } from '../math'
+  import Arrow from '../structure/Arrow.svelte'
+  import * as extras from '@threlte/extras'
+
+  let {
+    k_lattice,
+    vector_scale = 1.0,
+    size = 1,
+  }: {
+    k_lattice: Matrix3x3
+    vector_scale?: number
+    size?: number // characteristic scene size used to scale arrow proportions
+  } = $props()
+
+  const vector_colors = [`red`, `green`, `blue`]
+  const vector_labels = [`b₁`, `b₂`, `b₃`]
+</script>
+
+{#each 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}
+    shaft_radius={size * 0.008}
+    arrow_head_radius={size * 0.028}
+    arrow_head_length={-0.1}
+  />
+  <!-- Vector label beyond tip -->
+  <extras.HTML center position={label_position}>
+    <span style:color={vector_colors[idx]} style:font-size="1.2em">
+      {vector_labels[idx]}
+    </span>
+  </extras.HTML>
+{/each}

package/dist/brillouin/ReciprocalVectors.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Matrix3x3 } from '../math';
+type $$ComponentProps = {
+    k_lattice: Matrix3x3;
+    vector_scale?: number;
+    size?: number;
+};
+declare const ReciprocalVectors: import("svelte").Component<$$ComponentProps, {}, "">;
+type ReciprocalVectors = ReturnType<typeof ReciprocalVectors>;
+export default ReciprocalVectors;

package/dist/brillouin/compute.d.ts

@@ -12,6 +12,8 @@ type ClippingPlane = {
     normal: Vec3;
     dist: number;
 };
+export declare const IBZ_REFERENCE_DIRECTIONS: Vec3[];
+export declare function find_ibz_reference_direction(non_identity_ops: Matrix3x3[]): Vec3;
 export declare function compute_ibz_clipping_planes(point_group_ops: Matrix3x3[]): ClippingPlane[];
 export declare function compute_irreducible_bz(bz_data: BrillouinZoneData, point_group_ops: Matrix3x3[], edge_sharp_angle_deg?: number): IrreducibleBZData | null;
 export {};