threefiner

<p align="center"> <picture> <img alt="标志" src="https://yellow-cdn.veclightyear.com/835a84d5/8a440974-44b2-4ee3-9b3b-b07e0f5032db.png" width="20%"> </picture> </br> <b>Threefiner</b> </p>

一个用于文本引导的网格细化接口。

https://github.com/3DTopia/threefiner/assets/25863658/a4abe725-b542-4a4a-a6d4-e4c4821f7d96

特点

• 网格输入，网格输出：我们支持带顶点颜色的ply格式、obj格式，以及带纹理的单一对象glb/gltf格式！
• 易于使用：同时提供命令行界面和图形用户界面。
• 高性能：使用Deepfloyd-IF-II在1分钟内细化您的纹理。

安装

我们依赖torch和几个CUDA扩展，请确保先正确安装它们！

# tiny-cuda-nn
pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch

# nvdiffrast
pip install git+https://github.com/NVlabs/nvdiffrast

# [可选，如果不可用将使用pysdf] cubvh:
pip install git+https://github.com/ashawkey/cubvh

要使用Deepfloyd-IF模型，请登录您的huggingface账户并接受许可。

安装本包：

# 从pypi安装
pip install threefiner

# 从github安装
pip install git+https://github.com/3DTopia/threefiner

# 本地安装
git clone https://github.com/3DTopia/threefiner
cd threefiner
pip install .

使用方法

### 命令行界面
threefiner --help
# 这等同于
python -m threefiner.cli --help

### 使用Stable-diffusion细化粗糙网格('input.obj')并保存为'logs/hamburger.glb'
threefiner sd --mesh input.obj --prompt 'a hamburger' --outdir logs --save hamburger.glb

### 如果初始纹理良好，我们建议使用IF2进行细化。
# 默认情况下，它将保存为'./name_fine.glb'
threefiner if2 --mesh name.glb --prompt 'description'

### 如果初始纹理不佳，我们建议先使用SD或IF。
threefiner sd --mesh name.glb --prompt 'description'
threefiner if --mesh name.glb --prompt 'description'

### 如果初始几何形状良好，您可以固定几何形状。
threefiner sd_fixgeo --mesh name.glb --prompt 'description'
threefiner if_fixgeo --mesh name.glb --prompt 'description'
threefiner if2_fixgeo --mesh name.glb --prompt 'description'

### 高级用法
# 定向文本提示（在文本提示中附加前/侧/后视图）
# 您需要知道网格的正面朝向并通过'--front_dir'指定
# 我们使用OpenGL坐标系，即+x为右，+y为上，+z为前（更多详情：https://kit.kiui.moe/camera/）
# 顺时针旋转可以每90度指定一次，例如+z1，-y2
threefiner if2 --mesh input.glb --prompt 'description' --text_dir --front_dir='+z'

# 调整训练迭代次数
threefiner if2 --mesh input.glb --prompt 'description' --iters 1000

# 明确固定几何形状并只细化纹理
threefiner if2 --fix-geo --geom_mode mesh --mesh input.glb --prompt 'description' # 等同于if2_fixgeo

# 打开GUI以可视化训练进度（需要桌面环境）
threefiner if2 --mesh input.glb --prompt 'description' --gui

Gradio演示：

# 需要gradio 4
python gradio_app.py if2

更多示例，请参见scripts。

问答

• 如何确保模型的--front_dir正确？

  您可以首先在遵循OpenGL坐标系的3D查看器中进行可视化：

  <p align="center"> <picture> <img alt="示例_front_dir" src="https://yellow-cdn.veclightyear.com/835a84d5/d7699c19-12d6-4f5d-bd61-1736301c89d7.jpg" width="50%"> </picture> </p> 椅子面朝Y轴负方向（绿色），所以我们可以使用`--front_dir="-y"`将其校正为面向+Z轴（蓝色）。

• 致命错误：EGL/egl.h：没有这样的文件或目录

  默认情况下，我们使用OpenGL光栅化器。这个错误意味着没有安装OpenGL，这在无头服务器上经常发生。 建议安装OpenGL（连同NVIDIA驱动程序），因为它能带来更好的性能。 否则，您可以附加--force_cuda_rast来使用CUDA光栅化器。

致谢

本工作基于许多令人惊叹的研究成果和开源项目，非常感谢所有作者的分享！

• SDS guidance 类基于 diffusers。
• diffmc 几何形状基于 diso。
• mesh 几何形状基于 nerf2mesh。
• 纹理编码基于 tinycudann。
• 网格渲染器基于 nvdiffrast。
• GUI基于 dearpygui。
• 演示中使用的粗糙模型由 Genie 和 3DTopia 生成。