Metadata-Version: 2.4
Name: cervicalseg
Version: 0.1.0
Summary: Cervical colour segmentation with DINOv3, DPT, and WTConv
Author: Shi Minghai
License-Expression: MIT
Project-URL: Model Weights, https://huggingface.co/PlanetSMH/CervicalSeg
Keywords: cervical,medical-imaging,segmentation,dinov3,wtconv
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: licenses/DINOV3_LICENSE.md
License-File: licenses/WTCONV_LICENSE
Requires-Dist: huggingface-hub>=0.34
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10.0
Requires-Dist: safetensors>=0.4
Requires-Dist: torch>=2.5
Requires-Dist: transformers>=4.56
Dynamic: license-file

# CervicalSeg

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

Classes are `background`, `blue`, `green`, and `red`. This package is intended for research use and
is not a clinical diagnostic device.

## Local installation

```bash
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:

```python
from cervicalseg import CervicalSeg

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

result.save_mask("mask.png")
result.save_color_mask("color_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, 1=blue, 2=green, and 3=red.

## Batch inference

```python
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 `4 x H x W` float32 array.

## Command line

```bash
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:

```python
segmenter = CervicalSeg()

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

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

## Build the package

```bash
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/`.
