RecGen3D

https://github.com/zsh523/recgen3d
Admin
RecGen3D is a reconstruct-then-condition framework that couples feed-forward multi-view 3D...
Tokens:17,677
Snippets:117
Trust Score:4.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run bundled examples

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Prepares example data and runs inference on a selection of bundled examples using a manifest file. This is the fastest way to verify the installation.

```bash
bash scripts/prepare_examples.sh
MANIFEST=examples/select.json bash scripts/run_examples.sh
```

--------------------------------

### Download and run all example objects

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Downloads and unpacks the 27 example objects, then runs inference on all of them, writing results to outputs/examples/.

```bash
bash scripts/prepare_examples.sh    # download + unpack into examples/data/
bash scripts/run_examples.sh        # all 27 examples -> outputs/examples/
```

--------------------------------

### Install system libraries for headless machines

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Installs GL/GLib libraries required by pymeshlab and OpenCV on headless systems.

```bash
sudo apt-get install -y libegl1 libgl1 libopengl0 libglx0 libglvnd0 libgles2 \
                        libsm6 libxext6 libxrender-dev libglib2.0-0
```

--------------------------------

### Run a subset or custom manifest

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Runs a subset of examples by name, or uses a custom manifest (examples/select.json) to run a single object for a quick end-to-end check.

```bash
bash scripts/run_examples.sh lego-car colosseum
MANIFEST=examples/select.json bash scripts/run_examples.sh
```

--------------------------------

### Install extra dependencies and preprocess photos

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Installs required packages for BiRefNet and HEIC support, then runs the preprocessing script to convert photos into RGBA views. Reads JPEG, PNG, WebP, BMP, TIFF, and HEIC; images with an alpha channel are kept as-is.

```bash
pip install -r requirements-extra.txt     # BiRefNet needs kornia; .HEIC needs pillow-heif
python scripts/preprocess_images.py --input path/to/photos --output examples/data/my_object
python inference.py --ckpt pretrained_weights/recgen3d/recgen3d.safetensors \
    --images examples/data/my_object/*.png --name my_object --output outputs/
```

--------------------------------

### Install PyTorch and torch-cluster with CUDA 12.1

Source: https://github.com/zsh523/recgen3d/blob/main/requirements.txt

These commands install PyTorch 2.5.1 and torch-cluster 1.6.3 from their respective indices, as required before installing the dependencies in requirements.txt. They are provided in the file's comments and must be run first.

```bash
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu121
```

```bash
pip install torch-cluster==1.6.3 -f https://data.pyg.org/whl/torch-2.5.1+cu121.html
```

--------------------------------

### Clone and install RecGen3D with install.sh

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Clones the repository and runs install.sh to create the recgen3d conda environment. This is the recommended installation path.

```bash
git clone https://github.com/zsh523/RecGen3D.git
cd RecGen3D
bash install.sh                 # creates the `recgen3d` conda env
conda activate recgen3d
```

--------------------------------

### Manual installation of RecGen3D dependencies

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Manual steps to create the conda environment and install PyTorch, torch-cluster, and remaining requirements. The torch-cluster wheel index must match your PyTorch build.

```bash
conda create -n recgen3d python=3.10 && conda activate recgen3d
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu121
pip install torch-cluster==1.6.3 -f https://data.pyg.org/whl/torch-2.5.1+cu121.html
pip install -r requirements.txt
```

--------------------------------

### Example manifest JSON format

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Shows the JSON structure for a manifest file that lists an object name and the views to condition on. Write a manifest in this shape to point the entry point at your own collections.

```json
{"name": "lego-car", "folder_path": "lego-car",
 "image_names": ["view_00.png", "view_01.png", "view_02.png", "view_03.png"]}
```

--------------------------------

### Download and run paper sample objects

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Downloads and runs the 8 synthetic objects from GSO and Toys4k benchmarks used in the paper's figures, using the paper-samples manifest.

```bash
ARCHIVE_NAME=recgen3d-paper-samples.zip MANIFEST=examples/paper-samples.json \
    bash scripts/prepare_examples.sh
MANIFEST=examples/paper-samples.json bash scripts/run_examples.sh
```

--------------------------------

### Download pretrained weights

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Downloads all required pretrained weights into `pretrained_weights/` (about 23 GB total). The script checks files against `SHA256SUMS.txt`.

```bash
bash scripts/download_weights.sh
```

--------------------------------

### Generate mesh from custom images

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Runs inference on your own unposed, background-removed views. Inputs must be RGBA PNGs of a single object with the background removed; two to eight views work well. Outputs are written to `outputs/<name>/`.

```bash
python inference.py \
    --ckpt pretrained_weights/recgen3d/recgen3d.safetensors \
    --images path/to/view_*.png \
    --name my_object \
    --output outputs/
```

--------------------------------

### Set environment variables for model paths

Source: https://github.com/zsh523/recgen3d/blob/main/README.md

Exports the weights directory so `hy3dshape_omni` can find the backbone. Alternatively, `scripts/run_examples.sh` can do this automatically.

```bash
export HY3DGEN_MODELS=$PWD/pretrained_weights
export HF_HOME=$PWD/pretrained_weights
```
Tokens:
Raw