README.md

---
pipeline_tag: feature-extraction
tags:
- medical-imaging
- computed-tomography
- chest-ct
- 3d-medical-imaging
- organ-aware
- dinov2
- feature-extraction
datasets:
- ibrahimhamamci/CT-RATE
base_model:
- gigaheart/gigaheart-pretrain
license: other
---

# OrganLens

[Paper](https://arxiv.org/abs/2607.25164) |
[Official implementation](https://github.com/gezhixuan/OrganLens)

This is the official model release for
[**OrganLens: Organ-Specific Representation Learning for CT Foundation Models**](https://arxiv.org/abs/2607.25164).

OrganLens learns organ-conditioned representations from chest CT volumes. The
released model accepts a NIfTI CT volume and extracts a 1024-dimensional
embedding for any subset of 11 anatomical organs using the paper's all-slice,
soft-mask-area-weighted pooling method.

The implementation, preprocessing pipeline, training scripts, and evaluation
commands are available in the
[OrganLens GitHub repository](https://github.com/gezhixuan/OrganLens).

## Released files

| File | Size | Purpose |
| --- | ---: | --- |
| `teacher_checkpoint.pth` | 1.3 GB | Organ-conditioned backbone and mask decoder for embedding extraction |
| `heads/organlens_ctrate_heads_524999.pt` | 397 MB | Bundled MLP heads for 11 organ views and 18 CT-RATE diseases |
| `heads/organlens_radchest_heads_524999.pt` | 507 MB | Bundled MLP heads for 11 organ views and 23 RAD-ChestCT diseases |

The head bundles do not contain the teacher weights. Raw-volume prediction
requires the teacher checkpoint and the bundle for the target dataset.
Embedding extraction requires only the teacher checkpoint.

These files are distinct from GigaHeart's `pytorch_model.bin`. That checkpoint
initializes new OrganLens backbone training; `teacher_checkpoint.pth` is the
resulting OrganLens model used for inference.

## Download

Install the Hugging Face command-line client and download the complete release:

```bash
pip install -U huggingface_hub
hf download gezx1004/OrganLens --local-dir ./organlens_checkpoints
```

To download only the teacher:

```bash
hf download gezx1004/OrganLens teacher_checkpoint.pth \
  --local-dir ./organlens_checkpoints
```

## Installation

```bash
git clone https://github.com/gezhixuan/OrganLens.git
cd OrganLens
pip install .
```

## Extract organ embeddings

Extract embeddings for all 11 organs:

```bash
organlens-infer \
  --dataset ctrate \
  --volume /path/to/volume.nii.gz \
  --teacher-checkpoint ./organlens_checkpoints/teacher_checkpoint.pth \
  --embedding-output ./case_001.pt
```

Extract a selected subset:

```bash
organlens-infer \
  --dataset ctrate \
  --volume /path/to/volume.nii.gz \
  --teacher-checkpoint ./organlens_checkpoints/teacher_checkpoint.pth \
  --organs heart lung aorta \
  --embedding-output ./case_001.pt
```

Supported organ names are:

```text
spleen kidneys liver stomach pancreas lung esophagus trachea intestine heart aorta
```

## Direct CT-RATE prediction

```bash
organlens-infer \
  --dataset ctrate \
  --volume /path/to/volume.nii.gz \
  --teacher-checkpoint ./organlens_checkpoints/teacher_checkpoint.pth \
  --head-bundle ./organlens_checkpoints/heads/organlens_ctrate_heads_524999.pt \
  --embedding-output ./case_001.pt \
  --prediction-output ./case_001_predictions.json
```

See the
[GitHub README](https://github.com/gezhixuan/OrganLens#readme) for preprocessing,
training, RAD-ChestCT evaluation, the Python API, and multi-GPU benchmarking.
For CT-RATE, preprocessing follows the convention of the
[official CT-CLIP repository](https://github.com/ibrahimethemhamamci/CT-CLIP)
while determining orientation from the NIfTI header.

## Intended use and limitations

OrganLens is released for research and reproducibility in chest CT
representation learning. It is not a medical device, diagnostic system, or
clinical decision-support tool, and it has not been validated for clinical
deployment. Predictions require independent validation for any new population
or acquisition protocol.

The code repository is licensed under Apache-2.0. The released weights are
provided for research use and remain subject to applicable upstream model and
training-dataset terms, including the
[GigaHeart usage notice](https://huggingface.co/gigaheart/gigaheart-pretrain#model-uses)
and the
[CT-RATE terms](https://huggingface.co/datasets/ibrahimhamamci/CT-RATE).
Users are responsible for reviewing those terms before use or redistribution.

## Citation

```bibtex
@misc{ge2026organlensorganspecificrepresentationlearning,
  title         = {OrganLens: Organ-Specific Representation Learning for CT Foundation Models},
  author        = {Zhixuan Ge and Anqi Li and Sadeer Al-Kindi and Hanwen Xu and Wei Qiu},
  year          = {2026},
  eprint        = {2607.25164},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CV},
  url           = {https://arxiv.org/abs/2607.25164}
}
```