---
license: mit
library_name: pytorch
pipeline_tag: image-to-image
tags:
  - medical-imaging
  - registration
  - 3d-registration
  - x-ray
  - ct
  - mri
---

# `xvr`: X-ray to Volume Registration

[![Paper shield](https://img.shields.io/badge/arXiv-2503.16309-red.svg)](https://arxiv.org/abs/2503.16309)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
<a href="https://colab.research.google.com/drive/1K9lBPxcLh55mr8o50Y7aHkjzjEWKPCrM?usp=sharing"><img alt="Colab" src="https://colab.research.google.com/assets/colab-badge.svg"></a>
<a href="https://huggingface.co/eigenvivek/xvr/tree/main" target="_blank"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Models-ffc107?color=ffc107&logoColor=white"/></a>
<a href="https://huggingface.co/datasets/eigenvivek/xvr-data/tree/main" target="_blank"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Data-ffc107?color=ffc107&logoColor=white"/></a>
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

**`xvr` is a PyTorch package for training, fine-tuning, and performing 2D/3D X-ray to CT/MR registration using pose regression models.**  It provides a streamlined CLI and API for training patient-specific registration models efficiently.  Key features include significantly faster training than comparable methods, submillimeter registration accuracy, and human-interpretable pose parameters.


<p align="center">
  <img width="410" alt="image" src="https://github.com/user-attachments/assets/8a01c184-f6f1-420e-82b9-1cbe733adf7f" />
</p>

## Key Features

- 🚀 Single CLI/API for training and registration.
- ⚡️ Significantly faster training than existing methods.
- 📐 Submillimeter registration accuracy.
- 🩺 Human-interpretable pose parameters.
- 🐍 Pure Python/PyTorch implementation.
- 🖥️ Cross-platform support (macOS, Linux, Windows).

`xvr` leverages [`DiffDRR`](https://github.com/eigenvivek/DiffDRR), the differentiable X-ray renderer.

## Installation and Usage

This repository contains pretrained pose regression models to be run on public benchmarks datasets (reformatted into DICOM/NIfTI format) available [here](https://huggingface.co/datasets/eigenvivek/xvr-data/tree/main).

It also contains a foundation pose regression model (`wbct/model.pth`) intended to be quickly finetuned on new scans. Please refer to the [GitHub repository](https://github.com/eigenvivek/xvr) for detailed installation instructions, usage examples, and documentation on training, finetuning, and registration.