# GCPDS Computer Vision Python Kit
A comprehensive toolkit for computer vision and segmentation tasks, developed by the GCPDS Team. This package provides state-of-the-art tools for training, evaluating, and deploying segmentation models with support for various architectures, loss functions, and performance metrics.
## 🚀 Features
- **Segmentation Models**: Support for UNet, ResUNet, DeepLabV3Plus, and FCN architectures
- **Multiple Loss Functions**: DICE, Cross Entropy, Focal Loss, and Tversky Loss
- **Performance Evaluation**: Comprehensive metrics including Dice, Jaccard, Sensitivity, and Specificity
- **Training Pipeline**: Complete training workflow with validation and monitoring
- **Data Loading**: Efficient data loading utilities for segmentation tasks
- **Experiment Tracking**: Integration with Weights & Biases (wandb)
- **Mixed Precision Training**: Automatic Mixed Precision (AMP) support for faster training
- **Dataset Management**: Built-in Kaggle dataset download and preparation utilities
- **Visualization Tools**: Random sample visualization utilities for dataset exploration
- **Memory Management**: Efficient memory handling and cleanup utilities
## 📋 Requirements
- Python >= 3.8
- PyTorch >= 2.0.0
- CUDA-compatible GPU (recommended)
## 🔧 Installation
### From PyPI
```bash
pip install gcpds-cv-pykit
```
### From Source
```bash
git clone https://github.com/UN-GCPDS/gcpds-cv-pykit.git
cd gcpds-cv-pykit
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/UN-GCPDS/gcpds-cv-pykit.git
cd gcpds-cv-pykit
pip install -e ".[dev,docs]"
```
## 📦 Dependencies
### Core Dependencies
- `torch>=2.0.0` - Deep learning framework
- `torchvision>=0.15.0` - Computer vision utilities
- `numpy>=1.21.0` - Numerical computing
- `opencv-python>=4.6.0` - Image processing
- `matplotlib>=3.5.0` - Plotting and visualization
- `wandb>=0.15.0` - Experiment tracking
- `tqdm>=4.64.0` - Progress bars
- `Pillow>=9.0.0` - Image handling
- `scipy>=1.9.0` - Scientific computing
- `pandas>=1.4.0` - Data manipulation
- `kagglehub` - Kaggle dataset downloads
### Optional Dependencies
- **Development**: `pytest>=7.0.0`, `pytest-cov>=4.0.0`, `black>=22.0.0`, `flake8>=5.0.0`, `isort>=5.10.0`
- **Documentation**: `sphinx>=5.0.0`, `sphinx-rtd-theme>=1.0.0`
## 🏗️ Project Structure
```
gcpds_cv_pykit/
├── baseline/
│ ├── trainers/ # Training utilities
│ │ ├── trainer.py # Main training class
│ │ └── __init__.py
│ ├── models/ # Model architectures
│ │ ├── UNet.py # U-Net implementation
│ │ ├── ResUNet.py # Residual U-Net
│ │ ├── DeepLabV3Plus.py # DeepLab v3+ implementation
│ │ ├── FCN.py # Fully Convolutional Network
│ │ └── __init__.py
│ ├── losses/ # Loss functions
│ │ ├── DICE.py # DICE loss implementation
│ │ ├── CrossEntropy.py # Cross entropy loss
│ │ ├── Focal.py # Focal loss implementation
│ │ ├── Tversky.py # Tversky loss implementation
│ │ └── __init__.py
│ ├── dataloaders/ # Data loading utilities
│ │ ├── dataloader.py # Custom data loading implementations
│ │ └── __init__.py
│ └── performance_model.py # Model evaluation and performance metrics
├── crowd/ # Crowd-specific implementations (under development)
├── datasets/ # Dataset utilities and Kaggle integration
│ ├── datasets.py # Kaggle dataset download and preparation
│ └── __init__.py
├── visuals/ # Visualization tools
│ ├── random_sample_visualizations.py # Dataset visualization utilities
│ └── __init__.py
├── _version.py # Version information
└── __init__.py
```
## 🚀 Quick Start
### Dataset Download and Preparation
```python
from gcpds_cv_pykit.datasets import download_and_prepare_dataset
# Download a Kaggle dataset
dataset_path = download_and_prepare_dataset('username/dataset-name/versions/1')
print(f"Dataset prepared at: {dataset_path}")
```
### Dataset Visualization
```python
from gcpds_cv_pykit.visuals import random_sample_visualization
from torch.utils.data import DataLoader
# Visualize random samples from your dataset
random_sample_visualization(
dataset=your_dataloader,
num_classes=2,
single_class=None, # Show all classes
max_classes_to_show=7,
type="baseline"
)
```
### Model Training
```python
from gcpds_cv_pykit.baseline.trainers import Trainer
from gcpds_cv_pykit.baseline.models import UNet
# Initialize model
model = UNet(in_channels=3, out_channels=2, pretrained=True)
# Configure training
config = {
'Device': 'cuda',
'Loss Function': 'DICE',
'Number of classes': 2,
'Learning Rate': 0.001,
'Epochs': 100,
'Batch Size': 8,
# ... other configuration parameters
}
# Initialize trainer
trainer = Trainer(
model=model,
train_dataset=train_dataloader,
val_dataset=val_dataloader,
config=config
)
# Start training
trainer.train()
```
### Model Performance Evaluation
```python
from gcpds_cv_pykit.baseline import PerformanceModels
# Evaluate trained model
config = {
'Device': 'cuda',
'Loss Function': 'DICE',
'Number of classes': 2,
# ... other configuration parameters
}
evaluator = PerformanceModels(
model=trained_model,
test_dataset=test_dataloader,
config=config
)
```
## 📊 Supported Models
The toolkit provides several state-of-the-art segmentation model architectures, all with ResNet34 backbone support:
### **UNet**
- **Architecture**: Classic U-Net with ResNet34 encoder
- **Features**:
- Skip connections for precise localization
- Pretrained ResNet34 backbone support
- Configurable encoder/decoder channels
- Optional final activation functions (sigmoid, softmax, tanh)
- Bilinear interpolation for upsampling
- **Use Case**: General-purpose segmentation tasks
### **ResUNet**
- **Architecture**: Residual U-Net with ResNet34 backbone
- **Features**:
- Enhanced skip connections with residual blocks
- ResNet34 pretrained encoder
- Improved gradient flow through residual connections
- Batch normalization and ReLU activations
- **Use Case**: Complex segmentation tasks requiring deeper feature learning
### **DeepLabV3Plus**
- **Architecture**: DeepLab v3+ with Atrous Spatial Pyramid Pooling (ASPP)
- **Features**:
- ASPP module for multi-scale feature extraction
- Separable convolutions for efficiency
- ResNet34 backbone with dilated convolutions
- Low-level feature fusion
- Configurable atrous rates
- **Use Case**: High-resolution segmentation with multi-scale context
### **FCN (Fully Convolutional Network)**
- **Architecture**: FCN with ResNet34 backbone
- **Features**:
- Multi-scale skip connections (FCN-8s, FCN-16s, FCN-32s style)
- Transposed convolutions for upsampling
- ResNet34 pretrained encoder
- Feature fusion at multiple scales
- **Use Case**: Semantic segmentation with multi-scale feature integration
### **Common Model Features**
- **Backbone**: ResNet34 with ImageNet pretrained weights
- **Input Channels**: Configurable (default: 3 for RGB)
- **Output Channels**: Configurable number of classes
- **Activation Functions**: Support for sigmoid, softmax, tanh, or none
- **Mixed Precision**: Compatible with AMP training
- **Memory Efficient**: Optimized for GPU memory usage
### **Model Usage Example**
```python
from gcpds_cv_pykit.baseline.models import UNet, ResUNet, DeepLabV3Plus, FCN
# UNet with default settings
model = UNet(
in_channels=3,
out_channels=2, # Binary segmentation
pretrained=True,
final_activation='sigmoid'
)
# DeepLabV3Plus for multi-class segmentation
model = DeepLabV3Plus(
in_channels=3,
out_channels=5, # 5-class segmentation
pretrained=True,
final_activation='softmax'
)
# ResUNet for complex segmentation
model = ResUNet(
in_channels=3,
out_channels=1,
pretrained=True
)
# FCN for semantic segmentation
model = FCN(
in_channels=3,
out_channels=10,
pretrained=True,
final_activation='softmax'
)
```
## 🎯 Loss Functions
The following loss functions are available through the baseline.losses module:
- **DICE Loss**: Optimized for segmentation tasks with class imbalance
- **Cross Entropy**: Standard classification loss for multi-class segmentation
- **Focal Loss**: Addresses class imbalance by focusing on hard examples
- **Tversky Loss**: Generalization of Dice loss with configurable precision/recall balance
### **Loss Function Usage**
```python
from gcpds_cv_pykit.baseline.losses import DICELoss, CrossEntropyLoss, FocalLoss, TverskyLoss
# DICE Loss for binary segmentation
dice_loss = DICELoss()
# Cross Entropy for multi-class segmentation
ce_loss = CrossEntropyLoss()
# Focal Loss for handling class imbalance
focal_loss = FocalLoss(alpha=0.25, gamma=2.0)
# Tversky Loss with custom alpha/beta
tversky_loss = TverskyLoss(alpha=0.3, beta=0.7)
```
## 📈 Metrics
The toolkit provides comprehensive evaluation metrics through the PerformanceModels class:
- **Dice Coefficient**: Overlap-based similarity measure
- **Jaccard Index (IoU)**: Intersection over Union
- **Sensitivity (Recall)**: True positive rate
- **Specificity**: True negative rate
All metrics are calculated both globally and per-class with detailed statistical analysis.
## 🔧 Configuration
The toolkit uses dictionary-based configuration. Key parameters include:
```python
config = {
# Model Configuration
'Model': 'UNet',
'Backbone': 'resnet34',
'Pretrained': True,
'Number of classes': 2,
'Input size': [3, 256, 256],
# Training Configuration
'Loss Function': 'DICE',
'Optimizer': 'Adam',
'Learning Rate': 0.001,
'Epochs': 100,
'Batch Size': 8,
# Advanced Options
'AMP': True, # Automatic Mixed Precision
'Device': 'cuda',
'Wandb monitoring': ['api_key', 'project_name', 'run_name']
}
```
## 📊 Experiment Tracking
Integration with Weights & Biases for experiment tracking:
```python
config['Wandb monitoring'] = [
'your_wandb_api_key',
'your_project_name',
'experiment_name'
]
```
## 🎨 Visualization
Built-in visualization tools for:
- Random dataset sample visualization
- Multi-class segmentation mask display
- Training/validation curves (through wandb integration)
- Model predictions vs ground truth
Example usage:
```python
from gcpds_cv_pykit.visuals import random_sample_visualization
# Visualize a single class
random_sample_visualization(
dataset=dataloader,
num_classes=5,
single_class=1, # Show only class 1
type="baseline"
)
# Visualize multiple classes
random_sample_visualization(
dataset=dataloader,
num_classes=5,
max_classes_to_show=3,
type="baseline"
)
```
## 🧪 Testing
Run the test suite:
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=gcpds_cv_pykit
# Run specific test file
pytest tests/test_models.py
```
## 📚 Documentation
Build documentation locally:
```bash
cd docs
make html
```
## 🤝 Contributing
We welcome contributions! Please follow these steps:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Setup
```bash
# Clone the repository
git clone https://github.com/UN-GCPDS/gcpds-cv-pykit.git
cd gcpds-cv-pykit
# Install in development mode
pip install -e ".[dev]"
# Run code formatting
black gcpds_cv_pykit/
isort gcpds_cv_pykit/
# Run linting
flake8 gcpds_cv_pykit/
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 👥 Authors
- **GCPDS Team** - [gcpds_man@unal.edu.co](mailto:gcpds_man@unal.edu.co)
## 🙏 Acknowledgments
- PyTorch team for the excellent deep learning framework
- The computer vision community for inspiration and best practices
- Kaggle for providing accessible datasets through kagglehub
- Contributors and users of this toolkit
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/UN-GCPDS/gcpds-cv-pykit/issues)
- **Documentation**: [Read the Docs](https://gcpds-cv-pykit.readthedocs.io/)
- **Email**: gcpds_man@unal.edu.co
---
**Note**: This project is actively maintained and regularly updated. The API is stable for the current feature set. Please check the documentation and changelog for the latest updates and new features.
Raw data
{
"_id": null,
"home_page": "https://github.com/UN-GCPDS/gcpds-cv-pykit",
"name": "gcpds-cv-pykit",
"maintainer": "GCPDS Team",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "gcpds_man@unal.edu.co",
"keywords": "computer vision, segmentation, deep learning, pytorch, unet, medical imaging, image processing, machine learning, artificial intelligence",
"author": "GCPDS Team",
"author_email": "gcpds_man@unal.edu.co",
"download_url": "https://files.pythonhosted.org/packages/71/fb/4cf7727a8c31e619aee5b125939ac5a38e93cb64e01f73f18ec6ba6b52ca/gcpds-cv-pykit-0.1.0.43.tar.gz",
"platform": "any",
"description": "# GCPDS Computer Vision Python Kit\r\n\r\nA comprehensive toolkit for computer vision and segmentation tasks, developed by the GCPDS Team. This package provides state-of-the-art tools for training, evaluating, and deploying segmentation models with support for various architectures, loss functions, and performance metrics.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Segmentation Models**: Support for UNet, ResUNet, DeepLabV3Plus, and FCN architectures\r\n- **Multiple Loss Functions**: DICE, Cross Entropy, Focal Loss, and Tversky Loss\r\n- **Performance Evaluation**: Comprehensive metrics including Dice, Jaccard, Sensitivity, and Specificity\r\n- **Training Pipeline**: Complete training workflow with validation and monitoring\r\n- **Data Loading**: Efficient data loading utilities for segmentation tasks\r\n- **Experiment Tracking**: Integration with Weights & Biases (wandb)\r\n- **Mixed Precision Training**: Automatic Mixed Precision (AMP) support for faster training\r\n- **Dataset Management**: Built-in Kaggle dataset download and preparation utilities\r\n- **Visualization Tools**: Random sample visualization utilities for dataset exploration\r\n- **Memory Management**: Efficient memory handling and cleanup utilities\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python >= 3.8\r\n- PyTorch >= 2.0.0\r\n- CUDA-compatible GPU (recommended)\r\n\r\n## \ud83d\udd27 Installation\r\n\r\n### From PyPI\r\n```bash\r\npip install gcpds-cv-pykit\r\n```\r\n\r\n### From Source\r\n```bash\r\ngit clone https://github.com/UN-GCPDS/gcpds-cv-pykit.git\r\ncd gcpds-cv-pykit\r\npip install -e .\r\n```\r\n\r\n### Development Installation\r\n```bash\r\ngit clone https://github.com/UN-GCPDS/gcpds-cv-pykit.git\r\ncd gcpds-cv-pykit\r\npip install -e \".[dev,docs]\"\r\n```\r\n\r\n## \ud83d\udce6 Dependencies\r\n\r\n### Core Dependencies\r\n- `torch>=2.0.0` - Deep learning framework\r\n- `torchvision>=0.15.0` - Computer vision utilities\r\n- `numpy>=1.21.0` - Numerical computing\r\n- `opencv-python>=4.6.0` - Image processing\r\n- `matplotlib>=3.5.0` - Plotting and visualization\r\n- `wandb>=0.15.0` - Experiment tracking\r\n- `tqdm>=4.64.0` - Progress bars\r\n- `Pillow>=9.0.0` - Image handling\r\n- `scipy>=1.9.0` - Scientific computing\r\n- `pandas>=1.4.0` - Data manipulation\r\n- `kagglehub` - Kaggle dataset downloads\r\n\r\n### Optional Dependencies\r\n- **Development**: `pytest>=7.0.0`, `pytest-cov>=4.0.0`, `black>=22.0.0`, `flake8>=5.0.0`, `isort>=5.10.0`\r\n- **Documentation**: `sphinx>=5.0.0`, `sphinx-rtd-theme>=1.0.0`\r\n\r\n## \ud83c\udfd7\ufe0f Project Structure\r\n\r\n```\r\ngcpds_cv_pykit/\r\n\u251c\u2500\u2500 baseline/\r\n\u2502 \u251c\u2500\u2500 trainers/ # Training utilities\r\n\u2502 \u2502 \u251c\u2500\u2500 trainer.py # Main training class\r\n\u2502 \u2502 \u2514\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 models/ # Model architectures\r\n\u2502 \u2502 \u251c\u2500\u2500 UNet.py # U-Net implementation\r\n\u2502 \u2502 \u251c\u2500\u2500 ResUNet.py # Residual U-Net\r\n\u2502 \u2502 \u251c\u2500\u2500 DeepLabV3Plus.py # DeepLab v3+ implementation\r\n\u2502 \u2502 \u251c\u2500\u2500 FCN.py # Fully Convolutional Network\r\n\u2502 \u2502 \u2514\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 losses/ # Loss functions\r\n\u2502 \u2502 \u251c\u2500\u2500 DICE.py # DICE loss implementation\r\n\u2502 \u2502 \u251c\u2500\u2500 CrossEntropy.py # Cross entropy loss\r\n\u2502 \u2502 \u251c\u2500\u2500 Focal.py # Focal loss implementation\r\n\u2502 \u2502 \u251c\u2500\u2500 Tversky.py # Tversky loss implementation\r\n\u2502 \u2502 \u2514\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 dataloaders/ # Data loading utilities\r\n\u2502 \u2502 \u251c\u2500\u2500 dataloader.py # Custom data loading implementations\r\n\u2502 \u2502 \u2514\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 performance_model.py # Model evaluation and performance metrics\r\n\u251c\u2500\u2500 crowd/ # Crowd-specific implementations (under development)\r\n\u251c\u2500\u2500 datasets/ # Dataset utilities and Kaggle integration\r\n\u2502 \u251c\u2500\u2500 datasets.py # Kaggle dataset download and preparation\r\n\u2502 \u2514\u2500\u2500 __init__.py\r\n\u251c\u2500\u2500 visuals/ # Visualization tools\r\n\u2502 \u251c\u2500\u2500 random_sample_visualizations.py # Dataset visualization utilities\r\n\u2502 \u2514\u2500\u2500 __init__.py\r\n\u251c\u2500\u2500 _version.py # Version information\r\n\u2514\u2500\u2500 __init__.py\r\n```\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Dataset Download and Preparation\r\n\r\n```python\r\nfrom gcpds_cv_pykit.datasets import download_and_prepare_dataset\r\n\r\n# Download a Kaggle dataset\r\ndataset_path = download_and_prepare_dataset('username/dataset-name/versions/1')\r\nprint(f\"Dataset prepared at: {dataset_path}\")\r\n```\r\n\r\n### Dataset Visualization\r\n\r\n```python\r\nfrom gcpds_cv_pykit.visuals import random_sample_visualization\r\nfrom torch.utils.data import DataLoader\r\n\r\n# Visualize random samples from your dataset\r\nrandom_sample_visualization(\r\n dataset=your_dataloader,\r\n num_classes=2,\r\n single_class=None, # Show all classes\r\n max_classes_to_show=7,\r\n type=\"baseline\"\r\n)\r\n```\r\n\r\n### Model Training\r\n\r\n```python\r\nfrom gcpds_cv_pykit.baseline.trainers import Trainer\r\nfrom gcpds_cv_pykit.baseline.models import UNet\r\n\r\n# Initialize model\r\nmodel = UNet(in_channels=3, out_channels=2, pretrained=True)\r\n\r\n# Configure training\r\nconfig = {\r\n 'Device': 'cuda',\r\n 'Loss Function': 'DICE',\r\n 'Number of classes': 2,\r\n 'Learning Rate': 0.001,\r\n 'Epochs': 100,\r\n 'Batch Size': 8,\r\n # ... other configuration parameters\r\n}\r\n\r\n# Initialize trainer\r\ntrainer = Trainer(\r\n model=model,\r\n train_dataset=train_dataloader,\r\n val_dataset=val_dataloader,\r\n config=config\r\n)\r\n\r\n# Start training\r\ntrainer.train()\r\n```\r\n\r\n### Model Performance Evaluation\r\n\r\n```python\r\nfrom gcpds_cv_pykit.baseline import PerformanceModels\r\n\r\n# Evaluate trained model\r\nconfig = {\r\n 'Device': 'cuda',\r\n 'Loss Function': 'DICE',\r\n 'Number of classes': 2,\r\n # ... other configuration parameters\r\n}\r\n\r\nevaluator = PerformanceModels(\r\n model=trained_model,\r\n test_dataset=test_dataloader,\r\n config=config\r\n)\r\n```\r\n\r\n## \ud83d\udcca Supported Models\r\n\r\nThe toolkit provides several state-of-the-art segmentation model architectures, all with ResNet34 backbone support:\r\n\r\n### **UNet**\r\n- **Architecture**: Classic U-Net with ResNet34 encoder\r\n- **Features**:\r\n - Skip connections for precise localization\r\n - Pretrained ResNet34 backbone support\r\n - Configurable encoder/decoder channels\r\n - Optional final activation functions (sigmoid, softmax, tanh)\r\n - Bilinear interpolation for upsampling\r\n- **Use Case**: General-purpose segmentation tasks\r\n\r\n### **ResUNet**\r\n- **Architecture**: Residual U-Net with ResNet34 backbone\r\n- **Features**:\r\n - Enhanced skip connections with residual blocks\r\n - ResNet34 pretrained encoder\r\n - Improved gradient flow through residual connections\r\n - Batch normalization and ReLU activations\r\n- **Use Case**: Complex segmentation tasks requiring deeper feature learning\r\n\r\n### **DeepLabV3Plus**\r\n- **Architecture**: DeepLab v3+ with Atrous Spatial Pyramid Pooling (ASPP)\r\n- **Features**:\r\n - ASPP module for multi-scale feature extraction\r\n - Separable convolutions for efficiency\r\n - ResNet34 backbone with dilated convolutions\r\n - Low-level feature fusion\r\n - Configurable atrous rates\r\n- **Use Case**: High-resolution segmentation with multi-scale context\r\n\r\n### **FCN (Fully Convolutional Network)**\r\n- **Architecture**: FCN with ResNet34 backbone\r\n- **Features**:\r\n - Multi-scale skip connections (FCN-8s, FCN-16s, FCN-32s style)\r\n - Transposed convolutions for upsampling\r\n - ResNet34 pretrained encoder\r\n - Feature fusion at multiple scales\r\n- **Use Case**: Semantic segmentation with multi-scale feature integration\r\n\r\n### **Common Model Features**\r\n- **Backbone**: ResNet34 with ImageNet pretrained weights\r\n- **Input Channels**: Configurable (default: 3 for RGB)\r\n- **Output Channels**: Configurable number of classes\r\n- **Activation Functions**: Support for sigmoid, softmax, tanh, or none\r\n- **Mixed Precision**: Compatible with AMP training\r\n- **Memory Efficient**: Optimized for GPU memory usage\r\n\r\n### **Model Usage Example**\r\n```python\r\nfrom gcpds_cv_pykit.baseline.models import UNet, ResUNet, DeepLabV3Plus, FCN\r\n\r\n# UNet with default settings\r\nmodel = UNet(\r\n in_channels=3,\r\n out_channels=2, # Binary segmentation\r\n pretrained=True,\r\n final_activation='sigmoid'\r\n)\r\n\r\n# DeepLabV3Plus for multi-class segmentation\r\nmodel = DeepLabV3Plus(\r\n in_channels=3,\r\n out_channels=5, # 5-class segmentation\r\n pretrained=True,\r\n final_activation='softmax'\r\n)\r\n\r\n# ResUNet for complex segmentation\r\nmodel = ResUNet(\r\n in_channels=3,\r\n out_channels=1,\r\n pretrained=True\r\n)\r\n\r\n# FCN for semantic segmentation\r\nmodel = FCN(\r\n in_channels=3,\r\n out_channels=10,\r\n pretrained=True,\r\n final_activation='softmax'\r\n)\r\n```\r\n\r\n## \ud83c\udfaf Loss Functions\r\n\r\nThe following loss functions are available through the baseline.losses module:\r\n\r\n- **DICE Loss**: Optimized for segmentation tasks with class imbalance\r\n- **Cross Entropy**: Standard classification loss for multi-class segmentation\r\n- **Focal Loss**: Addresses class imbalance by focusing on hard examples\r\n- **Tversky Loss**: Generalization of Dice loss with configurable precision/recall balance\r\n\r\n### **Loss Function Usage**\r\n```python\r\nfrom gcpds_cv_pykit.baseline.losses import DICELoss, CrossEntropyLoss, FocalLoss, TverskyLoss\r\n\r\n# DICE Loss for binary segmentation\r\ndice_loss = DICELoss()\r\n\r\n# Cross Entropy for multi-class segmentation\r\nce_loss = CrossEntropyLoss()\r\n\r\n# Focal Loss for handling class imbalance\r\nfocal_loss = FocalLoss(alpha=0.25, gamma=2.0)\r\n\r\n# Tversky Loss with custom alpha/beta\r\ntversky_loss = TverskyLoss(alpha=0.3, beta=0.7)\r\n```\r\n\r\n## \ud83d\udcc8 Metrics\r\n\r\nThe toolkit provides comprehensive evaluation metrics through the PerformanceModels class:\r\n\r\n- **Dice Coefficient**: Overlap-based similarity measure\r\n- **Jaccard Index (IoU)**: Intersection over Union\r\n- **Sensitivity (Recall)**: True positive rate\r\n- **Specificity**: True negative rate\r\n\r\nAll metrics are calculated both globally and per-class with detailed statistical analysis.\r\n\r\n## \ud83d\udd27 Configuration\r\n\r\nThe toolkit uses dictionary-based configuration. Key parameters include:\r\n\r\n```python\r\nconfig = {\r\n # Model Configuration\r\n 'Model': 'UNet',\r\n 'Backbone': 'resnet34',\r\n 'Pretrained': True,\r\n 'Number of classes': 2,\r\n 'Input size': [3, 256, 256],\r\n \r\n # Training Configuration\r\n 'Loss Function': 'DICE',\r\n 'Optimizer': 'Adam',\r\n 'Learning Rate': 0.001,\r\n 'Epochs': 100,\r\n 'Batch Size': 8,\r\n \r\n # Advanced Options\r\n 'AMP': True, # Automatic Mixed Precision\r\n 'Device': 'cuda',\r\n 'Wandb monitoring': ['api_key', 'project_name', 'run_name']\r\n}\r\n```\r\n\r\n## \ud83d\udcca Experiment Tracking\r\n\r\nIntegration with Weights & Biases for experiment tracking:\r\n\r\n```python\r\nconfig['Wandb monitoring'] = [\r\n 'your_wandb_api_key',\r\n 'your_project_name',\r\n 'experiment_name'\r\n]\r\n```\r\n\r\n## \ud83c\udfa8 Visualization\r\n\r\nBuilt-in visualization tools for:\r\n- Random dataset sample visualization\r\n- Multi-class segmentation mask display\r\n- Training/validation curves (through wandb integration)\r\n- Model predictions vs ground truth\r\n\r\nExample usage:\r\n```python\r\nfrom gcpds_cv_pykit.visuals import random_sample_visualization\r\n\r\n# Visualize a single class\r\nrandom_sample_visualization(\r\n dataset=dataloader,\r\n num_classes=5,\r\n single_class=1, # Show only class 1\r\n type=\"baseline\"\r\n)\r\n\r\n# Visualize multiple classes\r\nrandom_sample_visualization(\r\n dataset=dataloader,\r\n num_classes=5,\r\n max_classes_to_show=3,\r\n type=\"baseline\"\r\n)\r\n```\r\n\r\n## \ud83e\uddea Testing\r\n\r\nRun the test suite:\r\n\r\n```bash\r\n# Run all tests\r\npytest\r\n\r\n# Run with coverage\r\npytest --cov=gcpds_cv_pykit\r\n\r\n# Run specific test file\r\npytest tests/test_models.py\r\n```\r\n\r\n## \ud83d\udcda Documentation\r\n\r\nBuild documentation locally:\r\n\r\n```bash\r\ncd docs\r\nmake html\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please follow these steps:\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/UN-GCPDS/gcpds-cv-pykit.git\r\ncd gcpds-cv-pykit\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n\r\n# Run code formatting\r\nblack gcpds_cv_pykit/\r\nisort gcpds_cv_pykit/\r\n\r\n# Run linting\r\nflake8 gcpds_cv_pykit/\r\n```\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\udc65 Authors\r\n\r\n- **GCPDS Team** - [gcpds_man@unal.edu.co](mailto:gcpds_man@unal.edu.co)\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- PyTorch team for the excellent deep learning framework\r\n- The computer vision community for inspiration and best practices\r\n- Kaggle for providing accessible datasets through kagglehub\r\n- Contributors and users of this toolkit\r\n\r\n## \ud83d\udcde Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/UN-GCPDS/gcpds-cv-pykit/issues)\r\n- **Documentation**: [Read the Docs](https://gcpds-cv-pykit.readthedocs.io/)\r\n- **Email**: gcpds_man@unal.edu.co\r\n\r\n---\r\n\r\n**Note**: This project is actively maintained and regularly updated. The API is stable for the current feature set. Please check the documentation and changelog for the latest updates and new features.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive toolkit for computer vision and segmentation tasks",
"version": "0.1.0.43",
"project_urls": {
"Bug Reports": "https://github.com/UN-GCPDS/gcpds-cv-pykit/issues",
"Documentation": "https://gcpds-cv-pykit.readthedocs.io/",
"Homepage": "https://github.com/UN-GCPDS/gcpds-cv-pykit",
"Source": "https://github.com/UN-GCPDS/gcpds-cv-pykit"
},
"split_keywords": [
"computer vision",
" segmentation",
" deep learning",
" pytorch",
" unet",
" medical imaging",
" image processing",
" machine learning",
" artificial intelligence"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b108b7732b0e6d7d617bc99d2661d0a40a55485432f18087f1115b25ca107bb5",
"md5": "4459fbaef24391d2056925e0bb99dd67",
"sha256": "4bfefe1a0dbb601cc5dbab84d1ac20e7ec4fc95eee261f83c414b7a47f045026"
},
"downloads": -1,
"filename": "gcpds_cv_pykit-0.1.0.43-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4459fbaef24391d2056925e0bb99dd67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43560,
"upload_time": "2025-07-29T04:13:59",
"upload_time_iso_8601": "2025-07-29T04:13:59.387157Z",
"url": "https://files.pythonhosted.org/packages/b1/08/b7732b0e6d7d617bc99d2661d0a40a55485432f18087f1115b25ca107bb5/gcpds_cv_pykit-0.1.0.43-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "71fb4cf7727a8c31e619aee5b125939ac5a38e93cb64e01f73f18ec6ba6b52ca",
"md5": "597e4b0833310e0977d010c533f9dcf7",
"sha256": "c0652a87ea3a1cd571d3e64128f11c88482d04cfd70484282e9a1126334933f0"
},
"downloads": -1,
"filename": "gcpds-cv-pykit-0.1.0.43.tar.gz",
"has_sig": false,
"md5_digest": "597e4b0833310e0977d010c533f9dcf7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 38256,
"upload_time": "2025-07-29T04:14:00",
"upload_time_iso_8601": "2025-07-29T04:14:00.768495Z",
"url": "https://files.pythonhosted.org/packages/71/fb/4cf7727a8c31e619aee5b125939ac5a38e93cb64e01f73f18ec6ba6b52ca/gcpds-cv-pykit-0.1.0.43.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 04:14:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "UN-GCPDS",
"github_project": "gcpds-cv-pykit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gcpds-cv-pykit"
}
JSON
