README.md

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

# DIRECT — Adaptive Sampling, Reconstruction & Registration

Pretrained models that jointly learn adaptive \(k\)-space sampling, reconstruction, and motion registration for dynamic MRI.

- Paper: [arXiv:2411.18249](https://arxiv.org/abs/2411.18249)
- Companion (sampling + recon only, MIDL 2026): [PMLR](https://proceedings.mlr.press/v315/yiasemis26a.html) · Hub [`NKI-AI/direct-e2e-ads-recon`](https://huggingface.co/NKI-AI/direct-e2e-ads-recon)
- Framework: [DIRECT](https://github.com/NKI-AI/direct)

## Dataset

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

## Models

Each experiment is a `.yaml` + `.pt` pair:

| Name | Notes |
|------|-------|
| `vsharp_ads_1d_phase_reg` | vSHARP + ADS phase-specific + registration (end-to-end) |
| `varnet_ads_1d_phase_reg` | VarNet + ADS phase-specific + registration |
| `vsharp_ads_1d_reg` | vSHARP + ADS unified + registration |
| `varnet_ads_1d_reg` | VarNet + ADS unified + registration |
| `vsharp_ads_1d_phase_init_reg` | Phase-specific + sampling init |
| `vsharp_ads_1d_init_reg` | Unified + sampling init |
| `*_disjoint` | Stage-wise training (`train_end_to_end: false`) |
| `vsharp_fixed_1d_*` | Fixed (non-adaptive) sampling baselines |
| `vsharp_loupe_1d_*` | LOUPE / optimized-sampling baselines |

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

## Training protocol

Same data domain as the companion E2E-ADS-Recon models: CMRxRecon cine with mixed discrete accelerations (typically \(R \in \{4.0327, 6, 8.2\}\), or init variants) and ACS `center_fractions` of matching length (usually `0.04`).

Released inference YAMLs pin **one** active \(R\) / ACS (default `val-4x`). Other rates are **commented** under `masking` — uncomment to switch (same `{name}.pt`).

## 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-reg --local-dir ./e2e_ads_recon_reg

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

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

These models include a `registration_model`, so inference YAMLs enable registration transforms that build a `reference_image` (default: drop frame index `6` via `FROM_KEY`). Volumes must have enough temporal frames for that index. To use a different reference frame, edit:

```yaml
transforms:
  registration:
    registration: true
    registration_simulate_reference: FROM_KEY
    registration_simulate_reference_from_key_index: 6
    registration_estimate_displacement: false
```

## 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
@article{yiasemis2024e2eadsreg,
  title={Deep End-to-End Adaptive k-Space Sampling, Reconstruction, and Registration for Dynamic {MRI}},
  author={Yiasemis, George and Moriakov, Nikita and Sonke, Jan-Jakob and Teuwen, Jonas},
  journal={arXiv preprint arXiv:2411.18249},
  year={2024}
}
```