一、模型介绍

Elevate3D 是一个面向实际生产场景的 3D 资产“上采样”框架：输入任何低质量 3D 模型（纹理模糊、几何残缺），输出在视觉与几何层面都逼近手工精修的高质量 3D 资产。整套流程零人工干预，完全自动化，目标是解决“高质量 3D 内容昂贵且稀缺”的痛点。（注：仅在 Linux 上测试。）

1. 核心思想
   • 视图迭代：把 3D 问题解耦成多轮“2D 视图 →3D 更新”循环。
   • 双分支交替：
   ① HFS-SDEdit 纹理增强——基于扩散模型，在保留原有外观前提下修复并超分辨纹理；
   ② 几何细化——利用单目法向/深度估计网络，从刚增强的 2D 视图提取几何线索，再做泊松重建与网格优化。
   • 一致性约束：每次迭代都在多视角间强制颜色、法向、mask 一致，防止“每面都不同”的伪影。

2. 技术亮点
   • HFS-SDEdit：提出高频分离（High-Frequency Separation）策略，只对高频细节做扩散补全，低频结构保持不变，既省算力又避免“过度幻想”。
   • 单目几何预测：集成 Marigold、Marigold-E2E 等 SOTA 单目估计器，无需多视角真值即可恢复精细几何。
   • 端到端：从低模输入到可直接渲染/3D 打印的高模输出，全程 GPU 加速，常用单卡 48 GB（A6000）即可完成。

   

二、模型部署

基础环境配置推荐

环境名称	版本信息
Ubuntu	22.04.4 LTS
Python	3.10
CUDA	12.1
NVIDIA Corporation	A100 SXM4

注：该模型支持多卡并行而不支持多卡推理，仅支持单卡推理，单卡显存不得低于48GB。

1.更新基础软件包、配置镜像源

查看系统版本信息

#查看系统的版本信息，包括 ID（如 ubuntu、centos 等）、版本号、名称、版本号 ID 等
cat /etc/os-release

更新软件包列表

#更新软件列表
apt-get update

配置国内镜像源（阿里云）

具体而言，vim 指令编辑文件 sources.list

#编辑源列表文件
vim  /etc/apt/sources.list

按 “i” 进入编辑模式，将如下内容插入至 sources.list 文件中

deb http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse

最后，按 "esc" 键退出编辑模式，输入 :wq 命令并按下 “enter” 键便可保存并退出 sources.list 文件

2.克隆github上的存储仓库

从github上将项目文件全部克隆下来，全部框架文件位于 ./Elevate3D目录下：

git clone --recurse-submodules https://github.com/ryunuri/Elevate3D.git
cd Elevate3D

3.创建虚拟环境、安装依赖包

• 进入Elevate3D目录后，先对 requirements.txt依赖包文件进行修改，添加额外的索引 url ：--find-links https://download.blender.org/pypi/bpy/，避免bpy包在 PyPI 中不可用而导致环境创建失败。
• 修改后完整的 requirements.txt：

--find-links https://dl.fbaipublicfiles.com/pytorch3d/packaging/wheels/py310_cu121_pyt240/download.html
--find-links https://data.pyg.org/whl/torch-2.5.1+cu121.html
--find-links https://download.blender.org/pypi/bpy/absl-py==2.1.0
accelerate==0.34.0
addict==2.4.0
aiohappyeyeballs==2.4.0
aiohttp==3.10.5
aiosignal==1.3.1
antlr4-python3-runtime==4.9.3
asttokens==2.4.1
async-timeout==4.0.3
attrs==24.2.0
bitsandbytes==0.44.1
blinker==1.8.2
bpy==3.6.0
carvekit==4.1.2
certifi==2024.8.30
cfgv==3.4.0
chardet==5.2.0
charset-normalizer==3.3.2
clean-fid==0.1.35
click==8.1.7
clip-anytorch==2.6.0
colorama==0.4.6
coloredlogs==15.0.1
comm==0.2.2
compel==2.0.3
ConfigArgParse==1.7
contourpy==1.3.0
cupy==13.5.1
cycler==0.12.1
dash==2.18.0
dash-core-components==2.0.0
dash-html-components==2.0.0
dash-table==5.0.0
dctorch==0.1.2
decorator==5.1.1
decord==0.6.0
diffusers==0.32.1
distlib==0.3.9
docker-pycreds==0.4.0
einops==0.8.0
et-xmlfile==1.1.0
exceptiongroup==1.2.2
executing==2.1.0
facexlib==0.3.0
fastjsonschema==2.20.0
fastrlock==0.8.2
filelock==3.15.4
filterpy==1.4.5
Flask==3.0.3
flatbuffers==24.3.25
fonttools==4.53.1
frozenlist==1.4.1
fsspec==2024.9.0
ftfy==6.2.3
future==1.0.0
fvcore==0.1.5.post20221221
gitdb==4.0.11
GitPython==3.1.43
glcontext==3.0.0
grpcio==1.66.1
h5py==3.11.0
huggingface-hub==0.24.6
humanfriendly==10.0
icecream==2.1.0
identify==2.6.1
idna==3.8
imageio==2.35.1
imageio-ffmpeg==0.5.1
importlib_metadata==8.4.0
iniconfig==2.0.0
iopath==0.1.10
ipython==8.27.0
ipywidgets==8.1.5
itsdangerous==2.2.0
jedi==0.19.1
Jinja2==3.1.4
joblib==1.4.2
jsmin==3.0.1
jsonmerge==1.9.2
jsonschema==4.23.0
jsonschema-specifications==2023.12.1
jupyter_core==5.7.2
jupyterlab_widgets==3.0.13
k-diffusion==0.1.1.post1
kiwisolver==1.4.7
kornia==0.7.3
kornia_rs==0.1.5
lazy_loader==0.4
lightning-utilities==0.11.7
llvmlite==0.43.0
lmdb==1.5.1
Markdown==3.7
markdown-it-py==3.0.0
MarkupSafe==2.1.5
matplotlib==3.9.2
matplotlib-inline==0.1.7
mdurl==0.1.2
modelcards==0.1.6
moderngl==5.12.0
mpmath==1.3.0
multidict==6.0.5
nbformat==5.10.4
nerfacc==0.3.3
nest-asyncio==1.6.0
networkx==3.3
ninja==1.11.1.1
nodeenv==1.9.1
numba==0.60.0
numpy==1.26.4
nvdiffrast @ git+https://github.com/NVlabs/nvdiffrast.git@729261dc64c4241ea36efda84fbf532cc8b425b8
objloader==0.2.0
omegaconf==2.2.3
onnxruntime==1.19.2
open-clip-torch==2.24.0
open3d==0.18.0
openai-clip==1.0.1
opencv-python==4.10.0.84
opencv-python-headless==4.10.0.84
openpyxl==3.1.5
packaging==24.1
pandas==2.2.2
parso==0.8.4
pexpect==4.9.0
Pillow==11.3.0
piq==0.8.0
platformdirs==4.2.2
plotly==5.24.0
pluggy==1.5.0
pooch==1.8.2
portalocker==2.10.1
pre_commit==4.0.1
prompt_toolkit==3.0.47
protobuf==5.28.0
psutil==6.0.0
ptyprocess==0.7.0
pure_eval==0.2.3
pybind11==2.13.5
PyGLM==2.7.3
Pygments==2.18.0
pyhocon==0.3.57
PyMatting==1.1.12
PyMCubes==0.1.6
pymeshlab==2023.12.post1
pyparsing==3.1.4
pyquaternion==0.9.9
pyransac3d==0.6.0
pysteps==1.12.0
pytest==8.3.3
python-dateutil==2.9.0.post0
pytorch-lightning==1.9.4
pytorch3d==0.7.8
pytz==2024.1
pyvista==0.44.2
PyYAML==6.0.2
referencing==0.35.1
regex==2024.7.24
rembg==2.0.59
requests==2.32.3
retrying==1.3.4
rich==13.8.0
rpds-py==0.20.0
safetensors==0.4.4
scikit-image==0.24.0
scikit-learn==1.5.1
scipy==1.14.1
scooby==0.10.0
seaborn==0.13.2
segment-anything==1.0
sentencepiece==0.2.0
sentry-sdk==2.13.0
setproctitle==1.3.3
six==1.16.0
smmap==5.0.1
stack-data==0.6.3
sympy==1.13.1
tabulate==0.9.0
tenacity==9.0.0
tensorboard==2.17.1
tensorboard-data-server==0.7.2
termcolor==2.4.0
threadpoolctl==3.5.0
tifffile==2024.8.30
timm==1.0.9
tinycudann @ git+https://github.com/NVlabs/tiny-cuda-nn/@c91138bcd4c6877c8d5e60e483c0581aafc70cce#subdirectory=bindings/torch
tokenizers==0.20.1
torchao==0.12.0
torch-scatter
tomli==2.0.2
tqdm==4.66.5
traitlets==5.14.3
trampoline==0.1.2
transformers==4.46.1
trimesh==3.9.8
typing_extensions==4.12.2
tzdata==2024.1
urllib3==2.2.2
virtualenv==20.27.0
vtk==9.3.1
wandb==0.17.8
wcwidth==0.2.13
Werkzeug==3.0.4
widgetsnbextension==4.0.13
xatlas==0.0.11
xformers==0.0.28.post3
yacs==0.1.8
yapf==0.40.2
yarl==1.9.11
zipp==3.20.1

• conda env create -f environment.yml --name elevate3d会使用提供的环境文件 environment.yml创建并激活 conda 环境。过程中会转到 requirements.txt下载依赖库。

conda env create -f environment.yml --name elevate3d
conda activate elevate3d

4.下载依赖项

下载检查点 ： Elevate3D框架依赖于几个现成的模型及依赖项。这里先下载依赖项，依托的模型有些会从 Hugging Face 自动下载，但其他需要手动放置。（这里建议手动将模型下载，放置指定的文件夹中）

如下的指令会创建 Checkpoints/sam二级目录，并从指定网址下载所需依赖项

# Create directories for checkpoints
mkdir -p Checkpoints/sam

# Download the Segment Anything Model (SAM) checkpoint
wget https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth -P Checkpoints/sam/

构建泊松侦察兵 ： 几何细化步骤会使用到泊松曲面重建。您需要从源代码构建可执行文件。

从github仓库中克隆下源代码文件

# Clone the PoissonRecon repository
git clone https://github.com/mkazhdan/PoissonRecon.git

进入文件目录，make指令将编译执行当前目录下的Makefile文件，编译的过程很长，请耐心等待。

# Navigate and build the executable
cd PoissonRecon/
make
cd ..

5.下载依赖模型

Elevate3D框架总共依赖于4种模型（FLUX.1-dev、FLUX.1-Depth-dev、FLUX.1-Redux-dev、marigold-e2e-ft-normals）。直接运行 python -m FLUX.flux_HFS-SDEdit进行2D细化会返回需要下载FLUX.1-dev；启动3D模型细化脚本 bash run_3d_refine_script_example.sh 则会提醒需要启用4种模型进行作业。这里的话，建议在github、huggingface中手动将所需模型下载至指定目录，便于后续修改.yaml环境脚本。

FLUX.1-dev模型：

#例如，这里将模型下载至sj-tmp指定目录下
cd /root/sj-tmp/
pip install modelscope
modelscope download --model 'black-forest-labs/FLUX.1-dev' --local_dir './'

FLUX.1-Depth-dev模型：

#例如，这里将模型下载至sj-tmp指定目录下
modelscope download --model 'black-forest-labs/FLUX.1-Depth-dev' --local_dir './'

FLUX.1-Redux-dev模型：

#例如，这里将模型下载至sj-tmp指定目录下
modelscope download --model 'black-forest-labs/FLUX.1-Redux-dev' --local_dir './'

marigold-e2e-ft-normals模型：

#modelscope中找不到该模型，这里用hugging face来下载模型
hf download GonzaloMG/marigold-e2e-ft-normals --local-dir marigold-e2e-ft-normals

6.实例数据准备、配置.yaml 文件

（1）在运行示例之前，您需要下载示例 2D 图像和低质量的 3D 模型。或者您可以自己的数据上运行，但要将数据文件放入指定的目录下：
示例数据下载：

• 单击链接从 Google Drive中 下载示例数据 （Inputs.zip）下载 Inputs.zip 。
• 解压缩文件：将下载的移动到该项目目录的根目录（例如，）。然后，在终端中运行以下命令以创建一个文件夹并将文件解压到其中：Inputs.zip Elevate3D/ ./Inputs

# Make sure Inputs.zip is in the current project directory
unzip Inputs.zip

自己的数据运行：

以此链接为例，在Elevate3d目录下：

解压缩后，您将拥有：

• knight.glb：低质量输入 3D 模型。
• knight.txt：描述目标外观的文本文件。

则按如下方式组织输入：

# Create the directory structure
mkdir -p Inputs/3D/MyData/knight

# Move the downloaded files into it
mv knight.glb Inputs/3D/MyData/knight
mv knight.txt Inputs/3D/MyData/knight

如下是各组织文件的目录结构：

Elevate3D/
├── Checkpoints/                <-- For pre-trained models
│   └── sam/
│       └── sam_vit_h_4b8939.pth
├── Inputs/                     <-- Example data you just downloaded
│   ├── 2D/
│   └── 3D/MyData/
|            └── knight/
|                ├── knight_normalized.obj
|                ├── prompt.txt
|                ├── train_0_0.png
|                └── ... (many more rendered images)
├── PoissonRecon/               <-- For geometry processing
│   └── Bin/
│       └── Linux/
│           └── PoissonRecon    <-- The compiled executable
├── ... (other project files)
└── README.md

（2）配置.yaml 文件

进入/Elevate3D/Configs/目录下，配置.yaml文件（config_gso.yaml、config_my.yaml、config_trellis.yaml）。

• config_gso.yaml：对应/Elevate3D/Inputs/3D/GSO/目录下GSO示例数据各对象依托模型的配置。
• config_my.yaml：对应/Elevate3D/Inputs/3D/MyData/目录下用户自己下载数据各对象依托模型的配置。
• config_trellis.yaml：对应/Elevate3D/Inputs/3D/TRELLIS/目录下TRELLIS示例数据各对象依托模型的配置。

如上三个配置.yaml文件按如下相同方式进行改动：

原：

#第45行
base_pipeline_path: "black-forest-labs/FLUX.1-dev"
depth_pipeline_path: "black-forest-labs/FLUX.1-Depth-dev"
redux_pipeline_path: "black-forest-labs/FLUX.1-Redux-dev"

#第97行
checkpoint: "GonzaloMG/marigold-e2e-ft-normals"

修改后：

#第45行
base_pipeline_path: "/root/sj-tmp/FLUX.1-dev"
depth_pipeline_path: "/root/sj-tmp/FLUX.1-Depth-dev"
redux_pipeline_path: "/root/sj-tmp/FLUX.1-Redux-dev"

#第97行
checkpoint: "/root/sj-tmp/marigold-e2e-ft-normals"

7.终端执行脚本代码

运行示例文件：

①2D 图像细化

使用 HFS-SDEdit 进行 2D 图像细化的示例，作用是转到FLUX目录下运行flux_HFS-SDEdit.py脚本，这将在单个图像上运行纹理增强模块。

python -m FLUX.flux_HFS-SDEdit

②全 3D 模型细化

此脚本在示例模型上运行完整的 Elevate3D 管道。它将执行迭代纹理和几何细化。

#运行GSO示例数据3D模型细化脚本
bash run_3d_refine_script_gso_example.sh
#运行TRELLIS示例数据3D模型细化脚本
bash run_3d_refine_script_trellis_example.sh

运行自己的数据：

该过程分为两个阶段：数据预处理和模型细化。

①数据预处理

此步骤获取输入的 3D 模型，并为细化阶段做好准备。

运行提供的 shell 脚本，将路径传递到对象的目录。此脚本处理模型规范化和多视图渲染。

bash run_preprocess_script.sh

该脚本将用新文件填充您的目录。

Inputs/3D/MyData/
            └── knight/
                ├── knight_normalized.obj
                ├── prompt.txt
                ├── train_0_0.png
                └── ... (many more rendered images)

②模型细化

现在数据已准备就绪，您可以运行主细化算法。 使用以下命令，确保参数与您刚刚创建的目录结构匹配。

python main_refactor.py \
  --obj_name="knight" \
  --conf_name="config_my" \
  --bake_mesh \
  --device_idx=0

细化处理后，结果将在 Outputs/3D/MyData/knight

8.3D模型细化web访问

github仓库中并没有相关的web访问接口，基于仓库的原有代码，如下的app.py文件能够实现网页3D模型的简单细化处理（仅作参考）。

vim app.py
python app.py

app.py:

import gradio as gr
import subprocess
import os
import shutil
from pathlib import Path

def run_refinement(model_file, conf_name, gpu_id, bake_mesh, render_video):
    """
    支持上传多种格式的3D文件并调用 main_refactor.py 进行处理
    """
    # 创建工作目录
    work_dir = "uploaded_objects"
    os.makedirs(work_dir, exist_ok=True)
    os.makedirs("logs", exist_ok=True)
  
    # 获取上传的文件名（不含路径）
    model_filename = os.path.basename(model_file.name)
    obj_name = os.path.splitext(model_filename)[0]  # 去掉扩展名
    file_extension = os.path.splitext(model_filename)[1][1:].lower()  # 获取扩展名（不含点）
  
    # 创建对象目录
    obj_dir = os.path.join(work_dir, obj_name)
    os.makedirs(obj_dir, exist_ok=True)
  
    # 复制上传的文件到指定位置，保持原始格式
    target_model_path = os.path.join(obj_dir, f"{obj_name}.{file_extension}")
    shutil.copy(model_file.name, target_model_path)
  
    # 构建命令行参数
    cmd = [
        "python", "mian_1.py",
        "--obj_name", obj_name,
        "--conf_name", conf_name,
        "--device_idx", str(gpu_id),
        "--input_model_dir", obj_dir,  # 修改参数名，支持多种格式
        "--input_model_format", file_extension  # 添加格式参数
    ]

    if bake_mesh:
        cmd.append("--bake_mesh")

    if render_video:
        cmd.append("--render_video")

    # 日志文件
    log_file = f"logs/gradio_{obj_name}.log"

    # 运行子进程
    with open(log_file, "w") as f:
        result = subprocess.run(cmd, stdout=f, stderr=f)

    # 返回日志内容给前端
    if os.path.exists(log_file):
        with open(log_file, "r", encoding="utf-8", errors="ignore") as f:
            logs = f.read()
        return logs
    else:
        return "❌ 日志文件未生成，请检查是否运行出错。"

# 支持的文件格式列表
SUPPORTED_FORMATS = [".obj", ".glb", ".gltf", ".fbx", ".ply", ".stl", ".dae", ".3mf", ".off"]

# Gradio UI 构建
with gr.Blocks(title="3D Mesh Refinement") as demo:
    gr.Markdown("## 🧊 3D Mesh Refinement Pipeline (Gradio Web UI)")
    gr.Markdown("### 📤 上传你的 3D 模型文件进行网格优化")
    gr.Markdown(f"**支持的格式**: {', '.join(SUPPORTED_FORMATS)}")

    with gr.Row():
        model_file = gr.File(
            label="📤 Upload 3D Model File", 
            file_types=SUPPORTED_FORMATS
        )
        conf_name = gr.Textbox(label="⚙️ Config Name", value="config_gso")
        gpu_id = gr.Number(label="🖥️ GPU ID", value=0, precision=0)

    with gr.Row():
        bake_mesh = gr.Checkbox(label="🍰 Bake Final Textured Mesh")
        render_video = gr.Checkbox(label="🎥 Render Final Video")

    run_btn = gr.Button("🚀 Start Refinement", variant="primary")

    output_logs = gr.Textbox(label="📋 Logs", interactive=False, lines=20, max_lines=30)

    run_btn.click(
        fn=run_refinement,
        inputs=[model_file, conf_name, gpu_id, bake_mesh, render_video],
        outputs=output_logs
    )

# 启动 Gradio 服务
if __name__ == "__main__":
    demo.launch(server_name="0.0.0.0", server_port=8080)