README.md

---
license: apache-2.0
library_name: direct
tags:
  - mri
  - reconstruction
  - modulated-convolution
  - fastmri
  - conditional
pipeline_tag: image-to-image
---

# DIRECT — Modulated Convolution for Conditional MRI Reconstruction

Pretrained vSHARP models with **modulated convolutions** (and baselines) that condition reconstruction on acceleration \(R\) and ACS fraction at inference time.

- Paper (MIDL 2026, PMLR 315): [Conditional Learned Reconstruction for Medical Imaging](https://proceedings.mlr.press/v315/moriakov26a.html)
- OpenReview: [PDF](https://openreview.net/pdf?id=qNjleGZJis)
- Project configs: [`projects/modulated_convolution`](https://github.com/NKI-AI/direct/tree/main/projects/modulated_convolution)

## Datasets

| Anatomy | Dataset | Link |
|---------|---------|------|
| Knee | fastMRI knee (multi-coil) | [fastmri.med.nyu.edu](https://fastmri.med.nyu.edu/) |
| Prostate | fastMRI prostate (multi-coil) | [fastmri.med.nyu.edu](https://fastmri.med.nyu.edu/) |

## Models

```text
knee/<name>.yaml + knee/<name>.pt
prostate/<name>.yaml + prostate/<name>.pt
```

### Knee

| Name | Description |
|------|-------------|
| `vsharp_triang` | Non-modulated vSHARP baseline (triangular \(R\) sampling) |
| `vsharp_modconv_features_triang` | ModConv features, triangular |
| `vsharp_modconv_features_triang_32_16` | ModConv features, MLP 32→16 |
| `vsharp_modconv_features_triang_32_8` | ModConv features, MLP 32→8 |
| `vsharp_modconv_features_triang_32_16_mod_inp` | ModConv at input |

### Prostate

| Name | Description |
|------|-------------|
| `vsharp_triang` | Non-modulated baseline |
| `vsharp_modconv_features_triang` | ModConv features |
| `vsharp_modconv_features_triang_32_16` | ModConv features, MLP 32→16 |
| `vsharp_modconv_features_triang_32_8` | ModConv features, MLP 32→8 |

## Training protocol

Training samples acceleration in a triangular / range schedule (typically \(R \in [4, 16]\)) with paired ACS `center_fractions` (e.g. `[0.08, 0.02]`) under `FastMRIEquispaced`. Models are conditioned on the realized \(R\) / ACS so a single checkpoint covers the training range.

Released inference YAMLs pin **exactly one** \(R\) and **one** ACS (default validation 4×: `accelerations: [4]`, `center_fractions: [0.08]`). Keep lists of length 1 when changing rate:

| Target \(R\) | `accelerations` | `center_fractions` |
|-------------|-----------------|--------------------|
| 4× | `[4]` | `[0.08]` |
| 8× | `[8]` | `[0.04]` |
| 16× | `[16]` | `[0.02]` |

## 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-modulated-convolution --local-dir ./modconv

direct predict ./predictions \
  --cfg ./modconv/knee/vsharp_modconv_features_triang_32_8.yaml \
  --checkpoint ./modconv/knee/vsharp_modconv_features_triang_32_8.pt \
  --data-root /path/to/fastmri/knee/multicoil_val \
  --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{moriakov2026modconv,
  title={Conditional Learned Reconstruction for Medical Imaging},
  author={Moriakov, Nikita and Yiasemis, George and Sonke, Jan-Jakob and Teuwen, Jonas},
  booktitle={Medical Imaging with Deep Learning},
  year={2026},
  url={https://proceedings.mlr.press/v315/moriakov26a.html}
}
```