ECG Toolkit Rust Crate - Documentation

Overview

The ECG Toolkit is a Rust library for reading, writing, converting, and processing electrocardiogram (ECG) medical data files. It is a conversion of the C# ECG Conversion Toolkit originally written by Maarten JB van Ettinger.

License: Apache License, Version 2.0
Original author: Maarten JB van Ettinger
Original source: van Ettinger Information Technology / Thoraxcentrum, Erasmus MC

Crate Structure

The crate is organized into seven modules:

ecgtoolkit/
├── types/          Core type definitions (LeadType, Date, enums)
├── signal/         ECG signal data (Signal, Signals, QrsZone)
├── demographics/   Patient demographic data (Demographic trait, Drug, AcquiringDeviceId)
├── diagnostic/     Diagnostic statements (Statements, DiagnosticStatements trait)
├── measurements/   ECG measurements (GlobalMeasurement, LeadMeasurement, Spike, Morphology)
├── dsp/            Digital signal processing (Butterworth filters, FIR, IIR)
├── converter/      Format conversion interfaces (EcgFormat trait, EcgConfig)
└── tools/          Utility functions (lead calculations, resampling, anonymization)

Module: `types`

Core type definitions used throughout the library.

`LeadType`

Enumeration of 150+ ECG lead types. Matches the C# LeadType enum values exactly.

use ecgtoolkit::types::LeadType;

let lead = LeadType::V1;
let lead_from_byte = LeadType::from_u8(3); // V1
assert_eq!(lead, lead_from_byte);

Standard 12-lead types: I, II, III, AVR, AVL, AVF, V1-V6.

Extended types include: V7-V9, V2R-V7R, X, Y, Z, Frank leads, derived leads (prefixed with D), and many more.

The from_u8 method safely converts a byte to a LeadType, returning Unknown for out-of-range values.

`LeadTypeVitalRefId`

MDC (Medical Device Communication) reference IDs for lead types. Maps to standard vital signs identifiers (e.g., MdcEcgLeadI = 1, MdcEcgLeadIII = 61).

`Date`

Simple date type with year, month, and day fields, matching the SCP format.

use ecgtoolkit::types::Date;

let date = Date::new(2024, 6, 15);
assert!(date.is_existing_date());

// Leap year validation
assert!(Date::new(2024, 2, 29).is_existing_date());
assert!(!Date::new(2023, 2, 29).is_existing_date());

Demographic Enums

Enum	Variants
`Sex`	Unspecified, Male, Female, Null
`Race`	Unspecified, Caucasian, Black, Oriental, Null
`AgeDefinition`	Unspecified, Years, Months, Weeks, Days, Hours
`HeightDefinition`	Unspecified, Centimeters, Inches, Millimeters
`WeightDefinition`	Unspecified, Kilogram, Gram, Pound, Ounce
`DeviceType`	Cart, System
`DeviceManufacturer`	Unknown, Burdick, Cambridge, ... Other (21 variants)
`ElectrodeConfigCodeTwelveLead`	Unspecified, StandardTwelveLead, ... (7 variants)
`ElectrodeConfigCodeXyz`	Unspecified, Frank, ... (7 variants)

Module: `signal`

ECG signal data structures.

`Signal`

Represents one ECG lead/channel.

use ecgtoolkit::signal::Signal;
use ecgtoolkit::types::LeadType;

let sig = Signal {
    lead_type: LeadType::I,
    rhythm_start: 0,
    rhythm_end: 1000,
    rhythm: Some(vec![0i16; 1000]),
    median: None,
};

Key methods:

apply_filter(rhythm_filter, median_filter) — Apply DSP filters, returning a new Signal
Signal::is_normal(leads) — Check if first 8 leads are I, II, V1-V6
Signal::nr_simultaneously(leads) — Count leads recorded at the same time (within 5-sample tolerance)
Signal::sort_on_type(leads) — Sort leads by type (quicksort)

`Signals`

Container for all ECG signal leads with metadata.

use ecgtoolkit::signal::Signals;

let mut sigs = Signals::with_nr_leads(12);
sigs.rhythm_avm = 2.5;              // Analog value multiplier in mV
sigs.rhythm_samples_per_second = 500;

Key methods:

Method	Description
`nr_leads()` / `set_nr_leads()`	Get/set number of leads
`get(i)` / `get_mut(i)`	Access lead by index
`set_leads(leads)`	Set all leads (max 255)
`is_normal()`	Check standard 8-lead order
`is_twelve_leads()`	Detect 12-lead configuration
`is_fifteen_leads()`	Detect 15-lead configuration (both variants)
`calculate_twelve_leads()`	Derive 12 leads from 8 (I, II, V1-V6)
`calculate_start_and_end()`	Get signal time boundaries
`nr_simultaneously()`	Count simultaneous leads
`sort_on_type()`	Sort leads by type
`trim_signals(val)`	Remove leading/trailing padding
`resample(sps)`	Resample all leads to new rate
`set_avm(avm)`	Change analog value multiplier
`apply_bandpass_filter(lo, hi)`	Apply Butterworth bandpass filter
`apply_lowpass_filter(cutoff)`	Apply Butterworth lowpass filter
`apply_highpass_filter(cutoff)`	Apply Butterworth highpass filter

`QrsZone`

Describes a QRS complex zone with start, fiducial point, and end positions.

Module: `demographics`

Patient and device identification data.

`Demographic` Trait

Defines 40+ getter/setter methods for patient demographics. Implementations provide access to:

Patient identity: last name, first name, patient ID, prefix/suffix
Physical data: age (with units), height, weight, sex, race
Device IDs: acquiring and analyzing machine identifiers
Acquisition info: timestamp, filters, blood pressure
Institutional: institution, department, physicians, technician
Clinical: drugs, referral indication, room description, stat code

`AcquiringDeviceId`

Device identification with institution number, department, device ID, manufacturer, capabilities, and model description.

use ecgtoolkit::demographics::AcquiringDeviceId;

let device = AcquiringDeviceId::no_device();
assert_eq!(&device.model_description[..5], b"MCONV");

`Drug`

Simple drug record with class, code, and text description.

Module: `diagnostic`

`Statements`

Diagnostic interpretation statements for an ECG.

use ecgtoolkit::diagnostic::Statements;

let stmt = Statements {
    confirmed: true,
    interpreted: true,
    time: 1700000000,
    statement: Some(vec!["Normal sinus rhythm".to_string()]),
};

`DiagnosticStatements` Trait

Interface for getting and setting diagnostic statements.

Module: `measurements`

ECG measurement data at both global and per-lead levels.

`GlobalMeasurement`

One wave measurement (SCP/UNIPRO defined) containing P/QRS/T onset/offset values and axis measurements.

use ecgtoolkit::measurements::GlobalMeasurement;

let mut m = GlobalMeasurement::default();
m.set_p_dur(80);      // P-wave duration: 80ms
m.set_qrs_dur(100);   // QRS duration: 100ms
m.set_qt_dur(400);    // QT duration: 400ms

// Calculate corrected QT (Bazett formula)
use ecgtoolkit::measurements::QTcCalcType;
let qtc = m.calc_qtc(800, 75, QTcCalcType::Bazett); // ~447ms

Sentinel values:

NO_VALUE = 29999 — indicates no measurement available (u16)
NO_AXIS_VALUE = 29999 — indicates no axis measurement (i16)

QTc calculation types: Bazett, Hodges, Fridericia, Framingham.

`GlobalMeasurements`

Collection of global measurements including ventricular rate, average RR/PP intervals, spike data, and QTc configuration.

`LeadMeasurement`

Per-lead measurement storage using a BTreeMap keyed by MeasurementType.

use ecgtoolkit::measurements::{LeadMeasurement, MeasurementType};
use ecgtoolkit::types::LeadType;

let mut lm = LeadMeasurement::with_lead_type(LeadType::V1);
lm.set(MeasurementType::Ramp, 1500);
lm.set(MeasurementType::Samp, -500);
assert_eq!(lm.count(), 2);

`MeasurementType`

44 measurement types including durations (Pdur, QRSdur, QTint), amplitudes (Qamp, Ramp, Samp), ST measurements, morphology indices, and wave offsets.

Aliases: RONSET = Qoffset, SONSET = Roffset, etc.

`Morphology`

Wave morphology classification: Positive, Negative, PositiveNegative, NegativePositive, NotchedMShaped, NotchedWShaped, etc.

`Spike`

Pacemaker spike data with time and amplitude.

Module: `dsp`

Digital signal processing filters for ECG data.

`Filter` Trait

pub trait Filter {
    fn compute(&mut self, input: f64) -> f64;
}

All filters implement this trait, allowing runtime polymorphism via Box<dyn Filter>.

Butterworth Filters

Multi-section Butterworth filter implementations for ECG signal processing:

Filter	Usage
`LowpassFilterButterworth`	Remove high-frequency noise
`HighpassFilterButterworth`	Remove baseline wander
`BandpassFilterButterworth`	Isolate frequency band (cascade of lowpass + highpass)

use ecgtoolkit::dsp::{Filter, BandpassFilterButterworth};

let mut filter = BandpassFilterButterworth::new(
    0.5,    // bottom frequency (Hz)
    40.0,   // top frequency (Hz)
    2,      // number of sections
    500.0,  // sample rate (Hz)
);

let output = filter.compute(input_sample);

Each filter is composed of sections (LowpassFilterButterworthSection, HighpassFilterButterworthSection), which internally use FIR and IIR filter building blocks.

`FirFilter` / `IirFilter`

Low-level Finite Impulse Response and Infinite Impulse Response filter implementations used by the Butterworth filter sections.

Module: `converter`

Core interfaces for ECG file format conversion.

`EcgFormat` Trait

Abstract interface that all ECG file format implementations must satisfy. Defines methods for:

Reading from files, streams, or byte buffers
Writing to files, streams, or byte buffers
Format detection (check_format_*)
Access to demographics, diagnostics, signals, and measurements
Anonymization
Format validation

`EcgConfig`

Configuration management for format-specific settings. Supports mandatory and optional configuration keys with validation.

use ecgtoolkit::converter::EcgConfig;

let mut cfg = EcgConfig::new(
    &["sample_rate"],           // mandatory
    &["encoding", "compression"], // optional
    None,                        // no custom check function
);

cfg.set("sample_rate", Some("500"));
assert!(cfg.configuration_works());

Module: `tools`

Utility functions for ECG signal processing.

Lead Calculations

Calculate derived ECG leads from primary leads using standard formulas:

Function	Formula
`calculate_lead_iii`	III = II - I
`calculate_lead_avr`	aVR = -(I + II) / 2
`calculate_lead_avl`	aVL = (2I - II) / 2 or (I - III) / 2
`calculate_lead_avf`	aVF = (2II - I) / 2 or (II + III) / 2
`calculate_leads_from_two`	All four from I and II
`calculate_leads_from_three`	aVR, aVL, aVF from I, II, III

These satisfy Einthoven's law: I + III = II.

Signal Processing

Function	Description
`lead_subtract(a, b)`	Subtract lead B from A in-place
`lead_add(a, b)`	Add lead B to A in-place
`change_multiplier(src, old, new)`	Scale signal values
`copy_signal(src, dst, ...)`	Copy signal data between buffers
`shift_signal(src, shift)`	DC offset removal

Resampling

Polynomial interpolation (Neville's algorithm) for sample rate conversion:

use ecgtoolkit::tools::ecg_tool;

let src = vec![100i16; 500]; // 500 samples at 250 Hz
let dst = ecg_tool::resample_lead(&src, 250, 500); // upsample to 500 Hz

Anonymization

use ecgtoolkit::tools::ecg_tool;

// Replaces patient names, IDs, and birth date with anonymized values
ecg_tool::anonymous(&mut demographics, '*');

ECG Lead Configurations

Standard 12-Lead ECG

The standard 12-lead ECG consists of:

Limb leads: I, II, III (Einthoven triangle)
Augmented leads: aVR, aVL, aVF (Goldberger)
Precordial leads: V1, V2, V3, V4, V5, V6 (Wilson)

The toolkit can derive the full 12 leads from 8 independent leads (I, II, V1-V6) using Einthoven's law and augmented lead formulas.

15-Lead ECG

Two standard 15-lead configurations are supported:

Standard 12 + V3R, V4R, V7 (right-sided and posterior)
Standard 12 + V7, V8, V9 (posterior leads)

Testing

The crate includes 184 comprehensive tests across 7 test modules:

cargo test

Tests cover all modules including:

Type conversions and enum values
Signal lead detection and sorting
All four QTc formulas with clinical ranges
Einthoven's law mathematical verification
DSP filter frequency response characteristics
Resampling accuracy
Configuration management
12-lead and 15-lead detection

Future Work

Format implementations (Phase 7) are planned for:

SCP — Standardized Communications Protocol
HL7 aECG — XML-based annotated ECG
DICOM — Medical imaging standard
ISHNE — Holter format
MUSE XML — GE Healthcare format
Omron ECG — Consumer device format
CSV — Comma-separated values export
PDF — PDF rendering
Raw — Raw binary format

ecgtoolkit 0.1.0

ECG Toolkit Rust Crate - Documentation

Overview

Crate Structure

Module: types

LeadType

LeadTypeVitalRefId

Date

Demographic Enums

Module: signal

Signal

Signals

QrsZone

Module: demographics

Demographic Trait

AcquiringDeviceId

Drug

Module: diagnostic

Statements

DiagnosticStatements Trait

Module: measurements

GlobalMeasurement

GlobalMeasurements

LeadMeasurement

MeasurementType

Morphology

Spike

Module: dsp

Filter Trait