AliG643 / voxelmorph_replica_practice

# 2D deformable image registration
A small, independent implementation of the core VoxelMorph registration idea: a U-Net predicts spatial deformation, a differentiable sampler warps the moving image, and image similarity plus smoothness trains the network. Optional stationary-velocity integration is supported. This is an educational 2D implementation, not a reproduction of the published 3D benchmark or the full original library.
## Setup
The existing environment already contains the required dependencies:
 [code] 
For a different environment, install `requirements.txt` and follow your hardware's PyTorch installation requirements. Python 3.10 or newer is recommended. No original VoxelMorph or Neurite package is required.
## One command for the full experiment
Use the OASIS archive already downloaded on this machine:
 [code] 
This prepares data if absent, trains, selects the best checkpoint using validation, evaluates test pairs, and saves figures and metrics. If no archive is supplied and data is absent, it downloads the public 24 MB 2D archive. A matching existing data folder is reused. Weights in an existing training output are protected; choose a different output or resume.
Change parameters from one place:
 [code] 
`--epochs` counts full passes over 354 training pairs. It is not the same as the earlier helper's `--steps`. `--integration-steps 0` is direct displacement; positive steps integrate velocity. `--similarity ncc` changes the image loss and needs its own regularization tuning. `--device cpu`, `cuda`, or `auto` selects hardware. Defaults come from `config.py`; command-line values override them.
## Separate commands
 [code] 
Resume to a larger total epoch count, using the same training settings and output directory:
 [code] 
For an integrated experiment, also supply its original `--integration-steps`, smoothness, learning rate, batch size and similarity settings. Changing settings while resuming is rejected. Checkpoints retain optimizer state, history and PyTorch random state. GPU runs may remain nondeterministic across devices/software.
## Inputs and outputs
The prepared directory has `train`, `validation`, and `test`, each with `moving` and `fixed` folders. Corresponding files have matching names. Optional `moving_seg` and `fixed_seg` folders contain matching `.npy` segmentation sidecars. Image batches require consistent shapes; pair shapes must always match.
The loader accepts grayscale PNG, 2D NIfTI (including singleton third axes), and 2D NumPy arrays. Unsupported full 3D inputs are rejected. Images must already be in compatible spatial grids and approximately aligned. There is no automatic skull stripping, affine alignment, resampling, or multimodal contrast handling. Shape equality alone does not prove compatible physical space.
PNG intensities are converted to [0,1]. NIfTI/NumPy intensities already in [0,1] are preserved; otherwise per-image min-max normalization is applied. Constant-valued images outside that range become zero.