Skip to content

image‐tag‐handler

Jump to bottom
Dusan Lesan edited this page Aug 11, 2025 · 1 revision

image-tag-handler

Overview

The Image Tag Handler is a C program for managing image tags through an SQLite database. It provides functionality to store, retrieve, and manipulate various types of tags (keywords, subjects, shared) associated with images. The program can synchronize tags between image files (via exiftool) and the database, perform searches, create symbolic link trees for browsing, and handle batch operations on image collections.

The program supports both terminal and graphical interfaces, with special integration for the lf file manager through dmenu prompts.

Usage

image-tag-handler [OPTIONS]

Database Schema

The program creates an SQLite database with the following structure:

  • images: Stores image paths and SHA-256 checksums
  • keywords: General descriptive tags
  • subjects: Subject-specific tags
  • shared: Sharing/publication status tags
  • Junction tables linking images to each tag type with foreign key constraints

Options

  • -D <path>: Specify database path (auto-discovers .image.db in current or parent directories if not provided)
  • -i <paths>: Image file paths (newline-separated for multiple images)
  • -t <name>: Tag category name (keywords, subjects, or shared)
  • -l <id>: lf file manager instance ID for GUI integration
  • -s: Search for images by tag
  • -m <mode>: Search output mode (d=default list, f=file output, t=symlink tree)
  • -p: Print tags from images or database
  • -u: Update/sync tags between file and database
  • -f: Target file metadata (used with -p or -u)
  • -d: Target database (used with -p or -u)
  • -a: Add tags to images
  • -r: Remove tags from images
  • -S <path>: Batch sync directory (calculates SHA-256 for all files)
  • -U: Update SHA-256 checksums for existing database entries

Set-up

Database Discovery: The program searches for .image.db starting from the current directory and traversing up the directory tree. If no database is found, it offers to create one in the current directory.

Examples

Initialize database and add images:

# Create database if needed and add image files
image-tag-handler -i "photo1.jpg" -a -t keywords

Sync tags from image files to database:

# Extract keywords from EXIF data and store in database
image-tag-handler -i "vacation/*.jpg" -u -d -t keywords

Search for images by tag:

# Find all images tagged with "landscape"
image-tag-handler -s -t keywords
# (will prompt for tag value)

# Create symlink tree organized by tags
image-tag-handler -s -t subjects -m t

Add multiple tags to images:

# Add comma-separated tags
image-tag-handler -i "image.jpg" -a -t keywords
# (will prompt for tag values like "nature,outdoor,sunset")

Print tags from image file:

# Show EXIF keywords
image-tag-handler -i "photo.jpg" -p -f

Print tags from database:

# Show database tags for image
image-tag-handler -i "photo.jpg" -p -d -t "keywords,subjects"

Batch operations:

# Sync entire directory and calculate checksums
image-tag-handler -S "/path/to/photos"

# Update checksums for existing entries
image-tag-handler -U

Integration with lf file manager:

# Search for images and select them in lf
image-tag-handler -sl "$id"

# Search and output to file for lf consumption
image-tag-handler -sl "$id" -m 'f'

# Add tags to selected files
image-tag-handler -l "$id" -i "$fx" -a -t keywords

File Outputs

Search file mode (-m f): Creates ~/.local/share/lf/search containing newline-separated image paths matching the search criteria.

Symlink tree mode (-m t): Creates a directory structure at .tag_tree/<tag_name>/<tag_value>/ containing symbolic links to matching images, organized by tag categories.

Behavior Notes

  • GUI vs Terminal: Automatically detects display environment and uses either dmenu or terminal prompts
  • Tag Synchronization: Bidirectional sync between image EXIF data and database
  • Duplicate Handling: Uses SHA-256 checksums to identify and handle duplicate images
  • Path Validation: Checks file existence and updates database accordingly
  • Transaction Safety: Uses database transactions for batch operations
  • Memory Management: Handles dynamic memory allocation with proper cleanup
  • lf Integration: Supports file selection and navigation in the lf file manager

Error Handling

The program includes error handling with notifications:

  • Database connection failures
  • File access permissions
  • Invalid image paths
  • Missing dependencies
  • Memory allocation errors

All errors are displayed via desktop notifications (GUI mode) or stderr output (terminal mode).

Clone this wiki locally