Magic123

环境要求

• Ubuntu 系统（README 说明仅在 Ubuntu 上测试）
• 已安装 git、wget 和 Eigen（libeigen3-dev）
• Python3 及 python3-venv（或 conda）
• NVIDIA GPU，官方示例在 32G V100 上运行

安装与启动步骤

1. 1安装系统依赖

   更新系统并安装 git、wget、Eigen 及 Python 开发包，为后续编译 CUDA 扩展做准备。

   apt update && apt upgrade
   apt install git wget libeigen3-dev python3-dev python3-venv -y

   复制

2. 2创建虚拟环境

   用 python venv 建独立环境并激活，随后升级 pip/setuptools/wheel 并安装 magic123 包。

   python -m venv venv_magic123
   source venv_magic123/bin/activate
   python -m pip install --upgrade pip setuptools wheel
   python -m pip install magic123

   复制

3. 3一键安装环境脚本

   在项目根目录执行 install.sh 完成其余环境配置；默认使用 venv，改用 conda 需先编辑该文件。

   source install.sh

   复制

4. 4编译 CUDA 扩展

   安装完 PyTorch 后编译 CUDA 扩展，仓库中的脚本会自动检测 GPU 计算能力。

   bash scripts/install_ext.sh

   复制

5. 5运行单图 3D 生成

   两阶段同时开启，GPU 0 上跑 dragon 示例，第一阶段任务名 nerf，第二阶段 dmtet。

   bash scripts/magic123/run_both_priors.sh 0 nerf dmtet data/realfusion15/metal_dragon_statue 1 1

   复制

6. 6追加运行参数

   更多参数可直接附加在命令末尾，例如调整 2D 与 3D 引导权重 lambda_guidance。

   bash scripts/magic123/run_both_priors.sh 0 nerf dmtet data/realfusion15/metal_dragon_statue 1 1 --lambda_guidance 1 40

   复制

7. 7免文本反演预处理

   跳过耗时约 2.5 小时的 textual inversion，先做前景与深度估计，速度快但效果可能下降。

   python preprocess_image.py --path data/demo/a-full-body-ironman/main.png

   复制

8. 8免文本反演粗阶段

   用 main.py 跑粗阶段，约 40 分钟；--workspace 指定输出目录，最后加 --save_mesh 导出网格。

   export RUN_ID='default-a-full-body-ironman'
   export DATA_DIR='data/demo/a-full-body-ironman'
   export IMAGE_NAME='rgba.png'
   export FILENAME=$(basename $DATA_DIR)
   export dataset=$(basename $(dirname $DATA_DIR))
   CUDA_VISIBLE_DEVICES=0 python main.py -O \
   --text "A high-resolution DSLR image of a full body ironman" \
   --sd_version 1.5 \
   --image ${DATA_DIR}/${IMAGE_NAME} \
   --workspace out/magic123-${RUN_ID}-coarse/$dataset/magic123_${FILENAME}_${RUN_ID}_coarse \
   --optim adam \
   --iters 5000 \
   --guidance SD zero123 \
   --lambda_guidance 1.0 40 \
   --guidance_scale 100 5 \
   --latent_iter_ratio 0 \
   --normal_iter_ratio 0.2 \
   --t_range 0.2 0.6 \
   --bg_radius -1 \
   --save_mesh

   复制

关键配置

如何确认成功

运行结束后检查 --workspace 指定目录，确认生成 checkpoints 及网格文件（--save_mesh 已开启）。

常见问题

注意事项

• install.sh 默认使用 python venv；若偏好 conda，需在文件中取消 conda 注释并注释掉 venv 后再执行。
• 换用自己的示例时，需修改脚本内部的图片路径与文本提示（text prompt）。
• 免文本反演的 quick 模式效果可能下降，仅适合快速验证。
• PyPI 安装后仍需在装好 PyTorch 的基础上编译 CUDA 扩展才能运行。