Compare commits
No commits in common. "92ca7253c79dd4d24dfbc5cc54b7a2e18149aeb6" and "3a8765adceeb1be55f8b2794b0ff0d31a501e5c1" have entirely different histories.
92ca7253c7
...
3a8765adce
3
.gitmodules
vendored
3
.gitmodules
vendored
@ -1,3 +0,0 @@
|
|||||||
[submodule "InstantMesh"]
|
|
||||||
path = InstantMesh
|
|
||||||
url = https://github.com/TencentARC/InstantMesh.git
|
|
||||||
@ -1 +0,0 @@
|
|||||||
3.12
|
|
||||||
121
CLAUDE.md
121
CLAUDE.md
@ -1,121 +0,0 @@
|
|||||||
# Claude notes — instamesh-docker
|
|
||||||
|
|
||||||
Agent context for this repo. Read before non-trivial changes.
|
|
||||||
|
|
||||||
## What this is
|
|
||||||
|
|
||||||
Docker wrapper around upstream [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
|
|
||||||
for single-image → 3D mesh generation. **Not** a fork of InstantMesh
|
|
||||||
itself — this repo owns the docker build + compose plus a small set of
|
|
||||||
patches that fix known upstream build breakage.
|
|
||||||
|
|
||||||
## Repo shape
|
|
||||||
|
|
||||||
```
|
|
||||||
instamesh-docker/
|
|
||||||
InstantMesh/ # UNTRACKED — upstream clone. Operators run
|
|
||||||
# `git clone https://github.com/TencentARC/InstantMesh.git`
|
|
||||||
# once before `docker compose build`. Not a submodule.
|
|
||||||
docker/
|
|
||||||
Dockerfile # patched (see "Patches applied" below)
|
|
||||||
compose.yml # GPU compose, named volume for model cache, port 43839
|
|
||||||
requirements.txt # InstantMesh's pip deps, kept here so the Dockerfile
|
|
||||||
# can ADD them without changing the upstream tree
|
|
||||||
main.py, pyproject.toml, uv.lock, .python-version
|
|
||||||
# leftover uv scaffolding from initial repo init;
|
|
||||||
# NOT part of the build path. Don't extend these.
|
|
||||||
README.md
|
|
||||||
CLAUDE.md
|
|
||||||
```
|
|
||||||
|
|
||||||
`InstantMesh/` is intentionally untracked. Don't add it as a submodule
|
|
||||||
or vendor it into source control — keep the upstream boundary clean.
|
|
||||||
|
|
||||||
## Patches applied (vs. upstream)
|
|
||||||
|
|
||||||
The Dockerfile is forked from InstantMesh's docker config with three
|
|
||||||
deliberate changes — call out any churn around these:
|
|
||||||
|
|
||||||
1. **CUDA aligned to 12.1.** Base image is
|
|
||||||
`nvidia/cuda:12.1.0-runtime-ubuntu22.04`; conda installs `cuda` from
|
|
||||||
`nvidia/label/cuda-12.1.0`; pip installs `torch==2.1.0 + cu121` and
|
|
||||||
`xformers==0.0.22.post7`. All four must stay in sync. Don't bump CUDA
|
|
||||||
without re-pinning all of them.
|
|
||||||
2. **Duplicate `conda create` removed.** Upstream's Dockerfile created
|
|
||||||
the conda env twice; the second one nuked the first's pinned
|
|
||||||
packages. Don't reintroduce.
|
|
||||||
3. **`onnxruntime` added.** Missing from upstream's `requirements.txt`
|
|
||||||
(InstantMesh issue #175). Installed as a separate `pip install` step
|
|
||||||
after the bulk requirements install so it's not silently dropped by
|
|
||||||
the `|| true` below.
|
|
||||||
|
|
||||||
## Intentional `|| true` on the bulk pip install
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
RUN pip install --no-cache-dir -r requirements.txt || true
|
|
||||||
```
|
|
||||||
|
|
||||||
This is **on purpose**. The requirements include `nvdiffrast` via a git
|
|
||||||
URL that needs `--no-build-isolation`, which pip's bulk install won't
|
|
||||||
do. We let that line fail, then install `nvdiffrast` correctly:
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
RUN pip install git+https://github.com/NVlabs/nvdiffrast.git --no-build-isolation
|
|
||||||
```
|
|
||||||
|
|
||||||
Don't "fix" the bulk install by removing `|| true` — the build will
|
|
||||||
hard-fail on nvdiffrast.
|
|
||||||
|
|
||||||
## Hardware contract
|
|
||||||
|
|
||||||
- **NVIDIA GPU required**, exposed through Docker via the nvidia
|
|
||||||
runtime. InstantMesh wants **≥ 12 GB VRAM** comfortably; smaller cards
|
|
||||||
may OOM during inference.
|
|
||||||
- **CUDA 12.1** — see patch #1 above.
|
|
||||||
|
|
||||||
## Build is slow + brittle
|
|
||||||
|
|
||||||
Expect a 15+ minute first build. Conda + nvdiffrast compilation +
|
|
||||||
PyTorch wheels add up. Triggers that re-run the slow layers:
|
|
||||||
- Editing `docker/requirements.txt` invalidates the conda install layer.
|
|
||||||
- Editing the Dockerfile's `apt-get install` line redoes the whole
|
|
||||||
thing from a fresh base image.
|
|
||||||
|
|
||||||
Lean on Docker's layer cache; don't restructure for "cleanliness"
|
|
||||||
without measuring the rebuild cost.
|
|
||||||
|
|
||||||
## Compose
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
ports:
|
|
||||||
- "43839:43839" # Gradio app, host-published
|
|
||||||
volumes:
|
|
||||||
- instantmesh-models:/workspace/models # weights cache (named volume)
|
|
||||||
```
|
|
||||||
|
|
||||||
No host-network mode, no bind mounts for code (the upstream tree is
|
|
||||||
COPYed at build time). If you need to iterate on InstantMesh source,
|
|
||||||
edit `InstantMesh/` locally and rebuild — there's no dev-mode wiring.
|
|
||||||
|
|
||||||
## Where outputs go
|
|
||||||
|
|
||||||
InstantMesh's Gradio app writes generated meshes inside the container
|
|
||||||
(under `/workspace/instantmesh/`). There's **no bind mount** for
|
|
||||||
outputs in `compose.yml` — operator downloads results from the Gradio
|
|
||||||
UI. If you find yourself wanting to bind-mount an outputs dir, mirror
|
|
||||||
`hunyuan3d-sunnie/docker/outputs/`.
|
|
||||||
|
|
||||||
## Don't-touch zones
|
|
||||||
|
|
||||||
- The CUDA 12.1 pins (base image / conda label / PyTorch wheel index /
|
|
||||||
xformers wheel) — load-bearing as a set.
|
|
||||||
- The `|| true` on bulk requirements install — required for nvdiffrast.
|
|
||||||
- The `onnxruntime` separate install line — load-bearing per upstream #175.
|
|
||||||
- The untracked `InstantMesh/` directory — let operators reclone.
|
|
||||||
|
|
||||||
## Bigger picture
|
|
||||||
|
|
||||||
Personal/one-off project, GPU-only. Runs on the dev tower; not part of
|
|
||||||
the homelab production stack. Sibling project `hunyuan3d-sunnie/` uses
|
|
||||||
a different model (Hunyuan3D-2) for the same general shape of problem
|
|
||||||
on a 10 GB card — pick that one if VRAM is tight.
|
|
||||||
@ -1 +0,0 @@
|
|||||||
Subproject commit 08822c52fdc399b93ea00e4fa9e596344ed52ccc
|
|
||||||
59
README.md
59
README.md
@ -1,59 +0,0 @@
|
|||||||
# 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.
|
|
||||||
Loading…
Reference in New Issue
Block a user