waveform-analysis 0.1.51 → 0.1.53

package/dist/types/components/core/useWaveformChartController.d.ts

@@ -334,6 +334,7 @@ export declare function useWaveformChartController(props: ResolvedWaveformChartP
     pannable: boolean;
     minZoomSpan?: number | undefined;
     minVisiblePoints: number;
+    maxZoomScale?: number | null | undefined;
     initialXDomains?: Record<string, [number, number]> | undefined;
     xDomainStrategy: import("../..").WaveformXDomainStrategy;
     yDomain?: [number, number] | undefined;

package/dist/types/components/core/waveformChartTypes.d.ts

@@ -14,6 +14,7 @@ export interface WaveformChartProps {
     pannable?: boolean;
     minZoomSpan?: number;
     minVisiblePoints?: number;
+    maxZoomScale?: number | null;
     initialXDomain?: [number, number];
     initialXDomains?: Record<string, [number, number]>;
     xDomainStrategy?: WaveformXDomainStrategy;

package/dist/types/components/interaction/zoomConstraints.d.ts

@@ -9,6 +9,7 @@ export type ZoomSeriesGroup = readonly PointSeriesSource[];
 interface ZoomConstraintOptions {
     minZoomSpan?: number;
     minVisiblePoints?: number;
+    maxZoomScale?: number | null;
 }
 export declare function resolveMinimumZoomSpan(boundary: [number, number], groups: readonly ZoomSeriesGroup[], options: ZoomConstraintOptions): number;
 export declare function constrainZoomDomain(domain: [number, number], boundary: [number, number], groups: readonly ZoomSeriesGroup[], options: ZoomConstraintOptions): [number, number];

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/package.json

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

package/src/components/core/useWaveformChartLifecycle.ts

@@ -213,6 +213,7 @@ export function useWaveformChartLifecycle(context: LifecycleContext) {
       isPresentationMode,
       () => props.minZoomSpan,
       () => props.minVisiblePoints,
+      () => props.maxZoomScale,
       () => props.initialXDomain,
       () => props.initialXDomains,
       () => props.xDomainStrategy,

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/components/core/waveformChartTypes.ts

@@ -35,6 +35,7 @@ export interface WaveformChartProps {
   pannable?: boolean
   minZoomSpan?: number
   minVisiblePoints?: number
+  maxZoomScale?: number | null
   initialXDomain?: [number, number]
   initialXDomains?: Record<string, [number, number]>
   xDomainStrategy?: WaveformXDomainStrategy

package/src/components/interaction/useWaveformZoom.ts

@@ -231,7 +231,7 @@ export function useWaveformZoom(context: ZoomContext) {
     const minimumSpan = resolveMinimumZoomSpan(domain, groups, props)
     return Math.max(
       ZOOM_CONSTRAINTS.MIN_SCALE,
-      minimumSpan > 0 ? domainSpan / minimumSpan : ZOOM_CONSTRAINTS.DEFAULT_MAX_SCALE,
+      minimumSpan > 0 ? domainSpan / minimumSpan : Number.POSITIVE_INFINITY,
     )
   }
   const constrainTransform = (

package/src/components/interaction/zoomConstraints.ts

@@ -14,6 +14,7 @@ export type ZoomSeriesGroup = readonly PointSeriesSource[]
 interface ZoomConstraintOptions {
   minZoomSpan?: number
   minVisiblePoints?: number
+  maxZoomScale?: number | null
 }
 
 const xValueCache = new WeakMap<object, Map<string, number[]>>()
@@ -80,10 +81,14 @@ export function resolveMinimumZoomSpan(
       : 0
   const required = resolveRequiredPointCount(options.minVisiblePoints)
   const pointSpan = minimumPointSpan(groups, normalized, required)
-  if (configuredSpan > 0 || required > 0) {
-    return Math.max(configuredSpan, pointSpan)
-  }
-  return boundarySpan / ZOOM_CONSTRAINTS.DEFAULT_MAX_SCALE
+  const configuredScale = Number(options.maxZoomScale)
+  const scaleSpan =
+    Number.isFinite(configuredScale) && configuredScale >= ZOOM_CONSTRAINTS.MIN_SCALE
+      ? boundarySpan / configuredScale
+      : options.maxZoomScale !== null && configuredSpan === 0 && required === 0
+        ? boundarySpan / ZOOM_CONSTRAINTS.DEFAULT_MAX_SCALE
+        : 0
+  return Math.max(configuredSpan, pointSpan, scaleSpan)
 }
 
 function expandToMinimumPoints(

package/src/components/waveformChartCases/zoomPointConstraints.test.ts

@@ -65,10 +65,10 @@ function dispatchBox(
 }
 
 describe('WaveformChart point-aware zoom constraints', () => {
-  it('wheel-zooms 1,200 samples to two distinct X values, stops, and still zooms out', async () => {
+  it('zooms to two distinct X values when the scale limit is disabled', async () => {
     const wrapper = await mountSizedChart(
       { kind: 'points', points: regularPoints },
-      { minVisiblePoints: 2 },
+      { minVisiblePoints: 2, maxZoomScale: null },
     )
     const { overlay, width, height } = prepareOverlay(
       wrapper,
@@ -151,7 +151,7 @@ describe('WaveformChart point-aware zoom constraints', () => {
     expect(visibleXCount(constrainedDomain)).toBe(2)
   })
 
-  it('retains the default 40x maximum when no explicit limit is configured', async () => {
+  it('retains the backwards-compatible default maximum zoom scale', async () => {
     const wrapper = await mountSizedChart({ kind: 'points', points: regularPoints })
     const { overlay, width, height } = prepareOverlay(
       wrapper,
@@ -163,6 +163,66 @@ describe('WaveformChart point-aware zoom constraints', () => {
     expect(domain[1] - domain[0]).toBeCloseTo(1_199 / 40)
   })
 
+  it('honors an explicit maximum zoom scale', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'points', points: regularPoints },
+      { maxZoomScale: 20 },
+    )
+    const { overlay, width, height } = prepareOverlay(
+      wrapper,
+      '.waveform-chart__overlay--independent',
+    )
+
+    await dispatchWheel(overlay, width, height, -4_000)
+    const domain = wrapper.emitted('zoom-change')?.at(-1)?.[0] as [number, number]
+    expect(domain[1] - domain[0]).toBeCloseTo(1_199 / 20)
+  })
+
+  it('disables the compatibility scale limit when configured with null', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'points', points: regularPoints },
+      { maxZoomScale: null },
+    )
+    const { overlay, width, height } = prepareOverlay(
+      wrapper,
+      '.waveform-chart__overlay--independent',
+    )
+
+    await dispatchWheel(overlay, width, height, -4_000)
+    const domain = wrapper.emitted('zoom-change')?.at(-1)?.[0] as [number, number]
+    expect(domain[1] - domain[0]).toBeLessThan(1_199 / 40)
+  })
+
+  it('falls back to the compatibility limit for an invalid maximum scale', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'points', points: regularPoints },
+      { maxZoomScale: 0 },
+    )
+    const { overlay, width, height } = prepareOverlay(
+      wrapper,
+      '.waveform-chart__overlay--independent',
+    )
+
+    await dispatchWheel(overlay, width, height, -4_000)
+    const domain = wrapper.emitted('zoom-change')?.at(-1)?.[0] as [number, number]
+    expect(domain[1] - domain[0]).toBeCloseTo(1_199 / 40)
+  })
+
+  it('uses the strictest configured zoom constraint', async () => {
+    const wrapper = await mountSizedChart(
+      { kind: 'points', points: regularPoints },
+      { minZoomSpan: 50, minVisiblePoints: 2, maxZoomScale: 40 },
+    )
+    const { overlay, width, height } = prepareOverlay(
+      wrapper,
+      '.waveform-chart__overlay--independent',
+    )
+
+    await dispatchWheel(overlay, width, height, -4_000)
+    const domain = wrapper.emitted('zoom-change')?.at(-1)?.[0] as [number, number]
+    expect(domain[1] - domain[0]).toBeCloseTo(50)
+  })
+
   it('retains two endpoint samples while replacing an independent data window', async () => {
     const sourcePoints = Array.from({ length: 1_000 }, (_, index) => ({
       x: -5 + (index * 10) / 999,

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,52 @@
+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)
+  })
+})

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,6 +5,7 @@ import { InputNumber, RadioButton, RadioGroup, Select } from 'ant-design-vue'
 import { WaveformChart } from '../components'
 import type {
   WaveformData,
+  WaveformAnnotation,
   WaveformRenderingOptions,
   WaveformSamplingDiagnostics,
   WaveformSamplingMode,
@@ -67,7 +68,9 @@ const data = createDenseData()
 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>(() => ({
@@ -75,7 +78,7 @@ const rendering = computed<WaveformRenderingOptions>(() => ({
     mode: mode.value,
     strategy: strategy.value,
     autoThreshold: autoThreshold.value,
-    maxPointsPerPixel: maxPointsPerPixel.value,
+    maxPointCount: maxPointCount.value,
     rawPointLimit: 100_000,
     wasmFailureFallback: 'javascript',
   },
@@ -126,24 +129,31 @@ function pointCount(value: number | undefined) {
         />
       </label>
       <label>
-        <span>每像素点数</span>
+        <span>最多渲染点</span>
         <InputNumber
-          v-model:value="maxPointsPerPixel"
-          :min="0.25"
-          :max="16"
-          :step="0.25"
+          v-model:value="maxPointCount"
+          :min="1"
+          :max="100000"
+          :step="100"
           size="small"
         />
       </label>
+      <label>
+        <span>最少可见点</span>
+        <InputNumber v-model:value="minVisiblePoints" :min="2" :max="1000" :step="1" size="small" />
+      </label>
     </section>
 
     <section class="sampling-demo__workspace">
       <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' }"
+          :max-zoom-scale="null"
+          :min-visible-points="minVisiblePoints"
           :title="{ visible: true, text: '多系列采样与缓存诊断', align: 'left' }"
           x-label="时间（s）"
           time-unit="s"