swajay-cv-toolkit 1.0.2

Advanced Computer Vision Toolkit for Image Classification

Swajay CV Toolkit 🚀

Advanced Computer Vision Toolkit for State-of-the-Art Image Classification

A comprehensive, production-ready toolkit featuring cutting-edge loss functions, model architectures, augmentation strategies, and training pipelines. Designed for researchers, practitioners, and Kaggle competitors who want to achieve state-of-the-art results with minimal code.

🎯 Key Features

🔥 Advanced Loss Functions

• Focal Loss - Handle class imbalance effectively
• Label Smoothing Cross Entropy - Improve generalization
• Polynomial Loss - Enhanced convergence properties
• Mixed Loss - Optimal combination of multiple loss functions
• Automatic class weight calculation for imbalanced datasets

🏗️ Universal Model Architectures

• Auto-adaptive models - Automatically adjust to any number of classes
• Multiple architectures - ConvNeXt, EfficientNet, ResNet, Vision Transformers
• Smart classifier heads - Optimal architecture for your dataset size
• Ensemble support - Combine multiple models for better performance

🎭 Professional Augmentations

• Competition-grade augmentations - Albumentations-based pipeline
• MixUp & CutMix - Advanced mixing strategies
• Test-Time Augmentation (TTA) - Boost inference accuracy
• 4 intensity levels - From lightweight to competition-grade

🏋️ Advanced Training Pipeline

• Mixed precision training - 2x faster with lower memory usage
• Differential learning rates - Optimal rates for backbone vs classifier
• Smart early stopping - Prevent overfitting automatically
• Comprehensive metrics - Track everything that matters

🚀 Quick Start

Installation

pip install swajay-cv-toolkit

Basic Usage

import torch
from swajay_cv_toolkit import create_model, get_loss_function, AdvancedTrainer
from torch.utils.data import DataLoader

# Create model for any number of classes
model = create_model('convnext_large', num_classes=10)

# Get advanced loss function
criterion = get_loss_function('mixed')  # Combines focal + label smoothing + poly

# Create optimizer 
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3)

# Advanced trainer with all the bells and whistles
trainer = AdvancedTrainer(
    model=model,
    criterion=criterion, 
    optimizer=optimizer,
    mixed_precision=True,
    gradient_clip_norm=1.0
)

# Train with automatic early stopping
history = trainer.fit(
    train_loader=train_loader,
    val_loader=val_loader, 
    epochs=50,
    early_stopping_patience=10
)

Complete Pipeline Example

from swajay_cv_toolkit import *

# 1. Setup
seed_everything(42)
device = setup_device()

# 2. Data augmentation
aug_config = get_augmentation_preset('competition', image_size=224)
train_dataset = AdvancedDataset(raw_dataset, aug_config['train_transform'])

# 3. Model creation  
model = create_model('convnext_large', num_classes=20).to(device)

# 4. Advanced training components
criterion = get_loss_function('mixed')
optimizer = create_optimizer(model, 'adamw', lr=1e-3, differential_lr=True)
scheduler = create_scheduler(optimizer, 'cosine', total_steps=1000)

# 5. Train with MixUp/CutMix
mixup_cutmix = MixupCutmix(mixup_alpha=0.2, cutmix_alpha=1.0)
trainer = AdvancedTrainer(model, criterion, optimizer, scheduler)
history = trainer.fit(train_loader, val_loader, epochs=30, mixup_cutmix=mixup_cutmix)

# 6. Test-Time Augmentation for final predictions
tta_predictor = TTAPredictor(model, device)
predictions = tta_predictor.predict_with_tta(test_dataset, aug_config['tta_transforms'])

🎯 Supported Use Cases

✅ Works on ANY Image Classification Task

• Medical Imaging - X-rays, MRIs, pathology slides
• Satellite Imagery - Land use, crop monitoring, disaster assessment
• Manufacturing - Quality control, defect detection
• Retail & E-commerce - Product categorization, visual search
• Security - Face recognition, object identification
• Agriculture - Plant disease detection, crop classification
• Wildlife & Conservation - Species identification, monitoring
• Food & Nutrition - Recipe classification, nutritional analysis
• Academic Research - Any custom image classification dataset

📊 Dataset Requirements

Just organize your data like this:

your_dataset/
├── class1/
│   ├── image1.jpg
│   ├── image2.jpg
│   └── ...
├── class2/
│   ├── image1.jpg
│   └── ...
└── class3/
    └── ...

That's it! The toolkit handles everything else automatically.

📚 Comprehensive Examples

Example 1: CIFAR-10 Classification

import torchvision.datasets as datasets
from swajay_cv_toolkit import *

# Load CIFAR-10
train_data = datasets.CIFAR10(root='./data', train=True, download=True)
test_data = datasets.CIFAR10(root='./data', train=False, download=True)

# Quick setup with presets
config = {
    'model': 'efficientnet_b4',
    'num_classes': 10,
    'image_size': 224
}

# One-line training
model, history = quick_train(
    train_data, test_data, 
    preset='competition',
    **config
)

Example 2: Custom Medical Dataset

# Your medical imaging dataset
train_data = datasets.ImageFolder('./medical_images/train')
test_data = datasets.ImageFolder('./medical_images/test')

# Specialized setup for medical images
model = create_model('convnext_large', num_classes=len(train_data.classes))
criterion = get_loss_function('focal', alpha=2, gamma=2)  # Good for imbalanced medical data

# Conservative augmentations for medical data
aug_config = get_augmentation_preset('standard', image_size=384)

# Train with higher resolution for medical precision
trainer = AdvancedTrainer(model, criterion, optimizer)
history = trainer.fit(train_loader, val_loader, epochs=100)

Example 3: Ensemble for Maximum Accuracy

# Create ensemble of different architectures
models = [
    create_model('convnext_large', num_classes=20),
    create_model('efficientnet_b7', num_classes=20),
    create_model('vit_large_patch16_224', num_classes=20)
]

ensemble = EnsembleModel(models, weights=[0.4, 0.35, 0.25])

# Train ensemble or individual models
for i, model in enumerate(models):
    print(f"Training model {i+1}/3...")
    trainer = AdvancedTrainer(model, criterion, optimizer)
    trainer.fit(train_loader, val_loader, epochs=30)

🔧 Advanced Features

🎯 Automatic Configuration

• Auto-detect classes - No need to count manually
• Auto-size networks - Optimal architecture for your data size
• Auto-balance classes - Handle imbalanced datasets automatically
• Auto-tune hyperparameters - Smart defaults that work

🔬 Research-Grade Components

All components are based on peer-reviewed research:

• ConvNeXt: Liu et al., 2022 - A ConvNet for the 2020s
• Focal Loss: Lin et al., 2017 - Focal Loss for Dense Object Detection
• Label Smoothing: Szegedy et al., 2016 - Rethinking the Inception Architecture
• MixUp: Zhang et al., 2017 - mixup: Beyond Empirical Risk Minimization
• Test-Time Augmentation: He et al., 2015 - Deep Residual Learning for Image Recognition
• AdamW: Loshchilov & Hutter, 2017 - Decoupled Weight Decay Regularization

🚀 Production Ready

• Memory efficient - Automatic mixed precision
• GPU optimized - Efficient data loading and processing
• Reproducible - Comprehensive seed management
• Robust - Extensive error handling and validation
• Scalable - Works from laptop to multi-GPU setups

🎮 Presets for Every Use Case

'lightweight' - Fast Development

• EfficientNet-B2, basic augmentations, 20 epochs
• Perfect for prototyping and quick experiments

'standard' - Balanced Performance

• ConvNeXt-Base, medium augmentations, 30 epochs
• Great balance of speed and accuracy

'competition' - Maximum Accuracy

• ConvNeXt-Large, aggressive augmentations, TTA, 40 epochs
• For when you need the absolute best results

'research' - Experimental Features

• Latest architectures, experimental techniques
• For pushing the boundaries

📖 Documentation

🚀 Quick References

• Installation Guide
• Quick Start Tutorial
• API Reference
• Example Gallery

📋 Detailed Guides

• Loss Functions Guide - When to use which loss
• Model Architecture Guide - Choosing the right model
• Augmentation Guide - Augmentation strategies
• Training Guide - Advanced training techniques
• Troubleshooting - Common issues and solutions

🤝 Contributing

We welcome contributions! Here's how:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: pytest tests/
5. Format code: black swajay_cv_toolkit/
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

🐛 Bug Reports

Found a bug? Open an issue with:

• Python version and OS
• Full error traceback
• Minimal code to reproduce
• Dataset information (if relevant)

💡 Feature Requests

Have an idea? Request a feature with:

• Use case description
• Expected behavior
• Example code (if possible)

🛠️ Technical Requirements

Minimum Requirements

• Python: 3.8+
• PyTorch: 1.12.0+
• CUDA: Optional but recommended
• RAM: 8GB+ (16GB+ recommended)
• Storage: 2GB for dependencies

Recommended Setup

• GPU: RTX 3080+ or Tesla V100+
• RAM: 32GB+
• Python: 3.10+
• CUDA: 11.7+

Dependencies

All dependencies are automatically installed:

torch>=1.12.0
torchvision>=0.13.0
timm>=0.6.0
albumentations>=1.3.0
opencv-python-headless>=4.6.0
numpy>=1.21.0
scikit-learn>=1.1.0
pandas>=1.4.0

💬 Get Help

• Documentation: swajay-cv-toolkit.readthedocs.io
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

🌟 Show Your Support

If this toolkit helps you:

• ⭐ Star the repository
• 🐦 Tweet about it
• 📝 Write a blog post
• 🗣️ Tell your colleagues
• 💖 Sponsor the project

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Citation

If you use this toolkit in your research, please cite:

@software{swajay_cv_toolkit,
  title={Swajay CV Toolkit: Advanced Computer Vision for Image Classification},
  author={Swajay},
  year={2024},
  url={https://github.com/swajayresources/swajay-cv-toolkit},
  version={1.0.0}
}

🙏 Acknowledgments

Special thanks to:

• PyTorch Team - For the amazing framework
• TIMM contributors - For the model implementations
• Albumentations team - For the augmentation library
• Research community - For the foundational papers
• Beta testers - For feedback and bug reports
• Contributors - For making this project better

---

Made with ❤️ by Swajay

⭐ Star on GitHub • 📖 Documentation • 🐛 Report Bug • 💡 Request Feature