158 lines
5.0 KiB
Markdown
158 lines
5.0 KiB
Markdown
# 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.
|