TagOmatic v5.0 User Manual

Introduction

What is TagOmatic?

TagOmatic is a privacy-first, AI-powered desktop application designed specifically for motorsport photographers. It automatically identifies vehicles, extracts race numbers, matches drivers from timing sheets, and writes comprehensive metadata directly to your image files—all processed locally on your computer.

Key Benefits

• 100% Local Processing: Your photos never leave your machine. Complete privacy guaranteed.
• AI-Powered Identification: Advanced vision models identify make, model, color, and distinctive features.
• Race Number Detection: Automatically detects and extracts race numbers from vehicle doors, roofs, and bodywork.
• PDF Timing Integration: Import race timing sheets to automatically match race numbers with driver information.
• Standards-Compliant Metadata: Writes EXIF and IPTC metadata compatible with all major photo management software.
• Batch Processing: Process hundreds of images efficiently with progress tracking.

TagOmatic LITE vs Pro

Installation & Setup

Prerequisites

1. Windows 10/11 (64-bit)
2. Ollama - Download from ollama.ai
3. 8GB RAM minimum (16GB recommended)
4. ~500MB storage for application + ~4GB for Ollama model
5. NVIDIA GPU (optional) - Recommended for faster AI processing

Step 1: Install Ollama

1. Visit https://ollama.ai
2. Download and install Ollama for Windows
3. Verify installation by opening Command Prompt and running:

   ollama --version

Step 2: Install AI Model

Open Command Prompt or PowerShell and run:

ollama pull qwen2.5vl:7b

Step 3: Install TagOmatic

For LITE Version:

1. Download TagOmatic-v5.0-LITE-setup.zip from www.tagomatic.co.uk
2. Extract the ZIP file
3. Run TagOmatic-v5.0-LITE-setup.exe
4. Follow the installation wizard
5. Launch TagOmatic LITE from the Start menu or desktop shortcut

For Pro Version:

1. Purchase and download from Steam
2. Install through Steam
3. Launch from Steam library

Step 4: Verify Setup

1. Launch TagOmatic
2. The application should detect Ollama automatically
3. If you see "Ollama not detected" or connection errors, ensure Ollama is running:
   • Check the system tray for the Ollama icon
   • Or run ollama serve in Command Prompt

Getting Started

First Launch

When you first launch TagOmatic, you'll see:

1. Main Window with image preview area
2. Control Panel on the right with processing options
3. Results List at the bottom showing processed images
4. Menu Bar with File, Edit, Tools, and Help options

Quick Start: Process Your First Image

1. Load an Image:
   • Click "Load Image" or File → Open Image
   • Select a motorsport photo with a visible vehicle
2. Process the Image:
   • Click "Process Image" or press Ctrl+P
   • Wait for AI analysis (typically 5-15 seconds)
3. Review Results:
   • The results panel will show:
     • Make & Model: Identified vehicle
     • Color: Detected color
     • Race Number: Extracted number (if visible)
     • Driver: Matched from timing sheet (if PDF loaded)
     • Metadata Preview: All extracted information
4. Write Metadata:
   • Review the results
   • Click "Write Metadata" to save EXIF/IPTC tags to the image file
   • The original file will be updated with the new metadata

Quick Start: Batch Processing

1. Load a Folder:
   • Click "Load Folder" or File → Open Folder
   • Select a folder containing motorsport images
2. Configure Batch Settings:
   • Skip Existing: Skip images that already have metadata
   • Overwrite: Replace existing metadata
   • Race Number Only: Only extract race numbers (faster)
3. Start Processing:
   • Click "Process Batch"
   • Monitor progress in the results list
   • Each image will be processed automatically

Core Features (LITE & Pro)

1. AI Vehicle Identification

TagOmatic uses advanced vision language models (Qwen2.5VL) to identify vehicles in images.

What it extracts:

• Make: Manufacturer (e.g., "Ferrari", "Porsche", "McLaren")
• Model: Specific model (e.g., "488 GT3", "911 GT3 R", "720S GT3")
• Color: Primary color (e.g., "Red", "Blue", "White")
• Distinctive Features: Spoilers, livery details, modifications
• License Plates: If visible
• Logos & Sponsors: Identified branding

How to use:

1. Load an image with a clear view of the vehicle
2. Click "Process Image"
3. Review the extracted information
4. Edit if necessary before writing metadata

2. Race Number Detection

Automatically detects and extracts race numbers from vehicle doors, roofs, and bodywork using OCR (Optical Character Recognition).

How it works:

1. AI identifies potential number locations
2. OCR extracts text from those regions
3. Numbers are matched with timing sheet data (if PDF loaded)

Supported formats:

• Single digits (1-9)
• Double digits (10-99)
• Triple digits (100-999)
• Various fonts and styles

3. PDF Timing Sheet Integration

Import race timing sheets (PDF format) to automatically match race numbers with driver information.

Supported formats:

• TSL Timing (Format B)
• SMART Timing (Format A)
• Auto-detection of format type

How to import:

1. Click "Load Timing PDF" or File → Import Timing Sheet
2. Select your PDF file
3. TagOmatic will parse the PDF and extract:
   • Race numbers
   • Driver names
   • Team names
   • Car information
   • Session times
   • Track and event names

Automatic matching:

• When processing images, TagOmatic automatically matches detected race numbers with driver data
• Session filtering available for multi-session events
• Driver name appears in metadata automatically

4. EXIF/IPTC Metadata Tagging

TagOmatic writes comprehensive metadata directly to image files using industry-standard formats.

Metadata fields written:

• IPTC Keywords: Make, model, color, driver, race number
• IPTC Caption: AI-generated description
• IPTC Headline: Vehicle identification
• EXIF UserComment: JSON-formatted complete data
• EXIF Artist: Photographer (if set)
• EXIF Copyright: Copyright information (if set)

Supported formats:

• JPEG (.jpg, .jpeg)
• TIFF (.tif, .tiff)
• PNG (.png)
• RAW formats (CR2, NEF, ARW, etc.)
• HEIC (.heic)
• WebP (.webp)

5. Batch Processing

Process entire folders of images automatically with progress tracking and error handling.

Batch options:

• Skip Existing: Skip images that already have TagOmatic metadata
• Overwrite: Replace existing metadata
• Race Number Only: Faster mode that only extracts race numbers
• Progress Tracking: Real-time progress bar and status updates

How to use:

1. Click "Load Folder" or File → Open Folder
2. Select your images folder
3. Configure batch settings
4. Click "Process Batch"
5. Monitor progress in the results list
6. Review any errors or warnings

6. Version Checking (LITE Only)

TagOmatic LITE automatically checks for updates and notifies you when a new version is available.

How it works:

• Checks version on application startup
• Compares with latest version on server
• Shows notification if update available
• Provides download link to latest version

Pro-Only Features

1. SAM3 Geometric Matching

Segment Anything Model 3 (SAM3) provides advanced geometric thumbprint extraction and component-based vehicle matching.

What it does:

• Component Segmentation: Identifies wheels, vents, plates, logos, and other vehicle components
• View Angle Detection: Determines if image shows side, front, rear, or top view
• Geometric Thumbprint: Creates scale-invariant geometric signature based on component positions
• KB Matching: Matches thumbprints against Knowledge Base for accurate identification

How it works:

1. SAM3 segments vehicle components in the image
2. View angle is detected automatically
3. Geometric thumbprint is extracted from component positions
4. Thumbprint is matched against Knowledge Base entries
5. Best match (if similarity > 85%) is used to guide AI identification

Benefits:

• Higher accuracy for known vehicles
• Works even with partial views or unusual angles
• Handles multiple reference images per vehicle
• Quality-based auto-replacement of KB entries

Requirements:

• NVIDIA GPU recommended (CUDA support)
• ~2-4GB VRAM for SAM3 operations
• CPU fallback available (slower)

2. Knowledge Base System

The Knowledge Base (KB) is a database of vehicle information used for validation and matching.

What it contains:

• Vehicle Entries: Make, model, distinguishing features
• Reference Images: Multiple images per vehicle (side/front/rear/top views)
• Geometric Thumbprints: SAM3-extracted geometric signatures
• Component Crops: Segmented component images (wheels, vents, logos, etc.)
• Distinguishing Features: AI-extracted unique characteristics

KB Manager:

• View Entries: Browse all KB entries with images
• Add Entries: Add new vehicles with reference images
• Edit Entries: Update existing entries
• Delete Entries: Remove incorrect or outdated entries
• Import/Export: Share KB data with others

How to use KB Manager:

1. Click "KB Manager" button or Tools → Knowledge Base Manager
2. Browse existing entries or add new ones
3. For new entries:
   • Click "Add Entry"
   • Enter make and model
   • Add reference images (multiple views recommended)
   • Click "Extract Features" to generate thumbprints
   • Save the entry

3. Advanced Validation

Pro version includes additional validation features:

• KB-Based Validation: Cross-reference AI results with KB entries
• Thumbprint Verification: Verify identification using geometric matching
• Confidence Scoring: Higher confidence when KB match found
• Quality Metrics: Assess thumbprint quality before KB storage

Workflows & Use Cases

Workflow 1: Single Race Event

Scenario: You photographed a single race event and have a timing sheet PDF.

Steps:

1. Import Timing Sheet:
   • File → Import Timing Sheet
   • Select your PDF file
   • Verify parsed data in the timing sheet panel
2. Process Images:
   • Load folder containing race photos
   • Configure batch settings (Skip Existing recommended)
   • Click "Process Batch"
3. Review Results:
   • Check results list for any errors
   • Review a few sample images to verify accuracy
   • Make manual corrections if needed
4. Write Metadata:
   • Select all processed images
   • Click "Write Metadata"
   • Verify metadata in your photo management software

Workflow 2: Multi-Session Event

Scenario: Multiple practice sessions, qualifying, and race sessions.

Steps:

1. Import Timing Sheet (contains all sessions)
2. Process with Session Filtering:
   • Select session from dropdown (if available)
   • Process images for that session
   • Repeat for each session
3. Alternative: Process all images, then filter by session in results

Workflow 3: Building Knowledge Base (Pro Only)

Scenario: You want to build a KB for a specific championship or series.

Steps:

1. Collect Reference Images:
   • Gather 2-4 images per vehicle (side/front/rear views)
   • Ensure high quality and clear visibility
2. Add KB Entries:
   • Open KB Manager
   • For each vehicle:
     • Click "Add Entry"
     • Enter make and model
     • Add reference images
     • Click "Extract Features"
     • Save entry
3. Verify Entries:
   • Process test images
   • Check if KB matching works correctly
   • Adjust entries if needed
4. Export KB (optional):
   • Export KB for sharing or backup
   • Keep exported file safe

Workflow 4: Quick Tagging (LITE)

Scenario: You need quick tagging without advanced features.

Steps:

1. Load Images: Single image or folder
2. Process: Click "Process Image" or "Process Batch"
3. Review: Quick review of results
4. Write: Write metadata and move on

Workflow 5: Professional Archive (Pro)

Scenario: Building a comprehensive archive with maximum accuracy.

Steps:

1. Build KB: Add all vehicles to Knowledge Base
2. Import Timing Sheets: For all events
3. Process with Validation:
   • Enable KB validation
   • Review KB matches
   • Verify accuracy
4. Quality Control:
   • Spot-check results
   • Update KB with corrections
   • Re-process if needed
5. Export Metadata:
   • Write all metadata
   • Verify in photo management software
   • Archive with complete metadata

Advanced Features

Model Selection

TagOmatic supports multiple Ollama models. Switch models in settings:

1. Tools → Settings → AI Model
2. Select model from dropdown
3. Available models depend on what you've installed in Ollama

Recommended model:

• qwen2.5vl:7b: Tested and recommended model for TagOmatic (~4GB)

Custom Metadata Fields

Add custom tags and fields to metadata:

1. Edit → Preferences → Metadata
2. Configure custom fields
3. Fields will be included in EXIF/IPTC output

Backup Settings

Configure automatic backups:

1. Edit → Preferences → Backup
2. Enable "Backup before writing metadata"
3. Set backup location
4. Backups are created automatically before metadata writes

Logging & Debugging

Enable detailed logging for troubleshooting:

1. Tools → Settings → Logging
2. Enable "Verbose logging"
3. Log file location: %AppData%\TagOmatic\logs\

Log file contains:

• Processing details
• Error messages
• AI inference results
• Performance metrics

Performance Optimization

For faster processing:

• Use GPU-accelerated Ollama (if available)
• Process in smaller batches
• Use "Race Number Only" mode when appropriate
• Close other applications to free RAM

For Pro users:

• Ensure CUDA is available for SAM3
• Monitor VRAM usage
• Adjust batch size based on available memory

Troubleshooting

Common Issues

1. "Ollama not detected"

Symptoms: Application cannot connect to Ollama.

Solutions:

• Ensure Ollama is installed and running
• Check system tray for Ollama icon
• Run ollama serve in Command Prompt
• Verify Ollama is accessible: ollama list
• Check firewall settings (Ollama uses port 11434)

2. "Model not found"

Symptoms: Error when processing images.

Solutions:

• Verify model is installed: ollama list
• Install model: ollama pull qwen2.5vl:7b
• Check model name in settings matches installed model

3. Slow Processing

Symptoms: Images take a long time to process.

Solutions:

• Use GPU-accelerated Ollama (if available)
• Reduce batch size
• Close other applications
• Check CPU/RAM usage
• Ensure you're using the recommended qwen2.5vl:7b model

4. Incorrect Identifications

Symptoms: AI identifies vehicles incorrectly.

Solutions:

• Ensure image quality is good (clear, well-lit)
• Try different angles/views
• For Pro: Add vehicle to Knowledge Base
• For Pro: Use KB matching for known vehicles
• Manual correction available in results panel

5. Race Numbers Not Detected

Symptoms: Race numbers not extracted from images.

Solutions:

• Ensure numbers are clearly visible
• Check image resolution (higher is better)
• Verify contrast (numbers should stand out)
• Manual entry available in results panel
• Try different images of the same vehicle

6. PDF Import Fails

Symptoms: Timing sheet PDF cannot be imported.

Solutions:

• Verify PDF is text-based (not scanned image)
• Check PDF format (TSL or SMART supported)
• Try opening PDF in text editor to verify text content
• Contact support with sample PDF if issue persists

7. Metadata Not Written

Symptoms: Metadata not appearing in image files.

Solutions:

• Check file permissions (ensure write access)
• Verify file format is supported
• Check backup location (if enabled)
• Review log file for errors
• Try writing to a different location first

8. SAM3 Errors (Pro Only)

Symptoms: SAM3 segmentation fails or crashes.

Solutions:

• Verify CUDA is available: Check GPU drivers
• Reduce batch size to lower VRAM usage
• Use CPU fallback (slower but more stable)
• Check PyTorch installation
• Update GPU drivers

Getting Help

Support Resources:

• Website: www.tagomatic.co.uk
• Documentation: This manual
• Log Files: Check %AppData%\TagOmatic\logs\ for detailed error information

When reporting issues, include:

• TagOmatic version (LITE or Pro)
• Windows version
• Error messages (from log file)
• Steps to reproduce
• Sample images (if applicable)

System Requirements

Minimum Requirements

• OS: Windows 10 (64-bit) or Windows 11
• RAM: 8GB (16GB recommended)
• Storage: 500MB for application + ~4GB for Ollama model
• CPU: Modern multi-core processor
• Internet: Required for initial Ollama model download

Recommended Requirements

• OS: Windows 11 (64-bit)
• RAM: 16GB or more
• Storage: SSD recommended for faster processing
• CPU: Modern 6+ core processor
• GPU: NVIDIA GPU with CUDA support (for Pro version)
• VRAM: 4GB+ for SAM3 operations (Pro only)

Ollama Requirements

• Ollama: Latest version from ollama.ai
• Model: qwen2.5vl:7b (tested and recommended)
• Storage: ~4GB for model files
• RAM: 8GB+ recommended for 7b model

Pro Version Additional Requirements

• GPU: NVIDIA GPU with CUDA 11.8+ support
• VRAM: 4GB+ for SAM3 operations
• PyTorch: Included in Pro installation
• Storage: Additional ~800MB for PyTorch dependencies

Appendix

Keyboard Shortcuts

File Locations

Application Data:

• %AppData%\TagOmatic\ - User data, logs, KB
• %AppData%\TagOmatic\logs\ - Log files
• %AppData%\TagOmatic\kb\ - Knowledge Base (Pro)
• %AppData%\TagOmatic\backups\ - Metadata backups

Installation:

• LITE: C:\Program Files\Pistonspy\Tagomatic-LITE\
• Pro: Steam installation directory

Supported Image Formats

• JPEG (.jpg, .jpeg)
• TIFF (.tif, .tiff)
• PNG (.png)
• RAW: Canon CR2, Nikon NEF, Sony ARW, Fuji RAF, etc.
• HEIC (.heic)
• WebP (.webp)

Supported PDF Formats

• TSL Timing (Format B)
• SMART Timing (Format A)
• Auto-detection of format

Metadata Standards

EXIF Fields:

• UserComment (JSON format)
• Artist
• Copyright
• Software

IPTC Fields:

• Keywords
• Caption/Description
• Headline
• Copyright Notice

Version History

v5.0 (Current)

• SAM3 geometric matching (Pro)
• Knowledge Base system (Pro)
• Improved PDF parsing
• Enhanced race number detection
• Better error handling
• Performance optimizations

v4.0

• Initial release
• Basic AI identification
• PDF timing integration
• EXIF/IPTC tagging

Conclusion

TagOmatic provides powerful, privacy-first photo tagging for motorsport photographers. Whether you choose LITE for quick workflows or Pro for maximum accuracy, TagOmatic helps you efficiently tag and organize your race photography.

For LITE users: Enjoy free, lightweight tagging with all essential features.

For Pro users: Leverage SAM3 and Knowledge Base for professional-grade accuracy and validation.

Questions or feedback? Visit www.tagomatic.co.uk for support and updates.