README.md

---
license: apache-2.0
language: en
tags:
  - medical
  - computed-tomography
  - micro-ct
  - mouse
  - segmentation
  - multi-organ
  - monai
  - swin-unetr
  - pytorch
library_name: monai
pipeline_tag: image-segmentation
---

# AutoMICE — Swin UNETR weights + Docker image (mouse micro-CT, 8-class)

[![GitHub](https://img.shields.io/badge/GitHub-namijiang%2FAutoMICE-181717?logo=github)](https://github.com/namijiang/AutoMICE)
[![Demo](https://img.shields.io/badge/🤗-Online_Demo-yellow)](https://huggingface.co/spaces/namijiang98/AutoMICE)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/namijiang/AutoMICE/blob/main/LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.3390%2Fbioengineering11121255-blue)](https://doi.org/10.3390/bioengineering11121255)

This repository hosts **both** the **pretrained checkpoint** *and* the
**ready-to-run Docker image** for **AutoMICE** (*Automated Micro-CT Imaging
Contouring Engine*): a Swin UNETR model for **fully automatic multi-organ
segmentation** of **mouse micro-CT** volumes (7 organs + background).

## ⚡ One-line install (Docker)

```bash
git clone https://github.com/namijiang/AutoMICE.git
cd AutoMICE && ./scripts/install_from_hf.sh

docker run --gpus all --rm \
    -v /your/inputs:/data -v /your/outputs:/results \
    automice:latest --data /data --results /results
```

`install_from_hf.sh` downloads `automice-image.tar.gz` from this repo and
runs `docker load`, leaving you with `automice:latest`. No Docker Hub
account is required.

## 📦 What is in this repo

| File                       | Size   | Description                                                              |
|----------------------------|--------|--------------------------------------------------------------------------|
| `model.pt`                 | ~150 MB| Swin UNETR checkpoint (training config **test4** in the original code).  |
| `automice-image.tar.gz`    | ~3.7 GB| Pre-built Docker image (`automice:latest`) with `model.pt` baked in.     |

The Docker image is the **fastest path** for users who just want to run
inference; the standalone `model.pt` is for users who prefer the Python CLI
or want to load the weights into their own pipeline.

## 🧠 Associated publication

> **Robust Automated Mouse Micro-CT Segmentation Using Swin UNEt TRansformers**  
> Lu Jiang, Di Xu, Qifan Xu, Arion Chatziioannou, Keisuke S. Iwamoto, Susanta Hui, Ke Sheng.  
> *Bioengineering* (MDPI), 2024. DOI: <https://doi.org/10.3390/bioengineering11121255>

Please cite the paper when you use these weights or the Docker image.

## 🏷 Label map (8 classes)

| Index | Structure   |
|------:|-------------|
| 0 | background |
| 1 | bladder |
| 2 | lung |
| 3 | heart |
| 4 | liver |
| 5 | intestine |
| 6 | kidney |
| 7 | spleen |

## 🧪 Model summary

- **Architecture:** Swin UNETR (MONAI implementation).  
- **Task:** 3D semantic segmentation of mouse trunk CT.  
- **Input:** single-channel CT in NIfTI (`.nii` / `.nii.gz`).  
- **Output:** 8-class label volume (uint8 NIfTI), same grid as input.

## ✅ Intended use

- Research and non-clinical workflows (e.g. radiation biology, dosimetry research, image analysis pipelines).  
- Users who already have **mouse micro-CT** in **Hounsfield-like** intensity units.

**Not for:** human clinical diagnosis, species or modalities outside the training distribution, or any safety-critical decision without independent validation.

## ⚙️ Preprocessing (must match training)

Fixed for this checkpoint (original **test4** configuration):

| Setting               | Value                                       |
|----------------------|---------------------------------------------|
| Resampling           | isotropic **0.2 mm** spacing                |
| Intensity clip       | **[-1000, 5000] HU** → linear to **[0, 1]** |
| Sliding window ROI   | **128 × 128 × 128**                         |
| Overlap              | **0.8** (Gaussian blending)                 |
| `feature_size`       | **36**                                      |

If your CT is **not** in Hounsfield Units (e.g. raw scanner counts), apply
the scanner-specific calibration **before** inference, otherwise predictions
will be poor.

## 🐍 Use the bare weights from Python

```bash
pip install -U "huggingface_hub[cli]"
hf download namijiang98/AutoMICE model.pt --local-dir ./weights

# from the AutoMICE source tree (https://github.com/namijiang/AutoMICE):
pip install -e .
automice --data ./inputs --results ./outputs
```

## 🐳 Use the prebuilt Docker image (manual)

```bash
curl -L -o automice-image.tar.gz \
    https://huggingface.co/namijiang98/AutoMICE/resolve/main/automice-image.tar.gz
gunzip -c automice-image.tar.gz | docker load   # creates `automice:latest`

docker run --gpus all --rm \
    -v /your/inputs:/data -v /your/outputs:/results \
    automice:latest --data /data --results /results
```

## ⚠️ Limitations

- Trained on **mouse** micro-CT; transfer to other species or modalities is **not** guaranteed.  
- Performance depends on **FOV**, **resolution**, **contrast**, and **HU scaling**.  
- The Hugging Face online [demo Space](https://huggingface.co/spaces/namijiang98/AutoMICE) runs on CPU with downsampling — for publication-quality runs, use the Docker image or the Python CLI.

## 🔒 License

Apache-2.0. See the [LICENSE](https://github.com/namijiang/AutoMICE/blob/main/LICENSE) file in the GitHub repository for the full text.

## 📚 Citation

```bibtex
@article{jiang2024automice,
  title   = {Robust Automated Mouse Micro-CT Segmentation Using Swin UNEt TRansformers},
  author  = {Jiang, Lu and Xu, Di and Xu, Qifan and Chatziioannou, Arion and
             Iwamoto, Keisuke S. and Hui, Susanta and Sheng, Ke},
  journal = {Bioengineering},
  year    = {2024},
  doi     = {10.3390/bioengineering11121255},
  url     = {https://doi.org/10.3390/bioengineering11121255}
}
```

Please also cite **MONAI** and the **Swin UNETR** papers as appropriate for
your manuscript.