| --- |
| license: mit |
| library_name: onnx |
| pipeline_tag: image-to-image |
| tags: |
| - ecg |
| - electrocardiogram |
| - document-dewarping |
| - onnx |
| --- |
| |
| # ECG photo rectifier |
|
|
| Turns a phone photo of a paper ECG (a strip or a sheet with one continuous grid; bent, crumpled, |
| folded, held in a hand) into a flat sheet with a square grid at 10 px/mm. CPU only: numpy, OpenCV and |
| onnxruntime; no GPU, no PyTorch. |
|
|
| **Live demo:** https://huggingface.co/spaces/pashaalex/ECG-Rectifier — upload a photo, get the flat sheet. |
|
|
| ``` |
| git clone https://huggingface.co/pashaalex/ecg-rectifier # the models need git-lfs or git-xet |
| cd ecg-rectifier |
| pip install -r requirements.txt |
| python3 rectify.py examples/folded.jpg flat.png |
| ``` |
|
|
| Without git: `pip install huggingface_hub && hf download pashaalex/ecg-rectifier --local-dir ecg-rectifier`. |
|
|
| Run the web demo locally: `pip install gradio && python3 app.py`. |
|
|
| ## Examples |
|
|
| Phone photos of printed synthetic ECGs (no patient data), rectified with |
| `python3 rectify.py examples/folded.jpg flat.png --illum`: |
|
|
| | photo | flat sheet (`flat-illum.jpg`; empty corners outside the photo filled with paper colour) | |
| |---|---| |
| |  |  | |
| |  |  | |
|
|
| ## Output |
|
|
| | file | content | |
| |---|---| |
| | `flat.png` | the flat sheet, 10 px/mm, cropped to the sheet (any OpenCV format; `.png` is lossless) | |
| | `flat.json` | status, reason, self-check, photo scale, timings | |
| | `flat-check.jpg` | the photo with the mask (blue), working area (yellow), crop (green) and grid nodes used (red) | |
|
|
| Options: `--illum` also writes `flat-illum.jpg` with shadows and the lamp tint removed |
| (`--illum-paper keep` keeps the paper colour); `--redshift` recolours dark lines red before the |
| networks, for black or grey grids. |
|
|
| Statuses: `ok`, `warn`, `fail`; `no_grid` (no 5 mm grid found: the masked crop is written without |
| rectification); `too_small` (sheet < 50 x 30 mm); `not_applicable` (the grid falls into separate |
| pieces, e.g. Holter reports with framed strips). Exit code 0 means an image was written. |
|
|
| ## How it works |
|
|
| 1. `mask.onnx` — a coarse mask of the ECG signal on the whole photo; the photo is cropped to it. |
| 2. Photo scale (px/mm): the detector is run at several assumed scales; the right one gives a lattice |
| with a 5 mm step, confirmed by four thin 1 mm lines inside each 5 mm cell. |
| 3. The crop is resized to 5.5 px/mm; `detector.onnx` finds the intersections of the bold 5 mm lines. |
| 4. `offsets.onnx` predicts, for overlapping 224 px windows, where on the sheet (mm) each of 7 x 7 patch |
| centres lies; the windows are fused into one smooth map photo pixel -> sheet mm (least squares). |
| 5. `lattice.onnx` (a graph network) numbers the detected nodes (i, j); node (i, j) must lie at (5i, 5j) mm. |
| 6. The map is corrected by the numbered nodes: a cubic polynomial (or a homography, whichever fits |
| the held-out nodes better), then a smooth local correction table. |
| 7. The flat sheet is resampled from the original photo by inverting the map. |
|
|
| The self-check fits the correction on half of the nodes (chessboard by i + j) and measures the other |
| half after a best similarity. It measures the shape of the grid, not the absolute scale, and it does |
| not see detector errors; judge the result by eye. |
|
|
| ## Repository |
|
|
| - `rectify.py` — the pipeline; `ecglib/` — its building blocks; `models/` — the four ONNX networks; |
| `examples/` — the photos above; `app.py` — the web demo (Gradio). |
| - `training/` — synthetic data generators and training scripts of the networks (see `training/README.md`); |
| photos are rendered with [MeshAugmentor](https://github.com/pashaalex/mesh_augmentor). |
|
|
| ## License |
|
|
| MIT (`LICENSE`). The fonts in `training/fonts/` keep their own licences (SIL OFL 1.1 for Caveat, |
| Bitstream Vera / DejaVu for DejaVu Sans Mono). |
|
|
