traccar_animation/py_scripts/3D_VIDEO_DOCUMENTATION.md

3D Video Animation Feature

Overview

The 3D Video Animation feature generates Relive-style video animations from GPS route data. This creates engaging, cinematic videos that visualize your journey in a 3D perspective.

Features

Visual Elements

• 3D Isometric View: Perspective projection that simulates 3D depth
• Sky Gradient Background: Blue gradient background that mimics sky
• Animated Route Trail: Color-coded path from blue (start) to red (end)
• Pulsing Position Marker: Animated current position indicator
• Grid Overlay: 3D grid effect for depth perception
• Real-time Data Display: Speed, timestamp, and progress information

Technical Specifications

• Resolution: 1920x1080 (Full HD)
• Frame Rate: 30 FPS
• Format: MP4 video
• Compression: MP4V codec for broad compatibility

Animation Effects

• Shadow Effects: Route lines and markers have 3D shadows
• Elevation Simulation: Simulated terrain elevation using sine waves
• Smooth Transitions: Interpolated movement between GPS points
• Progress Indicators: Visual progress through the route

Required Libraries

Core Dependencies

• OpenCV (cv2): Video generation and frame composition
• NumPy: Mathematical operations and array handling
• PIL/Pillow: Image processing and text rendering
• Requests: API calls for elevation data (future enhancement)

Optional Enhancements

• MoviePy: Advanced video editing and effects
• Matplotlib: Additional visualization options
• SciPy: Mathematical transformations

Usage

1. Navigate to the Create Animation screen
2. Select a project with GPS route data
3. Click "Generate 3D Video" button
4. Wait for processing (can take several minutes)
5. View the generated video in the project folder

Processing Steps

1. Data Loading (10%)

• Loads GPS positions from positions.json
• Validates minimum route length (10+ points)
• Calculates route boundaries and center point

2. Route Analysis (20%)

• Determines optimal viewport and scaling
• Calculates center coordinates for camera position
• Sets up coordinate transformation matrices

3. Frame Generation (30-70%)

• Creates individual frames for each GPS point
• Applies 3D perspective transformation
• Renders route trail with color progression
• Adds animated markers and text overlays

4. Video Compilation (75-90%)

• Combines frames into MP4 video
• Applies compression and optimization
• Adds metadata and timing information

5. Finalization (90-100%)

• Saves video to project folder
• Cleans up temporary files
• Shows completion notification

File Output

Naming Convention

{project_name}_3d_animation_{timestamp}.mp4

Example

MyTrip_3d_animation_20250702_143522.mp4

Location

Videos are saved in the project folder:

resources/projects/{project_name}/

Customization Options

Future Enhancements

• Real Elevation Data: Integration with elevation APIs
• Custom Colors: User-selectable color schemes
• Speed Control: Variable playback speeds
• Camera Angles: Multiple perspective options
• Terrain Textures: Realistic ground textures
• Weather Effects: Animated weather overlays

Performance Optimization

• Multi-threading: Parallel frame generation
• GPU Acceleration: OpenGL rendering support
• Compression Options: Quality vs. file size settings
• Preview Mode: Lower quality for faster processing

Error Handling

Common Issues

• Insufficient GPS Data: Minimum 10 points required
• Memory Limitations: Large routes may require optimization
• Storage Space: Videos can be 50-200MB depending on route length
• Processing Time: Can take 5-15 minutes for long routes

Troubleshooting

• Reduce Route Size: Use route optimization before generation
• Free Disk Space: Ensure adequate storage available
• Close Other Apps: Free memory for processing
• Check File Permissions: Ensure write access to project folder

Technical Architecture

Frame Generation Pipeline

GPS Point → Coordinate Transform → 3D Projection → 
Visual Effects → Text Overlay → Frame Export

Video Assembly Pipeline

Frame Sequence → Video Encoder → Compression → 
Metadata Addition → File Output

Memory Management

• Temporary Files: Frames stored in temp directory
• Batch Processing: Processes frames in chunks
• Automatic Cleanup: Removes temporary files after completion

Integration

UI Integration

• Progress Bar: Real-time processing updates
• Status Messages: Step-by-step progress information
• Error Dialogs: User-friendly error messages
• Result Notification: Success/failure feedback

File System Integration

• Project Structure: Maintains existing folder organization
• Automatic Naming: Prevents file name conflicts
• Folder Opening: Direct access to output location

This feature transforms GPS tracking data into professional-quality video animations suitable for sharing, presentations, or personal memories.