README.md

---
title: Image To Relief
emoji: 📉
colorFrom: green
colorTo: green
sdk: docker
pinned: false
license: mit
short_description: Generate a 3D relief STL from an image
---

# Image to 3D Relief

Generate an STL relief from an image using Depth Anything V2, then tune the interpreted 2D depth map before export.

## Workflow

1. Upload an image and click **Estimate Depth Map**.
2. Use the **Depth histogram + curves editor** to remap the model's estimated depth values:
   - drag points to reshape the curve,
   - click to add a point,
   - double-click or select + Delete to remove a non-endpoint,
   - use presets for midtone contrast, foreground emphasis, and background compression.
3. Adjust **Luminance Texture Strength** and **Luminance Texture Smoothing** while watching the previewed height map update.
4. Review the **Previewed height map used for STL** preview.
5. Tune STL dimensions/output parameters and click **Generate STL from Adjusted Depth**.


Note: luminance texture strength is compensated against the current Z-height span, so increasing `Max Z-Height` should not automatically double the physical texture amplitude.
HEIC/HEIF uploads are decoded server-side with `pillow-heif`. If a browser cannot preview HEIC directly, the file upload path should still work.

## Resolution controls

The app defaults to a conservative `1,500,000` processing-pixel limit for Hugging Face CPU runners. This is intentionally not user-editable in the web UI, so hosted users cannot accidentally overload the Space.

Local runners can raise the limit at launch:

```bash
python app.py --max-resolution-pixels 4000000
```

Environment variables are also available:

- `DEFAULT_MAX_RESOLUTION` — default launch value when no CLI flag is provided.
- `MAX_RESOLUTION_LIMIT` — upper clamp for the CLI/env value.

Example:

```bash
DEFAULT_MAX_RESOLUTION=4000000 MAX_RESOLUTION_LIMIT=30000000 python app.py
```

## Local run

```bash
pip install -r requirements.txt
python app.py
```

Once the feature is verified end-to-end, pin the package versions in `requirements.txt` for reproducible Hugging Face/Docker deployments.