Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,145 @@
+---
+license: mit
+tags:
+- video-classification
+- medical
+- microscopy
+- sperm-analysis
+- pytorch
+library_name: pytorch
+---
+
+# Sperm Normality Rate Classifier
+
+## Model Description
+
+This model classifies human sperm microscopic videos into normality rate categories using a 3D ResNet18 architecture.
+
+**Architecture**: 3D ResNet18  
+**Task**: Video Classification  
+**Classes**: 6 normality rate categories (0%, 60%, 70%, 80%, 85%, 90%)  
+**Input**: 90 frames (3 seconds at 30 fps), 224x224 RGB  
+**Framework**: PyTorch
+
+## Intended Use
+
+This model is designed for analyzing human sperm microscopic videos to predict normality rates. It's intended for research and diagnostic support in reproductive medicine.
+
+## Model Details
+
+- **Input Format**: Video clips of 90 frames (3 seconds at 30 fps)
+- **Preprocessing**: 
+  - Frames resized to 224x224
+  - ImageNet normalization + per-video standardization
+  - Combined normalization for robustness
+- **Output**: Probability distribution over 6 normality rate classes
+
+## Training Details
+
+- **Dataset**: Balanced dataset with 100 clips per class
+- **Normalization**: Combined ImageNet + per-video standardization
+- **Loss Function**: Focal Loss with class weights
+- **Optimizer**: Adam (lr=1e-4)
+- **Early Stopping**: Patience of 10 epochs
+
+## Usage
+
+```python
+import torch
+import torch.nn as nn
+import torchvision.models.video as video_models
+import cv2
+import numpy as np
+
+# Define model architecture
+class VideoClassifier(nn.Module):
+    def __init__(self, num_classes=6):
+        super(VideoClassifier, self).__init__()
+        self.backbone = video_models.r3d_18(pretrained=False)
+        in_features = self.backbone.fc.in_features
+        self.backbone.fc = nn.Linear(in_features, num_classes)
+    
+    def forward(self, x):
+        return self.backbone(x)
+
+# Load model
+device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+model = VideoClassifier(num_classes=6)
+model.load_state_dict(torch.load('best_model.pth', map_location=device))
+model.to(device)
+model.eval()
+
+# Preprocess video
+def preprocess_video(video_path, num_frames=90, target_size=(224, 224)):
+    cap = cv2.VideoCapture(video_path)
+    frames = []
+    
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+        frame = cv2.resize(frame, target_size)
+        frame = frame.astype(np.float32) / 255.0
+        frames.append(frame)
+    
+    cap.release()
+    
+    # Sample to 90 frames
+    if len(frames) < num_frames:
+        repeat_factor = int(np.ceil(num_frames / len(frames)))
+        frames = (frames * repeat_factor)[:num_frames]
+    elif len(frames) > num_frames:
+        indices = np.linspace(0, len(frames) - 1, num_frames).astype(int)
+        frames = [frames[i] for i in indices]
+    
+    # Convert to tensor (C, T, H, W)
+    frames = torch.FloatTensor(np.array(frames)).permute(3, 0, 1, 2)
+    
+    # Apply normalization
+    mean = torch.tensor([0.485, 0.456, 0.406]).view(3, 1, 1, 1)
+    std = torch.tensor([0.229, 0.224, 0.225]).view(3, 1, 1, 1)
+    frames = (frames - mean) / std
+    
+    # Per-video standardization
+    video_mean = frames.mean()
+    video_std = frames.std()
+    if video_std > 0:
+        frames = (frames - video_mean) / video_std
+    
+    return frames.unsqueeze(0)  # Add batch dimension
+
+# Inference
+video_tensor = preprocess_video("path/to/video.mp4")
+video_tensor = video_tensor.to(device)
+
+with torch.no_grad():
+    outputs = model(video_tensor)
+    probabilities = torch.softmax(outputs, dim=1)
+    predicted_class = torch.argmax(probabilities, dim=1).item()
+
+class_names = ["0%", "60%", "70%", "80%", "85%", "90%"]
+print(f"Predicted normality rate: {class_names[predicted_class]}")
+print(f"Confidence: {probabilities[0][predicted_class].item():.4f}")
+```
+
+## Limitations
+
+- Trained on specific microscopy equipment and protocols
+- Performance may vary with different imaging conditions
+- Should be used as diagnostic support, not sole decision-making tool
+- Requires proper video preprocessing
+
+## Citation
+
+If you use this model, please cite:
+
+```
+@misc{sperm-normality-classifier,
+  author = {Raid Athmane Benlala},
+  title = {Sperm Normality Rate Classifier},
+  year = {2025},
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/raidAthmaneBenlala/normality-rate-classifier}}
+}
+```