updated app

py_scripts/3D_VIDEO_DOCUMENTATION.md

@@ -0,0 +1,157 @@
+# 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.