DIRECT: an MRI reconstruction toolkit built around YAML configs and a command line

The gap DIRECT fills between a paper implementation and a training run

Most MRI reconstruction papers ship a model definition and a script that assumes the authors' directory structure. Reproducing a result then means rebuilding the sampling logic, the coil sensitivity handling, the metric computation and the data loading before you can check whether the network itself is the part you care about. DIRECT addresses that by treating the whole chain as the deliverable: undersampled multi-coil k-space goes in, and sampling, reconstruction, optional registration and metrics come out, in the project's own words, end to end. The audience is therefore not radiologists or clinical physicists. It is research engineers and PhD students who need to compare an unrolled network against a baseline without writing the surrounding infrastructure first. The presence of a JOSS citation and a papers page suggests the maintainers expect academic use, and the repository layout, with reproducible experiment configs under projects/, points the same way.

What actually flows through the pipeline

The data model is multi-coil k-space, covering static, dynamic and multislice volumes, with coil-sensitivity estimation handled inside the toolkit rather than left to the caller. Sampling is a first-class component: the README lists Cartesian, radial, spiral, Poisson, Gaussian and k-t masks, plus a learned Adaptive Dynamic Sampler that selects lines or pixels under a fixed acceleration budget. That last item is the most unusual piece, because it moves the sampling pattern from a fixed preprocessing decision into something the network can influence. On the reconstruction side the list is long: vSHARP, RecurrentVarNet, VarNet, RIM and CIRIM, LPDNet, XPDNet, IterDualNet, ConjGradNet, Joint-ICNet, KIKI-Net, MultiDomainNet, VarSplitNet, 2D and 3D U-Net, MEDL, and transformer reconstructors (ViT, UFormer) operating in image or k-space. Training supports fully supervised learning, self-supervised SSDU, and JSSL, which combines the two. The conditional and joint pipelines use modulated convolutions to condition an unrolled network on acceleration and ACS fraction, and registration can be learned or classical. Metrics include SSIM, pSNR, NMSE, VIF and HFEN. The breadth is the point and also the risk: a toolkit that implements this many reconstructors carries the maintenance surface of all of them.

Installing and running a pretrained model

The PyPI distribution is named direct-recon while the import name is direct, which is a small trap worth noting before you write a requirements file. A minimal install is pip install direct-recon. For development the README gives a uv-based path: git clone the repository, cd into it, then uv sync. Docker and conda instructions exist but are not reproduced in the README; they are on the installation page of the documentation site. The workflow that matters most for evaluation is the pretrained route. The README shows installing huggingface_hub, then hf download NKI-AI/direct-calgary-campinas --local-dir ./calgary, followed by direct predict ./predictions --cfg ./calgary/rim_5x.yaml --checkpoint ./calgary/rim_5x.pt --data-root /path/to/calgary_campinas --num-gpus 1. Two things stand out in that command. The config and the checkpoint are a matched pair, so a .yaml without its .pt is not useful on its own. And --data-root is a single path, which means your dataset has to present itself in the layout the corresponding config expects, not the other way round. Training is invoked as direct train with a YAML config, and the README mentions distributed multi-GPU training, mixed precision and TensorBoard logging as supported during training.

The checkpoint zoo is a convenience with a versioning cost

Pretrained .yaml and .pt pairs live on Hugging Face under the NKI-AI organisation and are indexed in the model zoo page. The Calgary-Campinas RIM checkpoint at 5x acceleration is the worked example in the README. This is genuinely useful for a first sanity check, because it removes training from the loop entirely. It also creates an obligation the README does not resolve. A checkpoint is bound to the config that produced it, and the config encodes the model class, the sampling scheme and the data assumptions. If a future release changes a default inside a reconstructor, an older .pt may no longer load cleanly against its own .yaml, and the README gives no compatibility statement about which toolkit versions can consume which published checkpoints. The release history shows v2.2.0 in August 2026, v2.1.1 earlier the same month, and v2.1.0 in July 2024. The long gap between v2.1.0 and v2.1.1 means the toolkit does not move on a predictable cadence, which cuts both ways: fewer breaking changes, but also less warning when one arrives. Pin the direct-recon version alongside the checkpoint you download and record both.

Where DIRECT is the wrong choice

The README states plainly that DIRECT is not intended for clinical use. That is not a formality. A reconstruction toolkit that ships research models, supports self-supervised training on undersampled data, and offers a learned sampler is a research instrument, and nothing in the material describes regulatory clearance, prospective validation or a quality assurance path. If your goal is a reconstruction that a radiologist reads, this is the wrong layer. There is a second, quieter limitation. The toolkit's value comes from its opinions: a fixed data model built on multi-coil k-space, a fixed set of sampling masks, configs that pair with checkpoints. If your acquisition geometry or file format falls outside the listed masks and the loaders the configs assume, you are not using DIRECT, you are extending it, and the README does not describe an extension guide. The breadth of reconstructors also means you inherit code for models you will never train. Finally, the README does not report inference latency, memory footprint or reconstruction quality numbers for any model, so nothing in the supplied material lets you judge whether a given reconstructor is fast enough for your scanner's throughput.

How this differs from BART, and why the README shows both

The reconstruction figure in the README places a compressed-sensing reconstruction using the BART toolbox next to a zero-filled reconstruction and a RIM model trained with DIRECT. That juxtaposition is the clearest statement of positioning available. BART is a C++ toolbox built around classical reconstruction: iterative and compressed-sensing solvers with a mature mathematical core and no learned components. DIRECT is a Python and PyTorch toolkit built around learned reconstruction, where the unrolled networks are the primary artifact and classical methods are not the focus. The practical difference is what you tune. With BART you adjust a solver and its regularisation parameters, and the result is deterministic given the data. With DIRECT you choose a config, load a checkpoint, and the behaviour you get is whatever that training run learned, which means the checkpoint's training distribution is part of the specification. Teams that need a defensible, inspectable reconstruction path and no GPU dependency will find BART the better fit. Teams that want to train and compare learned reconstructors, and want sampling masks and metrics in the same package, will find DIRECT closer to what they need.

Licence and what maintenance you are taking on

DIRECT is released under Apache-2.0, a permissive licence that allows commercial use and modification provided the licence and notices are preserved. Nothing here is legal advice, and the licence file itself, not this summary, governs. The practical implication is that the Apache-2.0 grant covers the toolkit code; it does not automatically cover the pretrained checkpoints on Hugging Face, whose terms are stated on their own repository pages, nor the datasets you train on. Check both before you ship anything derived from them. On maintenance, the cost is mostly in the config and checkpoint pairing. Every experiment you keep is a YAML file plus a .pt file, and both need to be versioned together with the direct-recon version that produced them. The projects/ directory in the repository is the model for how the maintainers do this, and copying that convention is cheaper than inventing one. Expect to re-verify a checkpoint against a newer toolkit release rather than assume it loads, because the material gives no compatibility guarantee across versions.

Editorial conclusion

DIRECT is worth adopting if you already work in PyTorch, your data is multi-coil k-space in a shape the toolkit accepts, and you want a config file plus a checkpoint rather than a bespoke training script. It is the wrong tool if you need a clinical-grade reconstruction path, if your acquisition geometry falls outside the Cartesian, radial, spiral, Poisson, Gaussian and k-t masks the README lists, or if you cannot accept that the toolkit is explicitly not intended for clinical use. Before committing, run direct predict against one of the Hugging Face checkpoint pairs on your own data root and confirm the data loader accepts your file layout; that single run tells you more than the feature list does.

Official sources

1. License: Apache-2.0
2. NKI-AI/direct on GitHub
3. Project website
4. README
5. Releases