5cff79d211
Repo had a 0-byte README and no CLAUDE.md. README: requirements (NVIDIA GPU + CUDA 12.1 + ≥12GB VRAM), build/run quickstart, project structure, callout that the root-level uv scaffolding is not part of the build path. CLAUDE.md captures the three upstream patches that are deliberately applied (CUDA 12.1 pin, dedup'd conda create, onnxruntime fix for upstream issue #175), the intentional `|| true` on bulk pip install (nvdiffrast needs --no-build-isolation), build performance gotchas, and the absence of an outputs bind mount. Untracked .python-version / InstantMesh/ / uv.lock left out of this commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# instamesh-docker
|
|
|
|
Docker wrapper around [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
|
|
for single-image → 3D mesh generation. Patches upstream's docker setup to
|
|
fix a couple of known build issues (missing `onnxruntime`, duplicate
|
|
conda env create) and pins CUDA to 12.1 to match the InstantMesh
|
|
PyTorch / xformers wheels.
|
|
|
|
## Requirements
|
|
|
|
- NVIDIA GPU with CUDA 12.1 support and ≥ 12 GB VRAM (InstantMesh is
|
|
not VRAM-friendly).
|
|
- Docker + the NVIDIA Container Toolkit (`nvidia` runtime exposed to
|
|
compose).
|
|
- Disk: several GB for the conda env + model weights.
|
|
- Network egress on first build to pull miniconda, PyTorch wheels, and
|
|
the nvdiffrast / InstantMesh dependencies (long build — 15+ minutes
|
|
is normal).
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Clone the upstream model repo into this directory (the Dockerfile
|
|
# COPYs it via the build context; not a git submodule). Operator-managed;
|
|
# not committed.
|
|
git clone https://github.com/TencentARC/InstantMesh.git
|
|
|
|
# Build and run
|
|
cd docker
|
|
docker compose build
|
|
docker compose up
|
|
|
|
# Gradio UI at http://localhost:43839
|
|
```
|
|
|
|
## Project structure
|
|
|
|
```
|
|
instamesh-docker/
|
|
InstantMesh/ # cloned upstream — operator-managed, not committed
|
|
docker/
|
|
Dockerfile # patched build (CUDA 12.1, onnxruntime fix)
|
|
compose.yml # GPU compose, named volume for model cache
|
|
requirements.txt # Python deps installed inside the conda env
|
|
README.md
|
|
CLAUDE.md
|
|
```
|
|
|
|
## Notes
|
|
|
|
- First run downloads model weights into the `instantmesh-models`
|
|
named volume (mounted at `/workspace/models`). Several GB.
|
|
- The build uses miniconda inside the container with a `python=3.10`
|
|
env named `instantmesh` — not the host's Python. The repo-root
|
|
`pyproject.toml` / `uv.lock` / `.python-version` are leftover uv
|
|
scaffolding and are not part of the build path.
|
|
- See `CLAUDE.md` for the agent-facing gotchas: the patched bits, the
|
|
intentional `|| true` on the bulk requirements install, and the CUDA
|
|
pin reasoning.
|