README.md

---
license: other
license_name: deepcan-research-license
license_link: LICENSE
library_name: pytorch
tags:
  - medical-imaging
  - segmentation
  - brain-mri
  - veterinary
  - canine
  - 3d-unet
  - position-encoding
language:
  - en
pipeline_tag: image-segmentation
---

# DeepCAN-SEG-PosEnc: Canine Brain MRI Segmentation Model

**GitHub**: <https://github.com/Core-BMC/DeepCAN-SegSR.git>

A lightweight canine brain MRI segmentation model with 3D position encoding, targeting 9 essential brain anatomical classes.

## Model Description

This model performs multi-class brain parcellation on canine MRI scans, segmenting 9 anatomical regions with left/right hemisphere discrimination.

- **Architecture**: 3D UNet with residual blocks (LRSegmentationMultiClassUNet)
- **Input**: 64x64x64 patches with 4 channels (intensity + xyz position encoding)
- **Output**: 9-class segmentation mask
- **Parameters**: ~66MB

### Segmentation Classes

| ID | Left Hemisphere | ID | Right Hemisphere |
|----|-----------------|----|--------------------|
| 1 | Ventricles (Left) | 5 | Ventricles (Right) |
| 2 | Gray Matter (Left) | 6 | Gray Matter (Right) |
| 3 | White Matter (Left) | 7 | White Matter (Right) |
| 4 | Cerebellum (Left) | 8 | Cerebellum (Right) |
| | | 0 | Background |

## Performance

### Validation Metrics (Epoch 26)

| Left Hemisphere | Dice | Right Hemisphere | Dice |
|-----------------|------|------------------|------|
| Ventricle_L | 0.9046 | Ventricle_R | 0.8998 |
| Gray Matter_L | 0.9123 | Gray Matter_R | 0.9036 |
| White Matter_L | 0.8581 | White Matter_R | 0.8604 |
| Cerebellum_L | 0.9558 | Cerebellum_R | 0.9489 |
| | | Background | 0.9954 |

**Mean Validation Dice**: **0.9054**

**Mean Validation Loss**: 1.019

### Training Metrics

- **Train Dice**: 0.946
- **Train Loss**: 0.060

## Training Details

- **Dataset**: DeepCAN v1.1a (balanced L/R patches, remapped labels)
- **Epochs**: 26 (early stopped, patience 20)
- **Batch Size**: 24
- **Learning Rate**: 1e-4 (cosine scheduler, T_max=500, eta_min=1e-6)
- **Optimizer**: AdamW (weight_decay=1e-5)
- **Loss**: MultiClass Dice + Cross-Entropy (dice_weight=0.7, gradual class weights)
- **Gradient Accumulation**: 4 steps
- **Hardware**: NVIDIA RTX 4090 (24GB)
- **Training Time**: ~23.7 hours

### Training Logs

Full training logs available on Weights & Biases:

- **Project**: [DeepCAN-SegSR](https://wandb.ai/heohwon/DeepCAN-SegSR)
- **Run**: `DeepCAN-SEG-PosEnc-v11a`

## Usage

```python
import torch
from src.models.lr_segmentation_model import LRSegmentationMultiClassUNet

# Load model
model = LRSegmentationMultiClassUNet(
    in_channels=4,  # intensity + xyz position encoding
    num_classes=9,
    features=[32, 64, 128, 256]
)
checkpoint = torch.load("DeepCAN-SEG-PosEnc.pth", map_location="cpu")
model.load_state_dict(checkpoint["model_state_dict"])
model.eval()

# Inference
with torch.no_grad():
    # input_patch: [B, 4, 64, 64, 64] - intensity + normalized xyz coords
    output = model(input_patch)
    prediction = torch.argmax(output, dim=1)
```

### With Clinical Pipeline

```bash
# Clone the main repository
git clone https://github.com/Core-BMC/DeepCAN-SegSR.git
cd DeepCAN-SegSR

# Run clinical pipeline
python -m src.inference.cli clinical \
    --input your_dicom_folder/ \
    --output outputs/
```

## Model Files

- `DeepCAN-SEG-PosEnc.pth`: Model weights (66MB)

## Limitations

- Trained on canine brain MRI only (not validated for other species)
- Optimized for T2-weighted sequences
- Requires preprocessing to match training data distribution
- Research use only - not validated for clinical diagnosis

## Citation

```bibtex
@software{deepcan2025,
  title = {DeepCAN SegSR Suite: Canine Brain MRI Super-Resolution and Segmentation},
  author = {Hwon Heo & Woo Hyun Shim, DeepCAN AI team},
  year = {2025},
  url = {https://github.com/Core-BMC/DeepCAN-SegSR}
}
```

## License

This model is released under the **DeepCAN Research License** - free for non-commercial research and educational use only.

For commercial licensing inquiries, contact: <heohwon@gmail.com>

See [LICENSE](LICENSE) for full terms.