Update README.md

README.md

@@ -1,3 +1,161 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+pipeline_tag: image-segmentation
+tags:
+- medical
+- biology
+---
+
+# CellVit Model for High-Grade Serous Ovarian Cancer Nuclei Segmentation
+
+# Model
+- **cellseg_models.pytorch** implementation of **CellVit**: [https://arxiv.org/abs/2306.15350](https://arxiv.org/abs/2306.15350)
+- Backbone encoder: pre-trained **samvit_base_patch16** from pytorch-image-models [https://github.com/huggingface/pytorch-image-models](https://github.com/huggingface/pytorch-image-models)
+
+
+# USAGE
+
+## 1. Install cellseg_models.pytorch and albumentations
+```
+pip install cellseg-models-pytorch
+pip install albumentations
+```
+
+## 2. Load trained model
+```python
+from cellseg_models_pytorch.models.cellvit import CellVit
+
+model = CellVit.from_pretrained("csmp-hub/cellvit-histo-hgsc-nuc-v1")
+```
+
+## 3. Run inference for one image
+```python
+from albumentations import Resize, Compose
+from cellseg_models_pytorch.utils import FileHandler
+from cellseg_models_pytorch.transforms.albu_transforms import MinMaxNormalization
+
+model.set_inference_mode()
+
+# Resize to multiple of 32 of your own choosing
+transform = Compose([Resize(1024, 1024), MinMaxNormalization()])
+
+im = FileHandler.read_img(IMG_PATH)
+im = transform(image=im)["image"]
+
+prob = model.predict(im)
+out = model.post_process(prob)
+# out = {"nuc": [(nuc instances (H, W), nuc types (H, W))], "cyto": None, "tissue": None}
+```
+
+## 3.1 Run inference for image batch
+```python
+import torch
+from cellseg_models_pytorch.utils import FileHandler
+
+model.set_inference_mode()
+
+# dont use random matrices IRL
+batch = torch.rand(8, 3, 1024, 1024)
+
+prob = model.predict(im)
+out = model.post_process(prob)
+# out = {
+#  "nuc": [
+#    (nuc instances (H, W), nuc types (H, W)),
+#    (nuc instances (H, W), nuc types (H, W)),
+#    .
+#    .
+#    .
+#    (nuc instances (H, W), nuc types (H, W))    
+#  ],
+#  "cyto": None,
+#  "tissue": None
+#}
+```
+
+## 4. Visualize output
+```python
+from matplotlib import pyplot as plt
+from skimage.color import label2rgb
+
+fig, ax = plt.subplots(1, 3, figsize=(18, 6))
+ax[0].imshow(im)
+ax[1].imshow(label2rgb(out["nuc"][0][0], bg_label=0)) # inst_map
+ax[2].imshow(label2rgb(out["nuc"][0][1], bg_label=0)) # type_map
+```
+
+## Dataset Details
+Semi-manually annotated HGSC Primary Omental samples from the (private) DECIDER cohort. Data acquired in the DECIDER project, 
+funded by the European Union’s Horizon 2020 research and innovation programme under grant agreement No 965193.
+
+**Contains:**
+- 198 varying sized image crops at 20x magnification.
+- 98 468 annotated nuclei
+
+## Dataset classes
+
+```
+nuclei_classes = {
+    0: "background",
+    1: "neoplastic",
+    2: "inflammatory",
+    3: "connective",
+    4: "dead",
+    5: "macrophage_cytoplasm",
+    6: "macrophage_nucleus",
+}
+```
+
+## Dataset Class Distribution
+- connective nuclei: 46 100 (~47%)
+- neoplastic nuclei: 22 761 (~23%)
+- inflammatory nuclei 19 185 (~19%)
+- dead nuclei 1859 (~2%)
+- macrophage nuclei and cytoplasms: 4550 (~5%)
+
+# Model Training Details:
+First, the image crops in the training data were tiled into 224x224px patches with a sliding window (stride=32px). 
+
+Rest of the training procedures follow this notebook: [link]
+
+# Citation
+
+cellseg_models.pytorch:
+```
+@misc{https://doi.org/10.5281/zenodo.12666959,
+  doi = {10.5281/ZENODO.12666959},
+  url = {https://zenodo.org/doi/10.5281/zenodo.12666959},
+  author = {Okunator,  },
+  title = {okunator/cellseg_models.pytorch: v0.2.0},
+  publisher = {Zenodo},
+  year = {2024},
+  copyright = {Creative Commons Attribution 4.0 International}
+}
+```
+
+CellVit original paper:
+```
+@article{CellViT,
+    title = {CellViT: Vision Transformers for precise cell segmentation and classification},
+    journal = {Medical Image Analysis},
+    volume = {94},
+    pages = {103143},
+    year = {2024},
+    issn = {1361-8415},
+    doi = {https://doi.org/10.1016/j.media.2024.103143},
+    url = {https://www.sciencedirect.com/science/article/pii/S1361841524000689},
+    author = {Fabian Hörst and Moritz Rempe and Lukas Heine and Constantin Seibold and Julius Keyl and Giulia Baldini and Selma Ugurel and Jens Siveke and Barbara Grünwald and Jan Egger and Jens Kleesiek},
+}
+```
+
+## Licence
+These model weights are released under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at:
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+## Additional Terms
+
+While the Apache 2.0 License grants broad permissions, we kindly request that users adhere to the following guidelines:
+Medical or Clinical Use: This model is not intended for use in medical diagnosis, treatment, or prevention of disease of real patients. It should not be used as a substitute for professional medical advice.