component-system/APRILTAG_MIGRATION.md

AprilTag Migration Summary

Completed Changes

1. Database Migration ✅

• Migrated from qr_code string field to apriltag_id integer field
• Added constraint to ensure valid AprilTag IDs (0-586)
• Created unique index for apriltag_id
• Preserved old qr_code data as qr_code_old for rollback safety

2. Schema Updates ✅

• Updated StorageLocation schema to use apriltag_id instead of qr_code
• Added validation for AprilTag ID range (0-586)
• Implemented auto-assignment of next available ID
• Added unique constraint validation

3. Business Logic Refactoring ✅

• Replaced ComponentsElixir.QRCode module with ComponentsElixir.AprilTag module
• Updated inventory functions to use AprilTag IDs instead of QR code strings
• Implemented AprilTag ID availability checking
• Added bulk SVG generation functionality

4. UI/UX Improvements ✅

• Replaced dropdown with 587 options with better UX:
  • Radio buttons for "Auto-assign" vs "Manual selection"
  • Number input for specific ID selection when manual mode selected
  • Shows available ID count and examples
  • Different interface for add vs edit forms
• Updated templates to show AprilTag information instead of QR codes
• Added download functionality for AprilTag SVGs

5. AprilTag Generation ✅

• Created ComponentsElixir.AprilTag module for managing tag36h11 family
• Generated all 587 placeholder SVG files with human-readable IDs
• Added Mix task mix apriltag.generate_all for batch generation
• SVG files served statically at /apriltags/tag36h11_id_XXX.svg

6. Event Handling ✅

• Updated LiveView event handlers for AprilTag scanning/assignment
• Added mode switching for manual vs automatic assignment
• Implemented proper form state management for different modes

Benefits Achieved

1. Better UX: No more 587-option dropdown menu
2. Future-Ready: AprilTags designed for multi-tag detection scenarios
3. Robust: 587 unique IDs provide ample space without conflicts
4. Maintainable: Simpler integer ID system vs complex string encoding
5. Industry Standard: AprilTags widely used in robotics/AR applications

Current State

• ✅ Database schema updated
• ✅ All 587 placeholder SVG files generated
• ✅ UI forms updated with better UX
• ✅ Business logic migrated to AprilTag system
• ⏳ Next: Real AprilTag pattern generation (future enhancement)
• ⏳ Next: Camera detection integration (future enhancement)

Usage

Generate AprilTag SVGs

mix apriltag.generate_all           # Generate missing files
mix apriltag.generate_all --force   # Regenerate all files

Available AprilTag IDs

• Range: 0-586 (tag36h11 family)
• Auto-assignment picks next available ID
• Manual assignment allows specific ID selection
• Unique constraint prevents conflicts

File Locations

• SVG files: priv/static/apriltags/tag36h11_id_XXX.svg
• URL pattern: /apriltags/tag36h11_id_XXX.svg
• Placeholder pattern includes human-readable ID label

The system is now ready for use with AprilTags instead of QR codes! The placeholder SVGs will work perfectly for testing and development until we implement actual AprilTag pattern generation.