matterviz 0.3.5 → 0.3.6

package/dist/src/lib/brillouin/BrillouinZone.svelte

@@ -0,0 +1,549 @@
+<script lang="ts">
+  import type { ShowControlsProp } from '$lib/controls'
+  import { normalize_show_controls } from '$lib/controls'
+  import EmptyState from '$lib/EmptyState.svelte'
+  import { StatusMessage } from '$lib/feedback'
+  import Spinner from '$lib/feedback/Spinner.svelte'
+  import Icon from '$lib/Icon.svelte'
+  import { create_file_drop_handler, load_from_url } from '$lib/io'
+  import { set_fullscreen_bg, toggle_fullscreen } from '$lib/layout'
+  import type { Vec3 } from '$lib/math'
+  import { PlotTooltip } from '$lib/plot'
+  import { type CameraProjection, DEFAULTS } from '$lib/settings'
+  import type { Crystal } from '$lib/structure'
+  import { parse_any_structure } from '$lib/structure/parse'
+  import { analyze_structure_symmetry } from '$lib/symmetry'
+  import { Canvas } from '@threlte/core'
+  import type { ComponentProps, Snippet } from 'svelte'
+  import { untrack } from 'svelte'
+  import { tooltip } from 'svelte-multiselect/attachments'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import BrillouinZoneControls from './BrillouinZoneControls.svelte'
+  import BrillouinZoneExportPane from './BrillouinZoneExportPane.svelte'
+  import BrillouinZoneInfoPane from './BrillouinZoneInfoPane.svelte'
+  import BrillouinZoneScene from './BrillouinZoneScene.svelte'
+  import BrillouinZoneTooltip from './BrillouinZoneTooltip.svelte'
+  import {
+    compute_brillouin_zone,
+    compute_irreducible_bz,
+    extract_point_group_from_operations,
+    reciprocal_lattice,
+  } from './compute'
+  import type {
+    BrillouinZoneData,
+    BZHoverData,
+    BZTooltipProp,
+    IrreducibleBZData,
+  } from './types'
+
+  type BZHandlerData = {
+    structure?: Crystal
+    bz_data?: BrillouinZoneData
+    bz_order?: number
+    filename?: string
+    file_size?: number
+    error_msg?: string
+    fullscreen?: boolean
+  }
+  let {
+    structure = $bindable(),
+    bz_order = $bindable(1),
+    bz_data = $bindable(),
+    controls_open = $bindable(false),
+    info_pane_open = $bindable(false),
+    surface_color = $bindable(`#4488ff`),
+    surface_opacity = $bindable(0.3),
+    edge_color = $bindable(`#000000`),
+    edge_width = $bindable(0.05),
+    show_vectors = $bindable(true),
+    vector_scale = $bindable(1.0),
+    camera_projection = $bindable(`perspective`),
+    // Irreducible BZ options
+    show_ibz = $bindable(false),
+    ibz_color = $bindable(`#ff8844`),
+    ibz_opacity = $bindable(0.5),
+    ibz_data = $bindable<IrreducibleBZData | null>(null),
+    show_controls,
+    fullscreen = $bindable(false),
+    wrapper = $bindable(),
+    width = $bindable(0),
+    height = $bindable(0),
+    hovered = $bindable(false),
+    dragover = $bindable(false),
+    allow_file_drop = true,
+    png_dpi = $bindable(150),
+    fullscreen_toggle = DEFAULTS.structure.fullscreen_toggle,
+    data_url,
+    structure_string,
+    on_file_drop,
+    spinner_props = {},
+    loading = $bindable(false),
+    error_msg = $bindable(),
+    k_path_points = [],
+    k_path_labels = [],
+    hovered_k_point = null,
+    hovered_qpoint_index = null,
+    children,
+    tooltip_config,
+    on_file_load,
+    on_error,
+    on_fullscreen_change,
+    on_hover,
+    ...rest
+  }:
+    & {
+      structure?: Crystal
+      bz_order?: number
+      bz_data?: BrillouinZoneData
+      controls_open?: boolean
+      info_pane_open?: boolean
+      surface_color?: string
+      surface_opacity?: number
+      edge_color?: string
+      edge_width?: number
+      show_vectors?: boolean
+      vector_scale?: number
+      camera_projection?: CameraProjection
+      // Irreducible BZ options
+      show_ibz?: boolean
+      ibz_color?: string
+      ibz_opacity?: number
+      ibz_data?: IrreducibleBZData | null
+      /**
+       * Controls visibility configuration.
+       * - 'always': controls always visible
+       * - 'hover': controls visible on component hover (default)
+       * - 'never': controls never visible
+       * - object: { mode, hidden, style } for fine-grained control
+       *
+       * Control names: 'filename', 'fullscreen', 'info-pane', 'export-pane', 'controls'
+       */
+      show_controls?: ShowControlsProp
+      fullscreen?: boolean
+      width?: number
+      height?: number
+      wrapper?: HTMLDivElement
+      png_dpi?: number
+      hovered?: boolean
+      dragover?: boolean
+      allow_file_drop?: boolean
+      fullscreen_toggle?: Snippet<[{ fullscreen: boolean }]> | boolean
+      data_url?: string
+      on_file_drop?: (content: string | ArrayBuffer, filename: string) => void
+      spinner_props?: ComponentProps<typeof Spinner>
+      loading?: boolean
+      error_msg?: string
+      structure_string?: string
+      // K-path points in Cartesian reciprocal space coordinates (not fractional coords)
+      // Should be computed using the reciprocal lattice matrix (includes 2π factor)
+      k_path_points?: Vec3[]
+      // K-path labels with positions in Cartesian reciprocal space coordinates
+      // Each position should match a corresponding point in k_path_points
+      k_path_labels?: { position: Vec3; label: string | null }[]
+      // Currently hovered k-point in Cartesian reciprocal space coordinates
+      hovered_k_point?: Vec3 | null
+      // Index of the currently hovered q-point in the band structure
+      hovered_qpoint_index?: number | null
+      children?: Snippet<
+        [{ structure?: Crystal; bz_data?: BrillouinZoneData }]
+      >
+      tooltip_config?: BZTooltipProp
+      on_file_load?: (data: BZHandlerData) => void
+      on_error?: (data: BZHandlerData) => void
+      on_fullscreen_change?: (data: BZHandlerData) => void
+      on_hover?: (data: BZHoverData | null) => void
+    }
+    & HTMLAttributes<HTMLDivElement> = $props()
+
+  let scene = $state(undefined)
+  let camera = $state(undefined)
+  let export_pane_open = $state(false)
+  let current_filename = $state<string | undefined>(undefined)
+  let hover_data = $state<BZHoverData | null>(null)
+
+  // Call on_hover callback when hover_data changes
+  $effect(() => {
+    on_hover?.(hover_data)
+  })
+
+  // Normalize show_controls prop into consistent config
+  let controls_config = $derived(normalize_show_controls(show_controls))
+
+  // Parse and load structure from content
+  function parse_structure(content: string | ArrayBuffer, filename: string) {
+    const text = content instanceof ArrayBuffer
+      ? new TextDecoder().decode(content)
+      : content
+    const parsed = parse_any_structure(text, filename)
+    if (!parsed) throw new Error(`Failed to parse structure from ${filename}`)
+
+    structure = parsed as Crystal
+    current_filename = filename
+    const file_size = new Blob([content]).size
+    on_file_load?.({ structure, bz_data, bz_order, filename, file_size })
+  }
+
+  // Load with error handling
+  function safe_parse(content: string | ArrayBuffer, filename: string) {
+    try {
+      parse_structure(content, filename)
+    } catch (err) {
+      error_msg = `Failed to parse ${filename}: ${
+        err instanceof Error ? err.message : err
+      }`
+      on_error?.({ error_msg, filename })
+    }
+  }
+
+  // Compute BZ when structure/order changes
+  $effect(() => {
+    // Skip if bz_data was already provided externally (has valid vertices)
+    if (bz_data?.vertices?.length) return
+
+    if (!structure || !(`lattice` in structure) || !structure.lattice) {
+      bz_data = undefined
+      return
+    }
+
+    try {
+      const k_lattice = reciprocal_lattice(structure.lattice.matrix)
+      // Ensure bz_order is 1, 2, or 3
+      const valid_order = Math.min(Math.max(1, bz_order), 3) as 1 | 2 | 3
+      bz_data = compute_brillouin_zone(k_lattice, valid_order)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      error_msg = `BZ computation failed: ${msg}`
+      bz_data = undefined
+      untrack(() => on_error?.({ error_msg, structure, bz_order }))
+    }
+  })
+
+  // Compute IBZ when show_ibz is enabled and structure changes
+  $effect(() => {
+    if (!show_ibz || !bz_data || !structure?.lattice) {
+      ibz_data = null
+      return
+    }
+
+    let stale = false
+    const captured_bz = bz_data
+
+    analyze_structure_symmetry(structure, {})
+      .then((sym_data) => {
+        if (stale) return
+        const point_group_ops = extract_point_group_from_operations(
+          sym_data.operations,
+        )
+        ibz_data = compute_irreducible_bz(captured_bz, point_group_ops)
+      })
+      .catch((err) => {
+        if (stale) return
+        console.warn(`IBZ computation failed:`, err)
+        ibz_data = null
+      })
+
+    return () => {
+      stale = true
+    }
+  })
+
+  // Load structure from URL or string
+  $effect(() => {
+    const handle_error = (err: unknown, source: string) => {
+      error_msg = err instanceof Error ? err.message : String(err)
+      on_error?.({ error_msg, filename: source })
+    }
+
+    if (data_url && !structure) {
+      loading = true
+      error_msg = undefined
+      load_from_url(
+        data_url,
+        (content, filename) =>
+          on_file_drop
+            ? on_file_drop(content, filename)
+            : safe_parse(content, filename),
+      )
+        .catch((err) => handle_error(err, data_url))
+        .finally(() => (loading = false))
+    } else if (structure_string && !data_url) {
+      loading = true
+      error_msg = undefined
+      try {
+        safe_parse(structure_string, `string`)
+      } catch (err) {
+        handle_error(err, `string`)
+      } finally {
+        loading = false
+      }
+    }
+  })
+
+  const handle_file_drop = create_file_drop_handler({
+    allow: () => allow_file_drop,
+    on_drop: (content, filename) => (on_file_drop || safe_parse)(content, filename),
+    on_error: (msg) => {
+      error_msg = msg
+      on_error?.({ error_msg: msg })
+    },
+    set_loading: (val) => {
+      loading = val
+      if (val) [error_msg, dragover] = [undefined, false]
+    },
+  })
+
+  function onkeydown(event: KeyboardEvent) {
+    const target = event.target
+    if (
+      target instanceof HTMLElement &&
+      (target.tagName === `INPUT` || target.tagName === `TEXTAREA`)
+    ) return
+
+    if (event.key === `f` && fullscreen_toggle) toggle_fullscreen(wrapper)
+    else if (event.key === `i`) info_pane_open = !info_pane_open
+    else if (event.key === `Escape`) {
+      if (info_pane_open) info_pane_open = false
+      else controls_open = false
+    }
+  }
+
+  $effect(() => { // fullscreen and background
+    if (typeof window === `undefined`) return
+    const fs_el = document.fullscreenElement
+    if (fullscreen && fs_el !== wrapper && wrapper) {
+      wrapper.requestFullscreen().catch(console.error)
+    } else if (!fullscreen && fs_el === wrapper) document.exitFullscreen()
+    set_fullscreen_bg(wrapper, fullscreen, `--bz-bg-fullscreen`)
+  })
+</script>
+
+<svelte:document
+  onfullscreenchange={() => {
+    fullscreen = Boolean(document.fullscreenElement)
+    on_fullscreen_change?.({ structure, bz_data, bz_order, fullscreen })
+  }}
+/>
+
+<div
+  class:dragover
+  class:active={info_pane_open || controls_open || export_pane_open}
+  role="region"
+  aria-label="Brillouin zone viewer"
+  bind:this={wrapper}
+  bind:clientWidth={width}
+  bind:clientHeight={height}
+  onmouseenter={() => (hovered = true)}
+  onmouseleave={() => (hovered = false)}
+  ondrop={handle_file_drop}
+  ondragover={(event) => {
+    event.preventDefault()
+    if (!allow_file_drop) return
+    dragover = true
+  }}
+  ondragleave={(event) => {
+    event.preventDefault()
+    dragover = false
+  }}
+  {onkeydown}
+  {...rest}
+  class="brillouin-zone {rest.class ?? ``}"
+>
+  {@render children?.({ structure, bz_data })}
+  {#if loading}
+    <Spinner text="Loading structure..." {...spinner_props} />
+  {:else if error_msg}
+    <StatusMessage bind:message={error_msg} type="error" dismissible />
+  {:else if structure && `lattice` in structure}
+    <section
+      class="control-buttons {controls_config.class}"
+      style={controls_config.style}
+    >
+      {#if controls_config.mode !== `never`}
+        {#if current_filename && controls_config.visible(`filename`)}
+          <span class="filename">{current_filename}</span>
+        {/if}
+
+        {#if fullscreen_toggle && controls_config.visible(`fullscreen`)}
+          <button
+            type="button"
+            onclick={() => fullscreen_toggle && toggle_fullscreen(wrapper)}
+            title="{fullscreen ? `Exit` : `Enter`} fullscreen"
+            aria-pressed={fullscreen}
+            class="fullscreen-toggle"
+            {@attach tooltip()}
+          >
+            {#if typeof fullscreen_toggle === `function`}
+              {@render fullscreen_toggle({ fullscreen })}
+            {:else}
+              <Icon icon="{fullscreen ? `Exit` : ``}Fullscreen" />
+            {/if}
+          </button>
+        {/if}
+
+        {#if controls_config.visible(`info-pane`)}
+          <BrillouinZoneInfoPane {structure} {bz_data} bind:pane_open={info_pane_open} />
+        {/if}
+
+        {#if controls_config.visible(`export-pane`)}
+          <BrillouinZoneExportPane
+            bind:export_pane_open
+            {bz_data}
+            {wrapper}
+            {scene}
+            {camera}
+            bind:png_dpi
+            filename={current_filename || `brillouin-zone`}
+          />
+        {/if}
+
+        {#if controls_config.visible(`controls`)}
+          <BrillouinZoneControls
+            bind:controls_open
+            bind:bz_order
+            bind:surface_color
+            bind:surface_opacity
+            bind:edge_color
+            bind:edge_width
+            bind:show_vectors
+            bind:camera_projection
+            bind:show_ibz
+            bind:ibz_color
+            bind:ibz_opacity
+          />
+        {/if}
+      {/if}
+    </section>
+
+    {#if typeof WebGLRenderingContext !== `undefined`}
+      <div style="overflow: hidden; height: 100%">
+        <Canvas>
+          <BrillouinZoneScene
+            {bz_data}
+            {surface_color}
+            {surface_opacity}
+            {edge_color}
+            {edge_width}
+            {show_vectors}
+            {vector_scale}
+            {camera_projection}
+            {k_path_points}
+            {k_path_labels}
+            {hovered_k_point}
+            {hovered_qpoint_index}
+            {show_ibz}
+            {ibz_data}
+            {ibz_color}
+            {ibz_opacity}
+            bind:scene
+            bind:camera
+            bind:hover_data
+          />
+        </Canvas>
+
+        <!-- Hover tooltip -->
+        {#if hover_data}
+          <PlotTooltip
+            x={hover_data.screen_position.x}
+            y={hover_data.screen_position.y}
+            bg_color={hover_data.is_ibz ? ibz_color : surface_color}
+            fixed
+            style="z-index: calc(var(--bz-buttons-z-index, var(--z-index-overlay-controls, 100000000)) + 1); backdrop-filter: blur(4px); box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3)"
+          >
+            <BrillouinZoneTooltip {hover_data} tooltip={tooltip_config} />
+          </PlotTooltip>
+        {/if}
+      </div>
+    {/if}
+  {:else if structure}
+    <p class="warn">Structure must have a lattice to compute Brillouin zone</p>
+  {:else}
+    <EmptyState>
+      <h3>Drop Structure File</h3>
+      <p>Supports CIF, POSCAR, JSON, (ext)XYZ, (+ .gz)</p>
+    </EmptyState>
+  {/if}
+</div>
+
+<style>
+  .brillouin-zone {
+    position: relative;
+    container-type: size;
+    height: var(--bz-height, 500px);
+    width: var(--bz-width, 100%);
+    max-width: var(--bz-max-width, 100%);
+    min-width: var(--bz-min-width, 300px);
+    border-radius: var(--bz-border-radius, var(--border-radius, 3pt));
+    background: var(--bz-bg, var(--surface-bg));
+    color: var(--bz-text-color, var(--text-color));
+  }
+  .brillouin-zone.active {
+    z-index: var(--bz-active-z-index, 2);
+  }
+  .brillouin-zone:fullscreen {
+    background: var(--bz-bg-fullscreen, var(--surface-bg));
+    overflow: hidden;
+  }
+  .brillouin-zone:fullscreen :global(canvas) {
+    height: 100vh !important;
+    width: 100vw !important;
+  }
+  .brillouin-zone.dragover {
+    background: var(--bz-dragover-bg, var(--dragover-bg));
+    border: var(--bz-dragover-border, var(--dragover-border));
+  }
+  .brillouin-zone :global(canvas) {
+    user-select: none;
+  }
+  section.control-buttons {
+    position: absolute;
+    display: flex;
+    top: var(--bz-buttons-top, var(--ctrl-btn-top, 1ex));
+    right: var(--bz-buttons-right, var(--ctrl-btn-right, 1ex));
+    gap: clamp(6pt, 1cqmin, 9pt);
+    z-index: var(
+      --bz-buttons-z-index,
+      var(--z-index-overlay-controls, 100000000)
+    );
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.2s ease;
+    align-items: center;
+  }
+  /* Mode: always - controls always visible */
+  section.control-buttons.always-visible {
+    opacity: 1;
+    pointer-events: auto;
+  }
+  /* Mode: hover - controls visible on component hover */
+  .brillouin-zone:hover section.control-buttons.hover-visible,
+  .brillouin-zone:focus-within section.control-buttons.hover-visible {
+    opacity: 1;
+    pointer-events: auto;
+  }
+  /* Mode: never - stays hidden (default state, no additional CSS needed) */
+  section.control-buttons > :global(button) {
+    background-color: transparent;
+    display: flex;
+    padding: 4px;
+    border-radius: var(--border-radius, 3pt);
+    font-size: clamp(0.85em, 2cqmin, 1.3em);
+  }
+  section.control-buttons :global(button:hover) {
+    background-color: color-mix(in srgb, currentColor 8%, transparent);
+  }
+  .filename {
+    font-family: monospace;
+    font-size: 0.9em;
+    background: var(--code-bg, rgba(0, 0, 0, 0.1));
+    padding: 3pt 6pt;
+    border-radius: 3pt;
+    max-width: 200px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  p.warn {
+    text-align: center;
+    padding: 2rem;
+  }
+</style>

package/dist/src/lib/brillouin/BrillouinZoneControls.svelte

@@ -0,0 +1,144 @@
+<script lang="ts">
+  import SettingsSection from '$lib/layout/SettingsSection.svelte'
+  import DraggablePane from '$lib/overlays/DraggablePane.svelte'
+  import type { CameraProjection } from '$lib/settings'
+
+  let {
+    controls_open = $bindable(false),
+    bz_order = $bindable(1),
+    surface_color = $bindable(`#4488ff`),
+    surface_opacity = $bindable(0.3),
+    edge_color = $bindable(`#000000`),
+    edge_width = $bindable(0.05),
+    show_vectors = $bindable(true),
+    camera_projection = $bindable(`perspective`),
+    // Irreducible BZ options
+    show_ibz = $bindable(false),
+    ibz_color = $bindable(`#ff8844`),
+    ibz_opacity = $bindable(0.5),
+  }: {
+    controls_open?: boolean
+    bz_order?: number
+    surface_color?: string
+    surface_opacity?: number
+    edge_color?: string
+    edge_width?: number
+    show_vectors?: boolean
+    camera_projection?: CameraProjection
+    // Irreducible BZ options
+    show_ibz?: boolean
+    ibz_color?: string
+    ibz_opacity?: number
+  } = $props()
+</script>
+
+<DraggablePane
+  bind:show={controls_open}
+  open_icon="Cross"
+  closed_icon="Settings"
+  pane_props={{ class: `bz-controls` }}
+  toggle_props={{ class: `controls-toggle`, title: `Brillouin zone controls` }}
+>
+  <SettingsSection
+    title="Brillouin Zone Controls"
+    current_values={{ bz_order, show_vectors }}
+    on_reset={() => {
+      bz_order = 1
+      show_vectors = true
+    }}
+    style="display: flex; gap: 2ex; flex-wrap: wrap"
+  >
+    <label>
+      <span>Order:</span>
+      <select bind:value={bz_order}>
+        <option value={1}>1st BZ</option>
+        <option value={2}>2nd BZ</option>
+        <option value={3}>3rd BZ</option>
+      </select>
+    </label>
+    <label>
+      <span>Show Vectors:</span>
+      <input type="checkbox" bind:checked={show_vectors} />
+    </label>
+  </SettingsSection>
+
+  <SettingsSection
+    title="Surface"
+    current_values={{ surface_color, surface_opacity }}
+    on_reset={() => {
+      surface_color = `#4488ff`
+      surface_opacity = 0.3
+    }}
+  >
+    <label>
+      <span>Color:</span>
+      <input type="color" bind:value={surface_color} />
+    </label>
+    <label>
+      <span>Opacity:</span>
+      <input type="range" min="0" max="1" step="0.01" bind:value={surface_opacity} />
+      <span class="value">{surface_opacity.toFixed(2)}</span>
+    </label>
+  </SettingsSection>
+
+  <SettingsSection
+    title="Edges"
+    current_values={{ edge_color, edge_width }}
+    on_reset={() => {
+      edge_color = `#000000`
+      edge_width = 0.05
+    }}
+  >
+    <label>
+      <span>Color:</span>
+      <input type="color" bind:value={edge_color} />
+    </label>
+    <label>
+      <span>Width:</span>
+      <input type="range" min="0.01" max="0.2" step="0.01" bind:value={edge_width} />
+      <span class="value">{edge_width.toFixed(2)}</span>
+    </label>
+  </SettingsSection>
+
+  <SettingsSection
+    title="Camera"
+    current_values={{ camera_projection }}
+    on_reset={() => {
+      camera_projection = `perspective`
+    }}
+  >
+    <label>
+      <span>Projection:</span>
+      <select bind:value={camera_projection}>
+        <option value="perspective">Perspective</option>
+        <option value="orthographic">Orthographic</option>
+      </select>
+    </label>
+  </SettingsSection>
+
+  <SettingsSection
+    title="Irreducible BZ"
+    current_values={{ show_ibz, ibz_color, ibz_opacity }}
+    on_reset={() => {
+      show_ibz = false
+      ibz_color = `#ff8844`
+      ibz_opacity = 0.5
+    }}
+  >
+    <label>
+      <span>Show IBZ:</span>
+      <input type="checkbox" bind:checked={show_ibz} />
+    </label>
+    {#if show_ibz}
+      <label>
+        <span>Color:</span>
+        <input type="color" bind:value={ibz_color} />
+      </label>
+      <label>
+        <span>Opacity:</span>
+        <input type="range" min="0" max="1" step="0.01" bind:value={ibz_opacity} />
+        <span class="value">{ibz_opacity.toFixed(2)}</span>
+      </label>
+    {/if}
+  </SettingsSection>
+</DraggablePane>