a) 安装所需的 Python 包

要安装所需的 Python 包并激活环境，请进入 SuGaR/ 目录并运行以下命令：

conda env create -f environment.yml
conda activate sugar

如果此命令未能成功创建可用环境，您可以尝试手动安装所需的包，方法是运行以下命令：

conda create --name sugar -y python=3.9
conda activate sugar
conda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.8 -c pytorch -c nvidia
conda install -c fvcore -c iopath -c conda-forge fvcore iopath
conda install pytorch3d==0.7.4 -c pytorch3d
conda install -c plotly plotly
conda install -c conda-forge rich
conda install -c conda-forge plyfile==0.8.1
conda install -c conda-forge jupyterlab
conda install -c conda-forge nodejs
conda install -c conda-forge ipywidgets
pip install open3d
pip install --upgrade PyMCubes

b) 安装高斯溅射光栅化器

在 SuGaR 目录内运行以下命令，以安装高斯溅射所需的额外 Python 子模块：

cd gaussian_splatting/submodules/diff-gaussian-rasterization/
pip install -e .
cd ../simple-knn/
pip install -e .
cd ../../../

更多详情请参阅 3D 高斯溅射仓库。

c) （可选）安装 Nvdiffrast 以加快网格光栅化速度

安装 Nvdiffrast 是可选的，但可以显著加快纹理网格提取步骤，从几分钟缩短到不到 10 秒。

git clone https://github.com/NVlabs/nvdiffrast
cd nvdiffrast
pip install .
cd ../

请在此处观看 简短视频,了解如何使用该查看器。

1. 安装

该查看器目前适用于 Linux 和 Mac OS，不支持 Windows。对于 Windows 用户，我们建议使用 WSL2（Windows Sub系统 for Linux），因为它安装和使用都非常方便。更多详情请参阅 官方文档。
我们感谢 Mark Kellogg 为 Three.js 提供的出色的 3D 高斯泼溅实现, 我们正是基于此实现构建了这款查看器。

首先，请安装最新版本的 Node.js（例如 21.x）和 npm。 一种简单的方法是运行以下命令（使用 aptitude）：

curl -fsSL https://deb.nodesource.com/setup_21.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install aptitude
sudo aptitude install -y npm

然后，进入 ./sugar_viewer/ 目录并运行以下命令：

npm install
cd ..

2. 使用

首先，请确保您已使用 train.py 脚本导出 .ply 文件和 .obj 文件。.ply 文件包含优化后的 3D 高斯点云，而 .obj 文件则包含带纹理的网格。默认情况下，运行 train.py 脚本时会导出这些文件，因此如果您在运行代码时使用了 --export_ply 和 --export_obj 的默认值，那么您应该可以直接使用。

.ply 文件应位于 ./output/refined_ply/<您的场景名称>/ 目录中。然后，在根目录下运行以下命令即可启动查看器：

python run_viewer.py -p <.ply 文件路径>

请确保您的 .ply 文件位于正确的位置，并使用以 ./output/refined_ply 开头的相对路径。该命令将重定向到本地 URL。点击链接即可在浏览器中打开查看器。单击右上角的图标可在不同表示形式之间切换（混合表示、带纹理的网格、线框网格）。使用鼠标旋转场景，使用鼠标滚轮进行缩放。

使用智能手机或相机拍摄覆盖您想要重建的 3D 场景整个表面的图片或视频。最简单的方法是在场景周围移动并录制视频。尽量缓慢平稳地移动，以避免运动模糊。为了实现一致的重建效果，并便于 COLMAP 进行相机位姿估计，保持统一的焦距和恒定的曝光时间也很重要。我们建议关闭智能手机的自动对焦功能，以确保焦距不变。

为了获得更好的重建效果，尽量从多个不同的角度拍摄物体，尤其是场景中细小而复杂的部分。
事实上，SuGaR 能够重建非常细小和复杂的物体，但如果这些细小物体在训练图像中没有被充分覆盖，只从一个方向可见，则可能会出现一些伪影。

要将视频转换为图片，您可以安装 ffmpeg 并运行以下命令：

ffmpeg -i <视频文件路径> -qscale:v 1 -qmin 1 -vf fps=<FPS> %04d.jpg

其中 <FPS> 是您希望的视频图像采样率。FPS 值为 1 表示每秒采样一张图像。我们建议根据视频长度调整采样率，使采样的图像数量在 100 到 300 张之间。

请先安装最新版本的 COLMAP（最好支持 CUDA），并将您想要使用的图像放入目录 <location>/input 中。然后，从原始的 Gaussian Splatting 实现中运行脚本 gaussian_splatting/convert.py，以使用 COLMAP 从图像中计算相机位姿。更多详情请参阅原始的 3D Gaussian Splatting 仓库。

python gaussian_splatting/convert.py -s <location>

有时 COLMAP 无法将所有图像重建为同一个模型，从而产生多个子模型。较小的子模型通常只包含少数几张图像。然而，默认情况下，脚本 convert.py 只会对第一个子模型应用去畸变处理，而这个子模型可能只包含少量图像。

如果是这种情况，一个简单的解决方法是只保留最大的子模型，丢弃其他子模型。为此，请打开包含输入图像的源目录，然后进入子目录 <Source_directory>/distorted/sparse/。您应该会看到几个名为 0/、1/ 等的子目录，每个子目录都包含一个子模型。删除除包含最大文件的子目录之外的所有子目录，并将其重命名为 0/。然后再次运行 convert.py 脚本，但跳过匹配步骤：

python gaussian_splatting/convert.py -s <location> --skip_matching

注意：如果这些子模型有共同的已注册图像，可以在后处理阶段使用 COLMAP 将它们合并为一个模型；然而，合并子模型需要在合并后运行另一次全局光束平差，这可能会非常耗时。

我们建议使用较新的 DN-一致性正则化以获得最佳质量的网格。

不过，论文中展示的结果是在以下情况下得到的：对于以物体为中心的场景使用密度正则化，而对于背景较为复杂的场景（如 Mip-NeRF 360 数据集）则使用 SDF 正则化。

正如我们在论文中所解释的那样，密度正则化最为简单，且在场景中物体居中时效果较好。SDF 提供了更强的正则化作用，尤其是在背景区域。因此，在标准数据集上，SDF 正则化的指标通常更高。然而，对于用环绕物体四周拍摄的图像来重建场景中居中的物体时，相对简单的密度正则化往往能生成比 SDF 更好的网格。

DN-一致性正则化是一种新的正则化方法，它 (a) 在使用密度正则化的同时，强制高斯分布与场景表面对齐；同时 (b) 强制深度梯度与法线图之间的一致性——这两者都是通过 3D 高斯分布渲染出来的。
如论文所述，高斯分布的法线被定义为该高斯分布协方差矩阵的最短轴。
这种正则化方法能够生成最高质量的网格。

如果您发现网格上有孔洞，这意味着 Poisson 网格的清理步骤对您的场景过于激进。您可以通过修改 sugar_extractors/coarse_mesh.py 文件第 43 行来降低用于清理的阈值 vertices_density_quantile。例如，您可以将这一行从

  vertices_density_quantile = 0.1

改为

  vertices_density_quantile = 0.

根据您的场景，Poisson 重建所使用的默认超参数可能相对于高斯分布的尺寸来说过于精细。这样一来，高斯分布就有可能在网格上显现出来，从而导致网格表面出现杂乱的椭圆形凸起。 这种情况可能发生在相机轨迹非常靠近简单的前景物体时。
要解决这个问题，您可以降低 Poisson 重建的深度 poisson_depth，方法是修改 sugar_extractors/coarse_mesh.py 文件第 42 行。
例如，您可以将第 42 行从

  poisson_depth = 10

改为

  poisson_depth = 7

如果效果仍不理想，您也可以尝试 poisson_depth = 6 或 poisson_depth = 8。

正如原始 3D Gaussian Splatting 仓库 所述，该方法适用于重建合理尺度的场景。对于重建规模更大的数据集（如城市街区），原作者建议降低高斯分布位置和缩放因子的学习率。场景越庞大，这些学习率就应该越低。

对于 SuGaR 来说，当重建非常大的场景时，也应相应降低这些学习率。此外，正如我们在论文补充材料中所解释的那样，在从高斯分布中提取具有最优顶点分布的网格时，我们实际上会进行两次 Poisson 重建：一次针对“前景”高斯分布，一次针对“背景”高斯分布。“前景”高斯分布是指位于预定义边界框内的高斯分布，“背景”高斯分布则是指位于该边界框外的高斯分布。

默认情况下，此边界框被计算为所有相机中心的包围盒。这种通用方法与原始 3D Gaussian Splatting 调整学习率的方式是一致的。我们在论文及演示视频中展示的所有重建均使用了这一默认边界框。

然而，在某些特定情况下，此边界框可能并不理想，尤其是当用户希望以高细节重建场景中某个特定物体，或者场景非常庞大，又或者相机中心距离场景十分遥远时。用户可以自由地通过 --bboxmin 和 --bboxmax 参数向 train.py 脚本提供自定义边界框。请注意，边界框必须以字符串形式提供，格式为 "(x,y,z)"，其中 x、y 和 z 分别表示边界框最小和最大点的坐标。