Metadata-Version: 2.4
Name: signal-digitizer
Version: 0.2.0
Summary: A Python library for converting scanned strip charts and grid-plot PDFs into calibrated one-dimensional signals.
Author: Manoj Kumar C S, V N Manjunath Aradhya, Nikhil D Bharadwaj
Maintainer: Manoj Kumar C S, Nikhil D Bharadwaj
License: MIT
Project-URL: Homepage, https://gitlab.com/manojkumarcs/signal-digitizer
Project-URL: Repository, https://gitlab.com/manojkumarcs/signal-digitizer
Project-URL: Issues, https://gitlab.com/manojkumarcs/signal-digitizer/-/issues
Keywords: signal digitization,chart digitization,graph digitization,strip chart,grid plot,PDF signal extraction,PDF processing,ECG digitization,ECG signal,signal processing,time series,scientific computing,image processing,computer vision,PyMuPDF,OpenCV,digital signal processing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymupdf>=1.24
Requires-Dist: numpy>=1.22
Requires-Dist: opencv-python-headless>=4.6
Requires-Dist: scipy>=1.8
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://gitlab.com/manojkumarcs/signal-digitizer/-/raw/main/assets/signal.png"
       alt="signal-digitizer logo"
       width="800">
</p>

# signal-digitizer

`signal-digitizer` is a Python library for converting scanned charts and grid-based plots into calibrated one-dimensional signals. It is designed for applications such as ECG traces, laboratory recorder outputs, and other plotted signals stored as PDF documents.

The library processes a chart by rendering the page, correcting skew, detecting the grid, extracting the signal trace, and converting pixel coordinates into calibrated signal values.

## Package Information

[![Python Versions](https://img.shields.io/pypi/pyversions/signal-digitizer.svg)](https://pypi.org/project/signal-digitizer/)
[![PyPI Version](https://img.shields.io/pypi/v/signal-digitizer.svg)](https://pypi.org/project/signal-digitizer/)

## Installation

```bash
pip install signal-digitizer
```

## Quick Start

```python
import signal_digitizer as sd

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

The returned `x` and `y` arrays contain the extracted and calibrated signal coordinates.

## Command Line Usage

```bash
signal-digitizer chart.pdf -o signal.csv
```

This processes the input PDF and saves the extracted signal to a CSV file.

## How It Works

The digitization workflow consists of the following stages:

1. **Page rendering** – The input PDF page is converted into an image.
2. **Skew correction** – Page rotation is estimated and corrected.
3. **Grid detection** – Grid lines are identified using image-processing techniques.
4. **Calibration** – Grid spacing is used to convert pixel coordinates into data units.
5. **Trace extraction** – The plotted signal is separated from the chart image.
6. **Signal generation** – The extracted trace is converted into calibrated `x` and `y` values.

## Main API

### `digitize()`

Processes a PDF file through the complete signal digitization pipeline.

```python
x, y = sd.digitize(
    "chart.pdf",
    unit_per_vgap=1.0,
    unit_per_hgap=1.0,
)
```

### `digitize_page()`

Processes an already opened PyMuPDF page.

```python
import pymupdf
import signal_digitizer as sd

document = pymupdf.open("chart.pdf")

x, y = sd.digitize_page(
    document[0],
    unit_per_vgap=1.0,
    unit_per_hgap=1.0,
)
```

### `digitize_image()`

Processes an image that has already been loaded as a NumPy array.

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

## Core Functionality

The library includes functionality for:

- PDF page rendering
- Skew estimation and correction
- Grid-line detection
- Axis calibration
- Signal trace extraction
- Conversion of extracted traces into calibrated signals
- Signal validation using Pearson correlation and RMSE

## Signal Validation

If a reference signal is available, the extracted signal can be evaluated using:

```python
result = sd.validate_signal(y, reference_signal)
print(result)
```

The validation result includes correlation and error-based measures for comparing the extracted signal with the reference.

## Requirements

`signal-digitizer` requires Python 3.9 or later.

Its core dependencies include:

- PyMuPDF
- NumPy
- OpenCV
- SciPy

These dependencies are installed automatically with the package.

## Authors

- Manoj Kumar C S
- V N Manjunath Aradhya
- Nikhil D Bharadwaj

## Maintainers

- Manoj Kumar C S
- Nikhil D Bharadwaj

## License

This project is distributed under the MIT License. See the [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.com/manojkumarcs/signal-digitizer/-/blob/main/LICENSE) file for details.
