🦻 Ear Segmentation AI

A state-of-the-art ear segmentation library powered by deep learning. Detect and segment human ears in images and video streams with high accuracy and real-time performance.

✨ Features

• 🚀 High Performance: Optimized for both CPU and GPU processing
• 🎯 Accurate Detection: State-of-the-art U-Net architecture with ResNet18 encoder
• 📷 Multiple Input Sources: Images, videos, webcam, and URLs
• 🔄 Real-time Processing: Smooth webcam segmentation with temporal smoothing
• 📊 Batch Processing: Efficient processing of multiple images
• 🛠️ Easy to Use: Simple Python API and CLI interface
• 🎨 Visualization Tools: Built-in mask overlay and heatmap visualization
• 📦 Lightweight: Minimal dependencies, easy to install

🚀 Quick Start

Installation

# Using pip
pip install earsegmentationai

# Using poetry (recommended)
poetry add earsegmentationai

For detailed installation instructions, see Installation Guide.

Basic Usage

Python API

from earsegmentationai import ImageProcessor

# Initialize processor
processor = ImageProcessor(device="cpu")  # or "cuda:0" for GPU

# Process single image
result = processor.process("path/to/image.jpg")
print(f"Ear detected: {result.has_ear}")
print(f"Ear area: {result.ear_percentage:.2f}% of image")

# Process with visualization
result = processor.process(
    "path/to/image.jpg",
    return_visualization=True
)

Command Line

# Process single image
earsegmentationai process-image path/to/image.jpg --save-viz

# Process directory
earsegmentationai process-image path/to/images/ -o output/

# Real-time webcam
earsegmentationai webcam --device cuda:0

# Process video
earsegmentationai process-video path/to/video.mp4 -o output.avi

📚 Documentation

• Installation Guide
• Quick Start Guide
• Architecture Overview
• API Reference
• Contributing Guide
• Migration Guide

📚 Advanced Usage

Batch Processing

from earsegmentationai import ImageProcessor

processor = ImageProcessor(device="cuda:0")

# Process multiple images
results = processor.process([
    "image1.jpg",
    "image2.jpg",
    "image3.jpg"
])

print(f"Detection rate: {results.detection_rate:.1f}%")
print(f"Average ear area: {results.average_ear_area:.0f} pixels")

Video Processing

from earsegmentationai import VideoProcessor

processor = VideoProcessor(
    device="cuda:0",
    skip_frames=2,      # Process every 3rd frame
    smooth_masks=True   # Temporal smoothing
)

# Process video file
stats = processor.process(
    "video.mp4",
    output_path="output.mp4",
    display=True
)

print(f"FPS: {stats['average_fps']:.1f}")
print(f"Detection rate: {stats['detection_rate']:.1f}%")

Custom Configuration

from earsegmentationai import ImageProcessor, Config

# Create custom configuration
config = Config(
    model={"architecture": "FPN", "encoder_name": "resnet50"},
    processing={"input_size": (640, 480), "batch_size": 8}
)

processor = ImageProcessor(config=config, threshold=0.7)

🔧 Configuration

Model Settings

Parameter	Default	Description
architecture	"Unet"	Model architecture (Unet, FPN, PSPNet, DeepLabV3, DeepLabV3Plus)
encoder_name	"resnet18"	Encoder backbone
input_size	(480, 320)	Input image size (width, height)
threshold	0.5	Binary mask threshold

Processing Options

Parameter	Default	Description
device	"cpu"	Processing device (cpu, cuda:0)
batch_size	1	Batch size for processing
skip_frames	0	Frame skipping for video (0 = process all)
smooth_masks	True	Enable temporal smoothing for video

🏗️ Architecture

The library uses a modular architecture with clear separation of concerns:

earsegmentationai/
├── core/           # Core model and prediction logic
├── preprocessing/  # Image preprocessing and validation
├── postprocessing/ # Visualization and export utilities
├── api/           # High-level Python API
├── cli/           # Command-line interface
└── utils/         # Logging, exceptions, and helpers

🧪 Testing

# Run all tests
make test

# Run with coverage
make test-cov

# Run specific test suite
poetry run pytest tests/unit/test_transforms.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Setup development environment
make install-dev

# Run linting and formatting
make format
make lint

# Run pre-commit hooks
make pre-commit

📈 Performance

Device	Image Size	FPS	Memory
CPU (i7-9700K)	480×320	15	200 MB
GPU (RTX 3080)	480×320	120	400 MB
GPU (RTX 3080)	1920×1080	45	800 MB

📄 License

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

🙏 Acknowledgments

• Built with PyTorch and segmentation-models-pytorch
• Inspired by state-of-the-art segmentation research
• Thanks to all contributors and the open-source community

📞 Support

• 📧 Email: umitkacar.phd@gmail.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ by the Ear Segmentation AI Team