README.md

---
license: apache-2.0
library_name: direct
tags:
  - mri
  - reconstruction
  - adaptive-sampling
  - dynamic-mri
  - cmrxrecon
pipeline_tag: image-to-image
---

# DIRECT — End-to-End Adaptive Sampling & Reconstruction

Pretrained models for joint learning of an adaptive \(k\)-space sampler and a reconstruction network on dynamic MRI (MIDL 2026).

- Paper (PMLR): [End-to-End Co-Optimization of Adaptive k-space Sampling and Reconstruction for Dynamic MRI](https://proceedings.mlr.press/v315/yiasemis26a.html)
- OpenReview: [forum](https://openreview.net/forum?id=0yrf87zVf2)
- Related: [arXiv:2403.10346](https://arxiv.org/abs/2403.10346)
- Companion (with registration): [`NKI-AI/direct-e2e-ads-recon-reg`](https://huggingface.co/NKI-AI/direct-e2e-ads-recon-reg)

## Dataset

| | |
|---|---|
| **Data** | [CMRxRecon](https://cmrxrecon.github.io/) multi-coil cardiac cine |
| **Challenge / site** | [cmrxrecon.github.io](https://cmrxrecon.github.io/) |
| **Task** | Adaptive sampling + reconstruction under a fixed acceleration budget |

## Models

Each experiment is a `.yaml` + `.pt` pair (inference YAML active at **4×**; other rates are commented under `masking`):

| Name | Reconstruction | Sampler |
|------|----------------|---------|
| `vsharp_ads_1d` | vSHARP | ADS 1D, unified mask |
| `medl_ads_1d` | MEDL | ADS 1D, unified |
| `vsharp_ads_1d_frame` | vSHARP | ADS 1D, frame-specific |
| `medl_ads_1d_frame` | MEDL | ADS 1D, frame-specific |
| `vsharp_ads_1d_init2` | vSHARP | ADS 1D unified + init |
| `medl_ads_1d_init2` | MEDL | ADS 1D unified + init |
| `vsharp_ads_1d_frame_init2` | vSHARP | ADS 1D frame-specific + init |
| `medl_ads_1d_frame_init2` | MEDL | ADS 1D frame-specific + init |
| `vsharp_ads_2d` | vSHARP | ADS 2D, unified |
| `medl_ads_2d` | MEDL | ADS 2D, unified |
| `vsharp_ads_2d_frame` | vSHARP | ADS 2D, frame-specific |
| `medl_ads_2d_frame` | MEDL | ADS 2D, frame-specific |

Full training configs: [`projects/e2e_ads_recon`](https://github.com/NKI-AI/direct/tree/main/projects/e2e_ads_recon).

## Acceleration rates

Hub YAMLs pin **one** active `accelerations` / `center_fractions` pair (default `val-4x`). To run another trained rate, uncomment the matching block under `masking` (and comment out the active lists). For `*init2*`, also update `target_acceleration`.

## Install DIRECT

```bash
git clone https://github.com/NKI-AI/direct.git
cd direct
conda create --name direct python=3.12
conda activate direct
pip install meson-python meson ninja
pip install --no-build-isolation -e ".[dev]"
```

## Usage

```bash
hf download NKI-AI/direct-e2e-ads-recon --local-dir ./e2e_ads_recon

direct predict ./predictions \
  --cfg ./e2e_ads_recon/vsharp_ads_1d.yaml \
  --checkpoint ./e2e_ads_recon/vsharp_ads_1d.pt \
  --data-root /path/to/cmrxrecon \
  --num-gpus 1
```

The first argument is the **prediction output directory**.

## Citation

If you use these models or [DIRECT](https://github.com/NKI-AI/direct), please cite the DIRECT toolkit and the method paper(s) below.

### DIRECT

```bibtex
@article{DIRECTTOOLKIT,
  title={DIRECT: Deep Image REConstruction Toolkit},
  author={Yiasemis, George and Moriakov, Nikita and Karkalousos, Dimitrios and Caan, Matthan and Teuwen, Jonas},
  journal={Journal of Open Source Software},
  volume={7},
  number={73},
  pages={4278},
  year={2022},
  doi={10.21105/joss.04278},
  url={https://doi.org/10.21105/joss.04278}
}
```

### Method

```bibtex
@inproceedings{yiasemis2026e2eads,
  title={End-to-End Co-Optimization of Adaptive k-space Sampling and Reconstruction for Dynamic {MRI}},
  author={Yiasemis, George and Moriakov, Nikita and Sonke, Jan-Jakob and Teuwen, Jonas},
  booktitle={Medical Imaging with Deep Learning},
  year={2026}
}
```