matterviz 0.3.4 → 0.3.6

package/src/webview/detect.ts

@@ -0,0 +1,444 @@
+// Data type detection for JSON values -- determines which visualization component to use.
+// Used by JsonBrowser to detect renderable items in JSON trees and by main.ts
+// to decide whether to show the browser or render directly.
+
+import { is_optimade_raw } from '$lib/structure/parse'
+
+// Visualization types that can be rendered in the extension
+export type RenderableType =
+  | `structure`
+  | `fermi_surface`
+  | `band_grid`
+  | `convex_hull`
+  | `volumetric`
+  | `phase_diagram`
+  | `band_structure`
+  | `dos`
+  | `bands_and_dos`
+  | `brillouin_zone`
+  | `xrd`
+  | `table`
+  | `plot`
+
+// Human-readable labels for badge display
+export const TYPE_LABELS: Record<RenderableType, string> = {
+  structure: `Structure`,
+  fermi_surface: `Fermi Surface`,
+  band_grid: `Band Grid`,
+  convex_hull: `Convex Hull`,
+  volumetric: `Volumetric`,
+  phase_diagram: `Phase Diagram`,
+  band_structure: `Band Structure`,
+  dos: `DOS`,
+  bands_and_dos: `Bands + DOS`,
+  brillouin_zone: `Brillouin Zone`,
+  xrd: `XRD`,
+  table: `Table`,
+  plot: `Plot`,
+}
+
+// Badge colors per type (CSS color values)
+export const TYPE_COLORS: Record<RenderableType, string> = {
+  structure: `#4fc3f7`,
+  fermi_surface: `#ab47bc`,
+  band_grid: `#7e57c2`,
+  convex_hull: `#66bb6a`,
+  volumetric: `#ffa726`,
+  phase_diagram: `#ef5350`,
+  band_structure: `#29b6f6`,
+  dos: `#26a69a`,
+  bands_and_dos: `#5c6bc0`,
+  brillouin_zone: `#8d6e63`,
+  xrd: `#ec407a`,
+  table: `#78909c`,
+  plot: `#7c3aed`,
+}
+
+// === Type Guards ===
+
+// Narrows unknown to a non-array object record; used by every type guard below
+const as_record = (obj: unknown): Record<string, unknown> | null =>
+  obj && typeof obj === `object` && !Array.isArray(obj)
+    ? (obj as Record<string, unknown>)
+    : null
+
+// Check that `key` on `data` is an Array with exactly `len` elements (or any length if omitted)
+const has_array = (data: Record<string, unknown>, key: string, len?: number): boolean => {
+  const val = data[key]
+  return Array.isArray(val) && (len === undefined || val.length === len)
+}
+
+// Structure: must have non-empty `sites` array where first site has `species` + coordinates
+function is_structure(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data || !has_array(data, `sites`)) return false
+  const sites = data.sites as unknown[]
+  if (sites.length === 0) return false
+  const first_site = as_record(sites[0])
+  if (!first_site) return false
+  const has_species = Array.isArray(first_site.species) && first_site.species.length > 0
+  return has_species && (Array.isArray(first_site.abc) || Array.isArray(first_site.xyz))
+}
+
+// FermiSurfaceData: pre-computed isosurfaces with reciprocal lattice info
+function is_fermi_surface(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  return (
+    has_array(data, `isosurfaces`) &&
+    has_array(data, `k_lattice`, 3) &&
+    typeof data.fermi_energy === `number` &&
+    (data.reciprocal_cell === `wigner_seitz` || data.reciprocal_cell === `parallelepiped`) &&
+    !!as_record(data.metadata)
+  )
+}
+
+// BandGridData: raw band energies on a k-grid (needs marching cubes extraction)
+function is_band_grid(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  return (
+    has_array(data, `energies`) &&
+    has_array(data, `k_grid`, 3) &&
+    has_array(data, `k_lattice`, 3) &&
+    typeof data.fermi_energy === `number` &&
+    typeof data.n_bands === `number` &&
+    typeof data.n_spins === `number`
+  )
+}
+
+// ConvexHull entries: array of objects with `composition` (object) + energy field
+// Accepts `energy`, `e_form_per_atom`, or `energy_per_atom` as the energy key
+function is_convex_hull_entries(obj: unknown): boolean {
+  if (!Array.isArray(obj) || obj.length < 2) return false
+  // Check first few entries to avoid false positives on random arrays
+  return obj.slice(0, 3).every((item) => {
+    const entry = as_record(item)
+    return (
+      entry &&
+      as_record(entry.composition) &&
+      (typeof entry.energy === `number` ||
+        typeof entry.e_form_per_atom === `number` ||
+        typeof entry.energy_per_atom === `number`)
+    )
+  })
+}
+
+// VolumetricData: 3D scalar grid with lattice info
+function is_volumetric(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data || !has_array(data, `grid`)) return false
+  // grid must be a 3D array (array of arrays of arrays)
+  const grid = data.grid as unknown[]
+  if (grid.length === 0) return false
+  const first_slice = grid[0]
+  if (!Array.isArray(first_slice) || !first_slice.length || !Array.isArray(first_slice[0]))
+    return false
+  return (
+    has_array(data, `grid_dims`, 3) &&
+    has_array(data, `lattice`, 3) &&
+    has_array(data, `origin`, 3) &&
+    !!as_record(data.data_range) &&
+    typeof data.periodic === `boolean`
+  )
+}
+
+// PhaseDiagramData: binary phase diagram with components, regions, boundaries
+function is_phase_diagram(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  if (!has_array(data, `components`, 2)) return false
+  const [comp_a, comp_b] = data.components as unknown[]
+  if (typeof comp_a !== `string` || typeof comp_b !== `string`) return false
+  return (
+    has_array(data, `regions`) &&
+    has_array(data, `boundaries`) &&
+    has_array(data, `temperature_range`, 2)
+  )
+}
+
+// BandStructure: normalized format (qpoints, branches, bands, nb_bands)
+// or pymatgen format (kpoints, branches, bands with spin keys, labels_dict)
+function is_band_structure(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  if (!has_array(data, `branches`) || (data.branches as unknown[]).length === 0) {
+    return false
+  }
+  if (!as_record(data.labels_dict)) return false
+  // Normalized format
+  if (
+    has_array(data, `qpoints`) &&
+    has_array(data, `bands`) &&
+    typeof data.nb_bands === `number`
+  )
+    return true
+  // Pymatgen format: kpoints + bands object (not array) + efermi
+  if (has_array(data, `kpoints`) && as_record(data.bands)) {
+    return typeof data.efermi === `number`
+  }
+  return false
+}
+
+// DOS: pymatgen CompleteDos format or normalized DosData
+// CompleteDos: has energies, densities, efermi, and @class containing "Dos"
+// DosData: has type ("phonon"|"electronic"), frequencies/energies, densities
+function is_dos(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  const has_spectra = has_array(data, `energies`) || has_array(data, `frequencies`)
+  // pymatgen CompleteDos format
+  if (
+    typeof data[`@class`] === `string` &&
+    (data[`@class`] as string).includes(`Dos`) &&
+    has_spectra &&
+    data.densities !== undefined
+  )
+    return true
+  // Normalized DosData format
+  if (
+    (data.type === `phonon` || data.type === `electronic`) &&
+    has_spectra &&
+    has_array(data, `densities`)
+  )
+    return true
+  return false
+}
+
+// BandsAndDos: object containing both band_structure and dos data at the same level.
+// Must be a focused wrapper (few keys), not a large object that happens to have both.
+function is_bands_and_dos(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  const keys = Object.keys(data).filter((key) => !key.startsWith(`@`) && !key.startsWith(`_`))
+  // Wrapper format: { band_structure: {...}, dos: {...} } with few extra keys
+  const has_bands = as_record(data.band_structure) && is_band_structure(data.band_structure)
+  const has_dos_key = as_record(data.dos) && is_dos(data.dos)
+  if (has_bands && has_dos_key && keys.length <= 5) return true
+  // Combined-fields format: single object with both band structure and DOS fields mixed in
+  const has_bands_fields = has_array(data, `branches`) && as_record(data.labels_dict)
+  const has_dos_fields =
+    (has_array(data, `energies`) || has_array(data, `frequencies`)) &&
+    data.densities !== undefined &&
+    (data.atom_dos !== undefined || data.spd_dos !== undefined)
+  return !!(has_bands_fields && has_dos_fields)
+}
+
+// BrillouinZone: reciprocal lattice data with optional k-path info
+// Matches objects with a lattice that has reciprocal vectors (k_lattice or reciprocal_lattice)
+// and optionally k-path points/labels for overlaying on the zone
+function is_brillouin_zone(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  // Must have reciprocal lattice vectors (3x3 matrix)
+  const has_k_lattice =
+    has_array(data, `k_lattice`, 3) || has_array(data, `reciprocal_lattice`, 3)
+  if (!has_k_lattice) return false
+  // Must have k-path or explicit BZ data to distinguish from Fermi surface data
+  // (Fermi surface also has k_lattice but additionally has isosurfaces)
+  if (has_array(data, `isosurfaces`)) return false // that's a Fermi surface, not a plain BZ
+  // Accept if it has k_path labels/points, or a structure with lattice
+  return (
+    has_array(data, `k_path`) ||
+    has_array(data, `k_points`) ||
+    !!as_record(data.k_labels) ||
+    !!as_record(data.labels_dict) ||
+    data.bz_order !== undefined
+  )
+}
+
+// XRD pattern: x + y arrays of equal length (2-theta angles vs intensities)
+// with optional hkls (Miller indices) and d_hkls (d-spacings)
+function is_xrd_pattern(obj: unknown): boolean {
+  const data = as_record(obj)
+  if (!data) return false
+  if (!has_array(data, `x`) || !has_array(data, `y`)) return false
+  const x_arr = data.x as unknown[]
+  const y_arr = data.y as unknown[]
+  if (x_arr.length !== y_arr.length || x_arr.length === 0) return false
+  // Must have numeric x/y values
+  if (typeof x_arr[0] !== `number` || typeof y_arr[0] !== `number`) return false
+  // Distinguish from generic scatter data: XRD patterns typically have hkls or d_hkls,
+  // or have @class containing "Xrd"
+  return (
+    has_array(data, `hkls`) ||
+    has_array(data, `d_hkls`) ||
+    (typeof data[`@class`] === `string` && (data[`@class`] as string).includes(`Xrd`)) ||
+    typeof data.wavelength === `number`
+  )
+}
+
+// Tabular data: array of objects with consistent keys (row-based table format)
+// or object with parallel arrays (column-based format)
+function is_tabular_data(obj: unknown): boolean {
+  // Row-based: array of objects with string keys and numeric/string values
+  if (Array.isArray(obj) && obj.length >= 3) {
+    const first = as_record(obj[0])
+    const second = as_record(obj[1])
+    if (!first || !second) return false
+    const first_keys = Object.keys(first)
+    if (first_keys.length < 2) return false
+    // Check that rows have consistent keys and mostly numeric/string values
+    const second_keys = Object.keys(second)
+    const overlap = first_keys.filter((key) => second_keys.includes(key))
+    if (overlap.length < first_keys.length * 0.5) return false
+    // At least some values should be numbers (not just metadata objects)
+    const num_count = first_keys.filter((key) => typeof first[key] === `number`).length
+    return num_count >= 1
+  }
+  // Column-based: object where multiple values are equal-length arrays
+  const data = as_record(obj)
+  if (!data) return false
+  const entries = Object.entries(data)
+  if (entries.length < 2) return false
+  const array_entries = entries.filter(([, val]) => Array.isArray(val) && val.length > 0)
+  if (array_entries.length < 2) return false
+  // Check that arrays have consistent lengths
+  const lengths = array_entries.map(([, val]) => (val as unknown[]).length)
+  const first_len = lengths[0]
+  if (!lengths.every((len) => len === first_len)) return false
+  // At least one column must contain numbers
+  return array_entries.some(([, val]) => typeof (val as unknown[])[0] === `number`)
+}
+
+// Plottable data: tabular data with at least 2 numeric columns (enough for a scatter plot).
+// Samples multiple rows/elements to handle leading nulls.
+export function is_plottable_data(obj: unknown): boolean {
+  if (!is_tabular_data(obj)) return false
+  if (Array.isArray(obj)) {
+    const sample = obj.slice(0, 10).map(as_record).filter(Boolean) as Record<string, unknown>[]
+    if (sample.length === 0) return false
+    const all_keys = new Set(sample.flatMap(Object.keys))
+    const num_cols = [...all_keys].filter((key) =>
+      sample.some((row) => typeof row[key] === `number`),
+    ).length
+    return num_cols >= 2
+  }
+  const data = as_record(obj)
+  if (!data) return false
+  const array_entries = Object.entries(data).filter(
+    ([, val]) => Array.isArray(val) && (val as unknown[]).length > 0,
+  )
+  const num_cols = array_entries.filter(([, val]) =>
+    (val as unknown[]).some((elem) => typeof elem === `number`),
+  ).length
+  return num_cols >= 2
+}
+
+// === Main Detection Function ===
+
+// Detect the visualization type for a given JSON value.
+// Returns the type if the value matches a known format, or null if not renderable.
+// Checks are ordered from most specific to least specific to minimize false positives.
+export function detect_view_type(value: unknown): RenderableType | null {
+  if (value == null) return null
+
+  // OPTIMADE format (special structure variant) -- check before generic structure
+  if (as_record(value) && is_optimade_raw(value)) return `structure`
+
+  // Fermi surface (pre-computed isosurfaces) -- very specific shape
+  if (is_fermi_surface(value)) return `fermi_surface`
+
+  // Band grid data (raw k-grid energies) -- very specific shape
+  if (is_band_grid(value)) return `band_grid`
+
+  // Phase diagram -- specific shape with components + regions + boundaries
+  if (is_phase_diagram(value)) return `phase_diagram`
+
+  // Combined bands + DOS -- check before individual band/dos checks
+  if (is_bands_and_dos(value)) return `bands_and_dos`
+
+  // Band structure -- qpoints + branches + bands
+  if (is_band_structure(value)) return `band_structure`
+
+  // DOS -- energies/frequencies + densities
+  if (is_dos(value)) return `dos`
+
+  // Brillouin zone -- reciprocal lattice with k-path info
+  if (is_brillouin_zone(value)) return `brillouin_zone`
+
+  // XRD pattern -- x/y arrays with hkls or d_hkls
+  if (is_xrd_pattern(value)) return `xrd`
+
+  // Volumetric data -- 3D grid with lattice
+  if (is_volumetric(value)) return `volumetric`
+
+  // Structure (pymatgen-style) -- check after more specific types since
+  // structures are common building blocks inside other data types
+  if (is_structure(value)) return `structure`
+
+  // Convex hull entries -- array check last (most generic)
+  if (is_convex_hull_entries(value)) return `convex_hull`
+
+  // Tabular data -- most generic, check last
+  if (is_tabular_data(value)) return `table`
+
+  return null
+}
+
+// === Renderable Path Scanner ===
+
+interface RenderablePath {
+  type: RenderableType
+  label: string
+}
+
+// Recursively scan a JSON object to find all paths that contain renderable data.
+// Returns a Map of JSON path strings to their detected type.
+// Used to show badges on JsonTree nodes indicating which subtrees contain visualizable data.
+export function scan_renderable_paths(
+  obj: unknown,
+  prefix: string = ``,
+  max_depth: number = 10,
+): Map<string, RenderablePath> {
+  const results = new Map<string, RenderablePath>()
+  const visited = new WeakSet<object>()
+
+  function walk(value: unknown, path: string, depth: number): void {
+    if (depth > max_depth) return
+    if (value == null) return
+    if (typeof value !== `object`) return
+
+    // Circular reference protection
+    const obj_ref = value as object
+    if (visited.has(obj_ref)) return
+    visited.add(obj_ref)
+
+    // Check if this value itself is renderable
+    const detected_type = detect_view_type(value)
+    if (detected_type) {
+      results.set(path, { type: detected_type, label: TYPE_LABELS[detected_type] })
+      // If tabular data is also plottable, register a plot badge too
+      if (detected_type === `table` && is_plottable_data(value)) {
+        const plot_path = path ? `${path}\x00plot` : `\x00plot`
+        results.set(plot_path, { type: `plot`, label: TYPE_LABELS.plot })
+      }
+      // Don't recurse into renderable objects -- their children are part of the data
+      return
+    }
+
+    // Recurse into children
+    if (Array.isArray(value)) {
+      // For arrays, only scan first few elements to avoid huge arrays
+      const scan_count = Math.min(value.length, 20)
+      for (let idx = 0; idx < scan_count; idx++) {
+        const child_path = path ? `${path}[${idx}]` : `[${idx}]`
+        walk(value[idx], child_path, depth + 1)
+      }
+    } else {
+      for (const [key, child_value] of Object.entries(value as Record<string, unknown>)) {
+        // Use bracket notation for keys containing dots to avoid ambiguity in resolve_path
+        const segment = key.includes(`.`) ? `["${key}"]` : key
+        const child_path = path
+          ? key.includes(`.`)
+            ? `${path}${segment}`
+            : `${path}.${segment}`
+          : segment
+        walk(child_value, child_path, depth + 1)
+      }
+    }
+  }
+
+  walk(obj, prefix, 0)
+  return results
+}