{"id":39425832,"url":"https://github.com/tok/depth-surge-3d","last_synced_at":"2026-01-18T04:00:09.105Z","repository":{"id":333000031,"uuid":"1076473055","full_name":"Tok/depth-surge-3d","owner":"Tok","description":"Convert 2D videos to 3D VR format using AI depth estimation.","archived":false,"fork":false,"pushed_at":"2026-01-17T02:12:33.000Z","size":449,"stargazers_count":6,"open_issues_count":1,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T07:17:44.587Z","etag":null,"topics":["3d-video-conversion","monocular-depth-estimation","virtual-reality"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T23:08:10.000Z","updated_at":"2026-01-16T23:41:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Tok/depth-surge-3d","commit_stats":null,"previous_names":["tok/depth-surge-3d"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Tok/depth-surge-3d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tok%2Fdepth-surge-3d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tok%2Fdepth-surge-3d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tok%2Fdepth-surge-3d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tok%2Fdepth-surge-3d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tok","download_url":"https://codeload.github.com/Tok/depth-surge-3d/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tok%2Fdepth-surge-3d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28529455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-video-conversion","monocular-depth-estimation","virtual-reality"],"created_at":"2026-01-18T04:00:08.372Z","updated_at":"2026-01-18T04:00:09.075Z","avatar_url":"https://github.com/Tok.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Depth Surge 3D\n\n[![CI](https://github.com/Tok/depth-surge-3d/actions/workflows/ci.yml/badge.svg)](https://github.com/Tok/depth-surge-3d/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/Tok/depth-surge-3d/branch/main/graph/badge.svg)](https://codecov.io/gh/Tok/depth-surge-3d)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Convert 2D videos to 3D VR format using AI depth estimation.**\n\nDepth Surge 3D transforms flat videos into stereoscopic 3D for VR headsets using **Depth Anything V3** and **Video-Depth-Anything V2** neural networks. It analyzes video frames with temporal consistency to predict depth, then generates left and right eye views for immersive stereoscopic viewing.\n\n## Key Features\n\n- **Dual Depth Models**:\n  - **Depth Anything V3** (default): 50% lower VRAM, faster processing, optimized for modern GPUs\n  - **Video-Depth-Anything V2**: Superior temporal consistency with 32-frame sliding windows\n- **CUDA Hardware Acceleration**: NVENC H.265 encoding and GPU-accelerated frame decoding\n- **Configurable Depth Quality**: Adjustable depth map resolution (518px to 4K) for quality vs. speed\n- **Multiple VR Formats**: Side-by-side and over-under stereoscopic formats\n- **Flexible Resolutions**: Square (VR-optimized), 16:9 (standard), cinema, and custom resolutions up to 8K\n- **Resume Capability**: Intelligent step-level resume for interrupted processing\n- **Audio Preservation**: Maintains original audio synchronization with lossless FLAC extraction\n- **Web Interface**: Modern browser-based UI with real-time progress tracking and live previews\n- **Wide Format Support**: Cinema, ultra-wide, and standard aspect ratios\n\n## Quick Start\n\n### Installation\n\n```bash\ngit clone https://github.com/Tok/depth-surge-3d.git depth-surge-3d\ncd depth-surge-3d\nchmod +x setup.sh\n./setup.sh\n```\n\nThe setup script automatically installs all dependencies, downloads the Video-Depth-Anything model (~1.3GB), and verifies your system.\n\n**See [Installation Guide](docs/INSTALLATION.md) for detailed setup instructions.**\n\n### Usage\n\n**Web UI (Recommended):**\n```bash\n./run_ui.sh\n# Opens http://localhost:5000 in your browser\n```\n\n**Command Line:**\n```bash\n# Basic usage\npython depth_surge_3d.py input_video.mp4\n\n# Process specific time range with custom settings\npython depth_surge_3d.py input_video.mp4 -s 01:30 -e 03:45 -f over_under --resolution 4k\n```\n\n**Quick Start Script:**\n```bash\n# Process a clip with optimized settings\n./start.sh 1:11 2:22\n```\n\n**See [Usage Guide](docs/USAGE.md) for comprehensive usage examples.**\n\n## Requirements\n\n- Python 3.9+\n- FFmpeg\n- CUDA 13.0+ (required for GPU acceleration)\n- CUDA-compatible GPU (optional but strongly recommended)\n\n## Documentation\n\n**User Guides:**\n- **[Installation Guide](docs/INSTALLATION.md)** - Detailed setup instructions and troubleshooting\n- **[Usage Guide](docs/USAGE.md)** - Complete usage examples and workflows\n- **[Parameters Reference](docs/PARAMETERS.md)** - All command-line options and settings explained\n- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and performance tips\n\n**Technical Documentation:**\n- **[Architecture](docs/ARCHITECTURE.md)** - Technical details and processing pipeline\n- **[Contributing Guide](docs/CONTRIBUTING.md)** - Development workflow and CI/CD setup\n- **[Coding Standards](docs/CODING_GUIDE.md)** - Code quality requirements and best practices\n\n**Development:**\n- **[Development Notes](docs/CLAUDE.md)** - Quick reference for development\n- **[Project Roadmap](docs/TODO.md)** - Planned features and improvements\n\n## Output Structure\n\nEach processing session creates a self-contained timestamped directory:\n\n```\noutput/\n└── timestamp_videoname_timestamp/\n    ├── original_video.mp4      # Source video\n    ├── original_audio.flac     # Pre-extracted audio\n    ├── frames/                 # Extracted frames\n    ├── vr_frames/             # Final VR frames\n    └── videoname_3D_side_by_side.mp4  # Final 3D video\n```\n\n## VR Viewing\n\nGenerated videos work with:\n- VR headsets (Meta Quest, HTC Vive, etc.)\n- Cardboard VR viewers\n- 3D video players supporting side-by-side or over-under formats\n\n## Performance\n\n- **GPU Processing**: ~2-4 seconds per output frame (RTX 4070+ class)\n- **CPU Processing**: ~30-60 seconds per output frame\n- **Typical 1-minute clip**: ~2-4 hours on modern GPU at 60fps output\n\n## Attribution\n\nThis project uses state-of-the-art depth estimation models:\n\n- **[Depth Anything V3](https://github.com/ByteDance-Seed/Depth-Anything-3)** - Default model with improved memory efficiency and performance\n- **[Video-Depth-Anything V2](https://github.com/DepthAnything/Video-Depth-Anything)** - Temporal-consistent depth estimation with 32-frame sliding windows\n\nBoth models are based on vision transformer architectures optimized for monocular depth prediction.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n**Third-Party Components**: Please review the [Video-Depth-Anything license](https://github.com/DepthAnything/Video-Depth-Anything) for terms before commercial use.\n\n## Quality Expectations, Parallax-Glitchwave and Z-Collapse Slopcore Aesthetics\n\nThis tool converts monocular video to pseudo-stereo using AI depth estimation. Results can be compelling for many types of content but will never match true stereo cameras or specialized VR equipment.\n\n**Best results with:**\n- Clear depth variation (landscapes, interiors, people)\n- Good lighting and detail\n- Source resolution 1080p or higher\n- Steady camera movement\n\n**May struggle with:**\n- Mirrors, glass, water reflections\n- Very dark or low-contrast scenes\n- Fast motion or rapid camera movements\n\n**Artifact Embracement**: Expect algorithmic stereo divergence, synthetic depth layers, and monocular hallucinations. These AI-generated depth discontinuities create a unique aesthetic - depth-drift, disparity shimmer, and temporal judder may become part of the experience.\n\nSee the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for detailed quality expectations and optimization tips.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftok%2Fdepth-surge-3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftok%2Fdepth-surge-3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftok%2Fdepth-surge-3d/lists"}