DigiKam-Nextcloud Face Sync Tool

From OISecWiki

digiKam-Nextcloud Face Sync Tool

A new open-source project has been released to bridge the powerful face management features of digiKam with Nextcloud Recognize.

The repository is available at: https://gitea.oisec.net/cliff/digikam-nextcloud

Overview

This tool performs a one-way synchronization of named face regions from digiKam (the source of truth) into Nextcloud's Recognize face detection system. It does not write any data back to digiKam, ensuring your primary photo library remains untouched.

Key capabilities include:

  • Reading face rectangles and person names from digiKam's SQLite database (digikam4.db).
  • Matching files between digiKam's filesystem and Nextcloud using path mapping and file size/filename fallbacks.
  • Comparing face regions using Intersection over Union (IoU).
  • Assigning or renaming faces in Nextcloud Recognize.
  • Optional insertion of new face boxes (via DB backend).
  • Conflict detection and reporting.
  • Support for very large libraries through batching, concurrency, and resumable sessions.

Features

  • Multiple backends:
    • HTTP/WebDAV (preferred, default) — Uses Nextcloud WebDAV and Recognize DAV endpoints. Efficient for large libraries with keep-alive connections and targeted queries. Supports assigning/renaming via MKCOL and MOVE operations.
    • DB (SQL) — Direct database access (with optional SSH tunnel) for inserting new face rectangles.
  • Performance optimizations:
    • Batched processing to keep memory usage low.
    • Concurrent HTTP workers.
    • Session-based resume for interrupted runs on massive collections.
    • Targeted processing for single persons or limited image sets.
  • Safety:
    • Dry-run mode by default.
    • Read-only access to digiKam database.
    • Skips unknown/unconfirmed/ignored faces.
    • Configurable conflict policies (digiKam wins by default on apply).

Technical Details

The tool is written in Python (3.10+) and structured as a package with clear separation of concerns: 

digikam_nextcloud/          # Python package
  cli.py                    # argparse / main
  sync.py                   # orchestration
  digikam.py                # digiKam SQLite reader
  nextcloud_db.py           # SQL backend (+ SSH tunnel)
  nextcloud_http.py         # WebDAV / Recognize DAV backend
  matching.py               # file + region matching
  models.py                 # dataclasses + backend protocol
  session_state.py          # cancel/resume session files

Face Matching

Face regions are matched using IoU between digiKam's pixel-based tagRegion and Recognize's relative (0-1) coordinates. Overlapping boxes with differing names trigger conflict reports.

Path Mapping

Configure path_maps in the YAML config to translate filesystem paths:

Example:

  • digiKam: /mnt/nas/Photos/2024/a.jpg
  • Nextcloud: files/Photos/2024/a.jpg
  • Mapping: from: /mnt/nas/Photos → to: Photos

Fallback matching uses filename + file size for robustness.

Configuration

Copy config.example.yaml to config.yaml and edit:

  • digiKam database path
  • Nextcloud connection details (URL, user, app password)
  • Backend choice
  • Path mappings
  • SSH options (if using DB backend)

Usage Examples

Basic dry-run: 

python sync_faces.py --config config.yaml

Apply changes: 

python sync_faces.py --config config.yaml --apply

Optimized run for large libraries (assign-only over HTTP): 

python sync_faces.py --config config.yaml \
  --no-insert-missing --batch-size 500 --http-workers 24 --apply

Single person test: 

python sync_faces.py --config config.yaml --only-person "Alice" --apply

Resume interrupted session: 

python sync_faces.py --config config.yaml --apply --resume 20260722-120000-abc123

JSON report output and other flags are supported for automation and monitoring.

Requirements

  • Python 3.10+
  • digiKam SQLite database (digikam4.db)
  • Nextcloud with Recognize app
  • Dependencies: listed in requirements.txt (install via venv + pip)

For Recognize API key issues (403 errors), see the project README for configuration options including auto-fetch or admin settings.

This tool is particularly useful for users maintaining large personal photo archives who want consistent face tagging across desktop (digiKam) and cloud/self-hosted (Nextcloud) environments. Contributions and issues are welcome on the Gitea repository.

The full source code, LICENSE, and detailed README are available in the repository.

Retrieved from "https://wiki.oisec.net/mediawiki/index.php?title=DigiKam-Nextcloud_Face_Sync_Tool&oldid=778"