README.md

---
library_name: transformers
pipeline_tag: image-segmentation
tags:
  - ct-pulmonary-angiography
  - medical-imaging
  - ct
  - pulmonary-embolism
  - segmentation
  - nnunet
  - pytorch
license: cc-by-nc-4.0
datasets:
  - mazurowski-lab/PulmonaryEmbolismSegmentation
paperswithcode_id: pulmonary-embolism-segmentation
---

# Pulmonary Embolism Segmentation

This repository contains a portable Hugging Face-compatible version of the
Pulmonary Embolism Segmentation model from Mazurowski Lab.

The model is a 3D Residual Encoder U-Net trained with nnU-Net v2. The runtime
model code is implemented directly in PyTorch, so inference does not require
`nnunetv2` or `dynamic-network-architectures`.

- GitHub: https://github.com/mazurowski-lab/PulmonaryEmbolismSegmentation
- Hugging Face model: https://huggingface.co/yzluka/PulmonaryEmbolismSegmentation
- Paper: https://link.springer.com/article/10.1007/s10278-026-01958-4
- Contact: Yixin Zhang, yz696@duke.edu

The model weights are released under a CC-BY 4.0-NC license. Researchers
interested in other licensing options should contact
[MinnHealth](https://www.minnhealth.com/).

## Model

- Architecture: 3D ResidualEncoderUNet
- Input: single-channel CT volume
- Output: 2 logits, background and pulmonary embolism
- Training patch size: `[224, 320, 320]`
- Plan spacing: `[1.0, 0.7373045682907104, 0.7373045682907104]`
- Published checkpoint: `fold_all`

## Usage

```python
from pulmonary_embolism_segmentation import PulmonaryEmbolismSegmentationModel

model = PulmonaryEmbolismSegmentationModel.from_pretrained(
    "yzluka/PulmonaryEmbolismSegmentation",
    trust_remote_code=True,
)
```

For full DICOM inference, use the included helper code from the project
repository:

```powershell
python scripts/run_inference.py `
  --model-dir yzluka/PulmonaryEmbolismSegmentation `
  --input sample_data/02GE/dicom `
  --output outputs/02GE_segmentation_nnunet_preprocess.npz `
  --tile-size 128,256,256
```

The inference helper follows the nnU-Net v2 preprocessing order:

1. read image and spacing
2. crop nonzero region
3. CT clip and normalize
4. resample image to plan spacing
5. sliding-window prediction
6. resample logits back to cropped source grid
7. argmax
8. insert crop back into the original image shape

## Dependencies

Core model loading:

- `torch`
- `transformers`
- `numpy`
- `scipy`
- `scikit-image`

DICOM/NIfTI helpers:

- `SimpleITK`
- `nibabel`

## Evaluation

Evaluation details are described in the associated paper. This model card does
not report standalone evaluation metrics because performance should be
interpreted in the context of the dataset, preprocessing, and intended research
use.

## Intended Use

This model is intended for research use in pulmonary embolism segmentation from
CT pulmonary angiography. It is not a medical device and should not be used for
clinical decision-making without appropriate validation.

## Citation

If you use this model, please cite the associated paper:

```bibtex
@article{pulmonary_embolism_segmentation_2026,
  title = {Pulmonary Embolism Segmentation},
  author = {Zhang, Yixin},
  journal = {Journal of Imaging Informatics in Medicine},
  year = {2026},
  doi = {10.1007/s10278-026-01958-4},
  url = {https://link.springer.com/article/10.1007/s10278-026-01958-4}
}
```