README.md

---
title: DimensioDepth
emoji: 🎨
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: true
license: mit
tags:
  - depth-estimation
  - computer-vision
  - depth-anything-v2
  - 3d-visualization
  - image-processing
---

# 🎨 DimensioDepth - Add Dimension to Everything

Transform 2D images into stunning 3D depth visualizations with state-of-the-art AI depth estimation.

## ✨ Features

### 🎯 Advanced Depth Estimation
- **🚀 REAL AI Models** - Depth-Anything V2 BASE (372MB) from Hugging Face Transformers! 🔥
- **SUPERB Quality** - Best available depth estimation quality, production-ready results
- **Auto-Download** - Models download automatically on first run (~60-90 seconds one-time)
- **Fast Inference** - Professional depth estimation (~800ms on CPU, <200ms on GPU)
- **Multiple Colormaps** - Inferno, Viridis, Plasma, Turbo, Magma, Hot, Ocean, Rainbow
- **Smart Fallback** - Gracefully falls back to Demo Mode if models fail to load
- **No Manual Setup** - Just clone and run, models auto-download from HuggingFace Hub!

### 🎬 Visualization Options
- **Colored Depth Maps** - Beautiful visualization with customizable color schemes
- **Grayscale Depth** - Classic depth representation
- **Side-by-Side Comparison** - Original vs. Depth view
- **3D Parallax Effect** - Create depth displacement visualizations

### 📦 Batch Processing
- Process multiple images at once
- Consistent depth estimation across your dataset
- Perfect for batch workflows

## 🚀 How to Use

### Basic Usage
1. **Upload an Image** - Drag & drop or click to upload
2. **Choose Quality Mode** - Fast for preview, High Quality for final output
3. **Select Colormap** - Pick your favorite depth visualization style
4. **Generate** - Click the button and watch the magic happen! ✨

### Advanced Features
- **Side-by-Side**: Compare original and depth maps
- **3D Parallax**: Create depth displacement effects
- **Batch Processing**: Process multiple images efficiently

## 🛠️ Technical Details

### Architecture
- **Model**: Depth-Anything V2 (ViT-S and ViT-L variants)
- **Inference**: ONNX Runtime with GPU acceleration
- **Backend**: FastAPI + Python
- **Frontend**: Gradio
- **3D Rendering**: Custom GLSL shaders (original web app)

### Performance
| Mode | Model | Speed (CPU) | Quality |
|------|-------|-------------|---------|
| Real AI | BASE (372MB) | ~800ms | SUPERB ⭐ |
| Demo Mode | Synthetic | <50ms | Decent |

**Note**: This Space uses the BASE model for best quality. GPU inference is ~200ms.

### Demo Mode
Don't have models downloaded? No problem! DimensioDepth includes a **Demo Mode** that uses:
- Edge detection
- Intensity analysis
- Gaussian smoothing
- Depth synthesis algorithms

This creates surprisingly good depth maps without any AI models!

## 📊 Use Cases

### 🎨 Creative & Artistic
- Create depth-enhanced photos
- Generate 3D parallax effects
- Artistic depth visualization

### 🎬 VFX & Film Production
- Depth map generation for compositing
- 3D reconstruction preparation
- Scene depth analysis

### 🔬 Research & Development
- Computer vision research
- Depth perception studies
- Dataset augmentation

### 📱 Social Media & Content Creation
- Create engaging 3D effects
- Enhance photos with depth
- Generate unique visual content

## 🎓 About Depth-Anything V2

Depth-Anything V2 is a state-of-the-art monocular depth estimation model that:
- Works on any image (indoor/outdoor, any domain)
- Produces high-quality depth maps
- Runs efficiently on consumer hardware
- Supports both fast and accurate modes

[Read the Paper](https://arxiv.org/abs/2406.09414)

## 🌟 Examples

Try these types of images:
- **Portraits** - See facial depth structure
- **Landscapes** - Visualize scene depth layers
- **Architecture** - Analyze building geometry
- **Street Scenes** - Understand urban depth
- **Nature** - Explore organic depth patterns

## 💡 Tips for Best Results

1. **Image Quality**: Higher resolution = better depth detail
2. **Lighting**: Well-lit images produce clearer depth maps
3. **Contrast**: Images with good contrast show better depth separation
4. **Colormap**: Inferno is great for general use, Viridis for scientific visualization
5. **Mode Selection**: Use Fast for experimentation, High Quality for final output

## 🔧 Running Locally

Want to run DimensioDepth on your own machine?

```bash
# Clone the repository
git clone https://github.com/chromahubz/dimensiodepth.git
cd dimensiodepth

# Install dependencies
pip install -r requirements.txt

# Run the Gradio app
python app.py
```

For the full web experience with Three.js 3D viewer:
```bash
# Backend
cd backend
pip install -r requirements.txt
python -m uvicorn api.main:app --reload

# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```

## 🎯 Roadmap

- [ ] Video depth estimation
- [ ] Point cloud export
- [ ] 3D mesh reconstruction
- [ ] Real-time webcam depth
- [ ] Depth-guided editing tools
- [ ] Multi-frame temporal consistency

## 📄 License

MIT License - Feel free to use in your projects!

## 🙏 Acknowledgments

- **Depth-Anything V2** - For the amazing depth estimation model
- **Hugging Face** - For the incredible Spaces platform
- **Gradio** - For making ML demos beautiful and easy

## 📞 Contact & Links

- **GitHub**: [DimensioDepth Repository](https://github.com/chromahubz/dimensiodepth)
- **Original Web App**: Full-featured web application with 3D viewer and video export
- **Issues**: Report bugs on GitHub Issues

---

**Made with ❤️ for the AI community**

*Transform your 2D world into 3D magic! 🎨✨*