README.md

---
license: other
license_name: dinov3-license
pipeline_tag: image-segmentation
library_name: cervicalseg
tags:
  - medical-imaging
  - cervical
  - binary-segmentation
  - dinov3
  - dpt
  - wtconv
---

# CervicalSeg

CervicalSeg is a binary lesion segmentation model for cervical colposcopy images. It combines a
DINOv3 ViT-S/16 backbone, a DPT decoder, and WTConv in the final two high-resolution decoder fusion
stages. It predicts the lesion region only and does not classify red, blue, or green annotation
categories.

CervicalSeg 是宫颈阴道镜图像二分类病灶分割模型，采用 DINOv3 ViT-S/16、DPT 解码器，并在最后
两个高分辨率融合阶段使用 WTConv。模型只预测病灶区域，不再区分红、蓝、绿标注类别。

## Classes / 类别

| Index | Class | Meaning |
|---:|---|---|
| 0 | background | non-lesion region / 非病灶区域 |
| 1 | lesion | lesion region / 病灶区域 |

## Usage / 使用方法

```bash
pip install "cervicalseg>=0.2.0"
```

```python
from cervicalseg import CervicalSeg

segmenter = CervicalSeg(device="auto")
result = segmenter.predict("image.jpg")

# result.mask contains only 0=background and 1=lesion.
result.save_mask("mask.png")       # binary PNG containing 0 and 255
result.save_overlay("overlay.jpg")
```

The first call downloads `model.safetensors`; later calls reuse the Hugging Face cache. Output masks
are restored to the original image size. The single overlay colour is for visualization only and is
not a lesion subtype.

首次调用会下载 `model.safetensors`，后续调用复用 Hugging Face 缓存。输出 mask 会恢复到原图尺寸。
叠加图中的单一颜色仅用于显示病灶范围，不代表病灶类别。

## Training and evaluation / 训练与评估

The public v0.2.0 checkpoint was trained for 51 epochs on all 1,465 available images: 1,028 from the
original training split, 221 from validation, and 216 from test. All non-background annotations were
merged into one lesion label. Because all samples were used to fit the final model, no held-out test
metric applies to this public checkpoint.

公开的 v0.2.0 权重使用全部 1,465 张图像训练 51 个 epoch，其中原 train/val/test 分别为
1,028/221/216 张。所有非背景标注合并为一个病灶标签。由于最终模型使用了全部样本训练，因此该
公开权重没有独立测试集指标。

For model-development reference only, the separate patient-level validation experiment at epoch 51
obtained lesion IoU 0.5847 and lesion Dice 0.7379. These are development results, not an independent
evaluation of the all-data public checkpoint.

仅供模型开发参考：按患者划分的独立验证实验在第 51 个 epoch 得到病灶 IoU 0.5847、病灶 Dice
0.7379；这些结果不是对全量训练公开权重的独立测试。

## Intended use and limitations / 用途与限制

- Research use only.
- Not a medical device and not for clinical diagnosis or treatment decisions.
- Predictions require review by qualified professionals.
- The model detects lesion extent but does not predict lesion grade, pathology, or colour category.
- Performance may not generalize to devices, institutions, populations, or acquisition conditions
  not represented in the training data.

- 仅用于研究。
- 不是医疗器械，不得直接用于临床诊断或治疗决策。
- 预测结果需要由具备资质的专业人员复核。
- 模型仅检测病灶范围，不预测病灶分级、病理结果或颜色类别。
- 对训练数据未覆盖的设备、机构、人群和采集条件，模型性能可能下降。

## License / 许可证

The CervicalSeg Python wrapper is released under the MIT License. The trained weights contain
DINOv3 materials and are distributed under the DINOv3 License included as `DINOV3_LICENSE.md`.
WTConv-derived code retains its MIT notice in `WTCONV_LICENSE`.

CervicalSeg Python 封装代码采用 MIT License。训练权重包含 DINOv3 材料，权重分发遵循仓库中的
`DINOV3_LICENSE.md`。WTConv 衍生代码保留其 MIT 许可声明。

## Author

Shi Minghai (`PlanetSMH`)