waveform-analysis 0.1.74 → 0.1.76

package/src/components/animation/geometry.ts

@@ -0,0 +1,148 @@
+import type { ScaleLinear } from 'd3'
+import type { WaveformPoint, WaveformLineType } from '@/types'
+import type { TrackSeriesPath } from '../core/types'
+import type { NumericGeometry } from '@/animation/types'
+import { resolveWaveformPointErrors } from '@/core'
+import { createPathBuffer } from './pathBuffer'
+
+// Weak ownership releases cached SVG strings and point arrays with their numeric snapshots.
+const projections = new WeakMap<
+  NumericGeometry,
+  {
+    path: TrackSeriesPath
+    x: ScaleLinear<number, number>
+    y: ScaleLinear<number, number>
+    result: TrackSeriesPath
+  }
+>()
+const dirty = new WeakSet<NumericGeometry>()
+const transitions = new WeakMap<NumericGeometry, WeakMap<NumericGeometry, NumericGeometry>>()
+const snapshots = new WeakMap<TrackSeriesPath, NumericGeometry>()
+const pathBuffers = new WeakMap<WaveformPoint[], ReturnType<typeof createPathBuffer>>()
+
+/** Private presentation buffer; the source/target snapshots and business points stay immutable. */
+export function interpolateGeometry(from: NumericGeometry, to: NumericGeometry, p: number) {
+  let targets = transitions.get(from)
+  if (!targets) transitions.set(from, (targets = new WeakMap()))
+  let result = targets.get(to)
+  if (!result) {
+    result = Object.fromEntries(
+      Object.entries(to).map(([key, rows]) => [
+        key,
+        // oxlint-disable-next-line unicorn/no-new-array -- Allocate fixed-length interpolation output.
+        (rows as number[][]).map((row) => new Array<number>(row.length)),
+      ]),
+    )
+    targets.set(to, result)
+  }
+  for (const key of Object.keys(to)) {
+    const a = from[key] as number[][],
+      b = to[key] as number[][],
+      output = result[key] as number[][]
+    for (let i = 0; i < b.length; i++)
+      for (let j = 0; j < b[i].length; j++) {
+        const value = p === 0 ? a[i][j] : p === 1 ? b[i][j] : (1 - p) * a[i][j] + p * b[i][j]
+        if (!Number.isFinite(value)) throw new RangeError('Nonfinite presentation geometry')
+        output[i][j] = value
+      }
+  }
+  dirty.add(result)
+  return result
+}
+
+export function generateWaveformPath(
+  points: WaveformPoint[],
+  type: WaveformLineType,
+  x: ScaleLinear<number, number>,
+  y: ScaleLinear<number, number>,
+): string | null {
+  if (!points.length || type === 'none') return null
+  let buffer = pathBuffers.get(points)
+  if (!buffer) pathBuffers.set(points, (buffer = createPathBuffer(x, y)))
+  return buffer(points, type, x, y)
+}
+function values(points: WaveformPoint[]): number[][] {
+  return points.map((point) => {
+    const error = resolveWaveformPointErrors(point)
+    return [point.x, point.y, error.lower, error.upper]
+  })
+}
+export function captureGeometry(
+  path: TrackSeriesPath,
+  x: ScaleLinear<number, number>,
+): NumericGeometry {
+  let geometry = snapshots.get(path)
+  if (!geometry) {
+    let line: number[][] | undefined, points: number[][] | undefined, errors: number[][] | undefined
+    // Layout paths are immutable. Static/enter rendering uses their existing SVG and does not
+    // need numeric copies; materialize a private endpoint only when an update reads it.
+    geometry = {
+      get line() {
+        return (line ??= values(path.lineRenderPoints ?? []))
+      },
+      get points() {
+        return (points ??= values(path.pointRenderPoints))
+      },
+      get errors() {
+        return (errors ??= values(path.errorBarRenderPoints))
+      },
+    }
+    snapshots.set(path, geometry)
+  }
+  projections.set(geometry, { path, x, y: path.yScale, result: path })
+  return geometry
+}
+function points(values: number[][], buffer: WaveformPoint[] = []): WaveformPoint[] {
+  for (let i = 0; i < values.length; i++) {
+    // Initialize all numeric fields together; overwrite before publishing the private buffer.
+    const point = buffer[i] ?? (buffer[i] = { x: NaN, y: NaN, lowerError: NaN, upperError: NaN })
+    const row = values[i]
+    point.x = row[0]
+    point.y = row[1]
+    point.lowerError = row[2]
+    point.upperError = row[3]
+  }
+  buffer.length = values.length
+  return buffer
+}
+export function projectGeometry(
+  path: TrackSeriesPath,
+  geometry: NumericGeometry,
+  x: ScaleLinear<number, number>,
+  y: ScaleLinear<number, number>,
+): TrackSeriesPath {
+  const cached = projections.get(geometry)
+  if (!dirty.has(geometry) && cached?.path === path && cached.x === x && cached.y === y)
+    return cached.result
+  const buffer = cached?.path === path && cached.result !== path ? cached.result : undefined
+  const linePoints = points(geometry.line as number[][], buffer?.lineRenderPoints)
+  const result = {
+    ...path,
+    lineRenderPoints: linePoints,
+    path: generateWaveformPath(linePoints, path.series.lineType, x, y),
+    pointRenderPoints: points(geometry.points as number[][], buffer?.pointRenderPoints),
+    errorBarRenderPoints: points(geometry.errors as number[][], buffer?.errorBarRenderPoints),
+    yScale: y,
+  }
+  projections.set(geometry, { path, x, y, result })
+  dirty.delete(geometry)
+  return result
+}
+export function compatibleGeometry(
+  a: TrackSeriesPath,
+  b: TrackSeriesPath,
+  from: NumericGeometry,
+  to: NumericGeometry,
+): boolean {
+  if (
+    a.series.lineType !== b.series.lineType ||
+    a.series.pointType !== b.series.pointType ||
+    a.series.errorBar.visible !== b.series.errorBar.visible
+  )
+    return false
+  return ['line', 'points', 'errors'].every((key) => {
+    const old = from[key] as number[][],
+      next = to[key] as number[][]
+    return old.length === next.length && old.every((point, i) => point[0] === next[i][0])
+  })
+}

package/src/components/animation/paginationPresentation.ts

@@ -0,0 +1,114 @@
+import { shallowRef, type ComputedRef } from 'vue'
+import type { AnimationContext } from './context'
+import type { ResolvedAnimationProps } from './config'
+import type { WaveformAnimationController } from '@/animation/WaveformAnimationController'
+import { clampProgress } from '@/animation/presets/shared'
+import { chartExportOptions } from '../controls/chartExportOptions'
+
+/** A single owner-scoped fade; it holds no old page geometry. */
+export function createPaginationPresentation(
+  context: AnimationContext,
+  controller: WaveformAnimationController,
+  config: ComputedRef<ResolvedAnimationProps>,
+  effective: ComputedRef<boolean>,
+  commit: () => void,
+) {
+  const opacity = shallowRef(1)
+  const key = { kind: 'custom', id: 'pagination', scope: 'update' } as const
+  let sequence = 0
+  let request: { page: number; version: number; environment: string; started: boolean } | undefined
+  const environment = () =>
+    JSON.stringify({
+      options: Object.fromEntries(
+        Object.entries(chartExportOptions(context.props)).filter(
+          ([name]) => !['annotations', 'annotationsVisible'].includes(name),
+        ),
+      ),
+      size: context.containerSize.value,
+      hidden: context.props.hiddenSeriesIds,
+      presentation: context.props.presentationMode,
+    })
+  function reset() {
+    request = undefined
+    opacity.value = 1
+  }
+  function cancel() {
+    controller.cancel(key)
+    reset()
+  }
+  function requestPage(page: number) {
+    cancel()
+    controller.finishAll()
+    if (!effective.value || !config.value.animationUpdate.enabled) return
+    request = { page, version: ++sequence, environment: environment(), started: false }
+    if (config.value.animationUpdate.duration > 0) opacity.value = 0
+  }
+  function reconcile(dataChanged: boolean) {
+    const current = request
+    if (!current) return false
+    if (
+      dataChanged ||
+      current.page !== context.currentPage.value ||
+      current.environment !== environment() ||
+      !effective.value ||
+      !config.value.animationUpdate.enabled
+    ) {
+      controller.finishAll()
+      reset()
+      return true
+    }
+    if (!current.started && config.value.animationUpdate.duration === 0) opacity.value = 1
+    commit()
+    if (context.sampling.state.value === 'pending' || !context.layoutReady.value) return true
+    if (context.sampling.state.value !== 'success') {
+      controller.finishAll()
+      reset()
+      return true
+    }
+    if (current.started) return true
+    const ids = context.tracks.value.flatMap((track) =>
+      track.width > 0 && track.height > 0
+        ? track.seriesList
+            .filter((series) => (series.source?.length ?? series.points.length) > 0)
+            .map((series) => series.id)
+        : [],
+    )
+    if (!ids.length) {
+      reset()
+      return true
+    }
+    current.started = true
+    const options = config.value.animationUpdate
+    const notify = (callback?: () => void) => ids.forEach(() => callback?.())
+    controller.animate(key, {
+      duration: options.duration,
+      easing: options.easing,
+      force: true,
+      initialize: () => {
+        opacity.value = options.duration > 0 ? 0 : 1
+      },
+      during: (progress, frame) => {
+        if (request?.version === current.version)
+          opacity.value = frame.terminal ? 1 : clampProgress(progress)
+      },
+      done: () => {
+        if (request?.version === current.version) reset()
+        notify(options.onComplete)
+      },
+      aborted: () => {
+        if (request?.version === current.version) reset()
+        notify(options.onAbort)
+      },
+    })
+    return true
+  }
+  function wrapPagination(goToPage: (page: number) => void, count: ComputedRef<number>) {
+    return (page: number) => {
+      const target = Math.min(count.value, Math.max(1, Math.floor(page)))
+      if (target === context.currentPage.value) return
+      requestPage(target)
+      goToPage(page)
+    }
+  }
+  return { opacity, reset, cancel, reconcile, wrapPagination, active: () => !!request }
+}

package/src/components/animation/pathBuffer.ts

@@ -0,0 +1,61 @@
+import { line, curveLinear, curveStep, curveStepBefore, curveStepAfter } from 'd3'
+import type { ScaleLinear } from 'd3'
+import type { WaveformPoint, WaveformLineType } from '@/types'
+
+let decoder: TextDecoder | undefined
+
+/** Stable D3 accessors/context keep their feedback across frames; storage is private to points. */
+export function createPathBuffer(x: ScaleLinear<number, number>, y: ScaleLinear<number, number>) {
+  let xScale = x,
+    yScale = y,
+    type: WaveformLineType | undefined
+  let bytes = new Uint8Array(1024),
+    length = 0
+  const append = (text: string) => {
+    if (length + text.length > bytes.length) {
+      const next = new Uint8Array(Math.max(bytes.length * 2, length + text.length))
+      next.set(bytes)
+      bytes = next
+    }
+    for (let i = 0; i < text.length; i++) bytes[length++] = text.charCodeAt(i)
+  }
+  const coordinate = (value: number) => append(String(Math.round(value * 1000) / 1000))
+  const point = (command: string, x: number, y: number) => {
+    append(command)
+    coordinate(x)
+    append(',')
+    coordinate(y)
+  }
+  const generator = line<WaveformPoint>()
+    .x((point) => xScale(point.x))
+    .y((point) => yScale(point.y))
+    .context({
+      moveTo: (x: number, y: number) => point('M', x, y),
+      lineTo: (x: number, y: number) => point('L', x, y),
+      closePath: () => append('Z'),
+    } as unknown as CanvasRenderingContext2D)
+  return (
+    points: WaveformPoint[],
+    nextType: WaveformLineType,
+    x: ScaleLinear<number, number>,
+    y: ScaleLinear<number, number>,
+  ): string => {
+    xScale = x
+    yScale = y
+    if (type !== nextType) {
+      generator.curve(
+        nextType === 'step-start'
+          ? curveStepBefore
+          : nextType === 'step-middle'
+            ? curveStep
+            : nextType === 'step-end' || nextType === 'step-after'
+              ? curveStepAfter
+              : curveLinear,
+      )
+      type = nextType
+    }
+    length = 0
+    generator(points)
+    return (decoder ??= new TextDecoder()).decode(bytes.subarray(0, length))
+  }
+}

package/src/components/animation/trackPresentation.ts

@@ -0,0 +1,172 @@
+import type { TrackLayout, TrackSeriesPath } from '../core/types'
+import type { WaveformAnnotation } from '@/types'
+import type { NumericGeometry } from '@/animation/types'
+import {
+  captureGeometry,
+  compatibleGeometry,
+  projectGeometry,
+  interpolateGeometry,
+} from './geometry'
+import { interpolateValue } from '@/animation/core/values'
+import { clampProgress, validDomain } from '@/animation/presets/shared'
+import type { ScaleLinear } from 'd3'
+
+function presentationScale(scale: ScaleLinear<number, number>, domain: [number, number]) {
+  const current = scale.domain()
+  return current[0] === domain[0] && current[1] === domain[1] ? scale : scale.copy().domain(domain)
+}
+
+interface AnchorValue {
+  seriesId: string
+  annotationY: number
+  x: number
+  y: number
+}
+interface SeriesGeometry {
+  path: TrackSeriesPath
+  values: NumericGeometry
+  old?: { path: TrackSeriesPath; values: NumericGeometry }
+  opacity: number
+}
+export interface TrackPresentation {
+  target: TrackLayout
+  series: Map<string, SeriesGeometry>
+  xDomain: [number, number]
+  yDomains: [number, number][]
+  anchors: Map<string, AnchorValue>
+  clips: Map<string, { id: string; x: number; width: number }>
+}
+export function staticTrack(
+  track: TrackLayout,
+  annotations: WaveformAnnotation[],
+  previous?: TrackPresentation,
+  refreshAnchors = false,
+): TrackPresentation {
+  const anchors = new Map<string, AnchorValue>()
+  for (const annotation of annotations) {
+    const series = track.seriesList.find((series) => series.id === annotation.seriesId)
+    if (!series || (series.source?.length ?? series.points.length) === 0) continue
+    const cached = previous?.anchors.get(annotation.id)
+    const point = refreshAnchors ? series.source?.nearestPoint(annotation.x) : undefined
+    if (refreshAnchors && !point) continue
+    anchors.set(annotation.id, {
+      seriesId: series.id,
+      annotationY: annotation.y,
+      x: annotation.x,
+      y:
+        point?.y ??
+        (cached?.x === annotation.x && cached.annotationY === annotation.y
+          ? cached.y
+          : annotation.y),
+    })
+  }
+  return {
+    target: track,
+    series: new Map(
+      track.seriesPaths.map((path) => [
+        path.series.id,
+        { path, values: captureGeometry(path, track.xScale), opacity: 1 },
+      ]),
+    ),
+    xDomain: track.xScale.domain() as [number, number],
+    yDomains: track.yAxes.map((axis) => axis.scale.domain() as [number, number]),
+    anchors,
+    clips: new Map(),
+  }
+}
+function domain(from: [number, number], to: [number, number], p: number): [number, number] {
+  if (!validDomain(to)) return from
+  const value = interpolateValue(from, to, clampProgress(p)) as [number, number]
+  return validDomain(value) ? value : to
+}
+export function hasThirdGeometry(from: TrackPresentation): boolean {
+  return [...from.series.values()].some((series) => !!series.old)
+}
+export function transitionTrack(
+  from: TrackPresentation,
+  to: TrackPresentation,
+  p: number,
+  terminal: boolean,
+): TrackPresentation {
+  if (terminal) return to
+  const series = new Map<string, SeriesGeometry>()
+  for (const [id, next] of to.series) {
+    const previous = from.series.get(id)
+    if (!previous) {
+      series.set(id, next)
+      continue
+    }
+    const compatible = compatibleGeometry(previous.path, next.path, previous.values, next.values)
+    series.set(
+      id,
+      compatible
+        ? {
+            ...next,
+            values: interpolateGeometry(previous.values, next.values, p),
+          }
+        : {
+            ...next,
+            old: { path: previous.path, values: previous.values },
+            opacity: clampProgress(p),
+          },
+    )
+  }
+  const anchors = new Map<string, AnchorValue>()
+  for (const [id, next] of to.anchors) {
+    const previous = from.anchors.get(id)
+    anchors.set(
+      id,
+      previous && !series.get(next.seriesId)?.old
+        ? {
+            seriesId: next.seriesId,
+            annotationY: next.annotationY,
+            x: (1 - p) * previous.x + p * next.x,
+            y: (1 - p) * previous.y + p * next.y,
+          }
+        : next,
+    )
+  }
+  return {
+    ...to,
+    series,
+    anchors,
+    xDomain: domain(from.xDomain, to.xDomain, p),
+    yDomains: to.yDomains.map((target, i) => domain(from.yDomains[i] ?? target, target, p)),
+    clips: to.clips,
+  }
+}
+export function projectTrack(state: TrackPresentation): TrackLayout {
+  const target = state.target
+  const xScale = presentationScale(target.xScale, state.xDomain)
+  const projectedAxes = target.yAxes.map((axis, index) => {
+    const scale = presentationScale(axis.scale, state.yDomains[index])
+    return scale === axis.scale ? axis : { ...axis, scale }
+  })
+  const yAxes = projectedAxes.every((axis, index) => axis === target.yAxes[index])
+    ? target.yAxes
+    : projectedAxes
+  const seriesPaths: TrackSeriesPath[] = []
+  for (const [id, series] of state.series) {
+    const y = yAxes[series.path.yAxisIndex]?.scale ?? target.yScale
+    if (series.old)
+      seriesPaths.push({
+        ...projectGeometry(series.old.path, series.old.values, xScale, y),
+        presentationKey: `${id}:old`,
+        opacity: 1 - series.opacity,
+      })
+    seriesPaths.push({
+      ...projectGeometry(series.path, series.values, xScale, y),
+      presentationKey: id,
+      opacity: series.opacity,
+      animationClip: state.clips.get(id),
+    })
+  }
+  return {
+    ...target,
+    xScale,
+    yScale: yAxes[0]?.scale ?? target.yScale,
+    yAxes,
+    seriesPaths,
+    path: seriesPaths[0]?.path ?? null,
+  }
+}