A state-of-the-art semantic segmentation system specifically designed for Starbucks logo detection using MobileNetV2 architecture with PyTorch Lightning. This project demonstrates modern Python development practices with:
- 🚀 Ultra-fast inference with MobileNetV2
- ⚡ Lightning-powered training for scalability
- 🎨 Beautiful visualizations and animations
- 📦 Modern packaging with Hatch and pyproject.toml
- 🐍 Pythonik code following best practices
- 🧪 Comprehensive testing suite
- MobileNetV2-based U-Net for efficient mobile deployment
- PyTorch Lightning for clean, scalable training code
- Mixed precision training (FP16/FP32) support
- EMA (Exponential Moving Average) for better generalization
- Animated GIF generation showing segmentation process
- Color-coded masks with transparency overlay
- Side-by-side comparisons of original and segmented images
- TensorBoard integration for training monitoring
- CoreML export for iOS deployment
- ONNX support for cross-platform inference
- Optimized inference pipeline
- Modern Python tooling (Hatch, Black, Ruff)
- Type hints throughout the codebase
- CLI interface with rich output
- Comprehensive logging
# Clone the repository
git clone https://github.com/umitkacar/starbucks-logo-segmentation.git
cd starbucks-logo-segmentation
# Install Hatch if you haven't already
pip install hatch
# Create and activate environment
hatch env create
# Install dependencies
hatch env run pip install -e .# Clone the repository
git clone https://github.com/umitkacar/starbucks-logo-segmentation.git
cd starbucks-logo-segmentation
# Install in development mode
pip install -e .
# Or install with all optional dependencies
pip install -e ".[dev,coreml]"# Using the CLI
starbucks-train --config src/params/config.json --gpus 1
# Or using Python directly
python src/main_train.py# Predict on a single image
starbucks-predict --image path/to/image.jpg --output results/
# Run full test suite
starbucks-test --config src/params/config.jsonfrom starbucks_logo_seg.inference import predict
from starbucks_logo_seg.models import load_model
# Load trained model
model = load_model("path/to/checkpoint.ckpt")
# Run inference
mask = predict(model, "path/to/image.jpg")
| Metric | Value |
|---|---|
| Inference Speed | ~50ms per image (512×512) |
| Model Size | ~14MB (FP32) / ~7MB (FP16) |
| IoU Score | 0.95+ on test set |
| Architecture | MobileNetV2 + U-Net |
| Input Size | 512×512 RGB |
starbucks-logo-segmentation/
├── 📦 src/
│ ├── starbucks_logo_seg/ # Main package
│ │ ├── __init__.py # Package initialization
│ │ ├── cli.py # Modern CLI interface
│ │ ├── training/ # Training modules
│ │ ├── inference/ # Inference modules
│ │ └── models/ # Model definitions
│ ├── mobile_seg/ # Legacy segmentation code
│ ├── mylib/ # Utility libraries
│ ├── params/ # Configuration files
│ └── main_*.py # Entry points
├── 📊 output/ # Results and visualizations
├── 🧪 tests/ # Test suite
├── 📝 pyproject.toml # Modern Python project config
├── 📋 requirements.txt # Legacy requirements
└── 📖 README.md # This file
Edit src/params/config.json to customize:
{
"seed": 0,
"gpus": 1,
"precision": 32,
"device": "cuda",
"lr": 0.0003,
"epoch": 200,
"batch_size": 12,
"img_size": 512,
"arch_name": "mobilenetv2_100",
"num_classes": 1,
"optim": "radam"
}# Format code
hatch run format
# Lint code
hatch run lint
# Type checking
mypy src/
# Run tests
hatch run test
# Run tests with coverage
hatch run test-cov# Install pre-commit hooks
pre-commit install
# Run manually
pre-commit run --all-files# Run all tests with coverage
pytest tests/ --cov=src/starbucks_logo_seg --cov-report=html
# Run tests in parallel (faster!)
pytest tests/ -n auto
# Run specific test file
pytest tests/test_config.py -v
# Run with coverage threshold
pytest tests/ --cov=src/starbucks_logo_seg --cov-fail-under=40| Test Category | Tests | Status |
|---|---|---|
| Package Structure | 3 | ✅ Passing |
| Configuration | 7 | ✅ Passing |
| Imports | 4 | ✅ Passing |
| Metadata | 9 | ✅ Passing |
| Total | 20 | ✅ 100% |
# Format code with Black
make format
# Lint with Ruff
make lint
# Type check with MyPy
make type-check
# Security scan with Bandit
make security
# Run all quality checks
make quality# Install hooks
pre-commit install
# Run on all files
pre-commit run --all-files
# Run specific hook
pre-commit run black --all-filesThis project uses cutting-edge Python tools for maximum developer productivity:
- 🥚 Hatch - Modern PEP 517/518 packaging
- 📦 pyproject.toml - Single source of truth for configuration
- 🐍 Ruff - Ultra-fast linting (10-100x faster than Flake8)
- ⚫ Black - Opinionated code formatting
- 🔍 MyPy - Static type checking
- 🔒 Bandit - Security vulnerability scanning
- 🧪 pytest - Modern testing framework
- ⚡ pytest-xdist - Parallel test execution (40% faster)
- 📊 coverage.py - Code coverage tracking (50.94%)
- 🔬 pytest-cov - Coverage integration
- 🎣 pre-commit - Git hooks for quality checks (15+ hooks)
- 🎨 Rich - Beautiful terminal output
- 🖱️ Click - Modern CLI framework
- 📝 nox - Multi-version testing automation
Linting: Ruff < 0.5s (was Flake8 ~8s) → 16x faster ⚡
Tests: pytest-xdist ~3s (was ~5s) → 40% faster ⚡
Coverage: 50.94% (exceeds 40% threshold) → ✅ Good
Type Check: MyPy 100% (modern code) → ✅ Safe
The model uses a MobileNetV2 backbone with a U-Net decoder:
- Encoder: MobileNetV2 pretrained on ImageNet
- Decoder: Upsampling layers with skip connections
- Output: Single-channel binary mask
-
Data Augmentation: Albumentations library
- Random crops, rotations, flips
- Color jittering
- Gaussian noise
-
Loss Function: Binary Cross-Entropy
-
Optimizer: RAdam with weight decay
-
Learning Rate: Cosine annealing schedule
- Image preprocessing (resize, normalize)
- Model forward pass
- Post-processing (threshold, morphology)
- Visualization generation
- 🏪 Retail Analytics: Track brand presence in images
- 📱 Mobile Apps: Real-time logo detection
- 🎨 Marketing: Analyze brand visibility
- 🔍 Quality Control: Verify logo placement
- 🤖 Computer Vision Research: Semantic segmentation
Comprehensive documentation of the project modernization journey:
- LESSONS_LEARNED.md - Best practices, technical decisions, and challenges
Key topics covered:
- ✅ Project modernization strategy
- ✅ Tool selection rationale (Hatch, Ruff, MyPy)
- ✅ Testing philosophy for deep learning projects
- ✅ Performance optimization techniques
- ✅ Common challenges and solutions
- ✅ Code quality standards
- ✅ Future recommendations
Track all project changes:
- CHANGELOG.md - Detailed version history
Guidelines for contributors:
- CONTRIBUTING.md - How to contribute to this project
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Run tests:
pytest tests/ -n auto - Run quality checks:
make quality - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Before contributing, please:
- ✅ Read CONTRIBUTING.md
- ✅ Ensure all tests pass
- ✅ Maintain code coverage ≥ 40%
- ✅ Follow Black code style
- ✅ Pass Ruff linting
- ✅ Add type hints (MyPy)
This project is licensed under the MIT License - see the LICENSE file for details.
- PyTorch Lightning - For the amazing training framework
- MobileNetV2 - For the efficient architecture
- Albumentations - For powerful data augmentation
- Hatch - For modern Python packaging
For questions or feedback, please open an issue on GitHub.