TAM - Image Metadata Search Tool

TAM (Image Metadata) is a powerful Python application for querying multiple image databases based on metadata including location, time, image properties, and custom criteria.

Features

• Multi-Database Support: SQLite and PostgreSQL adapters
• Comprehensive Metadata Extraction: EXIF data, GPS coordinates, file properties
• Advanced Search Capabilities: Location-based, time-range, property-based, and custom queries
• Batch Processing: Index entire directories of images
• Command Line Interface: Easy-to-use CLI for all operations
• Export Options: JSON and CSV export formats

Installation

1. Clone or download the TAM directory:

cd /home/ciso/TAM

2. Install required dependencies:

pip install -r requirements.txt

Quick Start

1. Initialize a database:

python tam.py init

2. Index images from a directory:

python tam.py index --directory /path/to/your/images

3. Search for images:

# Search by location (within 10km of coordinates)
python tam.py search --latitude 40.7128 --longitude -74.0060 --radius 10

# Search by time range
python tam.py search --start-time "2023-01-01T00:00:00" --end-time "2023-12-31T23:59:59"

# Search by image properties
python tam.py search --width-min 1920 --height-min 1080 --format JPEG

# Search by filename pattern
python tam.py search --pattern "vacation*.jpg"

# Search by camera info
python tam.py search --camera-make "Canon" --camera-model "EOS"

CLI Commands

init

Initialize the database with default schema:

python tam.py init [--adapter sqlite|postgresql] [--connection DB_FILE] [--table TABLE_NAME]

index

Index images from directory or single file:

python tam.py index --directory /path/to/images
# or
python tam.py index --file /path/to/image.jpg

search

Search for images with various criteria:

python tam.py search [OPTIONS]

Search Options:

• --latitude FLOAT: Latitude for location search
• --longitude FLOAT: Longitude for location search
• --radius FLOAT: Radius in km for location search
• --start-time ISO_DATETIME: Start time for time range search
• --end-time ISO_DATETIME: End time for time range search
• --width-min INT: Minimum image width
• --width-max INT: Maximum image width
• --height-min INT: Minimum image height
• --height-max INT: Maximum image height
• --format STRING: Image format (JPEG, PNG, etc.)
• --pattern STRING: Filename pattern with wildcards
• --camera-make STRING: Camera manufacturer
• --camera-model STRING: Camera model
• --limit INT: Maximum number of results (default: 20)

export

Export search results to file:

python tam.py export --output results.json --format json
# or
python tam.py export --output results.csv --format csv

list

List active database connections:

python tam.py list

Configuration

Create a custom configuration file:

python tam.py --config /path/to/config.json [command]

Example configuration structure:

{
  "default_database": {
    "adapter": "sqlite",
    "connection_string": "images.db",
    "table_name": "images"
  },
  "additional_databases": {
    "archive": {
      "adapter": "postgresql",
      "connection_string": "dbname=archive user=user password=pass host=localhost",
      "table_name": "archived_images"
    }
  }
}

Supported Image Formats

• PNG (.png)
• JPEG (.jpg, .jpeg)
• GIF (.gif)
• BMP (.bmp)
• TIFF (.tiff)
• WebP (.webp)

Metadata Extracted

• File Properties: Name, size, extension, creation/modification times
• Image Properties: Dimensions, format, color mode
• EXIF Data: Camera make/model, ISO, aperture, focal length, flash usage
• GPS Data: Latitude, longitude, altitude (if available)
• File Hash: MD5 for deduplication

Search Examples

Location-based searches:

# Images within 5km of Central Park
python tam.py search --latitude 40.7829 --longitude -73.9654 --radius 5

# Images in specific bounding box
python tam.py search --latitude 40.7 --longitude -74.0 --radius 0.1

Time-based searches:

# Images from January 2023
python tam.py search --start-time "2023-01-01T00:00:00" --end-time "2023-01-31T23:59:59"

# Recent images (last 30 days)
python tam.py search --start-time "2023-12-01T00:00:00"

Property-based searches:

# High-resolution images
python tam.py search --width-min 3840 --height-min 2160

# Specific format
python tam.py search --format PNG

# Large files (over 5MB)
python tam.py search --width-min 0 --height-min 0  # dummy criteria to enable file size filter

Camera-specific searches:

# All Canon photos
python tam.py search --camera-make "Canon"

# Photos from specific model with flash
python tam.py search --camera-model "EOS 5D" --flash-used true

Architecture

The application consists of several modular components:

• metadata_extractor.py: Extracts comprehensive metadata from image files
• database.py: Database abstraction layer supporting multiple backends
• query_engine.py: Advanced search and filtering capabilities
• tam.py: Command-line interface and main application logic

Error Handling

The application includes robust error handling for:

• Corrupted or unreadable image files
• Missing EXIF data
• Database connection issues
• Invalid search parameters
• File permission problems

Performance Considerations

• For large image collections (>50,000 images), consider using PostgreSQL for better performance
• The application uses batch processing for indexing operations
• Search results are limited by default to prevent memory issues
• File hashes are calculated for efficient deduplication

License

This project is provided as-is for educational and practical use.