KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #claude-code #mcp #rust #deepseek-harness #ai-agent #cli

iPhotron-LocalPhotoAlbumManager

★ 207 Open GitHub ↗

A macOS Photos–style photo manager for Windows — folder-native, non-destructive, with HEIC/MOV Live Photo, map view, and GPU-accelerated browsing.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 📸 iPhotron
> A macOS *Photos*-inspired, folder-native photo manager for Windows, macOS, and Linux with Live Photo, maps, and smart albums.

![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
![Language](https://img.shields.io/badge/language-Python%203.12%2B-blue)
![Framework](https://img.shields.io/badge/framework-PySide6%20(Qt6)-orange)
![License](https://img.shields.io/badge/license-MIT-green)
[![GitHub Repo](https://img.shields.io/badge/github-iPhotron-181717?logo=github)](https://github.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager)

**Languages / 语言 / Sprachen:**  
[![English](https://img.shields.io/badge/English-Click-blue?style=flat)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/README.md) | [![中文简体](https://img.shields.io/badge/中文简体-点击-red?style=flat)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/readme/README_zh-CN.md) | [![Deutsch](https://img.shields.io/badge/Deutsch-Klick-yellow?style=flat)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/readme/README_de.md)

---

## ☕ Support

[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20Development-yellow?style=for-the-badge&logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/oliverzhao)
[![PayPal](https://img.shields.io/badge/PayPal-Donate-blue?style=for-the-badge&logo=paypal&logoColor=white)](https://www.paypal.com/donate/?hosted_button_id=AJKMJMQA8YHPN)

## 📥 Download & Install

[![Download for Windows](https://img.shields.io/badge/⬇️%20Download-Windows%20(.exe)-blue?style=for-the-badge&logo=windows)](https://github.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/releases/download/v6.6.8/v6.68-x86-setup.exe)
[![Download for Linux (.deb)](https://img.shields.io/badge/⬇️%20Download-Linux%20(.deb)-orange?style=for-the-badge&logo=linux&logoColor=white)](https://github.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/releases/download/v6.6.8/iphotron_6.6.8_amd64.deb)
[![Download for Linux (.AppImage)](https://img.shields.io/badge/⬇️%20Download-Linux%20(.AppImage)-brightgreen?style=for-the-badge&logo=linux&logoColor=white)](https://github.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/releases/download/v6.6.8/iPhotron-6.6.8-x86_64.AppImage)
[![Download for Linux (.flatpak)](https://img.shields.io/badge/⬇️%20Download-Linux%20(.flatpak)-purple?style=for-the-badge&logo=flatpak&logoColor=white)](https://github.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/releases/download/v6.6.8/com.github.OliverZhaohaibin.iPhotron-6.6.8-x86_64.flatpak)

**💡 Quick Install:** Click the buttons above to download the latest installer directly.

- **Windows:** Run the `.exe` installer directly.
- **Linux (.deb):** Install with the following command:

```bash
sudo apt install ./iphotron_6.6.8_amd64.deb
```

- **Linux (.AppImage):** Make the file executable and run it:

```bash
chmod +x iPhotron-6.6.8-x86_64.AppImage
./iPhotron-6.6.8-x86_64.AppImage
```

- **Linux (.flatpak):** Install the bundle with Flatpak:

```bash
flatpak install --user ./com.github.OliverZhaohaibin.iPhotron-6.6.8-x86_64.flatpak
```

**For developers** — install from source:

```bash
pip install -e .
```

---

## 🚀 Quick Start

```bash
iphoto-gui
```

Or open a specific album directly:

```bash
iphoto-gui /photos/LondonTrip
```

---

## 🌟 Star History

## 🚀 Product Hunt

 <a href="https://www.producthunt.com/products/iphotron/launches/iphotron?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-iphotron" target="_blank" rel="noopener noreferrer">
 <img alt="iPhotron - A macOS Photos–style photo manager for Windows | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1067965&amp;theme=light&amp;t=1772225909629">
 </a>


 Please Upvote •
 Follow •
 Discuss on the Forum

---

## 🌟 Overview

**iPhotron** is a **folder-native photo manager** inspired by macOS *Photos*.  
It keeps your folders as the album structure, combines folder-local manifests
with a library-scoped `.iPhoto/global_index.db`, and separates rebuildable cache
facts from durable user choices while keeping destructive edits out of your
original media files.

Key highlights:
- 🗂 Folder-native design — every folder *is* an album, no import needed.
- ⚙️ Folder-local manifests record album metadata such as cover, featured items, and order.
- ⚡ **SQLite-powered global database** for lightning-fast session-backed queries on massive libraries.
- 🖼 Demand-driven Gallery scrolling with sparse asynchronous windows,
  micro-thumbnail fallback, and memory-aware full-thumbnail prefetching.
- 🧠 Smart incremental scanning with persistent SQLite index.
- 🎥 Full **Live Photo** pairing and playback support.
- 🗺 Optional map view that visualizes GPS metadata across all photos & videos and falls back gracefully when the maps extension is unavailable.
- 👥 Optional People scanning with face clusters, names, covers, hidden people,
  and multi-person groups.
![Main interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/mainview.png)
![Preview interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/preview.png)
---

## 🗺 Maps Extension

iPhotron's offline OBF map runtime ships as a self-contained **maps extension**
rooted at `src/maps/tiles/extension/`. That directory is the contract consumed
by local development, packaged builds, and platform-specific installers.
The app remains usable without this extension; map-specific views and panels use
the runtime availability surface to show graceful fallback behavior.

The extension currently contains:
- `World_basemap_2.obf` offline map data
- OsmAnd resources under `misc/`, `poi/`, `rendering_styles/`, `routing/`,
  and related runtime resource directories
- offline search data under `search/geonames.sqlite3`
- platform-specific native binaries under `bin/`
  - Windows: `osmand_render_helper.exe`, `osmand_native_widget.dll`,
    `OsmAndCore_shared.dll`, `OsmAndCoreTools_shared.dll`, and the required Qt DLLs
  - Linux: `osmand_render_helper`, `osmand_native_widget.so`,
    `libOsmAndCore_shared.so`, and `libOsmAndCoreTools_shared.so`
  - macOS: `osmand_render_helper`, `osmand_native_widget.dylib`, and copied
    non-system Mach-O dependencies

Platform maps notes:
- iPhotron can use both the helper-backed OBF renderer and the native OsmAnd widget when the platform runtime is available.
- If a sibling `PySide6-OsmAnd-SDK/` checkout exists, Linux and macOS development can prefer its `tools/osmand_render_helper_native/dist-*` widget builds.
- The native Linux widget currently expects Qt's XCB desktop OpenGL path. When that backend is selected, iPhotron auto-sets `QT_QPA_PLATFORM=xcb`, `QT_OPENGL=desktop`, and `QT_XCB_GL_INTEGRATION=xcb_glx`.
- On macOS, the legacy OpenGL map uses `QOpenGLWindow + createWindowContainer()` to avoid transparent-window `QOpenGLWidget` composition issues; media previews default to the Metal-capable QRhi path unless `IPHOTO_RHI_BACKEND=opengl` is set.

| Without maps extension | With maps extension |
| --- | --- |
| ![Without maps extension](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/without_extension.png) | ![With maps extension](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/maps_extension.png) |

The extension is built upstream from the standalone
[PySide6-OsmAnd-SDK](https://github.com/OliverZhaohaibin/PySide6-OsmAnd-SDK)
sub-project. That repository carries the vendored OsmAnd sources, build scripts
for Windows, Linux, and macOS, the native Qt widget bridge, and the preview app
used to produce the runtime consumed here.

See [Development](docs/development.md) for the full "build the maps extension
from the side project" workflow, and
[Executable Build](docs/misc/BUILD_EXE.md) for how the extension is synchronized
into Nuitka and platform-specific release builds.

## ✨ Features

### 🗺 Location View
Displays your photo footprints on an interactive map, clustering nearby photos by GPS metadata.
![Location interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/map1.png)
![Location interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/map2.png)
### 🎞 Live Photo Support
Seamlessly pairs HEIC/JPG and MOV files using Apple's `ContentIdentifier`.  
A "LIVE" badge appears on still photos — click to play the motion video inline.
![Live interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/live.png)
### 🧩 Smart Albums
The sidebar provides an auto-generated **Basic Library**, grouping photos into:
`All Photos`, `Videos`, `Live Photos`, `Favorites`, and `Recently Deleted`.

### 👥 People, Face Clusters & Groups
The optional People pipeline detects faces, builds face clusters, and presents
them as People cards. You can name people, merge duplicate clusters, hide or
show hidden people, and keep chosen covers persistent across rescans.

Drag people into groups to collect shared photos for multiple people. Group
cards can use a selected cover, be reordered, and be disbanded when they are not
pinned. Face scanning uses the optional `ai-demo` dependencies; the core photo
manager remains usable without installing the AI runtime, and People state is
kept behind the library session so names, covers, hidden flags, groups, and
manual faces survive rescans.
![People and groups interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/People%20%26%20Group.png)

### ⚡ Large-Library Gallery
Gallery browsing uses sparse asynchronous SQL windows instead of materializing
an entire collection. Scroll intent drives separate visible, nearby guard, and
speculative thumbnail lanes; fast bursts keep input responsive and use warmed
micro thumbnails while full thumbnails are decoded away from the GUI thread.
Memory and worker budgets adapt to the host platform and physical RAM, with
generation-aware cancellation preventing old viewport work from repainting the
current view.

### 🖼 Immersive Detail View
An elegant viewer with a filmstrip navigator, floating playback bar for videos,
and a platform-selected GPU path: QRhi/Metal on macOS, OpenGL-backed QRhi on
Windows and Linux.

### 🎨 Non-Destructive Photo Editing
A comprehensive editing suite with **Adjust** and **Crop** modes:

#### Adjust Mode
- **Light Adjustments:** Brilliance, Exposure, Highlights, Shadows, Brightness, Contrast, Black Point
- **Color Adjustments:** Saturation, Vibrance, Cast (white balance correction)
- **Black & White:** Intensity, Neutrals, Tone, Grain with artistic film presets
- **Color Curves:** RGB and per-channel (R/G/B) curve editor with draggable control points for precise tonal adjustments
- **Selective Color:** Target six hue ranges (Red/Yellow/Green/Cyan/Blue/Magenta) with independent Hue/Saturation/Luminance controls
- **Levels:** 5-handle input-output tone mapping with histogram backdrop and per-channel control
- **Master Sliders:** Each section features an intelligent master slider that distributes values across multiple fine-tuning controls
- **Live Thumbnails:** Real-time preview strips showing the effect range for each adjustment
![edit interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/editview.png)
![edit interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/professionaltools.png)
#### Crop Mode
- **Perspective Correction:** Vertical and horizontal keystoning adjustments
- **Straighten Tool:** ±45° rotation with sub-degree precision
- **Flip (Horizontal):** Horizontal flip support
- **Interactive Crop Box:** Drag handles, edge snapping, and aspect ratio constraints
- **Black Border Prevention:** Automatic validation ensures no black edges appear after perspective transforms
  
![crop interface](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/cropview.png)
All edits are stored in `.ipo` sidecar files through the edit session surface,
preserving original photos untouched.

### ℹ️ Floating Info Panel
Toggle a floating metadata panel with EXIF, camera/lens details, exposure,
aperture, focal length, dimensions, file size, and capture time. For assets
with People data, the panel shows detected face avatars and lets you remove a
face, move it to another person, or create a new person annotation.

Location tools are built in as well: geotagged assets can show an inline map,
and assets without a location can use the "Assign a Location" search flow to
pick and confirm a place. The assignment is always saved in the local library
database; if ExifTool is available, iPhotron also best-effort writes GPS
metadata back to the original file and warns when that write-back fails. If the
maps extension is missing, the panel offers the download path instead of failing
silently.

| Info panel with map | Floating info panel in detail view |
| --- | --- |
| ![Info panel with map](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/info.png) | ![Floating info panel in detail view](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/picture/info2.png) |

### 💬 Rich Interactions
- Drag & drop files from Explorer/Finder directly into albums.
- Multi-selection & context menus for Copy, Show in Folder, Move, Delete, Restore.
- Smooth thumbnail transitions and macOS-like album navigation.

---

## 📚 Documentation

For deeper technical details, see the following docs:

[![Architecture](https://img.shields.io/badge/📐_Architecture-blue?style=for-the-badge)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/architecture.md)
[![Development](https://img.shields.io/badge/🧰_Development-green?style=for-the-badge)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/development.md)
[![Executable Build](https://img.shields.io/badge/🧱_Executable_Build-purple?style=for-the-badge)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/misc/BUILD_EXE.md)
[![Security](https://img.shields.io/badge/🔒_Security-red?style=for-the-badge)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/security.md)
[![Changelog](https://img.shields.io/badge/📋_Changelog-orange?style=for-the-badge)](https://raw.githubusercontent.com/OliverZhaohaibin/iPhotron-LocalPhotoAlbumManager/main/docs/CHANGELOG.md)

| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | Current vNext library-scoped modular monolith architecture, module boundaries, legacy quarantine policy, data flow, and key design decisions |
| [Development](docs/development.md) | Dev environment, dependencies, debugging, and the side-project-based maps extension workflow for Windows, Linux, and macOS |
| [Executable Build](docs/misc/BUILD_EXE.md) | Nuitka packaging, AOT filters, QRhi shader assets, maps extension sync, and platform runtime notes |
| [Security](docs/security.md) | Permissions, encryption, data storage locations, threat model |
| [Changelog](docs/CHANGELOG.md) | All version release notes and changes |

---

## 🧩 External Tools

| Tool | Purpose |
|------|----------|
| **ExifTool** | Reads EXIF, GPS, QuickTime, and Live Photo metadata; writes GPS metadata for explicit Assign Location actions. |
| **FFmpeg / FFprobe** | Generates video thumbnails & parses video info. |
| **InsightFace / ONNXRuntime + `buffalo_s` models** | Optional People face scanning: face detection (`det_500m.onnx`) and face embeddings (`w600k_mbf.onnx`) from `src/extension/models/buffalo_s/`. |

> Ensure FFmpeg/FFprobe are available in your system `PATH`; install ExifTool if
> you want assigned GPS coordinates written back into original media files.
> The AI face runtime is optional; install it with `pip install -e ".[ai-demo]"`
> for source builds, and keep `extension/models` bundled for offline packaged builds.

Python dependencies (e.g., `Pillow`, `reverse-geocoder`) are auto-installed via `pyproject.toml`.

---

## 📄 License

> *iPhotron — A folder-native, human-readable, and fully rebuildable photo system.*  
> *No forced imports. No proprietary lock-in. Just your photos, organized elegantly.*

iPhotron-LocalPhotoAlbumManager

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README