Upload folder using huggingface_hub

README.md

@@ -6,6 +6,7 @@ tags:
 - cervical-cancer
 - pytorch
 - safetensors
+- cnn
 datasets:
 - custom
 metrics:
@@ -15,7 +16,7 @@ pipeline_tag: image-classification
 library_name: pytorch
 ---
 
-# Cervical Type Classification Model
+# CerviGuard - Cervical Transformation Zone Classifier
 
 ## Model Description
 
@@ -27,29 +28,112 @@ This model classifies cervical images into 3 transformation zone types, which is
 | 1 | Type 2 | Transformation zone partially visible (extends into endocervical canal) |
 | 2 | Type 3 | Transformation zone not visible (entirely within endocervical canal) |
 
+---
+
 ## Model Architecture
 
-Simple CNN with 4 convolutional layers:
+### Overview
+
+**BaseCNN** - A simple convolutional neural network with 4 conv blocks and 2 fully connected layers.
 
 ```
-Input (256x256x3)
-    ↓
-Conv2d(3→32) + BN + ReLU + MaxPool
-Conv2d(32→64) + BN + ReLU + MaxPool
-Conv2d(64→128) + BN + ReLU + MaxPool
-Conv2d(128→256) + BN + ReLU + MaxPool
-    ↓
-AdaptiveAvgPool2d(1)
-    ↓
-FC(256→256) + ReLU + Dropout(0.4)
-FC(256→128) + ReLU + Dropout(0.4)
-    ↓
-FC(128→3) → Output
+┌─────────────────────────────────────────────────────────────┐
+│                    INPUT (256×256×3)                        │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  CONV BLOCK 1                                               │
+│  Conv2d(3→32, 3×3) → BatchNorm2d → ReLU → MaxPool2d(2×2)   │
+│  Output: 128×128×32                                         │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  CONV BLOCK 2                                               │
+│  Conv2d(32→64, 3×3) → BatchNorm2d → ReLU → MaxPool2d(2×2)  │
+│  Output: 64×64×64                                           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  CONV BLOCK 3                                               │
+│  Conv2d(64→128, 3×3) → BatchNorm2d → ReLU → MaxPool2d(2×2) │
+│  Output: 32×32×128                                          │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  CONV BLOCK 4                                               │
+│  Conv2d(128→256, 3×3) → BatchNorm2d → ReLU → MaxPool2d(2×2)│
+│  Output: 16×16×256                                          │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  GLOBAL POOLING                                             │
+│  AdaptiveAvgPool2d(1×1)                                     │
+│  Output: 1×1×256 → Flatten → 256                            │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  FC BLOCK 1                                                 │
+│  Linear(256→256) → ReLU → Dropout(0.4)                     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  FC BLOCK 2                                                 │
+│  Linear(256→128) → ReLU → Dropout(0.4)                     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│  CLASSIFIER                                                 │
+│  Linear(128→3)                                              │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│                 OUTPUT (3 logits)                           │
+│            [Type 1, Type 2, Type 3]                         │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-**Parameters:** 488,451
+### Layer Details
+
+| Layer | Type | In Channels | Out Channels | Kernel | Output Size |
+|-------|------|-------------|--------------|--------|-------------|
+| conv_layers.0 | Conv2d | 3 | 32 | 3×3 | 256×256×32 |
+| conv_layers.1 | BatchNorm2d | 32 | 32 | - | 256×256×32 |
+| conv_layers.2 | ReLU | - | - | - | 256×256×32 |
+| conv_layers.3 | MaxPool2d | - | - | 2×2 | 128×128×32 |
+| conv_layers.4 | Conv2d | 32 | 64 | 3×3 | 128×128×64 |
+| conv_layers.5 | BatchNorm2d | 64 | 64 | - | 128×128×64 |
+| conv_layers.6 | ReLU | - | - | - | 128×128×64 |
+| conv_layers.7 | MaxPool2d | - | - | 2×2 | 64×64×64 |
+| conv_layers.8 | Conv2d | 64 | 128 | 3×3 | 64×64×128 |
+| conv_layers.9 | BatchNorm2d | 128 | 128 | - | 64×64×128 |
+| conv_layers.10 | ReLU | - | - | - | 64×64×128 |
+| conv_layers.11 | MaxPool2d | - | - | 2×2 | 32×32×128 |
+| conv_layers.12 | Conv2d | 128 | 256 | 3×3 | 32×32×256 |
+| conv_layers.13 | BatchNorm2d | 256 | 256 | - | 32×32×256 |
+| conv_layers.14 | ReLU | - | - | - | 32×32×256 |
+| conv_layers.15 | MaxPool2d | - | - | 2×2 | 16×16×256 |
+| adaptive_pool | AdaptiveAvgPool2d | - | - | - | 1×1×256 |
+| fc_layers.0 | Linear | 256 | 256 | - | 256 |
+| fc_layers.1 | ReLU | - | - | - | 256 |
+| fc_layers.2 | Dropout | - | - | p=0.4 | 256 |
+| fc_layers.3 | Linear | 256 | 128 | - | 128 |
+| fc_layers.4 | ReLU | - | - | - | 128 |
+| fc_layers.5 | Dropout | - | - | p=0.4 | 128 |
+| classifier | Linear | 128 | 3 | - | 3 |
+
+### Model Summary
+
+| Property | Value |
+|----------|-------|
+| **Total Parameters** | 488,451 |
+| **Trainable Parameters** | 488,451 |
+| **Input Size** | (B, 3, 256, 256) |
+| **Output Size** | (B, 3) |
+| **Model Size** | ~1.9 MB |
 
-## Training
+---
+
+## Training Configuration
 
 | Parameter | Value |
 |-----------|-------|
@@ -57,7 +141,11 @@ FC(128→3) → Output
 | Batch Size | 32 |
 | Dropout | 0.4 |
 | Optimizer | Adam |
+| Loss Function | CrossEntropyLoss |
 | Epochs | 50 |
+| Best Epoch | 41 |
+
+---
 
 ## Performance
 
@@ -66,23 +154,25 @@ FC(128→3) → Output
 | **Validation Accuracy** | 61.69% |
 | **Macro F1 Score** | 61.81% |
 
-### Per-Class F1 Scores
+### Per-Class Performance
 
-| Type | F1 Score |
-|------|----------|
-| Type 1 | 68.32% |
-| Type 2 | 56.41% |
-| Type 3 | 60.69% |
+| Type | Precision | Recall | F1 Score |
+|------|-----------|--------|----------|
+| Type 1 | - | - | 68.32% |
+| Type 2 | - | - | 56.41% |
+| Type 3 | - | - | 60.69% |
+
+---
 
 ## Usage
 
 ### Installation
 
 ```bash
-pip install torch torchvision safetensors
+pip install torch torchvision safetensors huggingface_hub
 ```
 
-### Quick Start
+### Quick Start (Local)
 
 ```python
 import torch
@@ -114,51 +204,74 @@ print(f"Prediction: {labels[prediction]}")
 print(f"Confidence: {probabilities[0][prediction]:.2%}")
 ```
 
-### Using with Hugging Face Hub
+### Load from Hugging Face Hub
 
 ```python
 from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
 import torch
+import json
+import importlib.util
 
-# Download model files
-model_path = hf_hub_download(repo_id="your-username/cervical-type-classifier", filename="model.safetensors")
-config_path = hf_hub_download(repo_id="your-username/cervical-type-classifier", filename="config.json")
+# Download files
+repo_id = "toderian/cerviguard_transfer_zones"
+model_weights = hf_hub_download(repo_id, "model.safetensors")
+config_file = hf_hub_download(repo_id, "config.json")
+model_file = hf_hub_download(repo_id, "model.py")
 
-# Load using safetensors
-from safetensors.torch import load_file
-state_dict = load_file(model_path)
+# Load model class dynamically
+spec = importlib.util.spec_from_file_location("model", model_file)
+model_module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(model_module)
 
-# Create model and load weights
-from model import BaseCNN
-import json
-
-with open(config_path) as f:
+# Load config and create model
+with open(config_file) as f:
     config = json.load(f)
 
-model = BaseCNN(**config['model_config'])
-model.load_state_dict(state_dict)
+model = model_module.BaseCNN(**config['model_config'])
+model.load_state_dict(load_file(model_weights))
 model.eval()
+
+# Now use model for inference
 ```
 
+---
+
+## Files in This Repository
+
+| File | Description |
+|------|-------------|
+| `model.safetensors` | Model weights (SafeTensors format, recommended) |
+| `pytorch_model.bin` | Model weights (PyTorch format, backup) |
+| `config.json` | Model architecture configuration |
+| `model.py` | Model class definition (BaseCNN) |
+| `preprocessor_config.json` | Image preprocessing configuration |
+| `README.md` | This model card |
+
+---
+
 ## Limitations
 
 - Model was trained on a specific dataset and may not generalize to all cervical imaging equipment
 - Type 2 classification has lower accuracy (56.41% F1) as it represents an intermediate state
-- Input images should be 256x256 RGB
+- Input images should be 256×256 RGB
+- This is a custom PyTorch model, not compatible with `transformers.AutoModel`
 
-## Citation
+---
 
-If you use this model, please cite:
+## Citation
 
 ```bibtex
-@misc{cervical-type-classifier,
-  title={Cervical Type Classification Model},
-  author={Your Name},
+@misc{cerviguard-transfer-zones,
+  title={CerviGuard Cervical Transformation Zone Classifier},
+  author={toderian},
   year={2026},
-  howpublished={\url{https://huggingface.co/your-username/cervical-type-classifier}}
+  howpublished={\url{https://huggingface.co/toderian/cerviguard_transfer_zones}}
 }
 ```
 
+---
+
 ## License
 
 MIT License

preprocessor_config.json

@@ -0,0 +1,14 @@
+{
+  "do_normalize": true,
+  "do_rescale": true,
+  "do_resize": true,
+  "image_mean": [0.5, 0.5, 0.5],
+  "image_std": [0.5, 0.5, 0.5],
+  "image_processor_type": "ImageProcessor",
+  "resample": 3,
+  "rescale_factor": 0.00392156862745098,
+  "size": {
+    "height": 256,
+    "width": 256
+  }
+}