# Nodule Spotter detection models

This directory contains the inference weights used by the LungNoduleAgent
Nodule Spotter release for the private Shenzhen cohort.

## Released checkpoints

| ID | Architecture | Source epoch | Checkpoint | Config |
| --- | --- | ---: | --- | --- |
| `retinanet` | RetinaNet, ResNet-18 + FPN | 100 | [`retinanet_r18_fpn_shenzhen.pth`](./retinanet/retinanet_r18_fpn_shenzhen.pth) | [`retinanet_r18_fpn_shenzhen.py`](./retinanet/retinanet_r18_fpn_shenzhen.py) |
| `faster_rcnn` | Faster R-CNN, ResNet-50 + FPN | 26 | [`faster_rcnn_r50_fpn_shenzhen.pth`](./faster_rcnn/faster_rcnn_r50_fpn_shenzhen.pth) | [`faster_rcnn_r50_fpn_shenzhen.py`](./faster_rcnn/faster_rcnn_r50_fpn_shenzhen.py) |
| `dino` | DINO, ResNet-50, four-scale | 12 | [`dino_r50_4scale_shenzhen.pth`](./dino/dino_r50_4scale_shenzhen.pth) | [`dino_r50_4scale_shenzhen.py`](./dino/dino_r50_4scale_shenzhen.py) |

Machine-readable paths, hashes, and compatibility details are recorded in
[`manifest.yaml`](./manifest.yaml). File hashes are also listed in
[`checksums.sha256`](./checksums.sha256).

## Sanitization

The public checkpoints are inference-only artifacts. Compared with the
original MMEngine training checkpoints, this release removes:

- optimizer and training-loop state;
- MMEngine message/history objects;
- the embedded training configuration;
- experiment names, timestamps, seeds, and internal filesystem paths.

Each public file contains only the CPU `state_dict` plus minimal metadata:
the `nodule` class, display palette, source epoch, and format version. Every
checkpoint was reloaded with `torch.load(..., weights_only=True)` and compared
tensor-by-tensor with its source `state_dict`.

The reproducible conversion utility is available at
[`tools/sanitize_checkpoint.py`](./tools/sanitize_checkpoint.py). It must only
be used with trusted source checkpoints.

## Download

```bash
hf download YangC777/LungNoduleAgent \
  --include "DetectionModel/**" \
  --local-dir ./LungNoduleAgent-models
```

## Compatibility

The original training environment used:

- MMDetection 3.3.0
- MMEngine 0.10.7
- MMCV 2.1.0
- PyTorch 1.13 / CUDA 11.7

The configs have been scrubbed of private server paths. Dataset paths are
portable placeholders and are not required by `mmdet.apis.init_detector` for
single-image inference.

## MMDetection inference

```python
from mmdet.apis import inference_detector, init_detector

config = "DetectionModel/dino/dino_r50_4scale_shenzhen.py"
checkpoint = "DetectionModel/dino/dino_r50_4scale_shenzhen.pth"

model = init_detector(config, checkpoint, device="cuda:0")
result = inference_detector(model, "slice.png")

# Class index 0 is the released lung-nodule class.
instances = result.pred_instances
instances = instances[instances.labels == 0]
```

The legacy RetinaNet and Faster R-CNN checkpoints retain their original
80-output detection heads so that their tensors load without modification.
Only class index `0` represents `nodule`; consumers must discard predictions
with other labels. DINO was trained with `num_classes=1`.

## Data and evaluation

The private clinical images and annotations are not released. The configs
document the expected COCO annotation filenames and preprocessing structure,
but do not contain patient data.

Per-checkpoint test metrics and a public-dataset reproduction protocol are not
yet included. Results should not be compared or reported without documenting
the data split, score threshold, and post-processing settings.

## Intended use and limitations

These checkpoints are provided for research reproducibility and method
development. They have not been validated as medical devices, may not
generalize across scanners, acquisition protocols, populations, or
institutions, and must not be used for clinical diagnosis or treatment.

See [`NOTICE.md`](./NOTICE.md) before redistributing or using the weights.

## Citation

```bibtex
@article{yang2025lungnoduleagent,
  title   = {LungNoduleAgent: A Collaborative Multi-Agent System for Precision Diagnosis of Lung Nodules},
  author  = {Yang, Cheng and Jin, Hui and Yu, Xinlei and Wang, Zhipeng and Liu, Yaoqun and Fan, Fenglei and Lei, Dajiang and Jia, Gangyong and Wang, Changmiao and Ge, Ruiquan},
  journal = {arXiv preprint arXiv:2511.21042},
  year    = {2025}
}
```