matterviz 0.3.6 → 0.4.0

package/dist/src/lib/plot/reference-line.ts

@@ -1,426 +0,0 @@
-// Reference line utilities: helper functions and coordinate resolution
-import type { LayerZIndex, RefLine, RefLineValue } from './types'
-
-export type IndexedRefLine = RefLine & { idx: number }
-
-// Create indexed ref_lines, filtering out invisible ones
-export function index_ref_lines(ref_lines: RefLine[] | undefined): IndexedRefLine[] {
-  return (ref_lines ?? [])
-    .filter((line) => line.visible !== false)
-    .map((line, idx) => ({ ...line, idx }))
-}
-
-// Z-index groups for ordered rendering
-export interface RefLinesByZIndex {
-  below_grid: IndexedRefLine[]
-  below_lines: IndexedRefLine[]
-  below_points: IndexedRefLine[]
-  above_all: IndexedRefLine[]
-}
-
-// Map z-index type values to object keys
-const Z_INDEX_KEY_MAP: Record<LayerZIndex, keyof RefLinesByZIndex> = {
-  'below-grid': `below_grid`,
-  'below-lines': `below_lines`,
-  'below-points': `below_points`,
-  'above-all': `above_all`,
-}
-
-const apply_span = (
-  start_val: number,
-  end_val: number,
-  span?: [number | null, number | null],
-): [number, number] => {
-  if (!span) return [start_val, end_val]
-  return [
-    span[0] !== null ? Math.max(start_val, span[0]) : start_val,
-    span[1] !== null ? Math.min(end_val, span[1]) : end_val,
-  ]
-}
-
-// Group indexed ref_lines by z-index for ordered rendering
-export function group_ref_lines_by_z(lines: IndexedRefLine[]): RefLinesByZIndex {
-  const groups: RefLinesByZIndex = {
-    below_grid: [],
-    below_lines: [],
-    below_points: [],
-    above_all: [],
-  }
-  for (const line of lines) {
-    const key = Z_INDEX_KEY_MAP[line.z_index ?? `below-lines`]
-    groups[key].push(line)
-  }
-  return groups
-}
-
-// Convert RefLineValue (number | Date | string) to numeric value
-export function normalize_value(value: RefLineValue): number {
-  if (typeof value === `number`) return value
-  if (value instanceof Date) return value.getTime()
-  // Empty/whitespace strings are invalid (Number("") returns 0 silently)
-  if (typeof value === `string` && value.trim() === ``) {
-    console.warn(`Invalid RefLineValue: empty string, defaulting to 0`)
-    return 0
-  }
-  // Try numeric conversion first (handles "42", "3.14", "-5")
-  const num = Number(value)
-  if (!isNaN(num)) return num
-  // Then try as ISO date string (handles "2024-06-15")
-  const parsed = Date.parse(value)
-  if (!isNaN(parsed)) return parsed
-  console.warn(`Invalid RefLineValue: "${value}", defaulting to 0`)
-  return 0
-}
-
-// Normalize a point tuple
-export const normalize_point = (point: [RefLineValue, RefLineValue]): [number, number] => [
-  normalize_value(point[0]),
-  normalize_value(point[1]),
-]
-
-// Clip a line segment to a rectangle using Liang-Barsky algorithm
-// Returns clipped [x1, y1, x2, y2] or null if segment is entirely outside
-function clip_segment_to_rect(
-  p1x: number,
-  p1y: number,
-  p2x: number,
-  p2y: number,
-  x_min: number,
-  x_max: number,
-  y_min: number,
-  y_max: number,
-): [number, number, number, number] | null {
-  const dx = p2x - p1x
-  const dy = p2y - p1y
-
-  // p values represent the direction, q values the signed distance to boundary
-  // Boundaries: left (x_min), right (x_max), bottom (y_min), top (y_max)
-  const p_vals = [-dx, dx, -dy, dy]
-  const q_vals = [p1x - x_min, x_max - p1x, p1y - y_min, y_max - p1y]
-
-  let [t_enter, t_leave] = [0, 1]
-
-  for (let idx = 0; idx < 4; idx++) {
-    if (p_vals[idx] === 0) {
-      // Line parallel to boundary
-      if (q_vals[idx] < 0) return null // Outside and parallel - no intersection
-    } else {
-      const t_val = q_vals[idx] / p_vals[idx]
-      // Entering boundary
-      if (p_vals[idx] < 0) t_enter = Math.max(t_enter, t_val)
-      // Leaving boundary
-      else t_leave = Math.min(t_leave, t_val)
-    }
-  }
-
-  if (t_enter > t_leave) return null // Segment entirely outside
-
-  return [p1x + t_enter * dx, p1y + t_enter * dy, p1x + t_leave * dx, p1y + t_leave * dy]
-}
-
-// Compute the screen coordinates for a reference line
-// Returns [x1, y1, x2, y2] in pixel coordinates, or null if line is not visible
-export function resolve_line_endpoints(
-  ref_line: RefLine,
-  {
-    x_min,
-    x_max,
-    y_min,
-    y_max,
-  }: {
-    x_min: number
-    x_max: number
-    y_min: number
-    y_max: number
-  },
-  {
-    x_scale,
-    x2_scale,
-    y_scale,
-    y2_scale,
-  }: {
-    x_scale: (val: number) => number
-    x2_scale?: (val: number) => number
-    y_scale: (val: number) => number
-    y2_scale?: (val: number) => number
-  },
-): [number, number, number, number] | null {
-  // Determine which scales to use based on axis assignment
-  const active_x_scale = ref_line.x_axis === `x2` && x2_scale ? x2_scale : x_scale
-  const active_y_scale = ref_line.y_axis === `y2` && y2_scale ? y2_scale : y_scale
-
-  // Check if value is within plot bounds (for visibility)
-  const is_x_visible = (x_val: number): boolean => x_val >= x_min && x_val <= x_max
-  const is_y_visible = (y_val: number): boolean => y_val >= y_min && y_val <= y_max
-
-  // Apply span constraints (works for both x and y)
-  const apply_x_span = (x1: number, x2: number) => apply_span(x1, x2, ref_line.x_span)
-  const apply_y_span = (y1: number, y2: number) => apply_span(y1, y2, ref_line.y_span)
-
-  // Relative to data coordinate conversion
-  const to_data_x = (rel: number): number => x_min + rel * (x_max - x_min)
-  const to_data_y = (rel: number): number => y_min + rel * (y_max - y_min)
-
-  let x1_data = 0
-  let y1_data = 0
-  let x2_data = 0
-  let y2_data = 0
-
-  const line_type = ref_line.type
-
-  if (line_type === `horizontal`) {
-    const y_val = normalize_value(ref_line.y)
-    const y_coord = ref_line.coord_mode === `relative` ? to_data_y(y_val) : y_val
-    if (!is_y_visible(y_coord)) return null
-    ;[x1_data, x2_data] = apply_x_span(x_min, x_max)
-    y1_data = y_coord
-    y2_data = y_coord
-  } else if (line_type === `vertical`) {
-    const x_val = normalize_value(ref_line.x)
-    const x_coord = ref_line.coord_mode === `relative` ? to_data_x(x_val) : x_val
-    if (!is_x_visible(x_coord)) return null
-    x1_data = x_coord
-    x2_data = x_coord
-    ;[y1_data, y2_data] = apply_y_span(y_min, y_max)
-  } else if (line_type === `diagonal` || line_type === `line`) {
-    // Get slope/intercept - either from props or computed from points
-    let slope: number
-    let intercept: number
-    let handled_as_vertical = false
-
-    if (ref_line.type === `diagonal`) {
-      slope = ref_line.slope
-      intercept = ref_line.intercept
-    } else {
-      const [p1x, p1y] = normalize_point(ref_line.p1)
-      const [p2x, p2y] = normalize_point(ref_line.p2)
-      const dx = p2x - p1x
-      if (Math.abs(dx) < 1e-10) {
-        // Nearly vertical line - check x-bounds like we do for vertical type
-        if (!is_x_visible(p1x)) return null
-        x1_data = p1x
-        x2_data = p1x
-        ;[y1_data, y2_data] = apply_y_span(y_min, y_max)
-        handled_as_vertical = true
-        slope = 0 // Won't be used
-        intercept = 0
-      } else {
-        slope = (p2y - p1y) / dx
-        intercept = p1y - slope * p1x
-      }
-    }
-
-    if (!handled_as_vertical) {
-      // Clip line to y bounds
-      let x1 = x_min
-      let x2 = x_max
-      let y1 = slope * x_min + intercept
-      let y2 = slope * x_max + intercept
-
-      if (slope === 0) {
-        if (y1 < y_min || y1 > y_max) return null
-      } else {
-        // Clip each endpoint to y bounds
-        const clip_y = (x: number, y: number, bound: number) =>
-          y < y_min || y > y_max ? [(bound - intercept) / slope, bound] : [x, y]
-        ;[x1, y1] = clip_y(x1, y1, y1 < y_min ? y_min : y_max)
-        ;[x2, y2] = clip_y(x2, y2, y2 < y_min ? y_min : y_max)
-        // If both endpoints clipped to same point, line is entirely outside bounds
-        if (x1 === x2 && y1 === y2) return null
-      }
-
-      // Ensure consistent ordering before applying span constraints
-      const [x_lo, x_hi] = x1 <= x2 ? [x1, x2] : [x2, x1]
-      const [y_lo, y_hi] = y1 <= y2 ? [y1, y2] : [y2, y1]
-      ;[x1_data, x2_data] = apply_x_span(x_lo, x_hi)
-      ;[y1_data, y2_data] = apply_y_span(y_lo, y_hi)
-      if (x1_data > x_max || x2_data < x_min) return null
-    }
-  } else if (line_type === `segment`) {
-    const [p1x, p1y] = normalize_point(ref_line.p1)
-    const [p2x, p2y] = normalize_point(ref_line.p2)
-
-    // Determine clipping bounds (span constraints override plot bounds)
-    const clip_x_min = ref_line.x_span?.[0] ?? x_min
-    const clip_x_max = ref_line.x_span?.[1] ?? x_max
-    const clip_y_min = ref_line.y_span?.[0] ?? y_min
-    const clip_y_max = ref_line.y_span?.[1] ?? y_max
-
-    const clipped = clip_segment_to_rect(
-      p1x,
-      p1y,
-      p2x,
-      p2y,
-      clip_x_min,
-      clip_x_max,
-      clip_y_min,
-      clip_y_max,
-    )
-    if (!clipped) return null
-    ;[x1_data, y1_data, x2_data, y2_data] = clipped
-  } else {
-    return null
-  }
-
-  // Convert data coordinates to screen pixels
-  const x1_px = active_x_scale(x1_data)
-  const y1_px = active_y_scale(y1_data)
-  const x2_px = active_x_scale(x2_data)
-  const y2_px = active_y_scale(y2_data)
-
-  // Validate that pixels are finite
-  if (!isFinite(x1_px) || !isFinite(y1_px) || !isFinite(x2_px) || !isFinite(y2_px)) {
-    return null
-  }
-
-  return [x1_px, y1_px, x2_px, y2_px]
-}
-
-interface AnnotationPosition {
-  x: number
-  y: number
-  text_anchor: `start` | `middle` | `end`
-  dominant_baseline: `auto` | `middle` | `hanging`
-  rotation?: number
-}
-
-// Calculate annotation position given line endpoints and annotation config
-export function calculate_annotation_position(
-  x1: number,
-  y1: number,
-  x2: number,
-  y2: number,
-  annotation: {
-    position?: `start` | `center` | `end`
-    side?: `above` | `below` | `left` | `right`
-    offset?: { x?: number; y?: number }
-    gap?: number
-    edge_padding?: number
-    rotate?: boolean
-  },
-): AnnotationPosition {
-  const position = annotation.position ?? `end`
-  const side = annotation.side ?? `above`
-  const offset_x = annotation.offset?.x ?? 0
-  const offset_y = annotation.offset?.y ?? 0
-  const gap = annotation.gap ?? 8 // pixels from line
-  const edge_padding = annotation.edge_padding ?? 4 // pixels from plot edge at start/end
-
-  // Fraction along line: start=0, center=0.5, end=1
-  const frac = position === `start` ? 0 : position === `center` ? 0.5 : 1
-
-  // Calculate base position with edge padding applied along line direction
-  const dx = x2 - x1
-  const dy = y2 - y1
-  const len = Math.sqrt(dx * dx + dy * dy)
-
-  let base_x = x1 + frac * dx
-  let base_y = y1 + frac * dy
-
-  // Apply edge padding to pull text slightly inward from plot boundaries
-  if (len > 0 && position !== `center`) {
-    const dir_x = dx / len
-    const dir_y = dy / len
-    // At 'end', move back toward start; at 'start', move toward end
-    const inward = position === `end` ? -edge_padding : edge_padding
-    base_x += dir_x * inward
-    base_y += dir_y * inward
-  }
-
-  let perp_x = 0
-  let perp_y = 0
-  if (len > 0) {
-    // Perpendicular vector (normalized)
-    const nx = -dy / len
-    const ny = dx / len
-    if (side === `above` || side === `below`) {
-      // In SVG, y increases downward. Flip sign if 'above' and perpendicular points down (ny > 0),
-      // or if 'below' and perpendicular points up (ny <= 0), to ensure offset is in correct direction
-      const sign = (side === `above`) === ny > 0 ? -1 : 1
-      perp_x = sign * nx * gap
-      perp_y = sign * ny * gap
-    } else {
-      // left = perpendicular to the "left" of direction vector, right = opposite
-      const sign = side === `left` ? 1 : -1
-      perp_x = sign * nx * gap
-      perp_y = sign * ny * gap
-    }
-  }
-
-  const final_x = base_x + perp_x + offset_x
-  const final_y = base_y + perp_y + offset_y
-
-  // Text anchor and baseline based on position/side
-  // For left/right sides, anchor is determined by side (text extends away from line)
-  // For above/below sides, anchor is determined by position along line
-  let text_anchor: `start` | `middle` | `end`
-  if (side === `left`) {
-    text_anchor = `end` // text ends at gap point, extends left
-  } else if (side === `right`) {
-    text_anchor = `start` // text starts at gap point, extends right
-  } else {
-    text_anchor = ({ start: `start`, end: `end`, center: `middle` }[position] ?? `middle`) as
-      | `start`
-      | `middle`
-      | `end`
-  }
-  const dominant_baseline = ({
-    above: `auto`,
-    below: `hanging`,
-    left: `middle`,
-    right: `middle`,
-  }[side] ?? `middle`) as `auto` | `middle` | `hanging`
-
-  // Calculate rotation if needed (keep text readable)
-  let rotation: number | undefined
-  if (annotation.rotate && len > 0) {
-    rotation = Math.atan2(dy, dx) * (180 / Math.PI)
-    if (rotation > 90) rotation -= 180
-    else if (rotation < -90) rotation += 180
-  }
-
-  return { x: final_x, y: final_y, text_anchor, dominant_baseline, rotation }
-}
-
-export interface Scene3DParams {
-  scene_x: number
-  scene_y: number
-  scene_z: number
-  x_range: [number, number]
-  y_range: [number, number]
-  z_range: [number, number]
-}
-
-/** Apply span constraints or use full range as fallback */
-export const span_or = (
-  span: [number | null, number | null] | undefined,
-  range: [number, number],
-): [number, number] => [span?.[0] ?? range[0], span?.[1] ?? range[1]]
-
-// Normalize a data value to scene coordinates (centered around 0)
-export function normalize_to_scene(
-  value: number,
-  [min_val, max_val]: [number, number],
-  scene_size: number,
-): number {
-  const range = max_val - min_val
-  // When range is zero (min === max), return center position
-  if (range === 0) return 0
-  return ((value - min_val) / range - 0.5) * scene_size
-}
-
-// Create a function to convert user data coordinates to Three.js coordinates
-// Note: In Three.js, Y is vertical. We map:
-// - user X → Three.js X (horizontal)
-// - user Y → Three.js Z (depth/horizontal)
-// - user Z → Three.js Y (vertical)
-export function create_to_threejs(
-  params: Scene3DParams,
-): (user_x: number, user_y: number, user_z: number) => { x: number; y: number; z: number } {
-  const { scene_x, scene_y, scene_z, x_range, y_range, z_range } = params
-  return (user_x: number, user_y: number, user_z: number) => ({
-    x: normalize_to_scene(user_x, x_range, scene_x),
-    y: normalize_to_scene(user_z, z_range, scene_z), // z → Y
-    z: normalize_to_scene(user_y, y_range, scene_y), // y → Z
-  })
-}