waveform-analysis 0.1.47 → 0.1.50

package/src/core/rendering.ts

@@ -12,6 +12,7 @@ export {
   DEFAULT_WAVEFORM_RENDERING_OPTIONS,
   resolveWaveformRenderingOptions,
   type ResolvedWaveformRenderingOptions,
+  type ResolvedWaveformSamplingOptions,
 } from './renderingOptions'
 
 const pointBisector = bisector((point: WaveformPoint) => point.x)
@@ -23,6 +24,8 @@ interface PointSeriesSource {
 
 interface SeriesRenderSelectionOptions {
   lineVisible: boolean
+  /** A current Worker result used only for the SVG line. */
+  linePointOverride?: WaveformPoint[]
   pointVisible: boolean
   errorBarVisible: boolean
   hasErrorPoints: boolean
@@ -84,6 +87,34 @@ function selectRenderablePointsInRange(
   })
 }
 
+function shouldDeferLineSampling(
+  visibleCount: number,
+  options: ResolvedWaveformRenderingOptions,
+): boolean {
+  if (options.sampling.mode === 'wasm') return true
+  return options.sampling.mode === 'auto' && visibleCount > options.sampling.autoThreshold
+}
+
+function selectSamplingPlaceholderPoints(
+  points: WaveformPoint[],
+  range: VisiblePointRange,
+  width: number,
+  options: ResolvedWaveformRenderingOptions,
+): WaveformPoint[] {
+  const start = Math.max(0, range.start - 1)
+  const end = Math.min(points.length, range.end + 1)
+  const count = end - start
+  if (count <= 0) return []
+  if (options.sampling.strategy === 'none') return points.slice(start, end)
+  const target = Math.max(1, Math.floor(width * options.sampling.maxPointsPerPixel))
+  if (count <= target) return points.slice(start, end)
+  if (target === 1) return [points[start]!]
+  return Array.from({ length: target }, (_, index) => {
+    const offset = Math.round((index * (count - 1)) / (target - 1))
+    return points[start + offset]!
+  })
+}
+
 /**
  * Select the visible source range and preserve first/min/max/last values in each X bucket.
  * Source points must be sorted by X.
@@ -247,7 +278,10 @@ export function selectSeriesRenderPoints(
   }
   const range = resolveVisiblePointRange(points, domain)
   const linePoints = selection.lineVisible
-    ? selectRenderablePointsInRange(points, range, domain, width, rendering)
+    ? (selection.linePointOverride ??
+      (shouldDeferLineSampling(range.end - range.start, rendering)
+        ? selectSamplingPlaceholderPoints(points, range, width, rendering)
+        : selectRenderablePointsInRange(points, range, domain, width, rendering)))
     : []
   const errorBarVisible = selection.errorBarVisible && selection.hasErrorPoints
   if (selection.pointVisible && errorBarVisible) {

package/src/core/renderingOptions.ts

@@ -1,4 +1,19 @@
-import type { WaveformRenderingOptions } from '@/types'
+import type {
+  WaveformRenderingOptions,
+  WaveformSamplingMode,
+  WaveformSamplingOptions,
+  WaveformSamplingStrategy,
+} from '@/types'
+
+export interface ResolvedWaveformSamplingOptions {
+  mode: WaveformSamplingMode
+  autoThreshold: number
+  autoHysteresis: number
+  strategy: WaveformSamplingStrategy
+  maxPointsPerPixel: number
+  rawPointLimit: number
+  wasmFailureFallback: 'error' | 'javascript'
+}
 
 export interface ResolvedWaveformRenderingOptions {
   downsample: boolean
@@ -6,6 +21,7 @@ export interface ResolvedWaveformRenderingOptions {
   maxPointsPerPixel: number
   pointMinSpacing: number
   errorBarMinSpacing: number
+  sampling: ResolvedWaveformSamplingOptions
 }
 
 export const DEFAULT_WAVEFORM_RENDERING_OPTIONS: ResolvedWaveformRenderingOptions = {
@@ -14,32 +30,125 @@ export const DEFAULT_WAVEFORM_RENDERING_OPTIONS: ResolvedWaveformRenderingOption
   maxPointsPerPixel: 4,
   pointMinSpacing: 10,
   errorBarMinSpacing: 12,
+  sampling: {
+    mode: 'auto',
+    autoThreshold: 1_000,
+    autoHysteresis: 0,
+    strategy: 'peak',
+    maxPointsPerPixel: 4,
+    rawPointLimit: 100_000,
+    wasmFailureFallback: 'error',
+  },
+}
+
+const samplingModes: readonly WaveformSamplingMode[] = ['auto', 'wasm', 'raw']
+const samplingStrategies: readonly WaveformSamplingStrategy[] = [
+  'auto',
+  'none',
+  'peak',
+  'lttb',
+  'average',
+  'min',
+  'max',
+  'minmax',
+  'sum',
+]
+
+function isSamplingMode(value: unknown): value is WaveformSamplingMode {
+  return typeof value === 'string' && samplingModes.includes(value as WaveformSamplingMode)
+}
+
+function isSamplingStrategy(value: unknown): value is WaveformSamplingStrategy {
+  return typeof value === 'string' && samplingStrategies.includes(value as WaveformSamplingStrategy)
+}
+
+function resolveFiniteInteger(value: unknown, minimum: number, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= minimum
+    ? Math.floor(value)
+    : fallback
+}
+
+function resolvePositiveNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback
+}
+
+function resolveNonNegativeNumber(value: number, fallback: number): number {
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+function resolveSamplingOptions(
+  options: WaveformSamplingOptions | undefined,
+  legacyDownsample: boolean | undefined,
+  legacyMaxPointsPerPixel: number,
+): ResolvedWaveformSamplingOptions {
+  const mode = isSamplingMode(options?.mode)
+    ? options.mode
+    : legacyDownsample === false
+      ? 'raw'
+      : DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.mode
+  const maxPointsPerPixel = resolvePositiveNumber(
+    options?.maxPointsPerPixel,
+    legacyMaxPointsPerPixel,
+  )
+  return {
+    mode,
+    autoThreshold: resolveFiniteInteger(
+      options?.autoThreshold,
+      1,
+      DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.autoThreshold,
+    ),
+    autoHysteresis: resolveFiniteInteger(
+      options?.autoHysteresis,
+      0,
+      DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.autoHysteresis,
+    ),
+    strategy: isSamplingStrategy(options?.strategy)
+      ? options.strategy
+      : DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.strategy,
+    maxPointsPerPixel,
+    rawPointLimit: resolveFiniteInteger(
+      options?.rawPointLimit,
+      1,
+      DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.rawPointLimit,
+    ),
+    wasmFailureFallback:
+      options?.wasmFailureFallback === 'javascript' || options?.wasmFailureFallback === 'error'
+        ? options.wasmFailureFallback
+        : DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.wasmFailureFallback,
+  }
 }
 
 export function resolveWaveformRenderingOptions(
   options?: WaveformRenderingOptions,
 ): ResolvedWaveformRenderingOptions {
   const threshold = Number(options?.downsampleThreshold)
-  const pointsPerPixel = Number(options?.maxPointsPerPixel)
+  const legacyMaxPointsPerPixel = Number(options?.maxPointsPerPixel)
   const pointMinSpacing = Number(options?.pointMinSpacing)
   const errorBarMinSpacing = Number(options?.errorBarMinSpacing)
+  const resolvedLegacyMaxPointsPerPixel =
+    Number.isFinite(legacyMaxPointsPerPixel) && legacyMaxPointsPerPixel > 0
+      ? legacyMaxPointsPerPixel
+      : DEFAULT_WAVEFORM_RENDERING_OPTIONS.maxPointsPerPixel
+  const sampling = resolveSamplingOptions(
+    options?.sampling,
+    typeof options?.downsample === 'boolean' ? options.downsample : undefined,
+    resolvedLegacyMaxPointsPerPixel,
+  )
   return {
-    downsample: options?.downsample ?? DEFAULT_WAVEFORM_RENDERING_OPTIONS.downsample,
+    downsample: sampling.mode !== 'raw',
     downsampleThreshold:
       Number.isFinite(threshold) && threshold >= 2
         ? Math.floor(threshold)
         : DEFAULT_WAVEFORM_RENDERING_OPTIONS.downsampleThreshold,
-    maxPointsPerPixel:
-      Number.isFinite(pointsPerPixel) && pointsPerPixel > 0
-        ? pointsPerPixel
-        : DEFAULT_WAVEFORM_RENDERING_OPTIONS.maxPointsPerPixel,
-    pointMinSpacing:
-      Number.isFinite(pointMinSpacing) && pointMinSpacing >= 0
-        ? pointMinSpacing
-        : DEFAULT_WAVEFORM_RENDERING_OPTIONS.pointMinSpacing,
-    errorBarMinSpacing:
-      Number.isFinite(errorBarMinSpacing) && errorBarMinSpacing >= 0
-        ? errorBarMinSpacing
-        : DEFAULT_WAVEFORM_RENDERING_OPTIONS.errorBarMinSpacing,
+    maxPointsPerPixel: sampling.maxPointsPerPixel,
+    pointMinSpacing: resolveNonNegativeNumber(
+      pointMinSpacing,
+      DEFAULT_WAVEFORM_RENDERING_OPTIONS.pointMinSpacing,
+    ),
+    errorBarMinSpacing: resolveNonNegativeNumber(
+      errorBarMinSpacing,
+      DEFAULT_WAVEFORM_RENDERING_OPTIONS.errorBarMinSpacing,
+    ),
+    sampling,
   }
 }

package/src/core/samplingReference.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+
+import type { WaveformPoint } from '../types'
+import {
+  sampleWaveformReference,
+  type ReferenceSamplingStrategy,
+  type SourceIndexSamplingResult,
+} from './samplingReference'
+import {
+  REFERENCE_AGGREGATE_VECTORS,
+  REFERENCE_SAMPLING_POINTS,
+  REFERENCE_SOURCE_INDEX_VECTORS,
+} from './samplingReferenceVectors'
+
+function indexes(strategy: Exclude<ReferenceSamplingStrategy, 'average' | 'sum'>, target: number) {
+  const result = sampleWaveformReference({
+    points: REFERENCE_SAMPLING_POINTS,
+    strategy,
+    targetPointCount: target,
+  })
+  expect(result.kind).toBe('source-indexes')
+  return Array.from((result as SourceIndexSamplingResult).sourceIndexes)
+}
+
+describe('sampleWaveformReference', () => {
+  it('locks the source-index strategy vectors', () => {
+    for (const vector of REFERENCE_SOURCE_INDEX_VECTORS) {
+      expect(indexes(vector.strategy, vector.targetPointCount)).toEqual(
+        vector.expectedSourceIndexes,
+      )
+    }
+  })
+
+  it('locks the aggregate bucket and synthesized-X semantics', () => {
+    for (const vector of REFERENCE_AGGREGATE_VECTORS) {
+      const result = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS,
+        strategy: vector.strategy,
+        targetPointCount: vector.targetPointCount,
+      })
+
+      expect(result).toMatchObject({ kind: 'aggregates', validPointCount: 8 })
+      expect(Array.from(result.kind === 'aggregates' ? result.x : [])).toEqual(vector.expectedX)
+      expect(Array.from(result.kind === 'aggregates' ? result.y : [])).toEqual(vector.expectedY)
+    }
+  })
+
+  it('uses the earliest point for equal extrema and removes duplicate peak entries', () => {
+    const tied = [
+      { x: 0, y: 0 },
+      { x: 1, y: -5 },
+      { x: 2, y: -5 },
+      { x: 3, y: 5 },
+      { x: 4, y: 5 },
+      { x: 5, y: 0 },
+      { x: 6, y: 0 },
+    ]
+
+    const minmax = sampleWaveformReference({
+      points: tied,
+      strategy: 'minmax',
+      targetPointCount: 4,
+    })
+    const peak = sampleWaveformReference({ points: tied, strategy: 'peak', targetPointCount: 6 })
+
+    expect(Array.from(minmax.kind === 'source-indexes' ? minmax.sourceIndexes : [])).toEqual([
+      0, 1, 3, 6,
+    ])
+    expect(Array.from(peak.kind === 'source-indexes' ? peak.sourceIndexes : [])).toEqual([
+      0, 1, 3, 5, 6,
+    ])
+  })
+
+  it('filters invalid points, stably orders X, and returns indexes into the original input', () => {
+    const input: WaveformPoint[] = [
+      { x: 2, y: 20 },
+      { x: Number.NaN, y: 99 },
+      { x: 1, y: 10 },
+      { x: 1, y: 11 },
+      { x: 3, y: Number.POSITIVE_INFINITY },
+    ]
+    const result = sampleWaveformReference({ points: input, strategy: 'none', targetPointCount: 1 })
+
+    expect(result).toMatchObject({ inputPointCount: 5, validPointCount: 3, kind: 'source-indexes' })
+    expect(Array.from(result.kind === 'source-indexes' ? result.sourceIndexes : [])).toEqual([
+      2, 3, 0,
+    ])
+    expect(input).toEqual([
+      { x: 2, y: 20 },
+      { x: Number.NaN, y: 99 },
+      { x: 1, y: 10 },
+      { x: 1, y: 11 },
+      { x: 3, y: Number.POSITIVE_INFINITY },
+    ])
+  })
+
+  it('defines empty, short, and low-target behavior without exceeding the target', () => {
+    const strategies: ReferenceSamplingStrategy[] = [
+      'none',
+      'peak',
+      'lttb',
+      'average',
+      'min',
+      'max',
+      'minmax',
+      'sum',
+    ]
+    for (const strategy of strategies) {
+      const empty = sampleWaveformReference({ points: [], strategy, targetPointCount: 3 })
+      expect(empty.kind === 'aggregates' ? empty.x : empty.sourceIndexes).toHaveLength(0)
+
+      const short = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS.slice(0, 2),
+        strategy,
+        targetPointCount: 10,
+      })
+      expect(short.kind === 'aggregates' ? short.x : short.sourceIndexes).toHaveLength(2)
+    }
+
+    expect(indexes('lttb', 2)).toEqual([0, 7])
+    expect(indexes('minmax', 3)).toEqual([0, 7])
+    expect(indexes('peak', 6)).toHaveLength(5)
+  })
+})

package/src/core/samplingReference.ts

@@ -0,0 +1,243 @@
+import type { WaveformPoint } from '../types'
+
+/** Sampling algorithms that can be implemented equivalently by the future WASM core. */
+export type ReferenceSamplingStrategy =
+  'none' | 'peak' | 'lttb' | 'average' | 'min' | 'max' | 'minmax' | 'sum'
+
+/**
+ * A pure TypeScript reference request. Source indexes in the result address the original
+ * `points` array, after filtering non-finite points and applying a stable ascending-X order.
+ */
+export interface ReferenceSamplingRequest {
+  points: readonly WaveformPoint[]
+  strategy: ReferenceSamplingStrategy
+  targetPointCount: number
+}
+
+interface ReferenceSamplingResultBase {
+  strategy: ReferenceSamplingStrategy
+  inputPointCount: number
+  validPointCount: number
+}
+
+/** A result made of real points from the input sequence. */
+export interface SourceIndexSamplingResult extends ReferenceSamplingResultBase {
+  kind: 'source-indexes'
+  sourceIndexes: Uint32Array
+}
+
+/** A result whose points are synthesized from a contiguous source bucket. */
+export interface AggregateSamplingResult extends ReferenceSamplingResultBase {
+  kind: 'aggregates'
+  x: Float64Array
+  y: Float64Array
+}
+
+export type ReferenceSamplingResult = SourceIndexSamplingResult | AggregateSamplingResult
+
+interface IndexedPoint {
+  sourceIndex: number
+  x: number
+  y: number
+}
+
+function normalizedPoints(points: readonly WaveformPoint[]): IndexedPoint[] {
+  const result: IndexedPoint[] = []
+  let ordered = true
+  let previousX = Number.NEGATIVE_INFINITY
+
+  for (let sourceIndex = 0; sourceIndex < points.length; sourceIndex += 1) {
+    const point = points[sourceIndex]
+    if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) continue
+    if (point.x < previousX) ordered = false
+    previousX = point.x
+    result.push({ sourceIndex, x: point.x, y: point.y })
+  }
+
+  // ES2019 guarantees stable Array#sort, preserving duplicate-X source order.
+  if (!ordered) result.sort((left, right) => left.x - right.x)
+  return result
+}
+
+function targetCount(value: number, pointCount: number) {
+  if (pointCount === 0) return 0
+  if (!Number.isFinite(value)) return pointCount
+  return Math.min(pointCount, Math.max(1, Math.floor(value)))
+}
+
+function bucketBounds(bucket: number, bucketCount: number, start: number, end: number) {
+  const span = end - start
+  return {
+    start: start + Math.floor((bucket * span) / bucketCount),
+    end: start + Math.floor(((bucket + 1) * span) / bucketCount),
+  }
+}
+
+function addUniqueIndex(indexes: number[], index: number) {
+  if (indexes[indexes.length - 1] !== index) indexes.push(index)
+}
+
+function withEndpoints(points: IndexedPoint[], target: number, selectInterior: () => number[]) {
+  if (points.length <= target) return points.map((_, index) => index)
+  if (target === 1) return [0]
+  if (target === 2) return [0, points.length - 1]
+
+  const indexes = [0]
+  for (const index of selectInterior()) addUniqueIndex(indexes, index)
+  addUniqueIndex(indexes, points.length - 1)
+  return indexes
+}
+
+function selectExtrema(points: IndexedPoint[], target: number, kind: 'min' | 'max' | 'minmax') {
+  const bucketCount = kind === 'minmax' ? Math.floor((target - 2) / 2) : Math.max(0, target - 2)
+
+  return withEndpoints(points, target, () => {
+    if (bucketCount === 0) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, points.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (points[index]!.y < points[minimum]!.y) minimum = index
+        if (points[index]!.y > points[maximum]!.y) maximum = index
+      }
+      if (kind === 'min') {
+        addUniqueIndex(result, minimum)
+      } else if (kind === 'max') {
+        addUniqueIndex(result, maximum)
+      } else if (minimum <= maximum) {
+        addUniqueIndex(result, minimum)
+        addUniqueIndex(result, maximum)
+      } else {
+        addUniqueIndex(result, maximum)
+        addUniqueIndex(result, minimum)
+      }
+    }
+    return result
+  })
+}
+
+function selectPeak(points: IndexedPoint[], target: number) {
+  const bucketCount = Math.floor((target - 2) / 4)
+  return withEndpoints(points, target, () => {
+    if (bucketCount === 0) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, points.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (points[index]!.y < points[minimum]!.y) minimum = index
+        if (points[index]!.y > points[maximum]!.y) maximum = index
+      }
+      for (const index of [bounds.start, minimum, maximum, bounds.end - 1].sort((a, b) => a - b)) {
+        addUniqueIndex(result, index)
+      }
+    }
+    return result
+  })
+}
+
+function selectLttb(points: IndexedPoint[], target: number) {
+  return withEndpoints(points, target, () => {
+    const bucketSize = (points.length - 2) / (target - 2)
+    const result: number[] = []
+    let previous = 0
+
+    for (let bucket = 0; bucket < target - 2; bucket += 1) {
+      const averageStart = Math.min(points.length, Math.floor((bucket + 1) * bucketSize) + 1)
+      const averageEnd = Math.min(points.length, Math.floor((bucket + 2) * bucketSize) + 1)
+      let averageX = 0
+      let averageY = 0
+      for (let index = averageStart; index < averageEnd; index += 1) {
+        averageX += points[index]!.x
+        averageY += points[index]!.y
+      }
+      const averageCount = averageEnd - averageStart
+      if (averageCount > 0) {
+        averageX /= averageCount
+        averageY /= averageCount
+      } else {
+        averageX = points[points.length - 1]!.x
+        averageY = points[points.length - 1]!.y
+      }
+
+      const bounds = bucketBounds(bucket, target - 2, 1, points.length - 1)
+      let selected = bounds.start
+      let maximumArea = -1
+      for (let index = bounds.start; index < bounds.end; index += 1) {
+        const area = Math.abs(
+          (points[previous]!.x - averageX) * (points[index]!.y - points[previous]!.y) -
+            (points[previous]!.x - points[index]!.x) * (averageY - points[previous]!.y),
+        )
+        if (area > maximumArea) {
+          maximumArea = area
+          selected = index
+        }
+      }
+      result.push(selected)
+      previous = selected
+    }
+    return result
+  })
+}
+
+function aggregate(points: IndexedPoint[], target: number, strategy: 'average' | 'sum') {
+  const count = targetCount(target, points.length)
+  const x = new Float64Array(count)
+  const y = new Float64Array(count)
+  for (let bucket = 0; bucket < count; bucket += 1) {
+    const bounds = bucketBounds(bucket, count, 0, points.length)
+    for (let index = bounds.start; index < bounds.end; index += 1) {
+      x[bucket] += points[index]!.x
+      y[bucket] += points[index]!.y
+    }
+    const bucketSize = bounds.end - bounds.start
+    x[bucket] /= bucketSize
+    if (strategy === 'average') y[bucket] /= bucketSize
+  }
+  return { x, y }
+}
+
+/**
+ * Samples an immutable point sequence without changing its objects or order. Aggregate X values
+ * are the arithmetic mean of each contiguous bucket's X values; extrema ties select the earliest
+ * source point. Source-point strategies preserve first and last points whenever the target is 2+.
+ */
+export function sampleWaveformReference(
+  request: ReferenceSamplingRequest,
+): ReferenceSamplingResult {
+  const points = normalizedPoints(request.points)
+  const base = {
+    strategy: request.strategy,
+    inputPointCount: request.points.length,
+    validPointCount: points.length,
+  }
+
+  if (request.strategy === 'average' || request.strategy === 'sum') {
+    return {
+      ...base,
+      kind: 'aggregates',
+      ...aggregate(points, request.targetPointCount, request.strategy),
+    }
+  }
+
+  const target = targetCount(request.targetPointCount, points.length)
+  let indexes: number[]
+  if (request.strategy === 'none' || points.length <= target) {
+    indexes = points.map((_, index) => index)
+  } else if (request.strategy === 'peak') {
+    indexes = selectPeak(points, target)
+  } else if (request.strategy === 'lttb') {
+    indexes = selectLttb(points, target)
+  } else {
+    indexes = selectExtrema(points, target, request.strategy)
+  }
+
+  return {
+    ...base,
+    kind: 'source-indexes',
+    sourceIndexes: Uint32Array.from(indexes, (index) => points[index]!.sourceIndex),
+  }
+}