MedHexPlane

MedHexPlane is a research codebase for dynamic contrast-enhanced MRI (DCE‑MRI) reconstruction from undersampled, multi‑coil k‑space. We model the 4D complex image volume as an implicit neural representation over (x, y, z, t), using a HexPlane‑style factorization (learned 2D planes + an MLP decoder). Training is end‑to‑end with a differentiable forward model (coil sensitivities + NUFFT) and k‑space data‑consistency losses.

This repository is under active development. It is not a clinical tool.

System Overview

At a high level:

1. Sample spatiotemporal coordinates (x, y, z, t).
2. Query factorized plane features (e.g., XY/XZ/YZ and XT/YT/ZT planes).
3. Decode to a coilless complex image volume.
4. Apply coil sensitivity maps to form per‑coil images.
5. Use NUFFT to predict k‑space samples and optimize data‑consistency + regularizers.

Repository Layout

• hexplane/: core library (model, training loop, losses, NUFFT forward model, visualization).
• config/: example YAML configs (OmegaConf).
• main.py: primary entry point (train/reconstruct).
• process_for_dl.py, extract_*.py: data preparation utilities (some require vendor tooling; see notes below).

Installation

Recommended: Python 3.10+ with a recent PyTorch build (GPU strongly recommended). Install PyTorch first (CPU or CUDA) via the official selector, then:

pip install -r requirements.txt
pip install -e .

Micromamba (optional)

If you prefer an isolated environment and don’t already have micromamba, one Linux install recipe is:

curl -Ls https://micro.mamba.pm/api/micromamba/linux-64/latest | tar -xvj bin/micromamba
./bin/micromamba shell init -s bash -r ~/micromamba
source ~/.bashrc
micromamba config append channels conda-forge

Then create/activate an env and install deps:

micromamba create -y -n medhex python=3.11
micromamba activate medhex
pip install -r requirements.txt
pip install -e .

Quickstart

Run a small phantom experiment (no external data required):

python main.py config=config/phantom.yaml optim.num_iters=50

Run with a prepared HDF5 (paths not included):

python main.py config=config/mri.yaml data.path=/path/to/prepared_nufft.h5

Configuration

Configs use OmegaConf and support CLI overrides with dot notation, e.g.:

python main.py config=config/phantom.yaml optim.num_iters=200 systems.base_dir=./log

Notes on Data Preparation

This repo expects a prepared HDF5 containing NUFFT trajectories, sampled k‑space, and coil sensitivity maps. The extract_*.py utilities include code paths that depend on vendor‑specific tooling (e.g., Philips precon) and are provided as reference; they are not required for running phantom experiments.

Acknowledgements

This project is strongly influenced by HexPlane and related implicit representation work. See LICENSE for licensing details.