JoshuaFreeman/skin_seg

🔬 Skin Histopathology Segmentation Models

State-of-the-art deep learning models for 12-class skin histopathology segmentation, trained on high-resolution skin tissue images.

📋 Available Models

EfficientNet Models

• efficientnet-b3_10x_unet_best.pt - EfficientNet-B3 backbone trained on 10x magnification data
• efficientnet-b7_10x_unet_best.pt - EfficientNet-B7 backbone trained on 10x magnification data

Other Architectures

• efficientnet-b5_unet_best.pt - EfficientNet-B5 backbone (general purpose)
• gigapath_unet_best.pt - GigaPath vision transformer backbone

🏷️ Model Nomenclature

Important: All models now follow strict magnification-aware nomenclature:

• {backbone}_{magnification}_unet_best.pt for magnification-specific models
• Models without magnification suffix are general-purpose

This prevents silent failures where a model trained on one magnification is used with data from another magnification.

🔬 Tissue Classes

The models segment 12 distinct tissue classes:

Class ID	Abbreviation	Full Name	Description
0	GLD	Gland	Skin glandular structures
1	INF	Inflammation	Inflammatory tissue
2	FOL	Follicle	Hair follicles
3	HYP	Hypodermis	Subcutaneous tissue
4	RET	Reticular	Reticular dermis
5	PAP	Papillary	Papillary dermis
6	EPI	Epidermis	Outer skin layer
7	KER	Keratin	Keratinized tissue
8	BKG	Background	Background/non-tissue
9	BCC	Basal Cell Carcinoma	Cancer tissue
10	SCC	Squamous Cell Carcinoma	Cancer tissue
11	IEC	Inflammatory/Epithelial Cells	Mixed cell types

🚀 Quick Start

Using the Inference Script

# Download and use EfficientNet-B3 10x model
python skin_seg_inference.py image.jpg --model_name efficientnet-b3_10x

# Use with specific magnification parameter
python skin_seg_inference.py image.jpg --model_name efficientnet-b3 --magnification 10x

# Process whole slide images (NDPI, SVS, etc.)
python skin_seg_inference.py slide.ndpi --model_name efficientnet-b3_10x

# Batch processing
python skin_seg_inference.py /path/to/images/ --batch --model_name efficientnet-b3_10x

Manual Model Loading

from skin_seg_inference import SkinSegmentationModel
from PIL import Image

# Initialize model with magnification awareness
model = SkinSegmentationModel(
    model_name="efficientnet-b3_10x",
    requested_magnification="10x"
)

# Load and predict
image = Image.open("skin_sample.jpg")
pred_mask, confidence = model.predict(image)

📊 Key Features

• 🎯 Magnification Awareness: Models explicitly specify their training magnification
• 🔍 Multi-Scale Support: Handles images from 1x to 40x magnification
• 🖼️ Whole Slide Imaging: Native support for WSI formats (NDPI, SVS, etc.)
• ⚡ Batch Processing: Efficient processing of multiple images
• 📈 Comprehensive Analysis: Generates detailed tissue statistics and visualizations
• 🎨 Rich Visualizations: 6-panel analysis with confidence maps and class distributions

🔧 Model Architecture

All models use a U-Net architecture with pre-trained backbones:

• EfficientNet: CNN backbones optimized for efficiency and accuracy
• GigaPath: Vision transformer backbone for pathology applications
• Input: 224×224 RGB patches
• Output: 12-class segmentation masks with confidence scores

📏 Magnification Guidelines

Magnification	Use Case	Recommended Model
10x	General skin analysis	efficientnet-b3_10x
20x	Detailed cellular analysis	efficientnet-b7_10x (if available)
Other	Mixed magnifications	efficientnet-b5 (general)

🔄 Migration from Legacy Models

If you were using models without magnification suffixes:

• efficientnet-b3_unet_best.pt → efficientnet-b3_10x_unet_best.pt
• efficientnet-b7_unet_best.pt → efficientnet-b7_10x_unet_best.pt

The inference script automatically handles this migration when you specify --magnification.

📦 Installation Requirements

pip install torch torchvision
pip install segmentation-models-pytorch
pip install albumentations
pip install huggingface-hub
pip install openslide-python  # For WSI support

🎓 Citation

If you use these models in your research, please cite:

@misc{skin_seg_models_2024,
  title={Skin Histopathology Segmentation Models},
  author={JoshuaFreeman},
  year={2024},
  publisher={HuggingFace},
  url={https://huggingface.co/JoshuaFreeman/skin_seg}
}

📄 License

These models are released under the MIT License. See LICENSE for details.

🤝 Contributing

Found an issue or want to contribute? Please open an issue or pull request in the associated repository.

---

🔬 Powered by state-of-the-art deep learning for advancing skin pathology research