Image Organizer Documentation

Welcome to the official documentation for Image Organizer, an AI-powered image organization, tagging, and discovery system for local photo collections.

Get Started in Minutes

Organize thousands of images with AI-powered tagging and search.

Get Started →

Interactive Showcase

Explore the capabilities of Image Organizer through our interactive visualization.

AI-Powered Tagging

Automatically tag images using multiple ML models including CLIP, BLIP, and face recognition.

Semantic Search

Search your collection using natural language queries like "photos of mountains at sunset".

Face Recognition

Automatically detect and recognize faces across your entire collection.

Visual Analytics

3D visualization of image clusters and relationships between photos.

Open Full Showcase

Key Features

Recent Additions

  • Square Thumbnails: Generate square-cropped thumbnails for consistent display
  • Parallel Processing: Multi-threaded thumbnail generation for large collections
  • Timeout Support: Configurable timeouts for thumbnail generation
  • Batch Pre-generation: CLI command for batch thumbnail generation
  • Embedded JPEG Support: Fast thumbnail extraction from RAW files
  • SQL Debug Logging: Performance analysis tools

Core Features

  • RAW File Support: Sony ARW, Nikon NEF, Canon CR2, and more
  • Automatic Organization: By date, location, content, and quality
  • Quality Scoring: ML-based quality assessment to surface best photos
  • Geolocation: GPS coordinate extraction and mapping
  • Temporal Analysis: Pattern discovery across time periods
  • Non-destructive: Sidecar files for metadata, never modify originals

Getting Started

Installation

# Clone the repository
git clone https://github.com/yourusername/image-organizer.git
cd image-organizer

# Install dependencies
pip install -r requirements.txt

# Initialize database
python -m image_organizer.cli init

Basic Usage

# Scan a directory for images
python -m image_organizer.cli scan /path/to/photos

# Generate thumbnails (new batch command)
python -m image_organizer.cli cache generate --size 150 --quality 92

# Start web server with thumbnail pre-generation
python -m image_organizer.cli serve --host localhost --port 8000 --pregen-thumbnails

CLI Reference

New Commands

  • cache generate: Batch thumbnail generation with timeout support
  • serve --pregen-thumbnails: Pre-generate thumbnails before starting server

Common Commands

  • scan <directory>: Scan directory for images
  • tag --all: Run AI tagging on all images
  • search "query": Semantic search across collection
  • serve: Start web interface
  • backup create: Create database backup

Development

This project uses Test-Driven Development (TDD) with Claude Code. Key development commands:

# Start TDD cycle for a feature
/tdd start "your feature"

# Run project health check
/hygiene

# Create quality-checked commit
/commit

See TDD with Claude for detailed workflow information.