Aegis Photo Voyager Documentation

Aegis Photo Voyager is a premium, local-first photo management application. It is designed to handle massive image collections with a focus on privacy, speed, and intelligence.

Key Philosophy

• Privacy First: Your photos never leave your computer. All AI analysis is performed locally.
• Speed: High-performance database indexing and lazy-loaded galleries.
• Intelligence: Semantic enrichment using local Large Language Models (LLMs).

Main Features

New Here?

If this is your first launch, start with the guided walkthrough rather than this reference.

Getting Started Guide 4-Step Setup Tutorial What's New

Discovery & Processing

Before you can browse your photos, Aegis Photo Voyager needs to "discover" them and build its internal index.

The Processing Pipeline

1. Discovery: The app scans your chosen folders, extracts EXIF metadata (Date Taken, Camera, GPS), records file sizes, and adds entries to the database.
2. Processing: Proxies (thumbnails) are generated so you can scroll smoothly. Perceptual hashes are computed to detect duplicates.
3. AI Analysis: The local LLM (Ollama) examines each photo to generate tags, categories, and natural language summaries.
4. Semantic Preparation: Local CLIP and sentence-embedding models compute the 512-dimension vectors that power similarity and natural-language search.
5. Face Recognition: Faces are detected across the library and clustered into person profiles.

Whenever you add new photos or folders, the app can automatically start a Full Auto Sequence (Discovery → Processing → AI → Semantic Prep → Similarity → Faces) to ensure your library stays up to date. Every stage runs in a background worker, so the interface stays responsive while indexing continues.

Where Your Data Lives

The catalog is a SQLite database in Write-Ahead Logging mode stored under your application data directory (~/.AegisPhotoVoyager/ on Linux and macOS). Your original photo files are never moved or modified by indexing — the database only references them.

Configuration & Options

Customize Aegis Photo Voyager to suit your specific workflow needs across dedicated configuration tabs.

Folders & Library

Define the directories that make up your library and the Master Directory that imported photos are copied into. You can also set page sizes for the grid and the hover preview delay.

AI Engine Settings

Configure your Ollama Base URL and select your active Vision Model. You can also control the Image Size sent for analysis to balance speed (256px) and accuracy (2048px). Metadata generation and quality assessment are configured independently, so you can use a different model for each.

Custom Prompting

The Prompt Editor allows advanced users to modify the exact JSON instructions sent to the AI, enabling custom metadata architectures tailor-made for specific library types.

Appearance & Behavior

Switch between light and dark themes, re-enable dialogs you dismissed with "don't ask again", and control whether the version welcome dialog appears at startup.

Read Detailed Configuration Tutorial

System Dependencies & AI Engines

Aegis Photo Voyager runs its vision models through a local inference engine. Four are supported, and the built-in LLM Setup Wizard checks your CPU, RAM and GPU before recommending one:

• llama-cpp-python — an in-process CPU engine that loads GGUF models directly, with no server to run. The wizard defaults to this when no discrete GPU is detected.
• Ollama — the most common choice on machines with a GPU.
• LM Studio and vLLM — for users who already run one of these locally.

Setting Up Ollama

If you choose Ollama, install it and pull the default vision model:

# 1. Install Ollama from ollama.com
# 2. Pull the default vision model:
ollama pull granite3.2-vision:2b

Voyager expects the Ollama API to be reachable at http://localhost:11434 by default. Request timeouts scale automatically to your hardware, so slower CPU-only machines are given more time instead of failing.

CLIP vision and text embedding models run through a bundled ONNX runtime and are downloaded by the Manage Vision Models tool. Face recognition uses dlib, which ships with the installers for all supported platforms.

Detailed Ollama Setup Guide

Importing Your Photos

The Import feature allows you to bring photos into Aegis Photo Voyager from various sources. All imported photos are organized automatically by date and checked for duplicates.

Import Sources

• External Drive or Folder: Import from SD cards, USB drives, or any local directory.
• Google Takeout & Apple iCloud: Point the importer at the ZIP archives these services produce; nested archives are unpacked and matched to their metadata.
• iPhone & iPad: Direct USB import. On Linux the app auto-pairs and mounts the device using libimobiledevice and ifuse.
• Android: USB import from the device's DCIM folders.

Choosing a Starting Point

• All Photos: Scans the entire source; duplicates are still skipped.
• Since Last Import: Matches the device signature and imports only photos taken after your last successful run from that device.
• Since a Custom Date: Import everything newer than a date and time you pick.

Import Preview

Before any files are copied, the preview screen reports the total item count, combined transfer size, the date range covered, an estimated duration, and free space on the target drive, alongside thumbnails of the first items found.

Target Structure

All imported photos are organized into a clean, date-based hierarchy:

Master Directory/
  └── YYYY/
      └── YYYY_MM_DD/
          ├── IMG_0001.JPG
          └── VID_0001.MOV

Contributors

Each import can be attributed to a contributor — a person or device that supplied the photos. The contributor is stored with every imported file so you can later filter the library by who provided the material.

Duplicate Management

Voyager uses Perceptual Hashing (pHash) for photos and partial checksum hashing for videos to prevent redundant files, even if they have different filenames.

Read Detailed Importing Workflow Tutorial

Curation Staging Queue

When you enable Stage in Curation Queue before import, incoming files are held in a staging area instead of being added straight to your library. This gives you a chance to vet a phone dump or an inherited hard drive before it becomes part of your permanent collection.

Reviewing Staged Photos

• Visual Deduplicate: Groups near-identical frames using perceptual hashing so you can keep the best shot from a burst.
• Auto Quality Sorter: Estimates sharpness so soft or out-of-focus frames surface first.
• Approve or Reject: Approving commits a photo to the library. Rejecting removes the staged entry and deletes the staged copy from disk.

Virtual Collections

Collections allow you to group photos together regardless of where they are stored. They are "virtual" groups, meaning a photo can belong to many collections without being duplicated on your disk.

Active Collection Workflow

Set a collection as Active in the sidebar, then use the Purple Plus icon on any thumbnail to instantly add/remove it from that set. This is ideal for quickly curating "Best of" albums or project-specific assets.

Collection Insights

The Collection Details dialog summarizes a collection with a date distribution histogram, GPS distance covered, and a chip-based breakdown of the AI tags, moods and places that appear most often in it.

Read Detailed Collections & Curation Tutorial

Trip Builder

Trips group photos into logical travel journeys. A trip has a name, a start and end date, a description and a cover photo, and it collects everything you shot during that window.

• Build a trip from a date range, a filter result, or an explicit selection.
• Review date distribution and the distance covered between geotagged photos.
• Open a trip in its own timeline to relive the journey in order.

Setting Photo Locations

Add missing geographic information to your photos to enable mapping and spatial search.

• Manual Selection: Draw a "rubberband" box over photos in the grid and use the Location tool to batch-select a pinpoint on the map.
• Analyze Clusters: An intelligent tool that finds "sessions" (photos taken together in time) and suggests locations based on other nearby geotagged photos.
• GPS Wizard: Finds photos with no coordinates and helps you search for a place, assign it, or correct coordinates that were recorded incorrectly.

Browser & Smart Filtering

The main library view is where you spend most of your time exploring your collection. It is designed for professional performance with libraries exceeding 100,000 items.

The Timeline Rail

The vertical bar on the right is the Timeline Rail. It shows a distribution of your photos over time. Click any month or year to jump instantly to that point in history.

AI-Driven Sidebar

Use the left sidebar to filter by Category, Mood, Quality, or specific Objects/Actions detected by the local AI engine.

Physical & Chronological Filters

Filter by capture date range (with hour and minute precision), star rating, camera body, file format, file size, and whether a photo has GPS coordinates. Every active filter appears as a badge above the grid and can be cleared individually.

Combining Filters

Filters intersect: selecting a camera, a mood and a year narrows to photos matching all three in a single indexed query. Filters also apply on top of search results, so you can restrict a concept search to starred photos from one particular year.

Selection & Batch Actions

Check individual photos or rubberband-select a range, then apply ratings, collection membership, locations, exports or removal to the whole selection at once. The selection toolbar also offers Find Similar, which searches the library for photos that resemble the first item you selected.

Keyword & Semantic Search

Two search modes share the same search box.

• Keyword Search matches filenames, camera models, place names and AI-generated tags and summaries. It is exact, fast, and best when you know what you are looking for.
• Semantic Search converts your sentence into a vector and ranks photos by conceptual similarity. Queries such as "a sunny afternoon on the grass with my dog" find matching photos even when none of those words appear in the metadata.

Semantic search requires the semantic preparation step to have run over your library. Results keep their similarity ranking when you layer filters on top of them.

Detail Panel & Inspector

The side detail panel opens beside the grid and shows everything the app knows about the selected photo without leaving the gallery.

• File information, capture details and the full EXIF breakdown — aperture, focal length, ISO and camera body.
• AI summary, tags, mood, detected objects, places and actions, with the option to regenerate metadata for that single photo.
• Star rating via an explicit 0–5 dropdown, collection membership and the faces detected in the photo.
• Zoom and pan controls, map centering on the photo's coordinates, spoken narration of the AI description, and launching the file in an external editor such as Aegis Photo Atelier.

Widen the panel past 500px and it switches to a two-column layout. Removing a photo advances the panel to the next one automatically, which makes it a practical culling tool.

Clicking a thumbnail instead opens the full-screen Detail View, which adds a slideshow mode with transitions, subtitles read from the AI narration, and configurable sort order.

Map Explorer

The Map View provides a geographic way to explore your photo library using high-performance Leaflet clusters on OpenStreetMap basemaps.

Geographic Clusters

Photos taken in similar locations are grouped into Clusters. Click a cluster to zoom in and see individual markers.

Rotating Hover Previews

Hovering over a cluster will automatically rotate through high-resolution previews of all photos in that area, giving you an instant summary of that location.

Map to Detail Panel

Selecting a cluster or a group thumbnail loads that photo into the side detail panel, so you can inspect metadata, rate and tag photos without leaving the map.

People & Face Recognition

Face recognition runs entirely on your own machine. The face worker detects faces across multiple CPU cores, extracts a 128-dimension encoding for each one, and groups them into person profiles using DBSCAN clustering.

The People View

• Rename auto-detected profiles (for example "Person 4" to "Anna") and choose a cover portrait.
• Sort profiles by photo count, by name, or by similarity so look-alike clusters sit next to each other.
• Merge two profiles by dragging one onto the other; a confirmation step protects against accidents and can be suppressed once you trust it.
• Hide profiles you do not want to see — passers-by in the background, for example.

Suggested Matches

Inside a person's detail dialog, a recommendations sidebar lists the most similar unnamed profiles by vector distance, with one-click merging. This is the fastest way to consolidate a face that was clustered into several groups across different decades or hairstyles.

Family Tree

Once people are named, you can connect them into a generational family tree. The layout uses a Sugiyama-style algorithm that aligns generations, keeps couples together, and minimizes crossing lines.

• Pan, zoom and fit controls directly on the canvas, with edge drag-scrolling when you pull a portrait toward the border.
• People who are not yet connected to anyone are arranged in a tidy grid beside the tree so they are easy to pick up and place.
• Selecting a person opens their photos, which makes the tree a navigation surface rather than a static chart.

Analytics & Word Cloud

The Word Cloud provides a visual summary of your library using AI-extracted tags.

• Frequency Visualization: Larger words indicate higher frequency in your current view.
• Interactive Filtering: Click any word in the cloud to immediately filter your library by that specific tag.
• Dynamic Scoping: The cloud updates in real-time as you apply other filters (e.g., year or location).

Library Dashboard

The analytics view adds date distribution histograms, a breakdown of the camera bodies in your library, mood and category matrices, and the distribution of technical quality tiers. It is a practical way to spot gaps — years with no photos, or a camera whose files never got EXIF dates.

3D Point Cloud & Photo Walker

3D Embedding Cloud

Your photos' 512-dimension CLIP embeddings are reduced with PCA and plotted as an interactive point cloud. Visually similar photos sit close together, so rotating through the cloud reveals themes you never tagged. Hovering a point previews the photo; selecting one shows its neighbours.

Timeline Tunnel

A 3D chronological view that flies through your library in time order — a more immersive alternative to the grid for browsing a long stretch of history.

Photo Walker

Navigates your library as a network graph. Photos are nodes connected by visual similarity and shared metadata, and you can constrain the connections by camera, GPS proximity or date range.

Duplicates & Bursts

Perceptual hashes computed during processing let the app recognize photos that look the same even when the files differ. The duplicates tool groups near-identical images and burst sequences so you can keep one frame and discard the rest, and reports duplicate files found in more than one directory.

Technical Quality Analysis

The quality analyzer scores each photo on measurable technical attributes rather than taste: sharpness, focus accuracy, noise and grain, contrast and white balance, and composition. Each assessment stores a short reasoning note alongside the score.

Scores become a filter dimension, so you can isolate your strongest photos for an export, or sweep up the soft ones for deletion. The Photo Quality Sorter presents the results as a ranked, reviewable list with star synchronization and soft delete.

Library Manager

The Library Manager (Tools → Photo Tools, or the "Library Mgr" sidebar shortcut) is a bulk cleanup tool for the clutter that accumulates in large libraries — web thumbnails, screen grabs, blurry frames and long-obsolete captures.

Finding Candidates

• Minimum dimensions: longest edge, width and height, or total megapixels.
• Minimum file size.
• AI quality score, with an option to include photos that have not been assessed yet.
• Capture date range.

Criteria combine with either match any (OR) or match all (AND) logic.

Review Before You Remove

A live summary updates as you adjust the criteria, showing how many photos are affected, the earliest and latest capture dates in the set, and the estimated disk space involved. A paginated thumbnail table lets you uncheck anything you want to keep before committing.

Removal soft-deletes the selected photos from the library database. The files on your disk are left untouched.

Exporting

The export tool copies photos out of your library to another drive or folder.

• Scope: the checked selection, everything matching the current filters, or the whole library.
• Structure: a dated hierarchy (YEAR/YEAR_MM_DD/) or a flat folder. Filename collisions in flat exports are resolved with numeric suffixes so nothing is overwritten.
• Incremental mode: the app writes a signature into the destination and records what it sent, so a repeat export copies only what is new and tells you the date and size of the previous run.

Static Website Builder

The website builder compiles a selection or collection into a self-contained static site you can host anywhere — no server code and no database.

• Themes: Standard, Lighthouse, Midnight, Portfolio, Journal, Horizon and Polaroid.
• Image handling: JPEG quality slider, maximum dimension limits from 800px to original, and optional text watermarks in any corner.
• AI captions: captions and a one-paragraph story introduction generated by your local model, guided by a purpose you choose such as travelogue, wedding or portfolio.
• Password protection: an optional client-side login screen so a shared gallery is not openly browsable.
• Project profiles: titles, themes, captions and settings are saved so you can reopen a site later, add photos and recompile.

Collage Maker

Found under Tools → Export, the collage maker compiles up to 100 photos from a collection into a single high-resolution PNG. Choose landscape or portrait, a Clean Grid or Scattered Polaroid layout, a canvas resolution, and a background treatment.

Encrypted Cloud Backup

Cloud backup is optional and off by default. When you enable it, Aegis Photo Voyager encrypts your catalog and metadata locally with AES-256, using a key derived from your password with PBKDF2, before anything is transferred to your own Google Drive account.

• Authentication uses OAuth2 against the official Google Drive API; no credentials are stored in plain text.
• Backups are incremental — only new or changed items are uploaded on later runs.
• You can limit a backup to specific collections or filter results.
• Restore rebuilds the encrypted catalog and metadata on a new machine.

Because the encryption key is derived from your password and never leaves your machine, the backup is unreadable without it — including by the storage provider.

Application Tools

The Tools panel groups the specialized utilities by purpose:

• Setup: LLM Setup Wizard, Manage Vision Models.
• Import: Smart Photo Importer, Curation Staging Queue, iPhone auto-photos cleaner.
• AI Processing: Generate AI Metadata, Semantic Search Prep, Visual Similarity Map, Scan & Cluster Faces, Technical Quality Analysis.
• Photo Tools: Session Finder (groups photos taken within minutes of each other), GPS Wizard, Photo Quality Sorter, Library Manager, duplicate detection.
• Export & Sharing: Custom Exporter, Static Website Builder, Collage Maker, Cloud Backup and Restore.
• Diagnostics: Database Health Check, which finds photos missing thumbnails, embeddings, descriptions or face scans and offers to fix them in a batch.

Tools operate on what you are looking at: the current selection if you have one, otherwise the current filter result. They all run in the background, so you can keep browsing.

Logs & Troubleshooting

Every background worker writes its own log file under ~/.AegisPhotoVoyager/logs/. These are the first place to look when something does not behave as expected.

• launcher.log — startup, crashes and worker exceptions.
• gui.log — interface and view rendering.
• discoverer.log, processor.log — scanning and thumbnailing.
• ollama.log — local LLM requests, timeouts and response parsing.
• face_worker.log — face detection and clustering.
• import.log, export.log, cloud_backup.log — media movement.

Common Checks

• The app will not start: check launcher.log, and faulthandler.log for low-level faults.
• AI metadata never appears: confirm Ollama is running and reachable at the URL set in configuration, and that a vision model has been pulled.
• Semantic search returns nothing: run Semantic Search Prep so embeddings exist.
• Photos show as missing: the source drive is offline; the app keeps the thumbnail and flags the file rather than deleting the record.