2D to 3D Studio - Offline Stereoscopic & Spatial Engine

A standalone, high-performance, 100% offline 2D-to-3D image and video converter. Transforms conventional 2D photos and videos into stereoscopic 3D (Half-SBS, Full-SBS, Dubois Anaglyph) and Apple Spatial Video (MV-HEVC / Spatial Photos) with zero cloud dependency, no subscriptions, and complete privacy.

Features native hardware acceleration across platforms:

• Apple Silicon (M1/M2/M3/M4/M5): Accelerated with Metal Performance Shaders (MPS) and VideoToolbox hardware HEVC encoding.
• NVIDIA GeForce / RTX / Quadro: Accelerated with CUDA inference and NVENC hardware video encoding.
• AMD Radeon: ROCm support on Linux and AMF hardware encoding on Windows.
• Intel Arc / Iris Xe: QuickSync (QSV) hardware encoding.
• CPU Multithreading: High-accuracy fallback for systems without a dedicated GPU.

---

Key Features

• 100% Offline & Private: Zero telemetry, no cloud APIs, no tokens, and no data leaves your machine.
• State-of-the-Art Depth AI: Pure PyTorch implementation of DINOv2 ViT-Small + DPT Depth Anything running directly on your GPU.
• Anti-Ghosting Stereo Synthesis (right_only mode): Keeps the original left eye 100% untouched and unwarped. Completely eliminates the line deformation, blurriness, and double-vision ghosting typical of naive DIBR converters.
• Stereo artifact repair: Existing one-sided conversions can be scanned and selectively regenerated in symmetric both mode. The repair reuses healthy frames and the existing audio, and runs depth inference only for frames carrying the one-sided signature.
• Bilateral Edge Snapping: Sharpens depth boundaries along high-contrast lines and subtitle edges to prevent warped text.
• Temporal Coherence Filter: Eliminates inter-frame depth flickering in video while adapting to fast-moving scene cuts.
• Dynamic Black Bar Protection: Detects letterbox or pillarbox bars per frame, neutralizes them only for depth inference, and preserves the full canvas through IMAX aspect-ratio changes.
• Fast Depth Re-Export: Save depth maps (_depth.mp4 / _depth.png) for manual grading in Photoshop, DaVinci Resolve, or After Effects, then re-render stereo in seconds without re-running AI inference.
• Multi-Format 3D Output:
  • Half-SBS (Side-by-Side): Ready for 3D TVs (LG Cinema 3D, Samsung 3D, Sony) and Jellyfin / Plex / Roku streaming.
  • Full-SBS: Full resolution for VR headsets (Meta Quest 2/3/Pro, Pico).
  • Dubois Anaglyph (Red/Cyan): Color-accurate Dubois algorithm viewable on any monitor with standard 3D glasses.
  • Apple Spatial Video (MV-HEVC): Multi-View HEVC for Apple Vision Pro and Meta Quest 3 via native spatial packaging.
  • Apple Spatial Photo (HEIC): Native spatial photo format for visionOS and iOS.
• Multi-Language Support (i18n): Default language is English (en), secondary is Spanish (es). Community translation files can be dropped into locales/ and are automatically discovered by both the Web GUI and CLI.

---

Hardware Autodetection & Diagnostics

The converter includes a cross-platform diagnostic engine that inspects your GPU, PyTorch acceleration stack, and multimedia binaries on startup.

Run System Diagnostics via CLI:

# Default English diagnostics
python convert_3d.py --check-system

# Spanish diagnostics
python convert_3d.py --check-system --lang es

Example Output:

========================================================================
        2D TO 3D STUDIO - SYSTEM DIAGNOSTICS REPORT
========================================================================
Operating System:   Darwin 23.6.0 (arm64)
AI Accelerator (GPU): Apple Silicon (arm) [Metal MPS] [MPS]
Video Encoder:   Apple VideoToolbox (Hardware Acceleration) (hevc_videotoolbox)
FFmpeg Installed:    ✓ Yes
Spatial CLI:         ✓ Yes
Overall Status:      OK
------------------------------------------------------------------------
✓ Excellent! All components and drivers are configured and optimized.

If drivers, CUDA packages, or FFmpeg are missing, the system will output actionable alerts with:

1. Urgency status (CRITICAL, RECOMMENDED, or OPTIONAL).
2. Exact copy-paste terminal command (e.g. winget install Gyan.FFmpeg on Windows, sudo apt install ffmpeg on Linux, pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 for NVIDIA CUDA).
3. Official direct download URLs.
4. Clear step-by-step instructions.

---

Web Graphical User Interface (GUI)

The project includes a web studio interface with real-time SSE progress streaming, FPS telemetry, ETA calculation, optical sliders, preset selectors, and an interactive Hardware Diagnostics Modal.

Launching the GUI (Windows, Linux, macOS):

🪟 Windows (10 / 11)

• Method 1 (One-Click Launcher):
  • Simply double-click start_windows.bat in the project folder.
• Method 2 (Command Prompt / PowerShell):

  cd path\to\2D-to-3D
  .venv\Scripts\activate
  python gui.py
  

🐧 Linux (Ubuntu, Debian, Fedora, Arch)

• Method 1 (One-Click / Terminal Launcher):
  • Make sure the script is executable and run it:

    chmod +x start_linux.sh
    ./start_linux.sh
    

• Method 2 (Terminal Step-by-Step):

  cd ~/2D-to-3D
  source .venv/bin/activate
  python3 gui.py
  

🍎 macOS (Apple Silicon M1–M5 & Intel)

• Method 1 (One-Click Launcher):
  • Double-click start_mac.command in the project root or the Desktop shortcut.
• Method 2 (Terminal):

  cd ~/Dev/3D/2D-to-3D
  source .venv/bin/activate
  python3 gui.py
  

The GUI will automatically open in your default web browser at http://127.0.0.1:8765.

Pro depth models

The Depth Model selector includes the built-in model plus ONNX, Transformers, Depth Anything 3, and ZoeDepth models. Models download on first use and are then read from the local Hugging Face or Torch cache.

# ONNX and Hugging Face models
python -m pip install -r requirements-pro.txt

# Additional DA3 models
python -m pip install -r requirements-da3.txt

# Inspect keys or select a model from the CLI
python convert_3d.py --list-depth-models
python convert_3d.py -i movie.mkv --depth-model da-v2-small-onnx

Metric estimators are converted to inverse depth before stereo synthesis so near objects retain the same disparity direction as the built-in model. Prompt Depth Anything uses the built-in estimator as its dense prompt when no LiDAR depth prompt is available.

---

First-Time Installation & Setup (Cross-Platform)

🪟 Windows Setup Guide

1. Install Python:
   • Download and install Python 3.10, 3.11, or 3.12 from python.org.
   • Important: Check the box "Add python.exe to PATH" during installation.
2. Install FFmpeg:
   • Open PowerShell as Administrator and run:

     winget install Gyan.FFmpeg
     

   • Or download builds manually from gyan.dev/ffmpeg/builds and add the bin folder to your System PATH.
3. Setup Virtual Environment & Dependencies:

   cd path\to\2D-to-3D
   python -m venv .venv
   call .venv\Scripts\activate
   
   :: For NVIDIA GPU acceleration (CUDA 12.1):
   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
   
   :: Install remaining dependencies:
   pip install -r requirements.txt
   

4. Launch: Double-click start_windows.bat.

---

🐧 Linux Setup Guide (Ubuntu / Debian / Fedora / Arch)

1. Install System Dependencies & FFmpeg:

   # Ubuntu / Debian / Linux Mint:
   sudo apt update && sudo apt install -y python3 python3-venv python3-pip ffmpeg zenity
   
   # Fedora / RHEL:
   sudo dnf install -y python3 python3-pip ffmpeg zenity
   
   # Arch Linux / Manjaro:
   sudo pacman -S python python-pip ffmpeg zenity
   

2. Setup Virtual Environment & Dependencies:

   cd ~/2D-to-3D
   python3 -m venv .venv
   source .venv/bin/activate
   
   # If you have an NVIDIA GPU (CUDA 12.1):
   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
   
   # If you have an AMD GPU (ROCm 6.0):
   pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.0
   
   # Install all requirements:
   pip install -r requirements.txt
   

3. Launch: Run ./start_linux.sh or python3 gui.py.

---

🍎 macOS Setup Guide

1. Requirements: macOS 13.0+ (Ventura, Sonoma, or Sequoia). Metal acceleration (MPS) is built-in.
2. Setup Virtual Environment & Dependencies:

   cd ~/Dev/3D/2D-to-3D
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

3. Launch: Run ./start_mac.command or python3 gui.py.

---

GUI Highlights:

• Language Switcher (🌐): Seamlessly switch between English, Spanish, or any user-contributed language in the header without reloading.
• Hardware Badge: Click the badge in the upper-right corner to open the System Diagnostics & Drivers modal.
• Real-Time Progress: View frame-by-frame progress, rendering speed, and remaining time.
• One-Click Media Access: Open the output folder or play the converted 3D file directly upon completion.

---

Command Line Interface (CLI)

1. Basic Conversion

cd ~/Dev/3D/2D-to-3D
source .venv/bin/activate

# Convert an image to Half-SBS (3D TV format)
python convert_3d.py -i photo.jpg -f hsbs

# Convert a video to Dubois Anaglyph (Red/Cyan glasses)
python convert_3d.py -i video.mp4 -f anaglyph

# Convert to Apple Vision Pro Spatial Video (MV-HEVC)
python convert_3d.py -i video.mp4 -f spatial

2. Using Conversion Profiles

Profiles automatically configure stereo divergence, convergence plane, and pop-out bias:

# Balanced profile (recommended baseline: comfortable parallax, zero ghosting)
python convert_3d.py -i video.mp4 --profile balanced

# Standard stereoscopic profiles available:
# --profile balanced        : Balanced depth for movies and documentaries (0.025).
# --profile cinematic_depth : Enhanced depth sensation and volume for live-action films (0.030).
# --profile subtle_parallax : Gentle parallax for fast motion, text, and comfort (0.020).
# --profile high_contrast   : Snapped depth edges for anime, animation, and high-contrast lines (0.022).

3. Save Depth Maps & Fast Re-Export

Export grayscale depth maps for inspection or manual retouching in video editing software:

# 1. Generate 3D video and save the depth map (_depth.mp4):
python convert_3d.py -i video.mp4 -f hsbs --save-depth

# 2. Re-export in seconds using an edited or existing depth map (skips AI inference):
python convert_3d.py -i video.mp4 --custom-depth video_depth.mp4 -f hsbs

4. Quick Preview Clipping (-s and -t)

Test depth settings on a short excerpt before processing an entire movie:

# Convert a 10-second test clip starting at second 30:
python convert_3d.py -i movie.mp4 -f hsbs -s 30 -t 10

5. Repairing a One-Sided Conversion

If a movie was converted with right_only or left_only and visible warping is found, the repair scanner can regenerate affected frames with symmetric both-eye rendering. It needs the synchronized original 2D master and the existing SBS conversion:

python -m src.stereo_artifact_repair \
  --source-2d "/path/to/original-2d.mkv" \
  --converted-3d "/path/to/existing-3d-hsbs.mp4" \
  --output "/path/to/existing-3d-hsbs.repaired.mp4" \
  --layout hsbs \
  --repair-ranges auto \
  --depth-intensity 0.030 \
  --convergence 0.45 \
  --temporal-smooth 0.70 \
  --style-3d cinematic

--repair-ranges auto samples the conversion, detects camera cuts, compensates normal stereo disparity, and scores missing edges, invented contours, local blur, and residual deformation. It writes an adjacent *.artifacts.json report listing every detected shot with its exact start, end, peak score, and pristine eye. Only those reported shots run through depth inference and symmetric reconstruction. For a manually identified artifact, pass one or more time ranges in seconds, such as --repair-ranges "812.5-819.2,1450-1455". Healthy frames are reused from the existing conversion; only selected frames run through depth inference again. The repaired video is encoded once and receives the audio from the existing 3D file. The input files are never overwritten.

---

CLI Options Reference

---

Internationalization (i18n) & Contributing Translations

2D to 3D Studio is built from the ground up to be multi-language. All user-facing strings are decoupled into standalone JSON files in the locales/ directory:

locales/
├── en.json   # English (Default)
└── es.json   # Spanish (Secondary)

How to Add a New Language:

You can contribute a new language without touching any Python or frontend code:

1. Copy the English template:

   cp locales/en.json locales/<your_lang_code>.json
   # Example for French:
   cp locales/en.json locales/fr.json
   

2. Edit __meta__ in your new file:

   {
     "__meta__": {
       "code": "fr",
       "name": "Français",
       "native_name": "Français"
     },
     "app": {
       "title": "2D to 3D Studio",
       "subtitle": "MOTEUR STÉRÉOSCOPIQUE ET SPATIAL HORS LIGNE"
     }
   }
   

3. Translate the string values. Missing keys automatically fall back to English (en).

4. Launch the app:

   • The Web GUI will automatically detect your new translation file and add it to the 🌐 Language dropdown selector.
   • The CLI will immediately accept your language via --lang <code_lang> (e.g. python convert_3d.py --check-system --lang fr).

Pull requests adding new language translations are warmly welcome!

---

Automated Verification Suite

To run the end-to-end test suite on synthetic 3D geometry and verify model inference, stereo synthesis, and encoder pipelines:

python tests/test_pipeline.py

Expected output:

ALL TESTS PASSED! OFFLINE 2D-TO-3D PIPELINE IS 100% OPERATIONAL.