matterviz 0.3.6 → 0.4.0

package/dist/plot/core/components/ReferencePlane.svelte

@@ -0,0 +1,175 @@
+<script lang="ts">
+  // ReferencePlane: 3D reference planes (axis-aligned, normal-defined, or point-defined)
+  import type { Vec3 } from '../../../math'
+  import { cross_3d, normalize_vec } from '../../../math'
+  import { T } from '@threlte/core'
+  import * as THREE from 'three'
+  import { create_to_threejs, span_or } from '../reference-line'
+  import type { RefPlane } from '../types'
+
+  let { ref_plane, scene_size = [10, 10, 5], ranges }: {
+    ref_plane: RefPlane
+    scene_size?: Vec3
+    ranges: { x: [number, number]; y: [number, number]; z: [number, number] }
+  } = $props()
+
+  let [scene_x, scene_y, scene_z] = $derived(scene_size)
+  let { x: x_range, y: y_range, z: z_range } = $derived(ranges)
+
+  // Transform data coords to Three.js Vector3
+  let to_vec3 = $derived.by(() => {
+    const transform = create_to_threejs({
+      scene_x,
+      scene_y,
+      scene_z,
+      x_range,
+      y_range,
+      z_range,
+    })
+    return (ux: number, uy: number, uz: number) => {
+      const { x, y, z } = transform(ux, uy, uz)
+      return new THREE.Vector3(x, y, z)
+    }
+  })
+
+  // Apply span constraints or use full range
+  let [x_min, x_max] = $derived(span_or(ref_plane.x_span, x_range))
+  let [y_min, y_max] = $derived(span_or(ref_plane.y_span, y_range))
+  let [z_min, z_max] = $derived(span_or(ref_plane.z_span, z_range))
+
+  // Helper to create quad from 4 corner coords
+  const quad = (coords: Vec3[]) =>
+    create_quad_geometry(coords.map(([ux, uy, uz]) => to_vec3(ux, uy, uz)))
+
+  // Compute plane geometry based on type - returns result to use in $effect
+  function compute_geometry(): THREE.BufferGeometry | null {
+    if (ref_plane.visible === false) return null
+
+    if (ref_plane.type === `xy`) {
+      const zval = ref_plane.z
+      return quad([
+        [x_min, y_min, zval],
+        [x_max, y_min, zval],
+        [x_max, y_max, zval],
+        [x_min, y_max, zval],
+      ])
+    }
+    if (ref_plane.type === `xz`) {
+      const yval = ref_plane.y
+      return quad([
+        [x_min, yval, z_min],
+        [x_max, yval, z_min],
+        [x_max, yval, z_max],
+        [x_min, yval, z_max],
+      ])
+    }
+    if (ref_plane.type === `yz`) {
+      const xval = ref_plane.x
+      return quad([
+        [xval, y_min, z_min],
+        [xval, y_max, z_min],
+        [xval, y_max, z_max],
+        [xval, y_min, z_max],
+      ])
+    }
+    if (ref_plane.type === `normal`) {
+      if (Math.hypot(...ref_plane.normal) < 1e-9) return null // degenerate normal
+      return create_plane_from_normal(ref_plane.normal, ref_plane.point)
+    }
+    if (ref_plane.type === `points`) {
+      const { p1, p2, p3 } = ref_plane
+      const v1: Vec3 = [p2[0] - p1[0], p2[1] - p1[1], p2[2] - p1[2]]
+      const v2: Vec3 = [p3[0] - p1[0], p3[1] - p1[1], p3[2] - p1[2]]
+      const cross = cross_3d(v1, v2)
+      if (Math.hypot(...cross) < 1e-9) return null // collinear points
+      return create_plane_from_normal(normalize_vec(cross), p1)
+    }
+    return null
+  }
+
+  // Create geometry with proper disposal on dependency change
+  let geometry: THREE.BufferGeometry | null = $state(null)
+
+  $effect(() => {
+    const geo = compute_geometry()
+    geometry = geo
+    return () => geo?.dispose()
+  })
+
+  // Create a quad geometry from 4 corners (two triangles: 0-1-2 and 0-2-3)
+  function create_quad_geometry(corners: THREE.Vector3[]): THREE.BufferGeometry {
+    const geo = new THREE.BufferGeometry()
+    const [c0, c1, c2, c3] = corners
+    const verts = [c0, c1, c2, c0, c2, c3].flatMap((corner) => [corner.x, corner.y, corner.z])
+    geo.setAttribute(
+      `position`,
+      new THREE.BufferAttribute(new Float32Array(verts), 3),
+    )
+    geo.computeVertexNormals()
+    return geo
+  }
+
+  // Create plane from normal and point, scaled to cover bounding box
+  function create_plane_from_normal(normal: Vec3, point: Vec3): THREE.BufferGeometry {
+    const normalized = normalize_vec(normal)
+    // Pick u perpendicular to normal (use axis least aligned with normal)
+    const u_dir = normalize_vec(
+      cross_3d(normalized, Math.abs(normalized[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0]),
+    )
+    const v_dir = cross_3d(normalized, u_dir)
+    // Scale to cover bounding box
+    const scale = Math.max(x_max - x_min, y_max - y_min, z_max - z_min) * 2
+    const [px, py, pz] = point
+    // Helper to offset point by u*su + v*sv
+    const corner = (su: number, sv: number): Vec3 => [
+      px + u_dir[0] * su + v_dir[0] * sv,
+      py + u_dir[1] * su + v_dir[1] * sv,
+      pz + u_dir[2] * su + v_dir[2] * sv,
+    ]
+    const corners = [
+      corner(-scale, -scale),
+      corner(scale, -scale),
+      corner(scale, scale),
+      corner(-scale, scale),
+    ]
+    return create_quad_geometry(corners.map(([ux, uy, uz]) => to_vec3(ux, uy, uz)))
+  }
+
+  // Material properties (with defaults)
+  let style = $derived({
+    color: ref_plane.style?.color ?? `#4488ff`,
+    opacity: ref_plane.style?.opacity ?? 0.3,
+    wireframe: ref_plane.style?.wireframe ?? false,
+    wireframe_color: ref_plane.style?.wireframe_color ?? `white`,
+    double_sided: ref_plane.style?.double_sided ?? true,
+  })
+
+  // Create wireframe geometry with automatic disposal when dependencies change
+  let wireframe_geometry: THREE.WireframeGeometry | null = $state(null)
+
+  $effect(() => {
+    const wf_geo = geometry && style.wireframe
+      ? new THREE.WireframeGeometry(geometry)
+      : null
+    wireframe_geometry = wf_geo
+    return () => wf_geo?.dispose()
+  })
+</script>
+
+{#if geometry}
+  <T.Mesh {geometry}>
+    <T.MeshBasicMaterial
+      color={style.color}
+      opacity={style.opacity}
+      transparent={true}
+      side={style.double_sided ? THREE.DoubleSide : THREE.FrontSide}
+      depthWrite={false}
+    />
+  </T.Mesh>
+
+  {#if wireframe_geometry}
+    <T.LineSegments geometry={wireframe_geometry}>
+      <T.LineBasicMaterial color={style.wireframe_color} />
+    </T.LineSegments>
+  {/if}
+{/if}

package/dist/plot/core/components/ReferencePlane.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Vec3 } from '../../../math';
+import type { RefPlane } from '../types';
+type $$ComponentProps = {
+    ref_plane: RefPlane;
+    scene_size?: Vec3;
+    ranges: {
+        x: [number, number];
+        y: [number, number];
+        z: [number, number];
+    };
+};
+declare const ReferencePlane: import("svelte").Component<$$ComponentProps, {}, "">;
+type ReferencePlane = ReturnType<typeof ReferencePlane>;
+export default ReferencePlane;

package/dist/plot/core/components/ZeroLines.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+  import type { Vec2 } from '../../../math'
+  import type { Sides } from '../layout'
+  import { get_scale_type_name, type ScaleType } from '../..'
+
+  let {
+    display,
+    x_scale_fn,
+    x2_scale_fn,
+    y_scale_fn,
+    y2_scale_fn,
+    x_range,
+    x2_range,
+    y_range,
+    y2_range,
+    x_scale_type,
+    x2_scale_type,
+    y_scale_type,
+    y2_scale_type,
+    x_is_time = false,
+    x2_is_time = false,
+    has_x2 = false,
+    has_y2 = false,
+    width,
+    height,
+    pad,
+  }: {
+    display: {
+      x_zero_line?: boolean
+      x2_zero_line?: boolean
+      y_zero_line?: boolean
+      y2_zero_line?: boolean
+    }
+    x_scale_fn: (val: number) => number
+    x2_scale_fn?: (val: number) => number
+    y_scale_fn: (val: number) => number
+    y2_scale_fn?: (val: number) => number
+    x_range: Vec2
+    x2_range?: Vec2
+    y_range: Vec2
+    y2_range?: Vec2
+    x_scale_type?: ScaleType
+    x2_scale_type?: ScaleType
+    y_scale_type?: ScaleType
+    y2_scale_type?: ScaleType
+    x_is_time?: boolean
+    x2_is_time?: boolean
+    has_x2?: boolean
+    has_y2?: boolean
+    width: number
+    height: number
+    pad: Required<Sides>
+  } = $props()
+
+  const spans_zero = (range: Vec2): boolean =>
+    Math.min(range[0], range[1]) <= 0 && Math.max(range[0], range[1]) >= 0
+</script>
+
+{#if display.x_zero_line && get_scale_type_name(x_scale_type) !== `log` &&
+    !x_is_time && spans_zero(x_range)}
+  {@const zero_x = x_scale_fn(0)}
+  {#if isFinite(zero_x)}
+    <line class="zero-line" x1={zero_x} x2={zero_x} y1={pad.t} y2={height - pad.b} />
+  {/if}
+{/if}
+
+{#if display.x2_zero_line && has_x2 && x2_scale_fn && x2_range &&
+    get_scale_type_name(x2_scale_type) !== `log` && !x2_is_time && spans_zero(x2_range)}
+  {@const zero_x2 = x2_scale_fn(0)}
+  {#if isFinite(zero_x2)}
+    <line class="zero-line" x1={zero_x2} x2={zero_x2} y1={pad.t} y2={height - pad.b} />
+  {/if}
+{/if}
+
+{#if display.y_zero_line && get_scale_type_name(y_scale_type) !== `log` &&
+    spans_zero(y_range)}
+  {@const zero_y = y_scale_fn(0)}
+  {#if isFinite(zero_y)}
+    <line class="zero-line" x1={pad.l} x2={width - pad.r} y1={zero_y} y2={zero_y} />
+  {/if}
+{/if}
+
+{#if display.y2_zero_line && has_y2 && y2_scale_fn && y2_range &&
+    get_scale_type_name(y2_scale_type) !== `log` && spans_zero(y2_range)}
+  {@const zero_y2 = y2_scale_fn(0)}
+  {#if isFinite(zero_y2)}
+    <line class="zero-line" x1={pad.l} x2={width - pad.r} y1={zero_y2} y2={zero_y2} />
+  {/if}
+{/if}
+
+<style>
+  .zero-line {
+    stroke: var(--plot-zero-line-color, light-dark(black, white));
+    stroke-width: var(--plot-zero-line-width, 1);
+    opacity: var(--plot-zero-line-opacity, 0.3);
+  }
+</style>

package/dist/plot/core/components/ZeroLines.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { Vec2 } from '../../../math';
+import type { Sides } from '../layout';
+import { type ScaleType } from '../..';
+type $$ComponentProps = {
+    display: {
+        x_zero_line?: boolean;
+        x2_zero_line?: boolean;
+        y_zero_line?: boolean;
+        y2_zero_line?: boolean;
+    };
+    x_scale_fn: (val: number) => number;
+    x2_scale_fn?: (val: number) => number;
+    y_scale_fn: (val: number) => number;
+    y2_scale_fn?: (val: number) => number;
+    x_range: Vec2;
+    x2_range?: Vec2;
+    y_range: Vec2;
+    y2_range?: Vec2;
+    x_scale_type?: ScaleType;
+    x2_scale_type?: ScaleType;
+    y_scale_type?: ScaleType;
+    y2_scale_type?: ScaleType;
+    x_is_time?: boolean;
+    x2_is_time?: boolean;
+    has_x2?: boolean;
+    has_y2?: boolean;
+    width: number;
+    height: number;
+    pad: Required<Sides>;
+};
+declare const ZeroLines: import("svelte").Component<$$ComponentProps, {}, "">;
+type ZeroLines = ReturnType<typeof ZeroLines>;
+export default ZeroLines;

package/dist/plot/core/components/ZoomRect.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import type { Point2D } from '../../../math'
+
+  let { start, current }: { start: Point2D | null; current: Point2D | null } = $props()
+</script>
+
+{#if start && current && isFinite(start.x) && isFinite(start.y) &&
+    isFinite(current.x) && isFinite(current.y)}
+  {@const x = Math.min(start.x, current.x)}
+  {@const y = Math.min(start.y, current.y)}
+  {@const rect_width = Math.abs(start.x - current.x)}
+  {@const rect_height = Math.abs(start.y - current.y)}
+  <rect class="zoom-rect" {x} {y} width={rect_width} height={rect_height} />
+{/if}
+
+<style>
+  .zoom-rect {
+    fill: var(--plot-zoom-rect-fill, rgba(100, 100, 255, 0.2));
+    stroke: var(--plot-zoom-rect-stroke, rgba(100, 100, 255, 0.8));
+    stroke-width: var(--plot-zoom-rect-stroke-width, 1);
+    pointer-events: none;
+  }
+</style>

package/dist/plot/core/components/ZoomRect.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Point2D } from '../../../math';
+type $$ComponentProps = {
+    start: Point2D | null;
+    current: Point2D | null;
+};
+declare const ZoomRect: import("svelte").Component<$$ComponentProps, {}, "">;
+type ZoomRect = ReturnType<typeof ZoomRect>;
+export default ZoomRect;

package/dist/plot/core/components/index.d.ts

@@ -0,0 +1,17 @@
+export { default as AxisLabel } from './AxisLabel.svelte';
+export { default as ColorBar } from './ColorBar.svelte';
+export { default as ColorScaleSelect } from './ColorScaleSelect.svelte';
+export { default as ControlPane } from './ControlPane.svelte';
+export { default as FillArea } from './FillArea.svelte';
+export { default as InteractiveAxisLabel } from './InteractiveAxisLabel.svelte';
+export { default as Line } from './Line.svelte';
+export { default as PlotAxis } from './PlotAxis.svelte';
+export { default as PlotControls } from './PlotControls.svelte';
+export { default as PlotLegend } from './PlotLegend.svelte';
+export { default as PlotTooltip } from './PlotTooltip.svelte';
+export { default as PortalSelect } from './PortalSelect.svelte';
+export { default as ReferenceLine } from './ReferenceLine.svelte';
+export { default as ReferenceLine3D } from './ReferenceLine3D.svelte';
+export { default as ReferencePlane } from './ReferencePlane.svelte';
+export { default as ZeroLines } from './ZeroLines.svelte';
+export { default as ZoomRect } from './ZoomRect.svelte';

package/dist/plot/core/components/index.js

@@ -0,0 +1,17 @@
+export { default as AxisLabel } from './AxisLabel.svelte';
+export { default as ColorBar } from './ColorBar.svelte';
+export { default as ColorScaleSelect } from './ColorScaleSelect.svelte';
+export { default as ControlPane } from './ControlPane.svelte';
+export { default as FillArea } from './FillArea.svelte';
+export { default as InteractiveAxisLabel } from './InteractiveAxisLabel.svelte';
+export { default as Line } from './Line.svelte';
+export { default as PlotAxis } from './PlotAxis.svelte';
+export { default as PlotControls } from './PlotControls.svelte';
+export { default as PlotLegend } from './PlotLegend.svelte';
+export { default as PlotTooltip } from './PlotTooltip.svelte';
+export { default as PortalSelect } from './PortalSelect.svelte';
+export { default as ReferenceLine } from './ReferenceLine.svelte';
+export { default as ReferenceLine3D } from './ReferenceLine3D.svelte';
+export { default as ReferencePlane } from './ReferencePlane.svelte';
+export { default as ZeroLines } from './ZeroLines.svelte';
+export { default as ZoomRect } from './ZoomRect.svelte';

package/dist/plot/core/data-cleaning.d.ts

@@ -0,0 +1,107 @@
+import type { Vec2 } from '../../math';
+import type { DataSeries } from './types';
+export interface OscillationWeights {
+    derivative_variance?: number;
+    amplitude_growth?: number;
+    sign_changes?: number;
+}
+export type InvalidValueMode = `remove` | `propagate` | `interpolate`;
+export type TruncationMode = `hard_cut` | `mark_unstable`;
+export interface PhysicalBounds {
+    min?: number | ((x: number) => number);
+    max?: number | ((x: number) => number);
+    mode?: `clamp` | `filter` | `null`;
+}
+export type SmoothingConfig = {
+    type: `moving_avg`;
+    window: number;
+} | {
+    type: `savgol`;
+    window: number;
+    polynomial_order?: number;
+} | {
+    type: `gaussian`;
+    sigma: number;
+};
+export interface LocalOutlierConfig {
+    window_half?: number;
+    mad_threshold?: number;
+    max_iterations?: number;
+}
+export interface LocalOutlierResult {
+    kept_indices: number[];
+    removed_indices: number[];
+    iterations_used: number;
+}
+export interface CleaningConfig {
+    oscillation_threshold?: number;
+    oscillation_weights?: OscillationWeights;
+    window_size?: number;
+    invalid_values?: InvalidValueMode;
+    bounds?: PhysicalBounds;
+    smooth?: SmoothingConfig;
+    local_outliers?: LocalOutlierConfig;
+    truncation_mode?: TruncationMode;
+    in_place?: boolean;
+}
+export interface CleaningQuality {
+    points_removed: number;
+    invalid_values_found: number;
+    oscillation_detected: boolean;
+    oscillation_score?: number;
+    bounds_violations: number;
+    outliers_removed?: number;
+    stable_range?: Vec2;
+    truncated_at_x?: number;
+}
+export interface CleaningResult<T = DataSeries> {
+    series: T;
+    quality: CleaningQuality;
+}
+export interface InstabilityResult {
+    detected: boolean;
+    onset_index: number;
+    onset_x: number;
+    combined_score: number;
+    method_scores: {
+        derivative_variance: number;
+        amplitude_growth: number;
+        sign_changes: number;
+    };
+}
+export declare function compute_local_variance(values: number[], window_size: number): number[];
+export declare function detect_instability(x_values: readonly number[], y_values: readonly number[], config?: Pick<CleaningConfig, `oscillation_weights` | `oscillation_threshold` | `window_size`>): InstabilityResult;
+export declare function smooth_moving_average(values: number[], window: number): number[];
+export declare function smooth_savitzky_golay(values: number[], window: number, polynomial_order?: number): number[];
+export declare function remove_local_outliers(y_values: readonly number[], config?: LocalOutlierConfig): LocalOutlierResult;
+export declare function handle_invalid_values(values: number[], mode: InvalidValueMode): {
+    cleaned: number[];
+    removed_indices: number[];
+    invalid_count: number;
+};
+export declare function apply_bounds(x_values: readonly number[], y_values: number[], bounds: PhysicalBounds): {
+    y: number[];
+    violations: number;
+    filtered_indices: number[];
+};
+export declare function sync_metadata<M>(metadata: M[] | M | undefined, kept_indices: number[]): M[] | M | undefined;
+export declare function clean_series<T extends DataSeries>(series: T, config?: CleaningConfig): CleaningResult<T>;
+export declare function clean_multi_series(x_values: readonly number[], y_arrays: number[][], config?: CleaningConfig): {
+    x: number[];
+    cleaned_y: number[][];
+    quality: CleaningQuality[];
+};
+export declare function clean_xyz(x_values: readonly number[], y_values: readonly number[], z_values: readonly number[], config?: CleaningConfig & {
+    primary_axis?: `x` | `y` | `z`;
+}): {
+    x: number[];
+    y: number[];
+    z: number[];
+    quality: CleaningQuality;
+};
+export declare function clean_trajectory_props(props: Record<string, number[]>, config?: CleaningConfig & {
+    independent_axis?: string;
+}): {
+    props: Record<string, number[]>;
+    quality: Record<string, CleaningQuality>;
+};