
# MonoPop3D — Single-Image 3D Pop-Up / Parallax Generator

Turn a single RGB image into a dynamic **3D parallax animation** with:

- **Interactive foreground segmentation** using SAM  
- **Edge-aware alpha matting**  
- **MiDaS depth estimation**  
- **Background inpainting** (LaMa or Telea fallback)  
- **Optional relighting & bokeh effects**  
- **Depth-based parallax animation**  
- **Auto-generated 6-panel debug visualization**  

This project is designed for CSC2529 *Computational Imaging* and shows a complete, modular, and extensible pipeline.

---

## 📁 Project Structure

```
project-root/
  config/
    settings.py
  src/
    main.py
    utils/
      image_ops.py
    processing/
      matting.py
      lighting.py
      bokeh.py
      visualization.py
    models/
      segmentation_sam.py
      depth_midas.py
      inpaint_lama.py
    animation/
      parallax.py
  data/
    image3.jpg
  environment.yml
  README.md
```

---

## 🚀 Installation

### 1. Create the Conda environment

```bash
conda env create -f environment.yml
conda activate monopop3d
```

### 2. (Optional) Install LaMa inpainting support

```bash
pip install simple-lama-inpainting
```

> If LaMa is not installed, the pipeline automatically falls back to OpenCV Telea inpainting.

---

## ▶️ Run the Pipeline

From the **project root**, run:

```bash
python -m src.main --image ./data/image3.jpg --output final_video.mp4
```

Output files:
- **`final_video.mp4`** — the final animated parallax video  
- **`debug_pipeline.png`** — 6-panel visualization of all intermediate results  

---

## 🧠 How the Pipeline Works

### **1. Interactive Segmentation (SAM)**
You click on the object to include. Each click expands the mask.  
Press:
- **ENTER/SPACE** to finish  
- **Z** to undo  
- **Q** to quit  

Disable UI (e.g., for remote servers):

```python
ENABLE_INTERACTIVE = False
```
in `config/settings.py`.

---

### **2. Alpha Matting**
Binary mask → trimap → guided filtering to produce smooth object edges.

---

### **3. Depth Estimation (MiDaS_small)**
MiDaS produces a relative depth map aligned to the texture resolution.

---

### **4. Optional Relighting & Bokeh**
- Normal-based shading for subtle volume cues  
- Gaussian DOF blur for background defocus  

Both are controlled in `config/settings.py`.

---

### **5. Background Inpainting**
Foreground is removed and the background is filled using:
- **LaMa inpainting** (if installed), or  
- **Telea (OpenCV)** fallback

---

### **6. Parallax Animation**
Foreground is warped per-depth using smooth sinusoidal displacement, and blended with the background across frames. Generates a 30 FPS MP4 video.

---

### **7. Debug Visualization**
A 6-panel composite is saved showing:
1. Original image  
2. Raw segmentation  
3. Stitched (merged) mask  
4. Alpha matte  
5. Inpainted background  
6. Video filmstrip preview  

---

## ⚙️ Configuration

Modify parameters inside `config/settings.py`:

```python
INFERENCE_DIM = 1024
TEXTURE_DIM = 1280

ANIMATION_FRAMES = 90
ANIMATION_SHIFT = 30

SHARPEN_STRENGTH = 1.5
MASK_MERGE_KERNEL_SIZE = 7

VOLUME_STRENGTH = 0.4
LIGHTING_STRENGTH = 0.3
BOKEH_STRENGTH = 5

ENABLE_INTERACTIVE = True

DEFAULT_IMAGE = "./data/image3.jpg"
DEFAULT_VIDEO = "final_video.mp4"
```

---