97 lines
2.8 KiB
Markdown
97 lines
2.8 KiB
Markdown
# 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=http://localhost:1234/v1
|
|
llm_api_key=your-api-key
|
|
llm_default_temperature=0.2
|
|
metadata_prefix=photools3:
|
|
LOG_LEVEL=DEBUG
|
|
LLM_FLUSH_EVERY_PHOTOS=50
|
|
LLM_MAX_RETRIES=5
|
|
```
|
|
|
|
Keyword suggestions are restricted to the vocabulary in `config/keywords.txt`.
|
|
`LOG_LEVEL=DEBUG` enables detailed per-request and per-photo timings. The flush
|
|
interval uses LM Studio's native model-management API to unload and reload the
|
|
model after every 50 attempted batch photos. This requires LM Studio's native
|
|
`/api/v1` model-management API. Set `LLM_FLUSH_EVERY_PHOTOS=0` to disable it;
|
|
use `0` for non-LM-Studio OpenAI-compatible providers.
|
|
`LLM_MAX_RETRIES` controls how many corrective retry requests are allowed after
|
|
the initial LLM response; `5` means up to 6 requests for a photo.
|
|
|
|
## 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
|
|
```
|