deckhearth/DUAL_VIEW_SYSTEM.md

Dual View System & Image Handling

🎨 View Modes

TCG Vault now supports two distinct viewing modes for your card collection:

🃏 Card View

• Image-focused display showing card artwork prominently
• Responsive grid that adapts from 1 column (mobile) to 5 columns (ultra-wide)
• Large card images with automatic fallbacks to game-themed placeholders
• Clean, minimal information focusing on visual identification

📊 Table View

• Data-focused tabular display for detailed card information
• Small thumbnail images alongside comprehensive card data
• Sortable columns for quick data analysis
• Compact format ideal for managing large collections

🖼️ Dual Image System

Stock Images (Official Reference)

• Purpose: Clean, official card images for consistent presentation
• Usage: Primary display in both view modes
• Features:
  • High-quality scans from official sources
  • Artwork cropping coordinates for thumbnails
  • Consistent lighting and framing

User Card Photos

• Purpose: Photos of your actual physical cards
• Usage: Quality assessment and condition documentation
• Features:
  • Multiple photos per card copy
  • Condition-specific documentation
  • Quality comparison with stock images

🔄 Image Display Features

Smart Fallbacks

When card images aren't available, the system displays:

• Game-themed gradients (Orange for MTG, Yellow for Pokemon, Purple for Lorcana)
• Card name abbreviated for readability
• Game identifier for quick recognition
• Consistent sizing maintaining layout integrity

Interactive Controls

• 📸/📋 Toggle: Switch between stock and user photos
• ◄/► Navigation: Browse multiple user photos
• 👤/✓ Indicators: Visual cues for image type
• Photo counters: Show current photo index (e.g., "2/3")

📁 Image Storage Structure

frontend/public/images/cards/
├── mtg/                    # Magic: The Gathering
│   ├── lightning-bolt-alpha.jpg
│   └── black-lotus-alpha.jpg
├── pokemon/                # Pokémon
│   └── pikachu-base-set.jpg
└── lorcana/               # Disney Lorcana
    ├── mickey-brave-tailor-tfc.jpg
    ├── elsa-snow-queen-tfc.jpg
    ├── be-prepared-tfc.jpg
    └── mickey-steamboat-pilot-tfc.jpg

🛠️ Database Schema

Cards Table (New Fields)

• stock_image_url: Official card image path
• artwork_crop_coords: JSON with cropping coordinates {x, y, width, height}
• image_url: Legacy field for backward compatibility

Collection Cards Table (New Fields)

• user_images: JSON array of user photo paths
• condition_notes: Detailed condition descriptions

🎯 Usage Examples

Card Identification

• Card View: Visual browsing and identification
• Stock Images: Official reference for card verification
• Game badges: Quick game identification

Collection Management

• Table View: Data analysis and bulk operations
• User Photos: Document card conditions and variations
• Pricing: Track market values alongside visual condition

Quality Assessment

• Side-by-side comparison: Stock image vs. your card photos
• Multiple angles: Document different aspects of card condition
• Condition notes: Detailed written condition descriptions

🚀 Future Enhancements

Image Processing

• Automatic cropping: Extract artwork from card images
• Quality scoring: AI-based condition assessment
• OCR integration: Extract text from user photos

Advanced Views

• Gallery mode: Large image browsing
• Comparison mode: Side-by-side stock vs. user photos
• 3D card view: Interactive card rotation

Collection Features

• Image upload: Drag-and-drop card photo upload
• Batch processing: Upload multiple card photos at once
• Cloud storage: Backup and sync card photos across devices

This dual-view system provides the foundation for professional-grade collection management while maintaining ease of use for casual collectors.