| --- |
| license: other |
| license_name: ambiq-model-weights-license |
| license_link: https://github.com/AmbiqAI/compressionkit/blob/main/LICENSE-MODEL-WEIGHTS.md |
| library_name: compressionkit |
| pipeline_tag: other |
| tags: |
| - compressionkit |
| - signal-compression |
| - ppg |
| - rvq |
| - tflite |
| - edge-ai |
| --- |
| |
| # compressionkit-ppg-2x |
|
|
| A **PPG** signal compression codec using Residual Vector Quantization (RVQ), optimized for edge and wearable devices. |
|
|
| ## Model Details |
|
|
| - **Modality:** PPG |
| - **Sample Rate:** 64 Hz |
| - **Compression Ratio:** 2x |
| - **Quantization:** INT8 |
| - **RVQ Levels:** 4 |
| - **Codebook Size:** 256 entries × 16D |
| - **Encoder Input:** `[None, 1, 320, 1]` |
| - **Encoder Output:** `[None, 1, 160, 16]` |
|
|
| ## Quality Metrics |
|
|
| ### Time Domain |
|
|
| | Metric | Mean | Median | P90 | |
| |--------|------|--------|-----| |
| | PRD (%) | 6.1800 | 2.2707 | 10.7564 | |
| | RMSE | 0.0241 | 0.0199 | 0.0386 | |
| | Cosine Similarity | 0.9912 | 0.9998 | 0.9999 | |
|
|
| ### Spectral |
|
|
| - **Band Total Relative Error (median):** 0.0263 |
|
|
| ### Bitrate |
|
|
| - **Codec CR (uniform):** 2.0x |
| - **Codec CR (learned prior):** 3.11x |
|
|
| ## Usage |
|
|
| ### Python (compressionkit runtime) |
|
|
| ```python |
| from compressionkit.runtime import RVQCodec |
| |
| codec = RVQCodec.from_pretrained("Ambiq/compressionkit-ppg-2x") |
| |
| # Encode: float32 signal → RVQ indices |
| indices = codec.encode(signal) |
| |
| # Decode: RVQ indices → reconstructed signal |
| recon = codec.decode(indices) |
| ``` |
|
|
| ### Local deployment directory |
|
|
| ```python |
| codec = RVQCodec("path/to/deploy/") |
| ``` |
|
|
| ## Files |
|
|
| | File | Description | |
| |------|-------------| |
| | `encoder_int8.tflite` | INT8 quantized encoder (on-device) | |
| | `encoder.h` | C header for encoder | |
| | `decoder_float32.tflite` | Float32 decoder (server-side evaluation) | |
| | `decoder_int8.tflite` | INT8 decoder (optional, on-device) | |
| | `codebook.npz` | RVQ codebook tables | |
| | `codebook.h` | C header for codebook | |
| | `config.json` | Deployment manifest | |
| | `sample_stimulus.npz` | Synthetic test data | |
| | `quality_scorecard.json` | Full evaluation metrics | |
|
|
| ## Dataset & License |
|
|
| Training data: MESA (NSRR restricted). Sample data uses synthetic physiokit waveforms only — no patient data is redistributed. |
|
|
| Model weights are released under the **Ambiq Model Weights License** — deployment is restricted to Ambiq silicon devices. See `LICENSE-MODEL-WEIGHTS.md` for full terms. |
|
|
| ## Citation |
|
|
| ```bibtex |
| @software{compressionkit, |
| author = {Ambiq AI}, |
| title = {compressionKIT: Signal Compression for Edge AI}, |
| url = {https://github.com/AmbiqAI/compressionkit} |
| } |
| ``` |
|
|
