# Photo Forensics
**Photo Forensics** is a Windows desktop application for identifying duplicate and near-duplicate photos in large image libraries.
It was built with a **safety-first, read-only workflow**: scanning and analysis never modify, move, rename, or delete the user's original photos.
## Features
- 🔎 Scan large photo libraries for duplicates
- 🧬 Detect exact duplicates
- 🖼️ Identify near-duplicate images using perceptual hashing
- 📊 Calculate total photo count and library size
- 💾 Estimate potentially reclaimable storage
- 📋 Group duplicate and near-duplicate results for review
- 📁 Browse file paths associated with each group
- 🖼️ Open images directly from the review interface
- 📂 Open the containing folder in Windows Explorer
- 📄 Export results to JSON and CSV
- 🛡️ Read-only scanning with no destructive file operations
## Why I Built It
Large personal photo libraries tend to accumulate duplicate files over time through phone backups, cloud synchronization, imports, and repeated transfers.
Photo Forensics was built to make that problem easier to analyze without immediately putting the underlying photo library at risk.
The design intentionally separates **discovery** from **cleanup**. The application analyzes the library and presents potential duplicates for human review rather than automatically deleting files.
## How It Works
Photo Forensics uses multiple levels of image analysis:
1. **Library inventory** — catalogs images and their metadata.
2. **Exact duplicate detection** — identifies files that are byte-for-byte duplicates.
3. **Perceptual hashing** — compares image characteristics to identify visually similar images.
4. **Grouping and reporting** — organizes potential duplicates into reviewable groups.
5. **Storage analysis** — estimates how much space could potentially be recovered.
## Safety Philosophy
Photo Forensics is designed around a **review-before-action** philosophy.
The application is intentionally non-destructive:
- Original photo files are never deleted by the scanner.
- Original photo files are never renamed or modified during scanning.
- Duplicate detection results are presented for human review.
- Quarantine and cleanup operations are kept separate from the scanning process.
- Reports are generated independently so scan results can be reviewed before taking action.
The goal is to make large-scale photo cleanup safer by separating **analysis, review, and cleanup** rather than combining them into a single automated operation.
## Current Status
Photo Forensics is currently in active development.
The core scanning and review workflow is functional, including:
- Photo library inventory
- Exact duplicate detection
- Near-duplicate detection
- Perceptual hashing
- Duplicate grouping
- Storage/reclaimable-space analysis
- JSON and CSV reporting
- GUI-based review
- Image and containing-folder navigation
The project is currently being refined for reliability, usability, and maintainability.
## Planned Improvements
Planned improvements include:
- Improved duplicate review and filtering
- Additional image similarity analysis
- Improved scan performance for very large libraries
- Better progress reporting and cancellation handling
- Expanded metadata analysis
- More robust error handling and logging
- Automated test coverage
- Improved packaging and installation workflow
- Additional documentation and usage examples
## Technology
- **Python 3.13**
- **Tkinter** — desktop GUI
- **Pillow** — image processing
- **ImageHash** — perceptual image hashing
- **SQLite** — local inventory and analysis data
- **CSV / JSON** — report generation
## Installation
Clone the repository and create a Python virtual environment:
py -3.13 -m venv .venv
.venv\\Scripts\\python.exe -m pip install -r requirements.txt
## Launch
Start the desktop application:
.venv\\Scripts\\python.exe -m photo\_forensics.gui
## Usage
Launch the GUI and select the photo library you want to analyze.
Photo Forensics will inventory the library, identify exact and near-duplicate images, and present the results for review.
Scan results are stored separately from the original photo library.
## Project Status
🚧 **Active development**
This project is currently being developed and tested on Windows with Python 3.13.