program flow

Program sequence: AI Rating & Keywords (version 3.3)

This schedule describes the main process of the LUA script for Darktable. The script performs AI-supported image ratings by sending images to a local LMStudio API and saving the results in Darktable, and optionally to a separate XMP file.

Survey

The script loads a configuration ai_config.json, checks API availability and processes selected images. It exports each image as Base64 JPEG, sends it to the API, parses the answer and applies the results. The process can be aborted by a stop button.

Step-by-step process

  1. Initialization and GUI Setup
    • Script is loaded into Darktable.
    • GUI widgets (checkboxes for overwrite options, buttons) are created and registered.
    • Default values for settings are set (if not available).
  2. User Response: Click on “AI Rating”
    • Function ai_rate_selection() is called.
    • Check selection of images: If no images are selected, view and cancel errors.
  3. Load configuration
    • load_config(): loads ai_config.json and parses Json.
    • In case of error: Cancel and report errors.
  4. Check API Achievement
    • check_api_reachability(): Tests connection to LMStudio API.
    • In case of error: Cancel and display notice.
  5. Generate Rating Lookup
    • generate_rating_lookup(): Creates rating scale table based on Config.
  6. Reset STOP flag
    • STOP_REQUESTED = FALSE
  7. Create a job and start a loop
    • Creates a Darktable job for progress.
    • Loop over all selected images:
      • Check STOP flag: if STOP_REQUESTED, break off loop.
      • update progress.
  8. XMP check per image
    • Check if XMP file exists and should not be overwritten.
    • If so: Skip the picture (count as “skip”), go to the next picture.
  9. process imageprocess_image_with_ai())
    • Output blank line for separation.
    • Export image: export_image_to_base64() – Converts to JPEG and encodes Base64.
      • In case of error: count error and next picture.
    • Measure and display export time.
    • API call: call_ai_api() – Sends Base64 image to AI.
      • In case of error: count error and next picture.
    • Parsing answer: parse_ai_response() – Extracted rating, keywords, description.
    • Apply results: apply_ai_result() – sets rating, description, tags in darktable; Writes XMP file.
    • Format output (stars for rating, tokens, duration) and displays.
  10. Finish loop
    • complete job.
    • Output Summary: “X successful, Y error, Z skipped.”
  11. Stop button (at any time)
    • Sets STOP_REQUESTED = TRUE and breaks a loop.

Flowchart

Fish
Start  
  ↓  
GUI laden & Settings initialisieren  
  ↓  
Button "AI-Bewertung durchführen" geklickt  
  ↓  
Auswahl prüfen (Bilder vorhanden?)  
  ├─ Nein → Fehler & Ende  
  ↓ Ja  
Konfiguration laden  
  ├─ Fehler → Ende  
  ↓ OK  
API-Erreichbarkeit prüfen  
  ├─ Fehler → Ende  
  ↓ OK  
Rating-Lookup generieren  
  ↓  
Stop-Flag = false  
  ↓  
Job erstellen  
  ↓  
Schleife über Bilder:  
  ├─ Stop angefordert? → Ja → Abbrechen  
  ↓ Nein  
  Fortschritt aktualisieren  
  ↓  
  XMP-Datei existiert & nicht überschreiben?  
  ├─ Ja → Überspringen & Zähler +1  
  ↓ Nein  
  Bild exportieren (Base64)  
  ├─ Fehler → Fehler-Zähler +1 & nächstes Bild  
  ↓ OK  
  API-Aufruf  
  ├─ Fehler → Fehler-Zähler +1 & nächstes Bild  
  ↓ OK  
  Antwort parsen  
  ↓  
  Ergebnisse anwenden (Rating, Beschreibung, Tags, XMP)  
  ↓  
  Ausgabe formatieren & anzeigen  
  ↓  
  Nächstes Bild (bis alle durch)  
  ↓  
Job abschließen  
  ↓  
Zusammenfassung ausgeben  
  ↓  
Ende

Notes on documentation

  • Configuration: All settings (API URL, Prompts, Image Sizes) are in ai_config.json defined.
  • error handling: API errors are treated with retries; Export errors cancel the image.
  • Performance: Export time and API duration are measured and displayed.
  • adjustments: Checkboxes in the GUI control what is overwritten (rating, description, tags, XMP).