waveform-analysis 0.1.52 → 0.1.54

package/dist/types/core/renderingOptions.d.ts

@@ -5,6 +5,7 @@ export interface ResolvedWaveformSamplingOptions {
     autoHysteresis: number;
     strategy: WaveformSamplingStrategy;
     maxPointsPerPixel: number;
+    maxPointCount: number | undefined;
     rawPointLimit: number;
     wasmFailureFallback: 'error' | 'javascript';
 }

package/dist/types/core/workerSampling/protocol.d.ts

@@ -70,6 +70,7 @@ export interface WorkerSamplingSeriesRequest {
     previousSelectedMode?: 'raw' | 'sampled';
     strategy: WaveformSamplingStrategy;
     maxPointsPerPixel?: number;
+    maxPointCount?: number;
     rawPointLimit?: number;
     wasmFailureFallback?: 'error' | 'javascript';
     /** Rendering inputs that affect the cache key, even when only line geometry is overridden. */

package/dist/types/types/chart.d.ts

@@ -84,6 +84,8 @@ export interface WaveformSamplingOptions {
     strategy?: WaveformSamplingStrategy;
     /** Upper bound for rendered points per horizontal CSS pixel. */
     maxPointsPerPixel?: number;
+    /** Fixed per-series target point count. When set, this takes precedence over pixel density. */
+    maxPointCount?: number;
     /** Visible-point count at which raw rendering should report a diagnostic. */
     rawPointLimit?: number;
     /** Controls whether a forced WASM failure may temporarily show JavaScript results. */

package/dist/types/views/wasmSamplingDemoSampling.d.ts

@@ -0,0 +1,6 @@
+import type { WaveformSamplingOptions, WaveformSamplingStrategy } from '../types';
+type SamplingSizeOptions = Pick<WaveformSamplingOptions, 'maxPointCount' | 'maxPointsPerPixel'>;
+export declare function usesFixedPointCount(strategy: WaveformSamplingStrategy): boolean;
+export declare function showsSamplingSize(strategy: WaveformSamplingStrategy): strategy is "auto" | "peak" | "lttb" | "average" | "min" | "max" | "minmax" | "sum";
+export declare function samplingSizeOptions(strategy: WaveformSamplingStrategy, maxPointsPerPixel: number, maxPointCount: number): SamplingSizeOptions;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waveform-analysis",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",

package/src/components/core/useWaveformRenderSampling.ts

@@ -75,11 +75,14 @@ function rawDiagnostics(target: SamplingTarget, requestId: number): WorkerSampli
   }
 }
 
-function fallbackPoints(target: SamplingTarget, maxPointsPerPixel: number) {
+function fallbackPoints(target: SamplingTarget) {
   const { source } = target
   const { start, end } = target.visibleRange
   const count = end - start
-  const targetCount = Math.max(1, Math.floor(target.request.plotWidth * maxPointsPerPixel))
+  const targetCount =
+    Number.isFinite(target.request.maxPointCount) && (target.request.maxPointCount ?? 0) >= 1
+      ? Math.floor(target.request.maxPointCount as number)
+      : Math.max(1, Math.floor(target.request.plotWidth * target.request.maxPointsPerPixel!))
   if (count <= targetCount) return source.pointsInRange(start, end)
   if (targetCount === 1) return source.pointAt(start) ? [source.pointAt(start)!] : []
   const points: WaveformPoint[] = []
@@ -141,6 +144,7 @@ export function useWaveformRenderSampling(context: SamplingContext) {
               autoHysteresis: sampling.autoHysteresis,
               strategy: sampling.strategy,
               maxPointsPerPixel: sampling.maxPointsPerPixel,
+              maxPointCount: sampling.maxPointCount,
               rawPointLimit: sampling.rawPointLimit,
               wasmFailureFallback: sampling.wasmFailureFallback,
               lineType: series.lineType,
@@ -159,7 +163,7 @@ export function useWaveformRenderSampling(context: SamplingContext) {
       `${dataEpoch.value}:${targets.value
         .map(
           (target) =>
-            `${target.request.datasetId}:${target.request.xDomain.join(',')}:${target.request.plotWidth}:${target.visibleRange.start}:${target.visibleRange.end}:${target.request.mode}:${target.request.autoThreshold}:${target.request.autoHysteresis}:${target.request.strategy}:${target.request.maxPointsPerPixel}:${target.request.rawPointLimit}:${target.request.wasmFailureFallback}:${target.request.lineType}:${target.request.pointType}:${target.request.errorBarVisible}:${target.request.pointMinSpacing}:${target.request.errorBarMinSpacing}`,
+            `${target.request.datasetId}:${target.request.xDomain.join(',')}:${target.request.plotWidth}:${target.visibleRange.start}:${target.visibleRange.end}:${target.request.mode}:${target.request.autoThreshold}:${target.request.autoHysteresis}:${target.request.strategy}:${target.request.maxPointsPerPixel}:${target.request.maxPointCount}:${target.request.rawPointLimit}:${target.request.wasmFailureFallback}:${target.request.lineType}:${target.request.pointType}:${target.request.errorBarVisible}:${target.request.pointMinSpacing}:${target.request.errorBarMinSpacing}`,
         )
         .join('|')}`,
   )
@@ -253,10 +257,7 @@ export function useWaveformRenderSampling(context: SamplingContext) {
         diagnostics.push(rawDiagnostics(target, token))
       } else {
         if (!nextOverrides[target.series.id]?.length) {
-          nextOverrides[target.series.id] = fallbackPoints(
-            target,
-            context.renderingOptions.value.sampling.maxPointsPerPixel,
-          )
+          nextOverrides[target.series.id] = fallbackPoints(target)
         }
         sampledTargets.push({
           ...target,

package/src/core/rendering.test.ts

@@ -69,6 +69,7 @@ describe('waveform rendering selection', () => {
         autoHysteresis: 20.8,
         strategy: 'minmax',
         maxPointsPerPixel: 2.5,
+        maxPointCount: 1_000.9,
         rawPointLimit: 50_000.2,
         wasmFailureFallback: 'javascript',
       },
@@ -83,6 +84,7 @@ describe('waveform rendering selection', () => {
         autoHysteresis: 20,
         strategy: 'minmax',
         maxPointsPerPixel: 2.5,
+        maxPointCount: 1_000,
         rawPointLimit: 50_000,
         wasmFailureFallback: 'javascript',
       },
@@ -96,6 +98,7 @@ describe('waveform rendering selection', () => {
           autoHysteresis: -1,
           strategy: 'invalid',
           maxPointsPerPixel: Number.POSITIVE_INFINITY,
+          maxPointCount: 0,
           rawPointLimit: 0,
           wasmFailureFallback: 'fallback',
         },

package/src/core/rendering.ts

@@ -106,7 +106,9 @@ function selectSamplingPlaceholderPoints(
   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))
+  const target =
+    options.sampling.maxPointCount ??
+    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) => {

package/src/core/renderingOptions.ts

@@ -11,6 +11,7 @@ export interface ResolvedWaveformSamplingOptions {
   autoHysteresis: number
   strategy: WaveformSamplingStrategy
   maxPointsPerPixel: number
+  maxPointCount: number | undefined
   rawPointLimit: number
   wasmFailureFallback: 'error' | 'javascript'
 }
@@ -36,6 +37,7 @@ export const DEFAULT_WAVEFORM_RENDERING_OPTIONS: ResolvedWaveformRenderingOption
     autoHysteresis: 0,
     strategy: 'peak',
     maxPointsPerPixel: 4,
+    maxPointCount: undefined,
     rawPointLimit: 100_000,
     wasmFailureFallback: 'error',
   },
@@ -72,6 +74,12 @@ function resolvePositiveNumber(value: unknown, fallback: number): number {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback
 }
 
+function resolveOptionalFiniteInteger(value: unknown, minimum: number): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= minimum
+    ? Math.floor(value)
+    : undefined
+}
+
 function resolveNonNegativeNumber(value: number, fallback: number): number {
   return Number.isFinite(value) && value >= 0 ? value : fallback
 }
@@ -106,6 +114,7 @@ function resolveSamplingOptions(
       ? options.strategy
       : DEFAULT_WAVEFORM_RENDERING_OPTIONS.sampling.strategy,
     maxPointsPerPixel,
+    maxPointCount: resolveOptionalFiniteInteger(options?.maxPointCount, 1),
     rawPointLimit: resolveFiniteInteger(
       options?.rawPointLimit,
       1,

package/src/core/renderingStrategies.ts

@@ -42,7 +42,10 @@ export const peakPreservingPointSelectionStrategy: RenderablePointSelectionStrat
 
   const domainStart = Math.min(domain[0], domain[1])
   const domainEnd = Math.max(domain[0], domain[1])
-  const maximumPointCount = Math.max(4, Math.floor(width * options.maxPointsPerPixel))
+  const maximumPointCount = Math.max(
+    4,
+    options.sampling.maxPointCount ?? Math.floor(width * options.maxPointsPerPixel),
+  )
   const bucketCount = Math.max(1, Math.floor(maximumPointCount / 4))
   const result: WaveformPoint[] = []
   const span = domainEnd - domainStart || 1
@@ -119,7 +122,8 @@ export function resolveRenderablePointSelectionStrategy(
 ): RenderablePointSelectionStrategy {
   const maximumPointCount = Math.max(
     4,
-    Math.floor(request.width * request.options.maxPointsPerPixel),
+    request.options.sampling.maxPointCount ??
+      Math.floor(request.width * request.options.maxPointsPerPixel),
   )
   const shouldUseCompletePoints =
     !request.options.downsample ||

package/src/core/workerSampling/protocol.ts

@@ -90,6 +90,7 @@ export interface WorkerSamplingSeriesRequest {
   previousSelectedMode?: 'raw' | 'sampled'
   strategy: WaveformSamplingStrategy
   maxPointsPerPixel?: number
+  maxPointCount?: number
   rawPointLimit?: number
   wasmFailureFallback?: 'error' | 'javascript'
   /** Rendering inputs that affect the cache key, even when only line geometry is overridden. */

package/src/core/workerSampling/repositorySampling.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+
+import type { WaveformPoint } from '@/types'
+import type { WorkerSamplingSeriesRequest } from './protocol'
+import { WorkerSamplingRepository } from './repository'
+
+const points: WaveformPoint[] = Array.from({ length: 12 }, (_, index) => ({
+  x: index,
+  y: index === 5 ? 100 : index,
+}))
+
+function register(repository: WorkerSamplingRepository, datasetId: string) {
+  return repository.handle({
+    type: 'register-dataset',
+    requestId: 1,
+    datasetId,
+    revision: 0,
+    points,
+  })
+}
+
+function sampleSeries(datasetId: string): WorkerSamplingSeriesRequest {
+  return {
+    seriesId: `${datasetId}-series`,
+    datasetId,
+    revision: 1,
+    xDomain: [0, 11],
+    plotWidth: 1_000,
+    mode: 'auto',
+    autoThreshold: 2,
+    strategy: 'peak',
+    maxPointsPerPixel: 4,
+    maxPointCount: 4,
+    rawPointLimit: 5,
+  }
+}
+
+describe('WorkerSamplingRepository sampling targets', () => {
+  it('uses a fixed maximum point count instead of pixel density when configured', () => {
+    const repository = new WorkerSamplingRepository()
+    register(repository, 'fixed-target')
+    const response = repository.handle({
+      type: 'sample-viewport',
+      requestId: 51,
+      series: [sampleSeries('fixed-target')],
+    })
+
+    expect(response.type).toBe('sample-viewport-response')
+    if (response.type !== 'sample-viewport-response') return
+    expect(response.results[0]?.diagnostics.renderedPointCount).toBeLessThanOrEqual(4)
+  })
+
+  it.each(['lttb', 'average', 'sum'] as const)(
+    'returns exactly the fixed target for %s when enough points are visible',
+    (strategy) => {
+      const source = Array.from({ length: 100_000 }, (_, index) => ({
+        x: index,
+        y: Math.sin(index / 10),
+      }))
+      const repository = new WorkerSamplingRepository()
+      repository.handle({
+        type: 'register-dataset',
+        requestId: 1,
+        datasetId: strategy,
+        revision: 0,
+        points: source,
+      })
+      const response = repository.handle({
+        type: 'sample-viewport',
+        requestId: 2,
+        series: [
+          {
+            ...sampleSeries(strategy),
+            xDomain: [0, 99_999],
+            strategy,
+            maxPointCount: 1_000,
+          },
+        ],
+      })
+
+      expect(response).toMatchObject({
+        results: [{ diagnostics: { visiblePointCount: 100_000, renderedPointCount: 1_000 } }],
+      })
+    },
+  )
+
+  it('does not add points when the visible source has fewer than the fixed target', () => {
+    const repository = new WorkerSamplingRepository()
+    register(repository, 'small-target')
+    const response = repository.handle({
+      type: 'sample-viewport',
+      requestId: 3,
+      series: [
+        {
+          ...sampleSeries('small-target'),
+          strategy: 'lttb',
+          maxPointCount: 100,
+        },
+      ],
+    })
+
+    expect(response).toMatchObject({
+      results: [{ diagnostics: { visiblePointCount: 12, renderedPointCount: 12 } }],
+    })
+  })
+})

package/src/core/workerSampling/repositorySupport.ts

@@ -92,6 +92,9 @@ export function selectedStrategy(strategy: WorkerSamplingSeriesRequest['strategy
 }
 
 export function targetPointCount(request: WorkerSamplingSeriesRequest) {
+  if (Number.isFinite(request.maxPointCount) && (request.maxPointCount ?? 0) >= 1) {
+    return Math.floor(request.maxPointCount as number)
+  }
   const width = Number.isFinite(request.plotWidth) ? Math.max(0, request.plotWidth) : 0
   const density = Number.isFinite(request.maxPointsPerPixel)
     ? Math.max(0, request.maxPointsPerPixel ?? 0)
@@ -179,6 +182,7 @@ export function cacheKey(
     request.plotWidth,
     target,
     request.maxPointsPerPixel,
+    request.maxPointCount,
     request.mode,
     backend,
     strategy,

package/src/types/chart.ts

@@ -96,6 +96,8 @@ export interface WaveformSamplingOptions {
   strategy?: WaveformSamplingStrategy
   /** Upper bound for rendered points per horizontal CSS pixel. */
   maxPointsPerPixel?: number
+  /** Fixed per-series target point count. When set, this takes precedence over pixel density. */
+  maxPointCount?: number
   /** Visible-point count at which raw rendering should report a diagnostic. */
   rawPointLimit?: number
   /** Controls whether a forced WASM failure may temporarily show JavaScript results. */

package/src/views/WasmSamplingDemo.vue

@@ -5,11 +5,17 @@ import { InputNumber, RadioButton, RadioGroup, Select } from 'ant-design-vue'
 import { WaveformChart } from '../components'
 import type {
   WaveformData,
+  WaveformAnnotation,
   WaveformRenderingOptions,
   WaveformSamplingDiagnostics,
   WaveformSamplingMode,
   WaveformSamplingStrategy,
 } from '../types'
+import {
+  samplingSizeOptions,
+  showsSamplingSize,
+  usesFixedPointCount,
+} from './wasmSamplingDemoSampling'
 
 const SERIES_COUNT = 10
 const POINTS_PER_SERIES = 100_000
@@ -68,7 +74,9 @@ const mode = ref<WaveformSamplingMode>('auto')
 const strategy = ref<WaveformSamplingStrategy>('peak')
 const autoThreshold = ref(1_000)
 const maxPointsPerPixel = ref(3)
+const maxPointCount = ref(1_000)
 const minVisiblePoints = ref(2)
+const annotations = ref<WaveformAnnotation[]>([])
 const diagnostics = reactive<Record<string, WaveformSamplingDiagnostics | undefined>>({})
 
 const rendering = computed<WaveformRenderingOptions>(() => ({
@@ -76,7 +84,7 @@ const rendering = computed<WaveformRenderingOptions>(() => ({
     mode: mode.value,
     strategy: strategy.value,
     autoThreshold: autoThreshold.value,
-    maxPointsPerPixel: maxPointsPerPixel.value,
+    ...samplingSizeOptions(strategy.value, maxPointsPerPixel.value, maxPointCount.value),
     rawPointLimit: 100_000,
     wasmFailureFallback: 'javascript',
   },
@@ -126,16 +134,27 @@ function pointCount(value: number | undefined) {
           size="small"
         />
       </label>
-      <label>
+      <label v-if="usesFixedPointCount(strategy)">
+        <span>目标渲染点数</span>
+        <InputNumber
+          v-model:value="maxPointCount"
+          :min="1"
+          :max="100000"
+          :step="100"
+          size="small"
+        />
+      </label>
+      <label v-else-if="showsSamplingSize(strategy)">
         <span>每像素点数</span>
         <InputNumber
           v-model:value="maxPointsPerPixel"
-          :min="0.25"
-          :max="16"
-          :step="0.25"
+          :min="0.1"
+          :max="10"
+          :step="0.1"
           size="small"
         />
       </label>
+      <span v-else class="sampling-demo__sampling-disabled">当前策略不执行降采样</span>
       <label>
         <span>最少可见点</span>
         <InputNumber v-model:value="minVisiblePoints" :min="2" :max="1000" :step="1" size="small" />
@@ -146,6 +165,7 @@ function pointCount(value: number | undefined) {
       <div class="sampling-demo__chart">
         <WaveformChart
           :data="data"
+          v-model:annotations="annotations"
           :rendering="rendering"
           :grid="{ rowCount: 1, columnCount: 1, showPagination: false }"
           :legend="{ position: 'top-right', orientation: 'vertical' }"

package/src/views/wasmSamplingDemoSampling.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  samplingSizeOptions,
+  showsSamplingSize,
+  usesFixedPointCount,
+} from './wasmSamplingDemoSampling'
+
+describe('WASM sampling demo sizing', () => {
+  it('uses pixel density for peak-oriented and extrema strategies', () => {
+    expect(samplingSizeOptions('auto', 3, 1_000)).toEqual({ maxPointsPerPixel: 3 })
+    expect(samplingSizeOptions('peak', 3, 1_000)).toEqual({ maxPointsPerPixel: 3 })
+    expect(samplingSizeOptions('minmax', 3, 1_000)).toEqual({ maxPointsPerPixel: 3 })
+  })
+
+  it('uses a fixed point count for LTTB and aggregate strategies', () => {
+    for (const strategy of ['lttb', 'average', 'sum'] as const) {
+      expect(usesFixedPointCount(strategy)).toBe(true)
+      expect(samplingSizeOptions(strategy, 3, 1_000)).toEqual({ maxPointCount: 1_000 })
+    }
+  })
+
+  it('does not show a sampling-size control or pass a size for none', () => {
+    expect(showsSamplingSize('none')).toBe(false)
+    expect(samplingSizeOptions('none', 3, 1_000)).toEqual({})
+  })
+})

package/src/views/wasmSamplingDemoSampling.ts

@@ -0,0 +1,23 @@
+import type { WaveformSamplingOptions, WaveformSamplingStrategy } from '../types'
+
+type SamplingSizeOptions = Pick<WaveformSamplingOptions, 'maxPointCount' | 'maxPointsPerPixel'>
+
+const fixedPointCountStrategies: readonly WaveformSamplingStrategy[] = ['lttb', 'average', 'sum']
+
+export function usesFixedPointCount(strategy: WaveformSamplingStrategy) {
+  return fixedPointCountStrategies.includes(strategy)
+}
+
+export function showsSamplingSize(strategy: WaveformSamplingStrategy) {
+  return strategy !== 'none'
+}
+
+export function samplingSizeOptions(
+  strategy: WaveformSamplingStrategy,
+  maxPointsPerPixel: number,
+  maxPointCount: number,
+): SamplingSizeOptions {
+  if (usesFixedPointCount(strategy)) return { maxPointCount }
+  if (!showsSamplingSize(strategy)) return {}
+  return { maxPointsPerPixel }
+}