Frequently Asked Questions (FAQ)

Table of Contents

• Installation & Startup
• Photo Import & Indexing
• Photo Browsing & Display
• Search
• AI & Face Recognition
• Album Management
• Export & Sharing
• Performance
• Software Activation
• Docker Deployment
• Data Backup & Recovery
• Other Issues

Installation & Startup

Q: Which operating systems are supported?

Supports Windows 10+ / Windows Server 2012 R2+, macOS (Apple Silicon), Ubuntu 24.04+. All three platforms have desktop GUI versions, and all support Docker deployment.

Q: What are the minimum system requirements?

Q: What should I do after first launch?

See Chapter 1: Quick Start. Basic workflow:

1. Add photo folders (Menu → Add Folder)
2. Wait for scan & indexing to complete
3. Browse photos and explore features

Q: How do I switch the interface language?

In the status bar at the bottom, click the dropdown next to "语言" / "Language" to select 中文 or English. Changes take effect immediately without restart.

Photo Import & Indexing

Q: How do I add photo folders?

Two methods:

• Menu: Sidebar ≡ → Add Folder, select folder
• Drag & drop: Drag a folder from file manager to the sidebar area (one at a time)

Q: Which image formats are supported?

Full list in Appendix.

Q: Why is scanning so slow?

It's normal for the first scan of a large photo collection. Scanning speed mainly depends on how many AI models run per photo:

By default, 5 models run per photo (sorted by time cost):

Speed-up tips:

1. Core only (fastest): Settings → AI Config → choose "Lightweight" preset, or manually check only core features. Runs only 2 models, fastest speed.
2. Enable on demand: Turn off face detection if not needed, turn off semantic search if not needed, turn off OCR if not needed.
3. GPU acceleration: Face (YuNet) and semantic (SigLIP2) run much faster on GPU than CPU. Settings → AI Config → Inference Device → select "GPU".
4. Only check the formats you need to manage (Settings → Scan Settings)
5. Set a reasonable minimum image size filter
6. Add photos in batches for large collections
7. Use SSD storage

Note: If you enable an AI capability after scanning, previously scanned photos need to be reprocessed, which takes extra time. Configure your desired AI capabilities before adding folders for the first time.

Q: Can I force quit during indexing?

Yes. The software persists the processing status of each photo, so completed indexing is never lost. It automatically resumes from the breakpoint on next launch, skipping processed files and handling only the remainder (see "What if scanning gets stuck or fails").

Q: How long does indexing usually take?

Depends on photo count and AI capability configuration. Rough estimates (average processing time per photo):

Actual times vary with CPU performance, GPU model, image resolution, OCR text volume, etc. The "Lightweight" preset (core only) is fastest.

Q: What if scanning gets stuck or fails?

1. Restart the software. Completed indexing is never lost — the software auto-recovers on launch and continues from the breakpoint ("Auto-recover index" is on by default)
2. Check that folders have read permissions
3. Verify sufficient disk space
4. Try adding the problematic folder in isolation
5. Use Menu → Refresh Index to manually trigger recovery scan

How it works: The software persists the processing status of each photo (completed / not completed). After restart, it automatically skips processed files and handles only the remainder. Controlled by Settings → Index Settings → "Auto-recover Index" (enabled by default).

Q: How do I exclude unwanted folders?

Settings → Scan Settings → Ignore Rules. Three rule types are supported:

Q: Can I manage multiple folders at once?

Yes. After adding multiple folders, photos from all folders are browsed together under "All Photos".

Photo Browsing & Display

Q: What to do if photos won't display?

1. Check if the original file opens normally
2. Confirm the file format is supported
3. Clear the thumbnail cache
4. Re-scan the folder

Q: What to do if thumbnails load slowly?

• Check disk read/write speed (SSD recommended)
• Clear cache in settings
• Adjust cache size settings

Q: How do I preview a photo?

• Double-click a photo to enter full-screen preview
• Right-click → Preview
• Select a photo and press Enter

Q: How to operate in preview mode?

Q: How do I view a photo's EXIF info?

In preview mode, click the info icon to view: capture time, camera model, shutter/aperture/ISO, GPS coordinates, resolution, etc.

Q: How do I quickly select multiple photos?

Enable the layer icon in the status bar to turn on "cross-page selection", which keeps selections across different views.

Search

Q: What search modes are supported?

The dropdown selector on the left of the search box provides 6 modes:

1. File Info: Search by filename, EXIF, tags, etc.
2. Scene Content: AI semantic search (describe what you see to find photos)
3. Blur Detection: Quickly filter blurry photos
4. With/Without People: Filter by presence of faces
5. 1-star ~ 5-star: Filter by rating

Extended buttons: image search (search by image), face search, folder-scoped search.

Q: How do I use scene content search?

1. Select the "Scene Content" search type
2. Enter subject descriptions separated by commas, e.g., cat, sofa, indoor
3. Press Enter to execute
4. Use concise, clear subject terms for best results

Q: What if search results are inaccurate?

• Rebuild index (Settings → Data Rebuild → Rebuild Index)
• Use more precise search conditions
• Adjust the similarity threshold (0–1, higher = stricter)
• For face search, use front-facing, well-lit photos

Q: What if search returns no results?

1. Confirm photos are fully indexed
2. Check that the correct search type is selected
3. Lower the similarity threshold and retry
4. Rebuild index and retry

Q: How do I search by image?

1. Click the image search icon to the right of the search box
2. Choose "Full Image Similarity" and upload a reference image
3. Or use "Local Similarity" to drag-crop regions of interest (up to 5)
4. Adjust the threshold slider to control match strictness

AI & Face Recognition

Q: Do AI features require internet?

No. All AI features (face recognition, semantic search, OCR, etc.) run locally. No internet required.

Q: What if face detection is inaccurate?

1. Adjust the face recognition threshold (Settings → AI Config, default 0.2)
2. Ensure faces in photos are clear, front-facing, and well-lit
3. Manually reassign misidentified faces
4. Rebuild face groups

Q: What if the same person is split into multiple characters?

Use the Merge Characters feature:

1. Select multiple characters that may be the same person
2. Use the merge function
3. Confirm, and the system merges them automatically

Q: How do I name a person?

Click an unnamed person → enter the person's name → confirm to save.

Q: How do I reassign misidentified faces?

1. In preview mode, click face boxes (multi-select supported)
2. Right-click and select "Reassign Face"
3. Choose the target person in the dialog

Q: How do I create zero-shot classification?

1. AI Groups page → Add Category
2. Enter a category name and description (English descriptions recommended)
3. Use "Default Categories" to quickly populate preset categories
4. Create at least two categories then click "Run Classification"

Q: What do the quality icons on photos mean?

Quality icons show the sharpness score of a photo:

Q: How do I change the AI inference device?

Settings → AI Config → Inference Device. Options: Auto, Processor (CPU), Graphics (GPU).

Q: How do I choose an inference configuration?

Settings → AI Config → Inference Engine Settings. The software provides 4 presets:

You can also fine-tune manually:

• Inference Device: Auto / CPU / GPU
• Processing Mode: Sequential (memory-friendly) / Parallel (faster) / Auto
• Capability Toggles: Core (required), Face, Text (OCR), Semantic

The Lightweight preset runs only 2 models — fastest indexing but no face/semantic/OCR features. You can enable additional capabilities later; previously scanned photos will then be reprocessed.

Q: What's the difference between large and small models?

Large models have better understanding but require downloading ~1.5 GB of extra files. Switching models requires rebuilding the index. Choose in Settings → AI Config.

Album Management

Q: What's the difference between albums and folders?

Albums are virtual collections — they do not copy or move original files. The same photo can exist in multiple albums. Removing a photo from an album does not delete the original file.

Q: How do I create an album?

• Go to the Albums page → Create Album
• Or select photos → right-click → Add to Album → New Album

Q: What are aggregation settings?

Configure auto-collection rules for an album. The system automatically matches and adds qualifying photos from multiple dimensions (path, OCR, date, face, semantic, etc.). Run aggregation after setting up.

Q: How do I save search results as an album?

On the search results page, use "Convert Current Search to Album" to save all results in one click.

Export & Sharing

Q: Which export formats are supported?

Original format, JPEG, PNG, WebP, AVIF (see Chapter 9: Export & Sharing).

Q: How to control quality during export?

• Quality range: 50% – 100%
• Web sharing: 70%–80% recommended
• Local archiving: 90%–100% recommended

Q: How do I create an online share?

1. On the Albums page, right-click an album → Share
2. Optionally set an access password
3. Copy the link and send to others

Q: Does the sharing feature require the software to keep running?

Yes, sharing pages are served by the software server. When the desktop version is closed, share links become inaccessible. Docker deployment can stay online 24/7.

Performance

Q: How to optimize if the software runs slowly?

1. Use SSD storage
2. Close unused background programs
3. Optimize database (Settings → System Settings → Optimize Database)
4. Only check the image formats you need to manage
5. Set a reasonable minimum image size filter
6. Clean up unnecessary cache files

Q: What to do if memory usage is too high?

• Reduce the number of photos processed simultaneously
• Adjust the processing mode in AI Config
• Restart the software to free memory

Q: Does the database need maintenance?

It's recommended to run database optimization once a month (Settings → System Settings → Optimize Database) — compresses the database and improves query performance.

Software Activation

Q: How to activate the desktop version?

Desktop version supports offline activation only:

1. Open the activation dialog (Menu → Activate)
2. Copy the request code
3. Send the request code to the vendor to obtain an activation code
4. Paste the activation code and verify
5. Restart the software to take effect

Q: Does the App Store version need activation?

No. The Microsoft Store version does not require activation.

Q: How to activate the Docker version?

Docker version supports online activation:

1. Open the activation dialog
2. Enter the activation code
3. The system verifies online automatically

Q: How to check activation status?

Menu → Help → About. View current activation status and validity period.

Q: Can the software be used offline?

The desktop version can be used fully offline. All AI features (face recognition, semantic search, OCR, etc.) run locally. Activation is also offline (copy request code → obtain activation code → local verification). The entire workflow requires no internet.

The Docker version runs in a browser, usually with internet access, so activation uses online verification.

Q: Is a perpetual license available?

A perpetual license (lifetime) is offered (coming soon), granting permanent usage rights for the current major version. Notes:

• Perpetual license covers only the current major version, not major version upgrades
• Upgrading to a new major version requires repurchase/renewal
• License is tied to the current machine; changing computers requires reactivation

Q: What if I change computers?

1. License transfer: On the new computer, open the activation dialog, copy the new request code, and contact the vendor for a new computer activation code
2. Data migration: Copy the old computer's data directory (Settings → System Settings → Open Data Directory) to the corresponding location on the new computer. After re-adding photo folders, all data (index, faces, albums, etc.) will be restored

Original photo files also need to be migrated to the new computer, or kept at the same network path.

Docker Deployment

Q: What environment does Docker deployment require?

Requires Docker and docker-compose. Supports standard (x86-64) and ARM (Raspberry Pi, Apple Silicon).

Q: How to deploy?

See Chapter 14: Docker Deployment:

1. Pull image: docker pull lightedium:latest
2. Create data directory and docker-compose.yaml
3. Start: docker-compose up -d
4. Access: http://your-server-ip:10242

Q: Are there functional differences between Docker and Desktop versions?

Q: How to update the Docker image?

docker-compose pull
docker-compose up -d

Q: How to back up Docker data?

tar -czf backup.tar.gz ./data

Back up the data directory, which contains the database and configuration.

Data Backup & Recovery

Q: What data needs to be backed up?

Q: How to back up?

1. Settings → System Settings → Open Data Directory
2. Copy the entire data directory to a backup location
3. It's recommended to also back up the original photo folders

Q: How to restore?

1. Reinstall the software
2. Overwrite the data directory with the backup
3. Re-add photo folders
4. Verify data integrity

Q: How to reset the database?

Settings → System Settings → Reset Database. Use with caution — this clears all data.

Other Issues

Q: Can deleted photos be recovered?

Q: How to view log files?

Menu → Settings → System Settings → Open Log File, or Menu → Help → Open Log File.

Q: What if HEIC/HEIF files won't display?

FFmpeg must be installed. Download/install FFmpeg in Settings → System Settings.

Q: How to update the software?

• Desktop: Menu → Help → Check for Updates
• Docker: docker-compose pull && docker-compose up -d

Q: What keyboard shortcuts are available?

Full list in Appendix. Frequently used:

Q: Can I batch rename photo filenames?

Yes. Select photos → right-click → Edit → Rename. Supports template variables and regex modes. See Chapter 8: Batch Operations.

Q: How to find duplicate photos?

Go to the "Duplicates" page, which provides two detection modes:

• Exact Match: Find completely identical copies based on file hash
• Similarity Match: Find visually similar images based on image features

You can use the image comparison tool for assistance.

For more details, see User Tutorial. For further assistance, go to Menu → Help → About for version info.

If issues persist, please contact the vendor for technical support.