pyw-vision 👁️

Computer vision utilities & helpers per l'ecosistema pythonWoods.

Overview

pyw-vision fornisce utilities e helpers per computer vision, con focus su semplicità d'uso e performance. Parte dell'ecosistema pythonWoods, si integra perfettamente con gli altri moduli per soluzioni complete di image processing e analisi visiva.

Features

🖼️ Image Processing

• Resize & Transform: Ridimensionamento intelligente con aspect ratio
• Filters & Effects: Blur, sharpen, brightness, contrast
• Format Conversion: Supporto multi-formato (JPEG, PNG, WebP, TIFF)
• Batch Processing: Elaborazione efficiente di grosse quantità di immagini

🎯 Object Detection

• YOLO Integration: Supporto per YOLOv5/v8 con model caching
• Custom Models: Caricamento di modelli personalizzati
• Bounding Boxes: Utilities per gestione e rendering bbox
• Confidence Filtering: Filtri automatici per detection quality

🔍 Feature Extraction

• Keypoints Detection: SIFT, ORB, Harris corners
• Descriptors: Feature matching e similarity
• Template Matching: Ricerca pattern in immagini
• Contour Analysis: Shape detection e analysis

📊 Analysis Tools

• Image Metrics: Histogram, statistics, quality metrics
• Comparison: SSIM, MSE, perceptual difference
• Color Analysis: Palette extraction, dominant colors
• Geometric: Perspective correction, distortion removal

Installation

# Base installation
pip install pyw-vision

# Con supporto deep learning (YOLOv8, PyTorch)
pip install pyw-vision[ml]

# Computer vision completo (include motion detection)
pip install pyw-cv  # Bundle: pyw-vision + pyw-motion

Quick Start

Basic Image Processing

from pyw.vision import Image, ImageProcessor

# Carica e processa immagine
img = Image.from_file("photo.jpg")

# Chain processing
processed = (img
    .resize(width=800, keep_aspect=True)
    .enhance_contrast(1.2)
    .apply_blur(radius=2)
    .convert_format("webp")
)

processed.save("output.webp", quality=85)

Object Detection

from pyw.vision import ObjectDetector

# Setup detector con model caching automatico
detector = ObjectDetector.yolo_v8(model_size="medium")

# Detection su singola immagine
results = detector.detect("image.jpg", confidence=0.5)

for detection in results:
    print(f"Object: {detection.class_name} ({detection.confidence:.2f})")
    print(f"Bbox: {detection.bbox}")

# Batch detection
batch_results = detector.detect_batch([
    "img1.jpg", "img2.jpg", "img3.jpg"
], max_workers=4)

Feature Matching

from pyw.vision import FeatureExtractor, FeatureMatcher

# Estrai features da due immagini
extractor = FeatureExtractor.sift(n_features=1000)
features1 = extractor.extract("template.jpg")
features2 = extractor.extract("scene.jpg")

# Match features
matcher = FeatureMatcher(algorithm="flann")
matches = matcher.match(features1, features2)

# Trova homography
homography = matcher.find_homography(matches, min_matches=10)
if homography is not None:
    print("Template found in scene!")

Advanced Usage

Custom Image Pipeline

from pyw.vision import ImagePipeline, filters

# Definisci pipeline custom
pipeline = ImagePipeline([
    filters.NormalizeLighting(),
    filters.RemoveNoise(method="bilateral"),
    filters.EnhanceSharpness(factor=1.5),
    filters.ColorBalance(auto=True)
])

# Applica a singola immagine
result = pipeline.process("noisy_image.jpg")

# Batch processing con progress
results = pipeline.process_batch(
    ["img1.jpg", "img2.jpg", "img3.jpg"],
    output_dir="processed/",
    show_progress=True
)

Smart Cropping

from pyw.vision import SmartCropper

cropper = SmartCropper(
    target_ratio=(16, 9),
    focus_detection=True  # Usa face/object detection
)

# Crop intelligente mantenendo soggetti importanti
cropped = cropper.crop("portrait.jpg")
cropped.save("cropped_16x9.jpg")

# Crop multipli per social media
variants = cropper.crop_variants("image.jpg", formats=[
    ("instagram_post", 1080, 1080),
    ("instagram_story", 1080, 1920),
    ("facebook_cover", 1200, 630)
])

Real-time Processing

from pyw.vision import VideoProcessor
import cv2

# Setup video processor
processor = VideoProcessor(
    input_source=0,  # Webcam
    fps_limit=30
)

@processor.frame_handler
def process_frame(frame):
    # Applica detection in real-time
    detections = detector.detect(frame, confidence=0.6)
    
    # Disegna bounding boxes
    for det in detections:
        frame = det.draw_on(frame, color="red", thickness=2)
    
    return frame

# Avvia processing
processor.start()

Integration con pyw-fs

from pyw.vision import Image
from pyw.fs import FileSystem

# Usa filesystem unificato (local/S3/GCS)
fs = FileSystem.from_url("s3://my-bucket/images/")

# Processa immagini remote
for image_path in fs.glob("*.jpg"):
    img = Image.from_fs(fs, image_path)
    
    # Genera thumbnail
    thumb = img.resize(width=200, keep_aspect=True)
    
    # Salva thumbnail
    thumb_path = image_path.replace(".jpg", "_thumb.jpg")
    thumb.save_to_fs(fs, thumb_path)

Configuration

from pyw.vision import VisionConfig
from pyw.core import BaseConfig

class MyVisionConfig(BaseConfig):
    # Model paths e caching
    model_cache_dir: str = "~/.pyw/vision/models"
    max_cache_size_gb: float = 5.0
    
    # Default processing settings
    default_image_quality: int = 85
    max_image_dimension: int = 4096
    
    # Performance
    max_workers: int = 4
    use_gpu: bool = True
    memory_limit_mb: int = 2048

# Applica config globalmente
VisionConfig.set_global(MyVisionConfig())

Performance Optimization

GPU Acceleration

from pyw.vision import accelerate

# Auto-detect e configura GPU
accelerate.setup_gpu(memory_fraction=0.8)

# Check disponibilità
if accelerate.gpu_available():
    print(f"GPU: {accelerate.gpu_info()}")
    
    # Usa GPU per batch processing
    detector = ObjectDetector.yolo_v8(device="cuda")

Memory Management

from pyw.vision import memory

# Context manager per gestione memoria
with memory.limit_usage(max_mb=1024):
    # Processa immagini grandi
    large_img = Image.from_file("huge_image.tiff")
    processed = large_img.resize(width=2000)

# Auto-cleanup di model cache
memory.cleanup_model_cache(max_age_days=7)

Profiling

from pyw.vision import profiler

# Profile performance di detection
with profiler.measure("yolo_detection") as p:
    results = detector.detect_batch(image_list)

print(f"Detection took {p.elapsed:.2f}s")
print(f"Images/sec: {len(image_list) / p.elapsed:.1f}")

Quality Assurance

Image Quality Metrics

from pyw.vision import quality

# Calcola metriche qualità
metrics = quality.analyze("image.jpg")
print(f"Sharpness: {metrics.sharpness:.2f}")
print(f"Brightness: {metrics.brightness:.2f}")
print(f"Contrast: {metrics.contrast:.2f}")
print(f"Noise level: {metrics.noise_level:.2f}")

# Compare due immagini
similarity = quality.compare("original.jpg", "processed.jpg")
print(f"SSIM: {similarity.ssim:.3f}")
print(f"PSNR: {similarity.psnr:.1f} dB")

Validation Pipeline

from pyw.vision import validation

# Valida batch di immagini
validator = validation.ImageValidator(
    min_resolution=(640, 480),
    max_file_size_mb=10,
    allowed_formats=["jpg", "png", "webp"]
)

results = validator.validate_batch("input_dir/")
valid_images = [r.path for r in results if r.is_valid]

Testing Support

from pyw.vision.testing import (
    generate_test_image, assert_image_equal,
    mock_detector, benchmark_pipeline
)

def test_image_processing():
    # Genera immagine test
    test_img = generate_test_image(
        width=800, height=600,
        pattern="checkerboard",
        noise_level=0.1
    )
    
    # Processa
    result = processor.enhance(test_img)
    
    # Assertions
    assert_image_equal(result, expected_result, tolerance=0.05)
    assert result.width == 800
    assert result.height == 600

# Mock detector per testing
with mock_detector(fake_detections=[
    {"class": "person", "confidence": 0.9, "bbox": [10, 10, 100, 200]}
]) as detector:
    results = detector.detect("test.jpg")
    assert len(results) == 1

CLI Tools

# Resize batch di immagini
pyw-vision resize input/*.jpg --width=800 --output=resized/

# Object detection con preview
pyw-vision detect image.jpg --model=yolov8m --show-preview

# Estrai frames da video
pyw-vision extract-frames video.mp4 --fps=1 --output=frames/

# Genera report qualità
pyw-vision quality-report images/ --format=html --output=report.html

# Benchmark performance
pyw-vision benchmark --model=yolov8s --images=test_set/ --iterations=10

Examples

Automated Photo Enhancement

from pyw.vision import PhotoEnhancer

# Setup enhancer con AI
enhancer = PhotoEnhancer(
    auto_exposure=True,
    noise_reduction=True,
    color_enhancement=True,
    face_aware=True  # Ottimizza per ritratti
)

# Enhance singola foto
enhanced = enhancer.enhance("photo.jpg")
enhanced.save("enhanced.jpg")

# Batch con settings ottimizzati per tipo
settings = {
    "portrait": {"face_aware": True, "skin_smoothing": 0.3},
    "landscape": {"saturation": 1.2, "clarity": 1.1},
    "night": {"denoise": "aggressive", "highlight_recovery": True}
}

for photo_type, photos in photo_collections.items():
    enhancer.update_settings(settings[photo_type])
    for photo in photos:
        enhanced = enhancer.enhance(photo)
        enhanced.save(f"enhanced/{photo_type}/{photo.name}")

Security Camera Analysis

from pyw.vision import SecurityAnalyzer
from pyw.logger import get_logger

logger = get_logger("security")

# Setup analyzer
analyzer = SecurityAnalyzer(
    person_detection=True,
    vehicle_detection=True,
    intrusion_zones=["front_door", "parking"],
    alert_confidence=0.7
)

# Analizza frame camera
frame = capture_camera_frame()
events = analyzer.analyze(frame, timestamp=datetime.now())

for event in events:
    if event.type == "person_detected":
        logger.warning(f"Person detected in {event.zone}")
        # Invia alert
        
    elif event.type == "vehicle_detected":
        logger.info(f"Vehicle detected: {event.details}")

Roadmap

• 🤖 AI Models: Integrazione con modelli Hugging Face, ONNX runtime
• 🎥 Video Processing: Advanced video analysis, object tracking
• 📱 Mobile Optimization: Lightweight models per deployment mobile
• ☁️ Cloud Integration: Processing su AWS Rekognition, Google Vision API
• 🔧 Custom Training: Tools per training di modelli personalizzati
• 📊 Analytics: Dashboard e reporting avanzati
• 🚀 Edge Computing: Ottimizzazioni per Raspberry Pi, edge devices

Architecture

pyw-vision/
├── pyw/
│   └── vision/
│       ├── __init__.py          # Public API
│       ├── core/
│       │   ├── image.py         # Image class e processing base
│       │   ├── detector.py      # Object detection
│       │   ├── features.py      # Feature extraction
│       │   └── pipeline.py      # Processing pipelines
│       ├── models/
│       │   ├── yolo.py         # YOLO integration
│       │   ├── opencv.py       # OpenCV models
│       │   └── custom.py       # Custom model loading
│       ├── filters/
│       │   ├── enhance.py      # Enhancement filters
│       │   ├── artistic.py     # Artistic effects
│       │   └── repair.py       # Image repair
│       ├── utils/
│       │   ├── metrics.py      # Quality metrics
│       │   ├── geometry.py     # Geometric operations
│       │   └── color.py        # Color space operations
│       └── cli/                # Command line tools
└── tests/                      # Test suite completa

Contributing

1. Fork & Clone: git clone https://github.com/pythonWoods/pyw-vision.git
2. Development setup: poetry install --with dev && poetry shell
3. Install test dependencies: poetry install --extras "ml"
4. Quality checks: ruff check . && mypy && pytest --cov
5. Test con immagini reali: Usa il dataset in tests/fixtures/
6. Documentation: Aggiorna examples per nuove features
7. Performance: Benchmark changes con pytest --benchmark-only
8. Pull Request: Include esempi e test coverage

Esplora il mondo della computer vision con pythonWoods! 🌲👁️

Links utili

Documentazione dev (work-in-progress) → https://pythonwoods.dev/docs/pyw-vision/latest/

Issue tracker → https://github.com/pythonWoods/pyw-vision/issues

Changelog → https://github.com/pythonWoods/pyw-vision/releases

© pythonWoods — MIT License