muaibinrah/image-to-3d-depth-capstone

Image-to-3D Depth Capstone

Capstone project for the Hugging Face ML for 3D Course, Unit 5. Reconstructs a textured 3D relief mesh from a single RGB image.

What this is

This repo holds the reconstruction code (reconstruct.py) used by the demo Space. It is not a trained/fine-tuned neural network — it is a small, from-scratch, deterministic pipeline built on top of an existing open monocular depth estimation model:

1. Run LiheYoung/depth-anything-small-hf on the input image to get a per-pixel depth map.
2. Resize the image and depth map to a grid_size x grid_size grid (default 128x128).
3. Treat the grid as a height field: each pixel becomes a vertex at (x, y, depth * depth_scale).
4. Triangulate adjacent grid cells into two triangles each.
5. Assign each vertex the RGB color of the corresponding image pixel.
6. Export with trimesh (.glb, .obj, .ply, ... all supported by trimesh.Trimesh.export).

Usage

from PIL import Image
from transformers import pipeline
from reconstruct import image_to_mesh

depth_pipe = pipeline("depth-estimation", model="LiheYoung/depth-anything-small-hf")
image = Image.open("photo.jpg").convert("RGB")
depth = depth_pipe(image)["depth"]

mesh = image_to_mesh(image, depth, grid_size=128, depth_scale=0.6)
mesh.export("output.glb")

Demo

Try it live in the companion Space: https://huggingface.co/spaces/muaibinrah/image-to-3d-demo

Limitations

This produces a 2.5D "relief" mesh from a single viewpoint, not a full volumetric or multi-view 3D reconstruction. Occluded and back-facing geometry is not recovered. depth_scale is a hand-picked constant and will over- or under-exaggerate relief depending on the scene.

Credits

Depth estimation: LiheYoung/depth-anything-small-hf (Depth Anything, Apache-2.0). Mesh construction and demo code: own work for this course capstone.