signal-digitizer

Turn a scanned strip-chart / grid-plot PDF (e.g. an ECG trace, an old lab recorder printout) into a calibrated 1D signal.

Pipeline: rasterize page → estimate & correct skew → detect grid lines (Canny + Hough) → calibrate axes from grid spacing → extract ink trace → optional adaptive noise cancellation (LMS/NLMS) → calibrated (x, y) signal.

This is a plain library that depends on the official pymupdf package from PyPI — it does not fork, patch, or vendor PyMuPDF in any way, so it installs cleanly alongside any other project using pymupdf.

Install

pip install signal-digitizer

(For local development, from this directory: pip install -e .)

Usage

import signal_digitizer as sd

x, y = sd.digitize(
    "chart.pdf",
    page_number=0,
    unit_per_vgap=1.0,
    unit_per_hgap=1.0,
)

# With adaptive noise cancellation (self-referencing Adaptive Line Enhancer)
x, y = sd.digitize("chart.pdf", use_anc=True, anc_mu=0.05, anc_filter_order=8)

# Validate against a ground-truth signal
result = sd.validate_signal(y, reference_signal)
print(result)  # {"pearson_r": ..., "rmse": ..., "meets_target": ...}

Working from an already-open pymupdf document

import pymupdf
import signal_digitizer as sd

doc = pymupdf.open("chart.pdf")
x, y = sd.digitize_page(doc[0], dpi=300, unit_per_vgap=1.0, unit_per_hgap=1.0)

From a numpy image you've already rasterized

x, y = sd.digitize_image(image_array, unit_per_vgap=1.0, unit_per_hgap=1.0)

CLI

signal-digitizer chart.pdf --page 0 -o signal.csv

# with adaptive noise cancellation
signal-digitizer chart.pdf --page 0 --use-anc --anc-mu 0.05 --anc-filter-order 8 -o signal.csv

API

• digitize(pdf_path, ...) — full pipeline from a PDF file path
• digitize_page(page, ...) — full pipeline from an open pymupdf.Page
• digitize_image(image, ...) — full pipeline from a numpy RGB image
• render_page, render_pymupdf_page — rasterization only
• estimate_skew_deg, deskew — skew correction
• detect_grid, GridLines — grid-line detection
• calibrate_from_grid, AxisCalibration — pixel → data-unit calibration
• extract_trace_pixels, to_signal — ink trace extraction
• AdaptiveNoiseCanceller, denoise_adaptive, build_self_reference — LMS/NLMS denoising
• validate_signal — Pearson-r / RMSE comparison against a reference signal

Key digitize() parameters

License

MIT. See LICENSE.