iPhotron

Product Introduction

1. Definition: iPhotron is a folder-native photo management application for Windows, built using PySide6/Qt6 and OpenGL. It functions as a non-destructive photo organizer and media viewer, directly leveraging the user's existing folder structure without requiring import.
2. Core Value Proposition: iPhotron delivers a macOS Photos-like experience on Windows by enabling folder-based album management, preserving original files, and offering advanced features like HEIC/MOV Live Photo pairing, GPS map visualization, and GPU-accelerated browsing/editing.

Main Features

1. Folder-Native Album Management:
   • How it works: Treats every folder as a distinct album. Uses lightweight .iphoto.album.json manifest files stored within each folder to record user decisions like cover photo selection, featured assets, and custom sort order. Avoids proprietary databases or file relocation.
   • Technology: JSON Schema validation (album.schema.json), filesystem watchers for real-time updates, hierarchical tree model in GUI.
2. SQLite-Powered Global Index:
   • How it works: Creates and maintains a global_index.db SQLite database at the library root. Performs incremental scanning using idempotent upsert operations. Indexes critical metadata (parent_album_path, timestamp, media_type, is_favorite, GPS coordinates) for lightning-fast queries across massive libraries.
   • Technology: SQLite with multi-column indexes, custom migration/recovery logic (cache/migrations/), file-level locking (cache/lock.py).
3. Live Photo Support:
   • How it works: Automatically pairs HEIC/JPG still images with corresponding MOV video files to recreate the Apple Live Photo experience. Uses Apple's embedded ContentIdentifier metadata for exact matching, falling back to time proximity. Displays a "LIVE" badge; clicking plays the video inline.
   • Technology: ExifTool for metadata extraction (utils/exiftool.py), pairing algorithms (core/pairing.py), FFmpeg for video playback (utils/ffmpeg.py), GUI integration with badge and player controls.
4. Interactive Map View:
   • How it works: Visualizes photo locations using embedded GPS metadata. Clusters nearby photos dynamically on an interactive map. Caches map tiles locally (maps/tile_manager.py) and parses vector data (maps/tile_parser.py).
   • Technology: Custom OpenGL-based map renderer (maps/map_widget/map_gl_widget.py, maps/map_widget/map_renderer.py), reverse-geocoding, MapLibre style parsing (maps/style_resolver.py).
5. Non-Destructive Editing Suite:
   • How it works: Stores all edits (Light/Color/B&W adjustments, Crop/Perspective transforms) in .ipo sidecar files (XMP-based), leaving originals untouched. Features master sliders resolving to fine controls (core/light_resolver.py, color_resolver.py, bw_resolver.py). Includes perspective correction, straightening, and flip tools.
   • Technology: OpenGL 3.3 real-time preview (gui/ui/widgets/gl_image_viewer/gl_renderer.py), geometric calculations for perspective and crop validation (gui/ui/widgets/gl_image_viewer/perspective_math.py), vectorized image processing filters (core/filters/).
6. GPU-Accelerated Browsing & Rendering:
   • How it works: Utilizes OpenGL for smooth, high-performance display of thumbnails and full-resolution images, especially critical during editing with real-time adjustments and perspective transforms.
   • Technology: PySide6 QOpenGLWidget, custom shaders for color grading and perspective transformation, lazy-loaded textures.

Problems Solved

1. Pain Point: Lack of a sophisticated, native-feeling photo manager for Windows comparable to macOS Photos. Users resort to basic file explorers, destructive editors, or cumbersome cloud-based solutions.
2. Pain Point: Destructive editing workflows in many tools that alter original image files, risking data loss and hindering experimentation.
3. Pain Point: Poor handling of Apple Live Photos (HEIC/MOV pairs) on Windows, where the motion component is often lost or separated.
4. Target Audience: Windows-based photographers, hobbyists, and professionals; Users migrating from macOS seeking a similar Photos experience; Individuals with large, folder-organized photo libraries; Enthusiasts valuing GPS location data in their photos.
5. Use Cases: Organizing decades of family photos stored in nested folders; Managing professional photo shoots while preserving RAW originals; Viewing and sharing Live Photos captured on iPhone within a Windows environment; Geotagging trips and exploring photos spatially; Performing quick, reversible edits without altering source files.

Unique Advantages

1. Differentiation: Unlike Adobe Lightroom (requires import, subscription) or native Windows Photos (limited organization/editing), iPhotron is folder-native, non-destructive, free/open-source (MIT License), and specifically emulates macOS Photos' UI/UX on Windows. Contrasts with cloud-centric managers (Google Photos) by keeping data local.
2. Key Innovation: The hybrid metadata architecture combining lightweight, human-readable JSON manifests per album with a high-performance global SQLite index. This enables rich album management without locking assets into a proprietary database while maintaining speed. The GPU-accelerated non-destructive editing pipeline with complex master slider resolvers and geometric validation is also a significant technical achievement.

Frequently Asked Questions (FAQ)

1. Does iPhotron move or copy my original photo files? No, iPhotron is completely non-destructive and folder-native. It reads your photos directly from their existing locations on disk. Edits are stored in separate .ipo sidecar files, and album organization is managed via .iphoto.album.json files within your folders.
2. How well does iPhotron handle Live Photos from my iPhone? iPhotron has robust Live Photo support for Windows. It automatically pairs HEIC/JPG stills with their corresponding MOV files using Apple's ContentIdentifier metadata or timestamp proximity. Clicking the "LIVE" badge plays the video inline seamlessly.
3. Can I use iPhotron on Linux or macOS? While primarily designed for Windows, the core backend is Python-based and potentially cross-platform. The current GUI is built with PySide6/Qt6, which can run on Linux/macOS, but the application is optimized and tested for Windows. Official support is for Windows only.
4. What happens to my photo metadata (EXIF, GPS)? iPhotron reads and utilizes existing metadata extensively. EXIF, GPS, and QuickTime data are extracted using ExifTool and stored in the global SQLite index for fast searching, sorting, and display (e.g., in the Info Panel and Map View). It does not strip or alter original metadata.
5. What are the system requirements for running iPhotron smoothly? iPhotron requires Windows 10/11, a GPU supporting OpenGL 3.3 or higher for optimal performance (especially editing and map view), Python 3.9+, and external tools (ExifTool, FFmpeg/FFprobe) in the system PATH. Sufficient RAM and SSD storage are recommended for large libraries.