Configuration & Settings Guide

✦ 1. Introduction

Aegis Photo Voyager is a highly configurable, privacy-first photo organizer. The Configure dialog (accessed via the Configure gear icon on the top toolbar) centralizes settings for directories, graphics, local AI backends, performance limits, and audio narration.

The settings are divided into ten tabs, arranged from left to right. When settings are changed, many apply immediately (such as themes and limits) while others configure parameters for background worker processes.

1 Tab 1: Sources

The Sources tab governs where Aegis Photo Voyager looks for your photos and where it moves newly imported media files.

Settings Breakdown

• Photos Master Directory (photos_master_directory):
  • Description: The central repository directory where all photos ingested via the Importer (e.g. from iPhones, USBs, or ZIP archives) are copied.
  • Folder Structure: Files copied here are organized in a YEAR/YEAR_MONTH_DAY/ directory tree.
• Library Folders (library_sources):
  • Description: A list of directories that Aegis actively watches and index-scans.
  • Actions: Use Add Folder to index external archives or staging folders without moving them, or Remove Selected to stop indexing a folder.

Impact on App Behavior

• Ingestion Destination: When importing photos, the master directory is the target folder. If your master directory drive runs out of space, imports will fail.
• Scan Scope: The File Discovery (discoverer) worker only scans the folders listed under "Library Folders". If a folder is removed from this list, its indexed photos remain in the database but are ignored during subsequent scans.
• Safe Ingestion Guard: If you close the settings dialog and have specified a Photos Master Directory but left the Library Folders list empty, Aegis will automatically append the Master Directory to the Library Folders list to guarantee your imported pictures show up in the gallery.

2 Tab 2: Appearance

The Appearance tab controls themes, font styling, hover cards, map rendering, and WebGL performance limits.

Settings Breakdown

Impact on App Behavior

• Visual Experience: Changing the Theme swaps the styling instantly between a curated dark mode (charcoal background with turquoise accents) and light mode (high-contrast grey/white). Changing the Font propagates immediately to all text boxes, sidebar labels, and tree menus.
• Hover Interaction: When Hover Preview is enabled, pausing your cursor over a thumbnail opens a popup showing a medium-sized image preview, camera details, tags, and AI description. The Popup Delay slider dictates how long the cursor must rest before the card appears (preventing unwanted visual clutter while scrolling).
• Database Filtering: Turning Show Hidden Photos on reveals photos that you have flagged as hidden. Leaving it off filters them completely out of the main grid, slideshows, and timeline views.
• Thumbnail Overlay: Show Quality Scores prints the AI-calculated sharpness and composition score directly on the bottom-right corner of the thumbnails, which is useful for sorting.
• Map Rendering overhead: Enabling Show Thumbnails on Map replaces default Leaflet marker pins with miniature image thumbnails.
  ⚠️

  Map Performance: If you filter by a large collection containing thousands of geotagged photos, enabling map thumbnails can cause significant rendering lag in the Map View sidebar as the browser loads and resizes hundreds of images simultaneously.

• Cluster Performance: Controls how many dots are rendered in the WebEngine-based 3D point cloud. Setting this to Unlimited on large libraries can cause WebGL to lag or freeze if your GPU lacks dedicated VRAM.

3 Tab 3: Integrations

The Integrations tab coordinates hooks into third-party tools, primarily the AegisPhotoWizard image editor.

Settings Breakdown

• AegisPhotoWizard Companion:
  • Installation Status: Scans local system directories and the system PATH to locate an installation of the desktop editor.
  • Executable Path: Displays where aegis_photo_wizard is located.
  • Re-scan: Forces a fresh verification scan if you installed the editor while Aegis Photo Voyager was open.

Impact on App Behavior

• Direct Editing: When AegisPhotoWizard is detected ("✅ FOUND"), right-clicking any photo in the Library Grid exposes a "Open in AegisPhotoWizard" action. This opens the image directly in the editing tool, allowing you to crop, apply color adjustments, or touch up details. When saving changes in the editor, Aegis detects the file modification and automatically updates the thumbnail.

4 Tab 4: AI Metadata

This tab configures the connection details, visual prompt, and processing constraints for generating descriptions, smart tags, category classifications, and mood tags.

Settings Breakdown

• Provider (llm_provider): Supports three local hosting APIs:
  1. Ollama: Recommended for standard local environments.
  2. LM Studio: Ideal for users running GGUF vision models via the local OpenAI-style API server.
  3. vLLM: Recommended for high-performance servers running multiple GPUs.
• Base URL: The network endpoint of your local API.
• Model Selection: The exact model string (e.g. llava:7b or granite3.2-vision:2b).
• Metadata Extraction Prompt (ollama_prompt): The system prompt instructing the vision model to return structured JSON.
• Max Image Size (ai_image_size): Controls the scale to which the image is resized before being sent to the model (defaults to Very Small: 256px to maximize processing speed).
• Context Window (ollama_num_ctx): The context length requested from the host (default 32000).

Impact on App Behavior

• Vision Model Diagnostics: Clicking Fetch Available Models queries the server URL (e.g. /api/tags for Ollama) and populates the list box with local models, avoiding manual typing mistakes.
• Performance Testing: The Test LLM Performance button opens a dialog that passes a sample image to the LLM and tracks how many seconds it takes to generate tags, reporting the generation rate (tokens/sec).
• AI Ingestion speed: Resizing to 256px speed-analyzes photos quickly. However, if your model struggles to recognize small objects, changing this to 512px or 1024px will improve accuracy at the expense of longer processing times.

5 Tab 5: AI Quality

Similar to Tab 4, the AI Quality tab connects to a vision LLM, but uses a separate prompt and configuration tailored for scoring technical image characteristics.

Settings Breakdown

• Quality Assessment Prompt (ai_quality_prompt): Instructs the vision LLM to evaluate the image's technical details (Sharpness, Composition, Focus, Contrast, Low Grain, White Balance) on a scale from 0 to 100.
• Max Image Size (ai_quality_image_size):
  💡

  High Resolution Requirement: While Tab 4 (Metadata) defaults to 256px to save time, Tab 5 (Quality) defaults to Large: 2048px. This is because a vision model cannot accurately evaluate micro-blur, focal errors, or noise/grain if the image has been heavily downsampled.

Impact on App Behavior

• Technical Quality Grading: The outputs generated under this configuration populate the database's ai_analysis table (sharpness, focus, composition columns) which is used by the Photo Quality Sorter and the Quality Sliders in the library sidebar.
• GPU Utilization: Because it transmits 2048px images, the AI Quality phase of the processing pipeline consumes significantly more VRAM and takes longer per image than the Metadata generation phase.

6 Tab 6: Similarity

The Similarity tab manages both natural language text search embeddings and visual similarity mapping (CLIP).

Settings Breakdown

Text Embedding Configuration

• Framework (text_embedding_provider): Connects to Ollama, LM Studio, or vLLM to generate text embeddings for search queries.
• Embedding Model Name (text_embedding_model): The model used to vectorize your search text (Ollama defaults to nomic-embed-text, LM Studio defaults to text-embedding-nomic-embed-text-v1.5, vLLM defaults to BAAI/bge-large-en-v1.5).

Visual Similarity Configuration (Image Embeddings)

• Framework (visual_embedding_provider): Defaults to Local (ONNX).
• Model Check: Verifies the presence of the 100MB model file: ~/.AegisPhotoVoyager/models/clip-vit-base-patch32-vision.onnx

Impact on App Behavior

• Semantic Search: When you search for "a dog running on the beach" in the library, Aegis uses the configured text embedding model to convert that phrase into a vector, which is matched against your photo database. If this model isn't running or configured correctly, natural language searches will return an error.
• 3D Point Cloud and Visual Similarity: The ONNX CLIP model generates visual embeddings for photos locally. This enables the 3D Cluster View, Photo Walker graph, and the Find Similar context action.
• Self-Healing Model Downloader: If you click Test Visual Embedding and the ONNX file is missing, Aegis will automatically download it from Hugging Face and store it in your models directory.

7 Tab 7: Search

The Search tab optimizes search query limits and visual similarity match thresholds.

Settings Breakdown

• Maximum number of results (search_max_results):
  • Options: 100, 250, 500, 1000, 2000, Unlimited.
  • Purpose: Sets the maximum number of items returned by keyword or semantic search.
• Degree of visual match preset (search_match_degree):
  • Options: High (requires close similarity), Medium, Low (returns more diverse matching items).
  • Purpose: Sets the similarity score threshold (cosine distance) for matching operations.

Impact on App Behavior

• UI Responsiveness: In massive libraries (e.g. 50,000+ photos), searching for a common tag might match 15,000 photos. Setting the results limit to 1000 prevents the UI from freezing while rendering thumbnails, ensuring a snappy search experience.
• Similarity Precision: When right-clicking a photo and selecting Find Similar, a High match preset limits the results to almost identical shots (bursts or duplicates). A Low match preset allows Aegis to return photos with similar color schemes, lighting, or overall composition.

8 Tab 8: Faces

This tab controls facial detection, face embedding extraction, clustering configurations, and diagnostics.

Settings Breakdown

• Model Status Check: Verifies if dlib's landmark predictor and ResNet face recognition models are located on disk.
• Enable Facial Recognition (enable_face_recognition): Activates or deactivates the face pipeline during AI processing.
• Confirm before merging people (skip_merge_confirmation): Toggles whether the application prompts you when combining two separate face groups.
• Clustering Sensitivity (face_clustering_strictness):
  • Loose: Uses a higher clustering threshold (wider grouping, might merge people who look slightly similar).
  • Balanced: The standard model setting.
  • Strict: Uses a tight clustering threshold (fewer merges, creates more individual profiles for the same person in different lighting).

Impact on App Behavior

• Face Pipeline Processing: If facial recognition is disabled, the background worker will skip extracting faces, leaving the People View empty.
• DBSCAN Clustering Sensitivity: Adjusts how faces are grouped. If you find that the app is grouping parents and children under the same person profile, change this setting to Strict and click Re-scan All Faces to rebuild the profile database.
• Isolated Environment Diagnostics: Clicking Test Facial Recognition executes ModelManager.run_isolated_diagnostics() in a separate python process. This tests system package bindings (dlib, face_recognition) and provides a detailed HTML report, making it easy to identify missing system dependencies.

9 Tab 9: Audio

The Audio tab controls text-to-speech engine options, language parameters, and voice narration models.

Settings Breakdown

• Speech Engine (tts_engine):
  • Auto-detect: Default engine selector based on OS.
  • Piper (Local Neural TTS): High-quality local neural text-to-speech.
  • System Default: Standard fallback command line narration (spd-say on Linux, say on macOS).
• Piper Voice Configuration:
  • Language: Language selector connected to the online Piper repository.
  • Voice Model (tts_voice): Chooses the specific vocal model (e.g. en_US-lessac-medium).
  • Download Voice: Downloads the corresponding .onnx and .json voice files.
  • Test Voice: Synthesizes a test sentence using the selected model.

Impact on App Behavior

• Narrated Library Tours: When hovering over photos or stepping through a slideshow, the TTS engine can read the description and tags out loud.
• Local Neural Realism: Choosing System Default sounds robotic. Swapping to Piper utilizes a local neural network to synthesize natural, human-sounding speech.
• Background Voice Downloader: Clicking Download Voice spawns a background thread that fetches the voice models directly into the local Piper cache directory, showing real-time download speed.

10 Tab 10: Caching

The Caching tab manages storage parameters for downloaded map tiles to support offline viewing.

Settings Breakdown

• Cache Directory: Displays the local filesystem folder holding cached map files.
• Disk Space Consumed: Calculates the size of the cache directory.
• Enable Map Tile Caching (enable_map_tile_caching): Turns map tile serialization on or off.
• Clear Map Tile Cache: Deletes all cached map files on disk.

Impact on App Behavior

• Offline Maps: When Map Caching is enabled, Leaflet map tiles (OpenStreetMap) viewed in the sidebar or fullscreen map are saved to your local drive. This allows you to view map pins and zoom in/out on locations even when your computer has no internet connection.
• Performance: Offline caching speeds up map loading times significantly by eliminating network latency.
• Storage Maintenance: Over months of heavy map usage, the map cache can grow to several gigabytes. Clicking Clear Map Tile Cache purges this folder, instantly freeing up disk space.