Add metadata-magic CLI for photo metadata generation and document usage.

2026-10-18 09:23:54 +02:00
parent c7de53f734
commit e818e0f31e
3 changed files with 360 additions and 94 deletions
@@ -0,0 +1,86 @@
+# PhotoTools3
+
+PhotoTools3 uses an OpenAI-compatible vision API to generate photo captions and
+keywords, then writes the results to photo metadata. It can also assess photo
+quality.
+
+## Setup
+
+Install the Python dependencies with `uv` and make sure ExifTool is installed and
+available on `PATH` (it is a system dependency, not a Python package):
+
+```bash
+uv sync
+```
+
+Create a `.env` file in the project root with the LLM connection details and the
+prefix used to identify metadata written by PhotoTools3:
+
+```dotenv
+llm_api_base_url=https://your-openai-compatible-api/v1
+llm_api_key=your-api-key
+llm_default_temperature=0.2
+metadata_prefix=photools3:
+```
+
+Keyword suggestions are restricted to the vocabulary in `config/keywords.txt`.
+
+## Generate metadata
+
+The `metadata-magic` command accepts one or more image paths and/or directories.
+The default mode is `both`, which generates and writes a caption and keywords:
+
+```bash
+uv run photools3 metadata-magic photo.dng
+```
+
+Choose a mode with `--mode`:
+
+```bash
+# Generate only keywords
+uv run photools3 metadata-magic photo.dng --mode keywords
+
+# Generate only a caption
+uv run photools3 metadata-magic photo.dng --mode captions
+
+# Explicitly request both (the default)
+uv run photools3 metadata-magic photo.dng --mode both
+```
+
+Pass multiple files to process them sequentially as a batch:
+
+```bash
+uv run photools3 metadata-magic photo1.dng photo2.jpg --mode both
+```
+
+Directories are scanned at the top level by default. Add `--recursive` to
+include supported images in subdirectories. You can combine directories and
+individual file paths:
+
+```bash
+uv run photools3 metadata-magic ./photos --recursive --mode keywords
+uv run photools3 metadata-magic ./photos photo-to-include.dng --mode captions
+```
+
+The command reports each processed file and exits with a non-zero status if any
+file fails. In a batch, it continues processing the remaining files after an
+individual failure. Generated metadata is written using ExifTool and XMP
+sidecars.
+
+## Assess photo quality
+
+The `quality` command reports an assessment without changing photo metadata:
+
+```bash
+uv run photools3 quality photo.dng
+```
+
+## Help
+
+Show the available commands and options with:
+
+```bash
+uv run photools3 --help
+uv run photools3 metadata-magic --help
+uv run photools3 quality --help
+```