waveform-analysis 0.1.29 → 0.1.31

package/src/core/rendering.ts

@@ -3,6 +3,10 @@ import { bisector } from 'd3'
 import type { WaveformPoint } from '@/types'
 import { resolveWaveformPointErrors } from './data'
 import type { ResolvedWaveformRenderingOptions } from './renderingOptions'
+import {
+  resolveRenderablePointSelectionStrategy,
+  type VisiblePointRange,
+} from './renderingStrategies'
 
 export {
   DEFAULT_WAVEFORM_RENDERING_OPTIONS,
@@ -13,11 +17,6 @@ export {
 const pointBisector = bisector((point: WaveformPoint) => point.x)
 const acceptAllPoints = () => true
 
-interface VisiblePointRange {
-  start: number
-  end: number
-}
-
 interface PointSeriesSource {
   points: WaveformPoint[]
 }
@@ -65,10 +64,6 @@ export function hasMinimumVisibleXValues(
   return false
 }
 
-function pushUniquePoint(target: WaveformPoint[], point: WaveformPoint | undefined) {
-  if (point && target[target.length - 1] !== point) target.push(point)
-}
-
 function selectRenderablePointsInRange(
   points: WaveformPoint[],
   range: VisiblePointRange,
@@ -76,82 +71,17 @@ function selectRenderablePointsInRange(
   width: number,
   options: ResolvedWaveformRenderingOptions,
 ): WaveformPoint[] {
-  const domainStart = Math.min(domain[0], domain[1])
-  const domainEnd = Math.max(domain[0], domain[1])
   const start = Math.max(0, range.start - 1)
   const end = Math.min(points.length, range.end + 1)
   const visibleCount = end - start
   if (visibleCount <= 0) return []
-  if (!options.downsample || visibleCount <= options.downsampleThreshold) {
-    return points.slice(start, end)
-  }
-
-  const maximumPointCount = Math.max(4, Math.floor(width * options.maxPointsPerPixel))
-  const bucketCount = Math.max(1, Math.floor(maximumPointCount / 4))
-  if (visibleCount <= maximumPointCount) return points.slice(start, end)
-
-  const result: WaveformPoint[] = []
-  const span = domainEnd - domainStart || 1
-  const bucketIndexes = Array.from({ length: 4 }, () => -1)
-  let activeBucket = -1
-  let firstIndex = -1
-  let lastIndex = -1
-  let minimumIndex = -1
-  let maximumIndex = -1
-
-  const addBucketIndex = (index: number, count: number) => {
-    if (index < 0) return count
-    for (let position = 0; position < count; position += 1) {
-      if (bucketIndexes[position] === index) return count
-    }
-    bucketIndexes[count] = index
-    return count + 1
-  }
-
-  const flushBucket = () => {
-    if (firstIndex < 0) return
-    let count = 0
-    count = addBucketIndex(firstIndex, count)
-    count = addBucketIndex(minimumIndex, count)
-    count = addBucketIndex(maximumIndex, count)
-    count = addBucketIndex(lastIndex, count)
-    for (let index = 1; index < count; index += 1) {
-      const value = bucketIndexes[index]
-      let position = index - 1
-      while (position >= 0 && bucketIndexes[position] > value) {
-        bucketIndexes[position + 1] = bucketIndexes[position]
-        position -= 1
-      }
-      bucketIndexes[position + 1] = value
-    }
-    for (let index = 0; index < count; index += 1) {
-      pushUniquePoint(result, points[bucketIndexes[index]])
-    }
-  }
-
-  pushUniquePoint(result, points[start])
-  for (let index = range.start; index < range.end; index += 1) {
-    const point = points[index]
-    const bucket = Math.min(
-      bucketCount - 1,
-      Math.max(0, Math.floor(((point.x - domainStart) / span) * bucketCount)),
-    )
-    if (bucket !== activeBucket) {
-      flushBucket()
-      activeBucket = bucket
-      firstIndex = index
-      lastIndex = index
-      minimumIndex = index
-      maximumIndex = index
-      continue
-    }
-    lastIndex = index
-    if (point.y < points[minimumIndex].y) minimumIndex = index
-    if (point.y > points[maximumIndex].y) maximumIndex = index
-  }
-  flushBucket()
-  pushUniquePoint(result, points[end - 1])
-  return result
+  return resolveRenderablePointSelectionStrategy({ visibleCount, width, options })({
+    points,
+    range,
+    domain,
+    width,
+    options,
+  })
 }
 
 /**

package/src/core/renderingStrategies.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+
+import type { WaveformPoint } from '../types'
+import { DEFAULT_WAVEFORM_RENDERING_OPTIONS } from './renderingOptions'
+import {
+  peakPreservingPointSelectionStrategy,
+  resolveRenderablePointSelectionStrategy,
+  type RenderablePointSelectionContext,
+} from './renderingStrategies'
+
+const denseOptions = {
+  ...DEFAULT_WAVEFORM_RENDERING_OPTIONS,
+  downsampleThreshold: 0,
+  maxPointsPerPixel: 1,
+}
+
+describe('renderable point selection strategies', () => {
+  it('resolves complete-point selection at the configured boundaries', () => {
+    const context: RenderablePointSelectionContext = {
+      points: [
+        { x: 0, y: 5 },
+        { x: 1, y: 1 },
+        { x: 2, y: 10 },
+        { x: 3, y: 3 },
+        { x: 4, y: 7 },
+      ],
+      range: { start: 0, end: 5 },
+      domain: [0, 4],
+      width: 100,
+      options: DEFAULT_WAVEFORM_RENDERING_OPTIONS,
+    }
+    const complete = resolveRenderablePointSelectionStrategy({
+      visibleCount: 100,
+      width: 100,
+      options: DEFAULT_WAVEFORM_RENDERING_OPTIONS,
+    })(context)
+    const disabled = resolveRenderablePointSelectionStrategy({
+      visibleCount: 10_000,
+      width: 100,
+      options: { ...denseOptions, downsample: false },
+    })(context)
+
+    expect(complete).toEqual(context.points)
+    expect(disabled).toEqual(context.points)
+  })
+
+  it('resolves peak-preserving selection for dense visible data', () => {
+    const context: RenderablePointSelectionContext = {
+      points: [
+        { x: 0, y: 5 },
+        { x: 1, y: 1 },
+        { x: 2, y: 10 },
+        { x: 3, y: 3 },
+        { x: 4, y: 7 },
+      ],
+      range: { start: 0, end: 5 },
+      domain: [0, 4],
+      width: 4,
+      options: denseOptions,
+    }
+    const selected = resolveRenderablePointSelectionStrategy({
+      visibleCount: 1_000,
+      width: 4,
+      options: denseOptions,
+    })(context)
+
+    expect(selected).toEqual(expect.arrayContaining([context.points[1], context.points[2]]))
+  })
+
+  it('retains first, last, minimum, and maximum points in a peak bucket', () => {
+    const points: WaveformPoint[] = [
+      { x: 0, y: 5 },
+      { x: 1, y: 1 },
+      { x: 2, y: 10 },
+      { x: 3, y: 3 },
+      { x: 4, y: 7 },
+    ]
+    const selected = peakPreservingPointSelectionStrategy({
+      points,
+      range: { start: 0, end: points.length },
+      domain: [0, 4],
+      width: 4,
+      options: denseOptions,
+    })
+
+    expect(selected[0]).toBe(points[0])
+    expect(selected.at(-1)).toBe(points.at(-1))
+    expect(selected.map((point) => point.y)).toEqual(expect.arrayContaining([1, 10]))
+  })
+})

package/src/core/renderingStrategies.ts

@@ -0,0 +1,131 @@
+import type { WaveformPoint } from '../types'
+import type { ResolvedWaveformRenderingOptions } from './renderingOptions'
+
+export interface VisiblePointRange {
+  start: number
+  end: number
+}
+
+export interface RenderablePointSelectionContext {
+  points: WaveformPoint[]
+  range: VisiblePointRange
+  domain: [number, number]
+  width: number
+  options: ResolvedWaveformRenderingOptions
+}
+
+export type RenderablePointSelectionStrategy = (
+  context: RenderablePointSelectionContext,
+) => WaveformPoint[]
+
+function selectionBounds(range: VisiblePointRange, pointCount: number) {
+  return {
+    start: Math.max(0, range.start - 1),
+    end: Math.min(pointCount, range.end + 1),
+  }
+}
+
+function pushUniquePoint(target: WaveformPoint[], point: WaveformPoint | undefined) {
+  if (point && target[target.length - 1] !== point) target.push(point)
+}
+
+export const completePointSelectionStrategy: RenderablePointSelectionStrategy = (context) => {
+  const { start, end } = selectionBounds(context.range, context.points.length)
+  return context.points.slice(start, end)
+}
+
+export const peakPreservingPointSelectionStrategy: RenderablePointSelectionStrategy = (context) => {
+  const { points, range, domain, width, options } = context
+  const { start, end } = selectionBounds(range, points.length)
+  const visibleCount = end - start
+  if (visibleCount <= 0) return []
+
+  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 bucketCount = Math.max(1, Math.floor(maximumPointCount / 4))
+  const result: WaveformPoint[] = []
+  const span = domainEnd - domainStart || 1
+  const bucketIndexes = Array.from({ length: 4 }, () => -1)
+  let activeBucket = -1
+  let firstIndex = -1
+  let lastIndex = -1
+  let minimumIndex = -1
+  let maximumIndex = -1
+
+  const addBucketIndex = (index: number, count: number) => {
+    if (index < 0) return count
+    for (let position = 0; position < count; position += 1) {
+      if (bucketIndexes[position] === index) return count
+    }
+    bucketIndexes[count] = index
+    return count + 1
+  }
+
+  const flushBucket = () => {
+    if (firstIndex < 0) return
+    let count = 0
+    count = addBucketIndex(firstIndex, count)
+    count = addBucketIndex(minimumIndex, count)
+    count = addBucketIndex(maximumIndex, count)
+    count = addBucketIndex(lastIndex, count)
+    for (let index = 1; index < count; index += 1) {
+      const value = bucketIndexes[index]
+      let position = index - 1
+      while (position >= 0 && bucketIndexes[position] > value) {
+        bucketIndexes[position + 1] = bucketIndexes[position]
+        position -= 1
+      }
+      bucketIndexes[position + 1] = value
+    }
+    for (let index = 0; index < count; index += 1) {
+      pushUniquePoint(result, points[bucketIndexes[index]])
+    }
+  }
+
+  pushUniquePoint(result, points[start])
+  for (let index = range.start; index < range.end; index += 1) {
+    const point = points[index]
+    const bucket = Math.min(
+      bucketCount - 1,
+      Math.max(0, Math.floor(((point.x - domainStart) / span) * bucketCount)),
+    )
+    if (bucket !== activeBucket) {
+      flushBucket()
+      activeBucket = bucket
+      firstIndex = index
+      lastIndex = index
+      minimumIndex = index
+      maximumIndex = index
+      continue
+    }
+    lastIndex = index
+    if (point.y < points[minimumIndex].y) minimumIndex = index
+    if (point.y > points[maximumIndex].y) maximumIndex = index
+  }
+  flushBucket()
+  pushUniquePoint(result, points[end - 1])
+  return result
+}
+
+export interface RenderablePointSelectionStrategyRequest {
+  visibleCount: number
+  width: number
+  options: ResolvedWaveformRenderingOptions
+}
+
+export function resolveRenderablePointSelectionStrategy(
+  request: RenderablePointSelectionStrategyRequest,
+): RenderablePointSelectionStrategy {
+  const maximumPointCount = Math.max(
+    4,
+    Math.floor(request.width * request.options.maxPointsPerPixel),
+  )
+  const shouldUseCompletePoints =
+    !request.options.downsample ||
+    request.visibleCount <= request.options.downsampleThreshold ||
+    request.visibleCount <= maximumPointCount
+  return shouldUseCompletePoints
+    ? completePointSelectionStrategy
+    : peakPreservingPointSelectionStrategy
+}

package/src/data/simulatedWaveforms.ts

@@ -6,16 +6,15 @@ const END_TIME = 5
 const TWO_PI = Math.PI * 2
 
 type SignalGenerator = (time: number, noise: number) => number
-type ErrorGenerator = (time: number, value: number) => Pick<
-  WaveformPoint,
-  'error' | 'lowerError' | 'upperError'
->
+type ErrorGenerator = (
+  time: number,
+  value: number,
+) => Pick<WaveformPoint, 'error' | 'lowerError' | 'upperError'>
 
-interface SimulatedSeriesDefinition
-  extends Pick<
-    WaveformSeries,
-    'id' | 'name' | 'unit' | 'lineType' | 'pointType' | 'errorBar'
-  > {
+interface SimulatedSeriesDefinition extends Pick<
+  WaveformSeries,
+  'id' | 'name' | 'unit' | 'lineType' | 'pointType' | 'errorBar'
+> {
   signal: SignalGenerator
   errors?: ErrorGenerator
 }
@@ -39,7 +38,7 @@ function createPoints(
     return {
       x: time,
       y: value,
-      ...(errors?.(time, value) ?? {}),
+      ...errors?.(time, value),
     }
   })
 }

package/src/demo/DemoChartHost.vue

@@ -22,8 +22,7 @@ defineExpose({ resetViewport })
       v-model:annotations="model.annotations"
       v-model:hidden-series-ids="model.hiddenSeriesIds"
       :data="model.data"
-      :min-zoom-span="model.minZoomSpan"
-      :min-visible-points="5"
+      :min-visible-points="2"
       :initial-x-domain="model.initialXDomain"
       :display-mode="model.displayMode"
       :overlay-mode="model.overlayMode"
@@ -45,6 +44,7 @@ defineExpose({ resetViewport })
       :clean-view="model.cleanView"
       :presentation-mode="model.presentationMode"
       :show-tooltip="model.showTooltip"
+      :plot-margin="model.plotMargin"
       :zero-line="model.zeroLine"
       :frame-number="model.frameWatermarkVisible ? 1 : undefined"
       :annotations-visible="model.annotationsVisible"

package/src/demo/DemoGridFrameControls.vue

@@ -8,6 +8,35 @@ const model = defineModel<DemoControlPanelModel>('model', { required: true })
 </script>
 
 <template>
+  <section class="control-section">
+    <h2>绘图区边距</h2>
+    <div class="plot-margin-controls">
+      <label class="frame-style-control">
+        <span>上边距</span>
+        <InputNumber
+          v-model:value="model.plotMarginTop"
+          :min="0"
+          :max="300"
+          :step="1"
+          addon-after="px"
+          size="small"
+          aria-label="绘图区上边距"
+        />
+      </label>
+      <label class="frame-style-control">
+        <span>下边距</span>
+        <InputNumber
+          v-model:value="model.plotMarginBottom"
+          :min="0"
+          :max="300"
+          :step="1"
+          addon-after="px"
+          size="small"
+          aria-label="绘图区下边距"
+        />
+      </label>
+    </div>
+  </section>
   <section class="control-section">
     <div class="control-section__header">
       <h2>零值参考线</h2>

package/src/demo/plotMarginControls.test.ts

@@ -0,0 +1,29 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { InputNumber } from 'ant-design-vue'
+import { describe, expect, it } from 'vitest'
+
+import App from '../App.vue'
+import { WaveformChart } from '../components'
+
+describe('plot margin demo controls', () => {
+  it('updates the chart top and bottom margins from the sidebar', async () => {
+    const wrapper = mount(App)
+    await flushPromises()
+    const chart = wrapper.getComponent(WaveformChart)
+    const controls = wrapper.get('.plot-margin-controls').findAllComponents(InputNumber)
+
+    expect(controls).toHaveLength(2)
+    expect(controls[0]?.props('value')).toBe(18)
+    expect(controls[1]?.props('value')).toBe(52)
+    expect(chart.props('plotMargin')).toEqual({ top: 18, bottom: 52 })
+
+    controls[0]?.vm.$emit('update:value', 30)
+    controls[1]?.vm.$emit('update:value', 70)
+    await flushPromises()
+
+    expect(chart.props('plotMargin')).toEqual({ top: 30, bottom: 70 })
+    expect(wrapper.get('.waveform-chart').attributes('data-plot-margin-top')).toBe('30')
+    expect(wrapper.get('.waveform-chart').attributes('data-plot-margin-bottom')).toBe('70')
+    wrapper.unmount()
+  })
+})

package/src/demo/types.ts

@@ -10,6 +10,7 @@ import type {
   WaveformLegendPosition,
   WaveformLineStyle,
   WaveformOverlayMode,
+  WaveformPlotMargin,
   WaveformTitleOptions,
   WaveformZeroLineOptions,
   WaveformZoomEndPayload,
@@ -26,6 +27,8 @@ export interface DemoControlPanelModel {
   displayMode: WaveformDisplayMode
   overlayMode: WaveformOverlayMode
   showTooltip: boolean
+  plotMarginTop: number
+  plotMarginBottom: number
   cleanView: boolean
   presentationMode: boolean
   selectedSeriesId: string
@@ -83,7 +86,6 @@ export interface DemoControlPanelModel {
 
 export interface DemoChartModel {
   data: WaveformData
-  minZoomSpan?: number
   initialXDomain?: [number, number]
   displayMode: WaveformDisplayMode
   overlayMode: WaveformOverlayMode
@@ -99,6 +101,7 @@ export interface DemoChartModel {
   cleanView: boolean
   presentationMode: boolean
   showTooltip: boolean
+  plotMargin: WaveformPlotMargin
   zeroLine: WaveformZeroLineOptions
   frameWatermarkVisible: boolean
   annotations: WaveformAnnotation[]

package/src/index.ts

@@ -17,6 +17,7 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformLegendPosition,

package/src/styles.css

@@ -195,6 +195,7 @@ body {
 }
 
 .frame-style-controls,
+.plot-margin-controls,
 .auxiliary-style-controls {
   display: grid;
   gap: 10px;

package/src/types/chart.ts

@@ -74,6 +74,14 @@ export interface WaveformRenderingOptions {
   errorBarMinSpacing?: number
 }
 
+/** Pixel margins reserved above and below the waveform plotting area. */
+export interface WaveformPlotMargin {
+  /** Space between the top of the drawing SVG and the plotting area. Defaults to 18. */
+  top?: number
+  /** Space between the plotting area and the bottom of the drawing SVG. Defaults to 52. */
+  bottom?: number
+}
+
 /** Text styling for the chart-level title. */
 export interface WaveformTitleTextStyle {
   color?: string

package/src/types/index.ts

@@ -12,6 +12,7 @@ export type {
   WaveformAnnotationStyle,
   WaveformAnnotation,
   WaveformRenderingOptions,
+  WaveformPlotMargin,
   WaveformTitleTextStyle,
   WaveformTitleOptions,
   WaveformLegendPosition,

package/src/utils/formatters.test.ts

@@ -40,10 +40,11 @@ describe('waveform number formatters', () => {
     expect(formatScientificAxisExponent(0.0001, 0.0003)).toBe('E-04')
   })
 
-  it('derives the exponent from Math.max(axisMin, axisMax)', () => {
+  it('derives the exponent from the largest absolute endpoint', () => {
     expect(resolveScientificAxisExponent(-9000, -1000)).toBe(3)
-    expect(resolveScientificAxisExponent(-10_000, 3000)).toBe(3)
-    expect(resolveScientificAxisExponent(-1000, 0)).toBeNull()
+    expect(resolveScientificAxisExponent(-100_000, -3000)).toBe(5)
+    expect(resolveScientificAxisExponent(-10_000, 3000)).toBe(4)
+    expect(resolveScientificAxisExponent(-1000, 0)).toBe(3)
     expect(resolveScientificAxisExponent(0, 0)).toBeNull()
   })
 

package/src/utils/formatters.ts

@@ -42,8 +42,7 @@ export function shouldUseScientificAxisLabel(maxAbsoluteValue: number): boolean
 export function resolveScientificAxisExponent(axisMin?: number, axisMax?: number): number | null {
   if (typeof axisMin !== 'number' || typeof axisMax !== 'number') return null
 
-  const maxValue = Math.max(axisMin, axisMax)
-  const absoluteMaxValue = Math.abs(maxValue)
+  const absoluteMaxValue = Math.max(Math.abs(axisMin), Math.abs(axisMax))
   return shouldUseScientificAxisLabel(absoluteMaxValue)
     ? Math.floor(Math.log10(absoluteMaxValue))
     : null

package/src/utils/sampling.ts

@@ -37,7 +37,8 @@ export function downsampleLTTB(data: WaveformPoint[], threshold: number): Wavefo
 
   // 确保阈值至少为 3
   const sampledLength = Math.max(3, Math.floor(threshold))
-  const sampled: WaveformPoint[] = new Array(sampledLength)
+  const sampled: WaveformPoint[] = []
+  sampled.length = sampledLength
 
   // 始终保留第一个和最后一个点
   sampled[0] = data[0]!