Release CervicalSeg v0.1.0 weights and model card

DINOV3_LICENSE.md

@@ -0,0 +1,66 @@
+# DINOv3 License
+
+*Last Updated: August 19, 2025*
+
+**“Agreement”** means the terms and conditions for use, reproduction, distribution and modification of the DINO Materials set forth herein.
+
+**“DINO Materials”** means, collectively, Documentation and the models, software and algorithms, including machine-learning model code, trained model weights, inference-enabling code, training-enabling code, fine-tuning enabling code, and other elements of the foregoing distributed by Meta and made available under this Agreement.
+
+**“Documentation”** means the specifications, manuals and documentation accompanying
+DINO Materials distributed by Meta.
+
+**“Licensee”** or **“you”** means you, or your employer or any other person or entity (if you are entering into this Agreement on such person or entity’s behalf), of the age required under applicable laws, rules or regulations to provide legal consent and that has legal authority to bind your employer or such other person or entity if you are entering in this Agreement on their behalf.
+
+**“Meta”** or **“we”** means Meta Platforms Ireland Limited (if you are located in or, if you are an entity, your principal place of business is in the EEA or Switzerland) or Meta Platforms, Inc. (if you are located outside of the EEA or Switzerland).
+
+**“Sanctions”** means any economic or trade sanctions or restrictions administered or enforced by the United States (including the Office of Foreign Assets Control of the U.S. Department of the Treasury (“OFAC”), the U.S. Department of State and the U.S. Department of Commerce), the United Nations, the European Union, or the United Kingdom.
+
+**“Trade Controls”** means any of the following: Sanctions and applicable export and import controls.
+
+By clicking “I Accept” below or by using or distributing any portion or element of the DINO Materials, you agree to be bound by this Agreement.
+
+## 1. License Rights and Redistribution.
+
+a. <ins>Grant of Rights</ins>. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under Meta’s intellectual property or other rights owned by Meta embodied in the DINO Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the DINO Materials.
+
+b. <ins>Redistribution and Use</ins>.
+
+i. Distribution of DINO Materials, and any derivative works thereof, are subject to the terms of this Agreement. If you distribute or make the DINO Materials, or any derivative works thereof, available to a third party, you may only do so under the terms of this Agreement and you shall provide a copy of this Agreement with any such DINO Materials.
+
+ii.  If you submit for publication the results of research you perform on, using, or otherwise in connection with DINO Materials, you must acknowledge the use of DINO Materials in your publication.
+
+iii. Your use of the DINO Materials must comply with applicable laws and regulations, including Trade Control Laws and applicable privacy and data protection laws.
+
+iv. Your use of the DINO Materials will not involve or encourage others to reverse engineer, decompile or discover the underlying components of the DINO Materials.
+
+v. You are not the target of Trade Controls and your use of DINO Materials must comply with Trade Controls. You agree not to use, or permit others to use, DINO Materials for any activities subject to the International Traffic in Arms Regulations (ITAR) or end uses prohibited by Trade Controls, including those related to military or warfare purposes, nuclear industries or applications, espionage, or the development or use of guns or illegal weapons.
+
+## 2. User Support.
+
+Your use of the DINO Materials is done at your own discretion; Meta does not process any information nor provide any service in relation to such use.  Meta is under no obligation to provide any support services for the DINO Materials. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
+
+## 3. Disclaimer of Warranty.
+
+UNLESS REQUIRED BY APPLICABLE LAW, THE DINO MATERIALS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OF ANY KIND, AND META DISCLAIMS ALL WARRANTIES OF ANY KIND, BOTH EXPRESS AND IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING OR REDISTRIBUTING THE DINO MATERIALS AND ASSUME ANY RISKS ASSOCIATED WITH YOUR USE OF THE DINO MATERIALS AND ANY OUTPUT AND RESULTS.
+
+## 4. Limitation of Liability.
+
+IN NO EVENT WILL META OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, ARISING OUT OF THIS AGREEMENT, FOR ANY LOST PROFITS OR ANY DIRECT OR INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR PUNITIVE DAMAGES, EVEN IF META OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+
+## 5. Intellectual Property.
+
+a. Subject to Meta’s ownership of DINO Materials and derivatives made by or for Meta, with respect to any derivative works and modifications of the DINO Materials that are made by you, as between you and Meta, you are and will be the owner of such derivative works and modifications.
+
+b. If you institute litigation or other proceedings against Meta or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the DINO Materials, outputs or results, or any portion of any of the foregoing, constitutes infringement of intellectual property or other rights owned or licensable by you, then any licenses granted to you under this Agreement shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Meta from and against any claim by any third party arising out of or related to your use or distribution of the DINO Materials.
+
+## 6. Term and Termination.
+
+The term of this Agreement will commence upon your acceptance of this Agreement or access to the DINO Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein. Meta may terminate this Agreement if you are in breach of any term or condition of this Agreement. Upon termination of this Agreement, you shall delete and cease use of the DINO Materials. Sections 3, 4 and 7 shall survive the termination of this Agreement.
+
+## 7. Governing Law and Jurisdiction.
+
+This Agreement will be governed and construed under the laws of the State of California without regard to choice of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement. The courts of California shall have exclusive jurisdiction of any dispute arising out of this Agreement.
+
+## 8. Modifications and Amendments.
+
+Meta may modify this Agreement from time to time; provided that they are similar in spirit to the current version of the Agreement, but may differ in detail to address new problems or concerns. All such changes will be effective immediately. Your continued use of the DINO Materials after any modification to this Agreement constitutes your agreement to such modification. Except as provided in this Agreement, no modification or addition to any provision of this Agreement will be binding unless it is in writing and signed by an authorized representative of both you and Meta.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shi Minghai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,99 @@
+---
+license: other
+license_name: dinov3-license
+pipeline_tag: image-segmentation
+library_name: cervicalseg
+tags:
+  - medical-imaging
+  - cervical
+  - semantic-segmentation
+  - dinov3
+  - dpt
+  - wtconv
+---
+
+# CervicalSeg
+
+CervicalSeg is a four-class semantic 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.
+
+宫颈阴道镜图像四分类语义分割模型，采用 DINOv3 ViT-S/16、DPT 解码器，并在最后两个高分辨率
+融合阶段使用 WTConv。
+
+## Classes / 类别
+
+| Index | Class | Colour |
+|---:|---|---|
+| 0 | background | black |
+| 1 | blue | blue |
+| 2 | green | green |
+| 3 | red | red |
+
+## Usage / 使用方法
+
+```bash
+pip install cervicalseg
+```
+
+```python
+from cervicalseg import CervicalSeg
+
+segmenter = CervicalSeg(device="auto")
+result = segmenter.predict("image.jpg")
+result.save_mask("mask.png")
+result.save_color_mask("color_mask.png")
+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.
+
+首次调用会下载 `model.safetensors`，后续调用复用 Hugging Face 缓存。输出 mask 会恢复到原图尺寸。
+
+## Evaluation / 评估结果
+
+The data were split at the patient level to prevent patient leakage between train, validation, and
+test sets.
+
+数据按患者划分，避免同一患者同时出现在训练、验证或测试集合中。
+
+| Split | Samples | Foreground mIoU | Foreground Dice | Pixel accuracy |
+|---|---:|---:|---:|---:|
+| Validation | 221 | 0.4075 | 0.5704 | 0.9121 |
+| Test | 216 | 0.3633 | 0.5296 | 0.8891 |
+
+Test-set per-class metrics:
+
+| Class | Precision | Recall | Dice | IoU |
+|---|---:|---:|---:|---:|
+| blue | 0.5651 | 0.5697 | 0.5674 | 0.3961 |
+| green | 0.3784 | 0.4950 | 0.4289 | 0.2730 |
+| red | 0.6850 | 0.5219 | 0.5924 | 0.4209 |
+
+## 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.
+- Performance may not generalize to devices, institutions, populations, or acquisition conditions
+  not represented in the training data.
+- Green-region segmentation is the weakest class in the reported test results.
+
+- 仅用于研究。
+- 不是医疗器械，不得直接用于临床诊断或治疗决策。
+- 预测结果需要由具备资质的专业人员复核。
+- 对训练数据未覆盖的设备、机构、人群和采集条件，模型性能可能下降。
+
+## 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`)

WTCONV_LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shahaf Finder, Roy Amoyal, Eran Treister, Oren Freifeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

config.json

@@ -0,0 +1,85 @@
+{
+  "format_version": 1,
+  "model": {
+    "class_names": [
+      "background",
+      "blue",
+      "green",
+      "red"
+    ],
+    "image_size": [
+      576,
+      768
+    ],
+    "image_mean": [
+      0.485,
+      0.456,
+      0.406
+    ],
+    "image_std": [
+      0.229,
+      0.224,
+      0.225
+    ],
+    "padding_color": [
+      124,
+      116,
+      104
+    ],
+    "hidden_state_indices": [
+      3,
+      6,
+      9,
+      12
+    ],
+    "dpt_features": 64,
+    "dpt_channels": [
+      48,
+      96,
+      192,
+      384
+    ],
+    "wt_kernel_size": 5,
+    "wt_levels": 2,
+    "wt_type": "db1",
+    "backbone": {
+      "model_type": "dinov3_vit",
+      "architectures": [
+        "DINOv3ViTModel"
+      ],
+      "attention_dropout": 0.0,
+      "drop_path_rate": 0.0,
+      "hidden_act": "gelu",
+      "hidden_size": 384,
+      "image_size": 224,
+      "initializer_range": 0.02,
+      "intermediate_size": 1536,
+      "key_bias": false,
+      "layer_norm_eps": 1e-05,
+      "layerscale_value": 1.0,
+      "mlp_bias": true,
+      "num_attention_heads": 6,
+      "num_channels": 3,
+      "num_hidden_layers": 12,
+      "num_register_tokens": 4,
+      "patch_size": 16,
+      "pos_embed_jitter": null,
+      "pos_embed_rescale": 2.0,
+      "pos_embed_shift": null,
+      "proj_bias": true,
+      "query_bias": true,
+      "rope_theta": 100.0,
+      "use_gated_mlp": false,
+      "value_bias": true
+    }
+  },
+  "checkpoint": {
+    "filename": "model.safetensors",
+    "size_bytes": 96876480,
+    "sha256": "2fdec883d6a94b7a3478a750f6943bb41b60abcb8316649bd8a050f9bd3e5f4d",
+    "training_epoch": 66,
+    "best_validation_miou_foreground": 0.40750709018075176,
+    "test_miou_foreground": 0.3633164423801378,
+    "test_mean_dice_foreground": 0.5295766998594339
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2fdec883d6a94b7a3478a750f6943bb41b60abcb8316649bd8a050f9bd3e5f4d
+size 96876480