CervicalSeg

Inference-only binary cervical lesion segmentation using DINOv3 ViT-S/16, DPT, and WTConv.

Classes are background and lesion. The model detects the lesion region only; it does not predict red, blue, or green annotation categories. This package is intended for research use and is not a clinical diagnostic device.

The package supports both DINOv3 state-dict layouts used by Transformers 4.56+ and 5.x.

Local installation

pip install -e .

The source checkout automatically finds weights/model.safetensors. After the public release, an installed wheel downloads the versioned weights from PlanetSMH/CervicalSeg automatically. A local weights file can also be selected explicitly:

from cervicalseg import CervicalSeg

segmenter = CervicalSeg(weights_path="/path/to/model.safetensors")
result = segmenter.predict("image.jpg")

result.save_mask("mask.png")
result.save_overlay("overlay.jpg")

result.mask is an H x W uint8 NumPy array restored to the original image size. Class indices are 0=background and 1=lesion. save_mask() writes a binary PNG with values 0 and 255. The single green overlay colour is visualization only and does not represent a lesion subtype.

Batch inference

results = segmenter.predict_batch(
    ["a.jpg", "b.jpg"],
    batch_size=2,
    return_probabilities=False,
)

Input may be a path, a PIL RGB image, or an H x W x 3 RGB NumPy array. Set return_probabilities=True to populate result.probabilities with a 2 x H x W float32 array. Channel 0 is background probability and channel 1 is lesion probability.

Command line

cervicalseg image1.jpg image2.jpg \
  --weights /path/to/model.safetensors \
  --output results

Hugging Face weights

Published weights are downloaded automatically and pinned to the package version:

segmenter = CervicalSeg()

# Explicit repository selection is also supported.
segmenter = CervicalSeg(repo_id="PlanetSMH/CervicalSeg", revision="v0.2.0")

Downloaded assets are cached by huggingface_hub. CERVICALSEG_WEIGHTS may be set to a local weights path for offline use.

Build the package

python -m build
python -m twine check dist/*

The Python distributions contain inference code and license notices only. Model weights are published separately on Hugging Face Hub.

Third-party notices

The trained weights contain DINOv3 materials distributed under the DINOv3 License. WTConv-derived code is used under the MIT License. Copies are provided in licenses/.