[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Anttwo--SuGaR":3,"tool-Anttwo--SuGaR":62},[4,18,26,35,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,2,"2026-04-18T11:18:24",[14,15,13],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":32,"last_commit_at":41,"category_tags":42,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[43,13,15,14],"插件",{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[52,15,13,14],"语言模型",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,61],"视频",{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":68,"readme_en":69,"readme_zh":70,"quickstart_zh":71,"use_case_zh":72,"hero_image_url":73,"owner_login":74,"owner_name":75,"owner_avatar_url":76,"owner_bio":77,"owner_company":78,"owner_location":79,"owner_email":80,"owner_twitter":81,"owner_website":82,"owner_url":83,"languages":84,"stars":125,"forks":126,"last_commit_at":127,"license":128,"difficulty_score":129,"env_os":130,"env_gpu":131,"env_ram":132,"env_deps":133,"category_tags":143,"github_topics":145,"view_count":32,"oss_zip_url":80,"oss_zip_packed_at":80,"status":17,"created_at":155,"updated_at":156,"faqs":157,"releases":187},9052,"Anttwo\u002FSuGaR","SuGaR","[CVPR 2024] Official PyTorch implementation of SuGaR: Surface-Aligned Gaussian Splatting for Efficient 3D Mesh Reconstruction and High-Quality Mesh Rendering","SuGaR 是一款专为 3D 内容创作打造的高效工具，旨在解决从\"3D 高斯泼溅（3D Gaussian Splatting）”技术中难以提取高质量网格模型的难题。虽然 3D 高斯泼溅能以极快速度生成逼真的场景渲染，但其生成的数百万个微小高斯球通常杂乱无章，无法直接用于传统的建模、动画或游戏引擎中。\n\nSuGaR 通过引入一种创新的正则化项，引导这些高斯球紧密贴合物体表面排列，从而能够利用泊松重建算法快速提取出细节丰富且拓扑结构完整的 3D 网格。更独特的是，它支持构建“网格 + 表面高斯”的混合表示，将高斯球绑定在网格表面。这意味着用户可以在 Blender、Unity 或 Unreal Engine 等主流软件中，像操作普通模型一样对场景进行编辑、雕刻、绑定骨骼、制作动画或重新打光，而无需直接处理复杂的高斯数据。\n\n相比传统方法需要数小时的处理时间，SuGaR 能在几分钟内完成这一过程，同时在渲染质量上实现了更优的表现。这款工具非常适合计算机视觉研究人员、3D 开发者以及数字艺术家使用，帮助他们轻松地将高保真的扫描数据转化为可交互、可编辑的资产，极大地简化了从实景重建到内容创作的流","SuGaR 是一款专为 3D 内容创作打造的高效工具，旨在解决从\"3D 高斯泼溅（3D Gaussian Splatting）”技术中难以提取高质量网格模型的难题。虽然 3D 高斯泼溅能以极快速度生成逼真的场景渲染，但其生成的数百万个微小高斯球通常杂乱无章，无法直接用于传统的建模、动画或游戏引擎中。\n\nSuGaR 通过引入一种创新的正则化项，引导这些高斯球紧密贴合物体表面排列，从而能够利用泊松重建算法快速提取出细节丰富且拓扑结构完整的 3D 网格。更独特的是，它支持构建“网格 + 表面高斯”的混合表示，将高斯球绑定在网格表面。这意味着用户可以在 Blender、Unity 或 Unreal Engine 等主流软件中，像操作普通模型一样对场景进行编辑、雕刻、绑定骨骼、制作动画或重新打光，而无需直接处理复杂的高斯数据。\n\n相比传统方法需要数小时的处理时间，SuGaR 能在几分钟内完成这一过程，同时在渲染质量上实现了更优的表现。这款工具非常适合计算机视觉研究人员、3D 开发者以及数字艺术家使用，帮助他们轻松地将高保真的扫描数据转化为可交互、可编辑的资产，极大地简化了从实景重建到内容创作的流程。","\u003Cdiv align=\"center\">\n\n# SuGaR: Surface-Aligned Gaussian Splatting for Efficient 3D Mesh Reconstruction and High-Quality Mesh Rendering\n\n\u003Cfont size=\"4\">\nCVPR 2024\n\u003C\u002Ffont>\n\u003Cbr>\n\n\u003Cfont size=\"4\">\n\u003Ca href=\"https:\u002F\u002Fanttwo.github.io\u002F\" style=\"font-size:100%;\">Antoine Guédon\u003C\u002Fa> \n\u003Ca href=\"https:\u002F\u002Fvincentlepetit.github.io\u002F\" style=\"font-size:100%;\">Vincent Lepetit\u003C\u002Fa> \n\u003C\u002Ffont>\n\u003Cbr>\n\n\u003Cfont size=\"4\">\nLIGM, Ecole des Ponts, Univ Gustave Eiffel, CNRS\n\u003C\u002Ffont>\n\n| \u003Ca href=\"https:\u002F\u002Fanttwo.github.io\u002Fsugar\u002F\">Webpage\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2311.12775\">arXiv\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender add-on\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=MAkFyWfiBQo\">Presentation video\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=YbjE0wnw67I\">Viewer video\u003C\u002Fa> |\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_f88c483a5a19.gif\" alt=\"walk.gif\" width=\"350\"\u002F>\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_32131941ca56.gif\" alt=\"attack.gif\" width=\"350\"\u002F> \u003Cbr>\n\u003Cb>Our method extracts meshes from 3D Gaussian Splatting reconstructions and builds hybrid representations \u003Cbr>that enable easy composition and animation in Gaussian Splatting scenes by manipulating the mesh.\u003C\u002Fb>\n\u003C\u002Fdiv>\n\n## Abstract\n\n_We propose a method to allow precise and extremely fast mesh extraction from \u003Ca href=\"https:\u002F\u002Frepo-sam.inria.fr\u002Ffungraph\u002F3d-gaussian-splatting\u002F\">3D Gaussian Splatting (SIGGRAPH 2023)\u003C\u002Fa>.\nGaussian Splatting has recently become very popular as it yields realistic rendering while being significantly faster to train than NeRFs. It is however challenging to extract a mesh from the millions of tiny 3D Gaussians as these Gaussians tend to be unorganized after optimization and no method has been proposed so far.\nOur first key contribution is a regularization term that encourages the 3D Gaussians to align well with the surface of the scene.\nWe then introduce a method that exploits this alignment to sample points on the real surface of the scene and extract a mesh from the Gaussians using Poisson reconstruction, which is fast, scalable, and preserves details, in contrast to the Marching Cubes algorithm usually applied to extract meshes from Neural SDFs.\nFinally, we introduce an optional refinement strategy that binds Gaussians to the surface of the mesh, and jointly optimizes these Gaussians and the mesh through Gaussian splatting rendering. This enables easy editing, sculpting, rigging, animating, or relighting of the Gaussians using traditional softwares (Blender, Unity, Unreal Engine, etc.) by manipulating the mesh instead of the Gaussians themselves.\nRetrieving such an editable mesh for realistic rendering is done within minutes with our method, compared to hours with the state-of-the-art method on neural SDFs, while providing a better rendering quality in terms of PSNR, SSIM and LPIPS._\n\n\u003Cdiv align=\"center\">\n\u003Cb>Hybrid representation (Mesh + Gaussians on the surface)\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_d4d0b3b22fbd.gif\" alt=\"garden_hybrid.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_f5a25af6a79c.gif\" alt=\"kitchen_hybrid.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_0a2030aeeab8.gif\" alt=\"counter_hybrid.gif\" width=\"250\"\u002F>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_bd9323a524ec.gif\" alt=\"playroom_hybrid.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_6b38f719abc4.gif\" alt=\"qant03_hybrid.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_2d289293c862.gif\" alt=\"_hybrid.gif\" width=\"102\"\u002F>\u003Cbr>\n\u003Cb>Underlying mesh without texture\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_771ddc756807.gif\" alt=\"garden_notex.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_28cfe88f2c00.gif\" alt=\"kitchen_notex.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_aa75a773a3fe.gif\" alt=\"counter_notex.gif\" width=\"250\"\u002F>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_75b219b4162c.gif\" alt=\"playroom_notex.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_a8eafc9ed3dd.gif\" alt=\"qant03_notex.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_d2d22b7d61a9.gif\" alt=\"dukemon_notex.gif\" width=\"102\"\u002F>\u003Cbr>\n\u003C\u002Fdiv>\n\n\n## BibTeX\n\n```\n@article{guedon2023sugar,\n  title={SuGaR: Surface-Aligned Gaussian Splatting for Efficient 3D Mesh Reconstruction and High-Quality Mesh Rendering},\n  author={Gu{\\'e}don, Antoine and Lepetit, Vincent},\n  journal={CVPR},\n  year={2024}\n}\n```\n\n## Updates and To-do list\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Updates\u003C\u002Fspan>\u003C\u002Fsummary>\n\u003Cul>\n  \u003Cli>\u003Cb>[09\u002F18\u002F2024]\u003C\u002Fb> Improved the quality of the extracted meshes with the new `dn_consistency` regularization method, and added compatibility with the new Blender add-on for composition and animation. \u003C\u002Fli>\n  \u003Cli>\u003Cb>[01\u002F09\u002F2024]\u003C\u002Fb> Added a dedicated, real-time viewer to let users visualize and navigate in the reconstructed scenes (hybrid representation, textured mesh and wireframe mesh).\u003C\u002Fli>\n  \u003Cli>\u003Cb>[12\u002F20\u002F2023]\u003C\u002Fb> Added a short notebook showing how to render images with the hybrid representation using the Gaussian Splatting rasterizer.\u003C\u002Fli>\n  \u003Cli>\u003Cb>[12\u002F18\u002F2023]\u003C\u002Fb> Code release.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003C\u002Fdetails>\u003Cbr>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">To-do list\u003C\u002Fspan>\u003C\u002Fsummary>\n\u003Cul>\n  \u003Cli>\u003Cb>Viewer:\u003C\u002Fb> Add option to load the postprocessed mesh.\u003C\u002Fli>\n  \u003Cli>\u003Cb>Mesh extraction:\u003C\u002Fb> Add the possibility to edit the extent of the background bounding box.\u003C\u002Fli>\n  \u003Cli>\u003Cb>Tips&Tricks:\u003C\u002Fb> Add to the README.md file (and the webpage) some tips and tricks for using SuGaR on your own data and obtain better reconstructions (see the tips provided by user kitmallet).\u003C\u002Fli>\n  \u003Cli>\u003Cb>Improvement:\u003C\u002Fb> Add an \u003Ccode>if\u003C\u002Fcode> block to \u003Ccode>sugar_extractors\u002Fcoarse_mesh.py\u003C\u002Fcode> to skip foreground mesh reconstruction and avoid triggering an error if no surface point is detected inside the foreground bounding box. This can be useful for users that want to reconstruct \"\u003Ci>background scenes\u003C\u002Fi>\". \u003C\u002Fli>\n  \u003Cli>\u003Cb>Using precomputed masks with SuGaR:\u003C\u002Fb> Add a mask functionality to the SuGaR optimization, to allow the user to mask out some pixels in the training images (like white backgrounds in synthetic datasets).\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>Using SuGaR with Windows:\u003C\u002Fb> Adapt the code to make it compatible with Windows. Due to path-writing conventions, the current code is not compatible with Windows. \n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>Synthetic datasets:\u003C\u002Fb> Add the possibility to use the NeRF synthetic dataset (which has a different format than COLMAP scenes)\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>Composition and animation:\u003C\u002Fb> Finish to clean the code for composition and animation, and add it to the \u003Ccode>sugar_scene\u002Fsugar_compositor.py\u003C\u002Fcode> script.\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>Composition and animation:\u003C\u002Fb> Make a tutorial on how to use the scripts in the \u003Ccode>blender\u003C\u002Fcode> directory and the \u003Ccode>sugar_scene\u002Fsugar_compositor.py\u003C\u002Fcode> class to import composition and animation data into PyTorch and apply it to the SuGaR hybrid representation.\n  \u003C\u002Fli>\n  \u003C!-- \u003Cli>\u003Cb>Improvement:\u003C\u002Fb> Implement a simple method to avoid artifacts when reconstructing thin objects with poor coverage\u002Fvisibility in the training images.\u003C\u002Fli>\n  \u003C\u002Fli> -->\n\u003C\u002Ful>\n\u003C\u002Fdetails>\n\n## Overview\n\nAs we explain in the paper, SuGaR optimization starts with first optimizing a 3D Gaussian Splatting model for 7k iterations with no additional regularization term. Consequently, the current implementation contains a version of the original \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting code\u003C\u002Fa>, and we built our model as a wrapper of a vanilla 3D Gaussian Splatting model.\nPlease note that, even though this wrapper implementation is convenient for many reasons, it may not be the most optimal one for memory usage.\n\nThe full SuGaR pipeline consists of 4 main steps, and an optional one:\n1. **Short vanilla 3DGS optimization**: optimizing a vanilla 3D Gaussian Splatting model for 7k iterations, in order to let Gaussians position themselves in the scene.\n2. **SuGaR optimization**: optimizing Gaussians alignment with the surface of the scene.\n3. **Mesh extraction**: extracting a mesh from the optimized Gaussians.\n4. **SuGaR refinement**: refining the Gaussians and the mesh together to build a hybrid Mesh+Gaussians representation.\n5. **Textured mesh extraction (Optional)**: extracting a traditional textured mesh from the refined SuGaR model as a tool for visualization, composition and animation in Blender using our \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender add-on\u003C\u002Fa>.\n\nWe provide a dedicated script for each of these steps, as well as a script `train_full_pipeline.py` that runs the entire pipeline. We explain how to use this script in the next sections. \u003Cbr>\n\n\u003Cdiv align=\"center\">\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_7573cc8f9ed4.png\" alt=\"blender_edit.png\" height=\"200\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_32131941ca56.gif\" alt=\"attack.gif\" height=\"200\"\u002F>\n\u003Cbr>\u003Cb>You can visualize, edit, combine or animate the reconstructed textured meshes in Blender \u003Ci>(left)\u003C\u002Fi> \u003Cbr>and render the result with SuGaR \u003Ci>(right)\u003C\u002Fi> thanks to our \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender add-on\u003C\u002Fa>.\u003C\u002Fb>\u003Cbr>\n\u003C\u002Fdiv>\u003Cbr>\n\nPlease note that the final step, _Textured mesh extraction_, is optional but is enabled by default in the `train_full_pipeline.py` script. Indeed, it is very convenient to have a traditional textured mesh for visualization, composition and animation using traditional softwares such as \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender\u003C\u002Fa>. If you installed Nvdiffrast as described below, this step should only take a few seconds anyway.\n\n\u003Cdiv align=\"center\">\n\u003Cb>Hybrid representation (Mesh + Gaussians on the surface)\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_c93a15ea88b9.png\" alt=\"garden_hybrid.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_00fcce24199f.png\" alt=\"kitchen_hybrid.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_4ce70cff4b3c.png\" alt=\"qant03_hybrid.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_9c06f29fc1f7.png\" alt=\"_hybrid.gif\" height=\"135\"\u002F>\u003Cbr>\n\u003Cb>Underlying mesh with a traditional colored UV texture\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_86b89032627d.png\" alt=\"garden_notex.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_1db4ecff95d4.png\" alt=\"kitchen_notex.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_7d48eaf3b2d3.png\" alt=\"qant03_notex.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_d36d6c222154.png\" alt=\"dukemon_notex.gif\" height=\"135\"\u002F>\u003Cbr>\n\u003C\u002Fdiv>\u003Cbr>\n\nBelow is another example of a scene showing a robot with a black and specular material. The following images display the hybrid representation (Mesh + Gaussians on the surface), the mesh with a traditional colored UV texture, and a depth map of the mesh:\n\u003Cdiv align=\"center\">\n\u003Cb>Hybrid representation - Textured mesh - Depth map of the mesh\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_2c257f1378d2.png\" alt=\"alpha_hybrid.png\" height=\"400\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_80a222e655d9.png\" alt=\"alpha_texture.gif\" height=\"400\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_e8f00083db7b.png\" alt=\"alpha_depth.gif\" height=\"400\"\u002F>\n\u003C\u002Fdiv>\n\n## Installation\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Click here to see content.\u003C\u002Fspan>\u003C\u002Fsummary>\n\n### 0. Requirements\n\nThe software requirements are the following:\n- Conda (recommended for easy setup)\n- C++ Compiler for PyTorch extensions\n- CUDA toolkit 11.8 for PyTorch extensions\n- C++ Compiler and CUDA SDK must be compatible\n\nPlease refer to the original \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting repository\u003C\u002Fa> for more details about requirements.\n\n### 1. Clone the repository\n\nStart by cloning this repository:\n\n```shell\n# HTTPS\ngit clone https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR.git --recursive\n```\n\nor\n\n```shell\n# SSH\ngit clone git@github.com:Anttwo\u002FSuGaR.git --recursive\n```\n\n### 2. Creating the Conda environment\n\nTo create and activate the Conda environment with all the required packages, go inside the `SuGaR\u002F` directory and run the following command:\n\n```shell\npython install.py\nconda activate sugar\n```\n\nThis script will automatically create a Conda environment named `sugar` and install all the required packages. It will also automatically install the \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting\u003C\u002Fa> rasterizer as well as the \u003Ca href=\"https:\u002F\u002Fnvlabs.github.io\u002Fnvdiffrast\u002F\">Nvdiffrast\u003C\u002Fa> library for faster mesh rasterization.\n\nIf you encounter any issues with the installation, you can try to follow the detailed instructions below to install the required packages manually.\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">\nDetailed instructions for manual installation\n\u003C\u002Fspan>\u003C\u002Fsummary>\n\n#### a) Install the required Python packages\nTo install the required Python packages and activate the environment, go inside the `SuGaR\u002F` directory and run the following commands:\n\n```shell\nconda env create -f environment.yml\nconda activate sugar\n```\n\nIf this command fails to create a working environment, you can try to install the required packages manually by running the following commands:\n```shell\nconda create --name sugar -y python=3.9\nconda activate sugar\nconda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.8 -c pytorch -c nvidia\nconda install -c fvcore -c iopath -c conda-forge fvcore iopath\nconda install pytorch3d==0.7.4 -c pytorch3d\nconda install -c plotly plotly\nconda install -c conda-forge rich\nconda install -c conda-forge plyfile==0.8.1\nconda install -c conda-forge jupyterlab\nconda install -c conda-forge nodejs\nconda install -c conda-forge ipywidgets\npip install open3d\npip install --upgrade PyMCubes\n```\n\n#### b) Install the Gaussian Splatting rasterizer\n\nRun the following commands inside the `SuGaR` directory to install the additional Python submodules required for Gaussian Splatting:\n\n```shell\ncd gaussian_splatting\u002Fsubmodules\u002Fdiff-gaussian-rasterization\u002F\npip install -e .\ncd ..\u002Fsimple-knn\u002F\npip install -e .\ncd ..\u002F..\u002F..\u002F\n```\nPlease refer to the \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting repository\u003C\u002Fa> for more details.\n\n#### c) (Optional) Install Nvdiffrast for faster Mesh Rasterization\n\nInstalling Nvdiffrast is optional but will greatly speed up the textured mesh extraction step, from a few minutes to less than 10 seconds.\n\n```shell\ngit clone https:\u002F\u002Fgithub.com\u002FNVlabs\u002Fnvdiffrast\ncd nvdiffrast\npip install .\ncd ..\u002F\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n\n## Quick Start\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Click here to see content.\u003C\u002Fspan>\u003C\u002Fsummary>\n\n### Training from scratch\n\nYou can run the following single script to optimize a full SuGaR model from scratch using a COLMAP dataset:\n\n```shell\npython train_full_pipeline.py -s \u003Cpath to COLMAP dataset> -r \u003C\"dn_consistency\", \"density\" or \"sdf\"> --high_poly True --export_obj True\n```\n\nYou can choose the regularization method with the `-r` argument, which can be `\"dn_consistency\"`, `\"density\"` or `\"sdf\"`. We recommend using the newer `\"dn_consistency\"` regularization for best quality meshes, but the results presented in the paper were obtained with the `\"density\"` regularization for object-centered scenes and `\"sdf\"` for scenes with a challenging background, such as the Mip-NeRF 360 dataset.\n\nYou can also replace the `--high_poly True` argument with `--low_poly True` to extract a mesh with 200k vertices instead of 1M, and 6 Gaussians per triangle instead of 1.\n\nMoreover, you can add `--refinement_time \"short\"`, `\"medium\"` or `\"long\"` to set the time spent on the refinement step. The default is `\"long\"` (15k iterations), but `\"short\"` (2k iterations) can be enough to produce a good-looking hybrid representation.\n\nFinally, you can choose to export a traditional textured mesh with the `--export_obj` argument. This step is optional but is enabled by default in the `train_full_pipeline.py` script, as the mesh is required for using the \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender add-on\u003C\u002Fa> and editing, combining or animating scenes in Blender.\n\nResults are saved in the `output\u002F` directory.\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Please click here to see the most important arguments for the `train_full_pipeline.py` script.\u003C\u002Fspan>\u003C\u002Fsummary>\n\n| Parameter | Type | Description |\n| :-------: | :--: | :---------: |\n| `--scene_path` \u002F `-s`   | `str` | Path to the source directory containing a COLMAP dataset.|\n| `--gs_output_dir` | `str` | Path to the checkpoint directory of a vanilla 3D Gaussian Splatting model. If no path is provided, the script will start from scratch and first optimize a vanilla 3DGS model. |\n| `--regularization_type` \u002F `-r` | `str` | Type of regularization to use for aligning Gaussians. Can be `\"dn_consistency\"`, `\"density\"` or `\"sdf\"`. We recommend using the newer `\"dn_consistency\"` regularization for best quality meshes. |\n| `--eval` | `bool` | If True, performs an evaluation split of the training images. Default is `True`. |\n| `--low_poly` | `bool` | If True, uses the standard config for a low poly mesh, with `200_000` vertices and `6` Gaussians per triangle. |\n| `--high_poly` | `bool` | If True, uses the standard config for a high poly mesh, with `1_000_000` vertices and `1` Gaussian per triangle. |\n| `--refinement_time` | `str` | Default configs for time to spend on refinement. Can be `\"short\"` (2k iterations), `\"medium\"` (7k iterations) or `\"long\"` (15k iterations). |\n| `--export_ply` | `bool` | If True, export a `.ply` file with the refined 3D Gaussians at the end of the training. This file can be large (+\u002F- 500MB), but is needed for using 3DGS viewers. Default is `True`. |\n| `--export_obj` \u002F `-t` | `bool` | If True, will optimize and export a traditional textured mesh as an `.obj` file from the refined SuGaR model, after refinement. Computing a traditional color UV texture should just take a few seconds with Nvdiffrast. Default is `True`. |\n| `--square_size` | `int` | Size of the square allocated to each pair of triangles in the UV texture. Increase for higher texture resolution. Please decrease if you encounter memory issues. Default is `8`. |\n|`--white_background` | `bool` | If True, the background of the images will be set to white. Default is `False`. |\n\n\n\u003C\u002Fdetails>\n\u003Cbr>\n\nAs we explain in the paper, this script extracts a mesh in 30 minutes on average on a single GPU. After mesh extraction, the refinement time only takes a few minutes when using `--refinement_time \"short\"`, but can be much longer when using `--refinement_time \"long\"`. A short refinement time is enough to produce a good-looking hybrid representation in most cases.\n\nPlease note that the optimization time may vary depending on the complexity of the scene and the GPU used. Moreover, the current implementation splits the optimization into modular scripts that can be run separately so it reloads the data at each part, which is not optimal and takes several minutes.\n\nPlease see the `train_full_pipeline.py` for more details on all the command line arguments.\n\n### Training from a vanilla Gaussian Splatting model\n\nIf you have already trained a \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">vanilla Gaussian Splatting model\u003C\u002Fa> for a scene (we recommend training it for 7k iterations), you can use the `--gs_output_dir` argument to provide the path to the output directory of the vanilla Gaussian Splatting model. This will skip the first part of the optimization and directly load the Gaussians from the vanilla model:\n\n```shell\npython train_full_pipeline.py -s \u003Cpath to COLMAP dataset> -r \u003C\"dn_consistency\", \"density\" or \"sdf\"> --high_poly True --export_obj True --gs_output_dir \u003Cpath to the Gaussian Splatting output directory>\n```\n\n\u003C\u002Fdetails>\n\n\n## Visualize a SuGaR model in real-time\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Click here to see content.\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nAfter optimizing a SuGaR model, you can visualize the model in real-time using the 3D Gaussian Splatting viewer of your choice. \u003Cbr>\nIndeed, after optimization, we automatically export a `.ply` file in the `.\u002Foutput\u002Frefined_ply\u002F` directory, containing the refined 3D Gaussians of SuGaR's hybrid representation and compatible with any 3DGS viewer.\nFor instance, you can use the viewer provided in the original implementation of \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting\u003C\u002Fa>, or the awesome \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fplaycanvas\u002Fsupersplat\">SuperSplat viewer\u003C\u002Fa>. \u003Cbr>\nAn online, \u003Ca href=\"https:\u002F\u002Fplaycanvas.com\u002Fsupersplat\u002Feditor\">in-browser version of SuperSplat\u003C\u002Fa> is also available.\n\nWe also propose a dedicated real-time viewer that allows you to visualize not only the refined 3D Gaussians but also the textured mesh and the wireframe mesh. Please see the instructions below to install and use this viewer.\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Please click here to see the instructions for installing and using our real-time viewer.\u003C\u002Fspan>\u003C\u002Fsummary>\n\nPlease find \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=YbjE0wnw67I\">here\u003C\u002Fa> a short video illustrating how to use the viewer.\n\n### 1. Installation\n\n*The viewer is currently built for Linux and Mac OS. It is not compatible with Windows. For Windows users, we recommend to use WSL2 (Windows Subsystem for Linux), as it is very easy to install and use. Please refer to the \u003Ca href=\"https:\u002F\u002Fdocs.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall-win10\">official documentation\u003C\u002Fa> for more details.\u003Cbr> We thank \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fmkkellogg\u002FGaussianSplats3D\">Mark Kellogg for his awesome 3D Gaussian Splatting implementation for Three.js\u003C\u002Fa>, which we used for building this viewer.*\n\nPlease start by installing the latest versions of Node.js (such as 21.x) and npm.\nA simple way to do this is to run the following commands (using aptitude):\n\n```shell\ncurl -fsSL https:\u002F\u002Fdeb.nodesource.com\u002Fsetup_21.x | sudo -E bash -\nsudo apt-get install -y nodejs\nsudo apt-get install aptitude\nsudo aptitude install -y npm\n```\n\nThen, go inside the `.\u002Fsugar_viewer\u002F` directory and run the following commands:\n\n```shell\nnpm install\ncd ..\n```\n\n### 2. Usage\n\nFirst, make sure you have exported a `.ply` file and an `.obj` file using the `train.py` script. The `.ply` file contains the refined 3D Gaussians, and the `.obj` file contains the textured mesh. These files are exported by default when running the `train.py` script, so if you ran the code with default values for `--export_ply` and `--export_obj`, you should be good to go.\n\nThe ply file should be located in `.\u002Foutput\u002Frefined_ply\u002F\u003Cyour scene name>\u002F`. Then, just run the following command in the root directory to start the viewer:\n\n```shell\npython run_viewer.py -p \u003Cpath to the .ply file>\n```\nPlease make sure your `.ply` file is located in the right folder, and use a relative path starting with `.\u002Foutput\u002Frefined_ply`.\nThis command will redirect you to a local URL. Click on the link to open the viewer in your browser. Click the icons on the top right to switch between the different representations (hybrid representation, textured mesh, wireframe mesh). Use the mouse to rotate the scene, and the mouse wheel to zoom in and out. \n\n\u003C\u002Fdetails>\n\n\u003Cdiv align=\"center\" >\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_756ea471a36b.png\" alt=\"viewer_example.png\" width=\"800\"\u002F>\n\u003C\u002Fdiv>\u003Cbr>\n\nWe also recommend using our \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender add-on\u003C\u002Fa> to create animations and video clips of SuGaR representations. \nMore specifically, the add-on allows you to import SuGaR meshes and visualize, edit, combine or animate them in Blender.\nFinally, you can render the result using the 3DGS rasterizer, which provides high-quality and realistic rendering of SuGaR's hybrid representation.\n\n\u003C\u002Fdetails>\n\n\n## Rendering, composition and animation with Blender\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Click here to see content.\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nThe `view_sugar_results.ipynb` notebook and the `metrics.py` script provides examples of how to load a refined SuGaR model for rendering a scene.\n\nWe also provide a \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender add-on\u003C\u002Fa> for editing, combining, and animating SuGaR meshes within Blender and render the result using SuGaR's hybrid representations. Meshes are located in the `.\u002Foutput\u002Frefined_mesh\u002F` directory.\n\nPlease refer to the Blender add-on repository for more details on how to use the add-on and create a rendering package for SuGaR.\nAfter preparing the rendering package with Blender, which should be a `.JSON` file located in the `.\u002Foutput\u002Fblender\u002Fpackage\u002F` directory, you can render the scene using the `render_blender_scene.py` script:\n\n```shell\npython render_blender_scene.py -p \u003CPath to the rendering package>\n```\n\nThe rendered images will be saved in the `.\u002Foutput\u002Fblender\u002Frenders\u002F` directory.\u003Cbr>\nFeel free to adjust the arguments of the script to adjust the rendering quality if you observe artifacts in the images.\nSpecifically, you can switch to `--adaptation_method simple` or reduce `deformation_threshold` to mitigate artifacts in the rendering.\nPlease refer to the script for more details on the command line arguments.\n\n\u003C\u002Fdetails>\n\n\n## Evaluation\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Click here to see content.\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nTo evaluate the quality of the reconstructions, we provide a script `metrics.py` that computes the PSNR, SSIM and LPIPS metrics on test images. Start by optimizing SuGaR models for the desired scenes and a regularization method (`\"dn_consistency\"`, `\"density\"` or `\"sdf\"`), then create a `.json` config file containing the paths to the scenes in the following format: `{source_images_dir_path: vanilla_gaussian_splatting_checkpoint_path}`.\n\nFinally, run the script as follows:\n\n```shell\npython metrics.py --scene_config \u003CPath to the .json file> -r \u003C\"sdf\" or \"density\"> \n```\n\nResults are saved in a `.json` file in the `output\u002Fmetrics\u002F` directory. \nPlease refer to the script for more details on the command line arguments.\n\n\u003C\u002Fdetails>\n\n## Tips for using SuGaR on your own data and obtain better reconstructions\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">Click here to see content.\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">1. Capture images or videos that cover the entire surface of the scene\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nUsing a smartphone or a camera, capture images or a video that cover the entire surface of the 3D scene you want to reconstruct. The easiest way to do this is to move around the scene while recording a video. Try to move slowly and smoothly in order to avoid motion blur. For consistent reconstruction and easier camera pose estimation with COLMAP, maintaining a uniform focal length and a constant exposure time is also important. We recommend to disable auto-focus on your smartphone to ensure that the focal length remains constant.\n\nFor better reconstructions, try to cover objects from several and different angles, especially for thin and detailed parts of the scene. \nIndeed, SuGaR is able to reconstruct very thin and detailed objects, but some artifacts may appear if these thin objects are not covered enough and are visible only from one side in the training images.\n\nTo convert a video to images, you can install `ffmpeg` and run the following command:\n```shell\nffmpeg -i \u003CPath to the video file> -qscale:v 1 -qmin 1 -vf fps=\u003CFPS> %04d.jpg\n```\nwhere `\u003CFPS>` is the desired sampling rate of the video images. An FPS value of 1 corresponds to sampling one image per second. We recommend to adjust the sampling rate to the length of the video, so that the number of sampled images is between 100 and 300.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">2. Estimate camera poses with COLMAP\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nPlease first install a recent version of COLMAP (ideally CUDA-powered) and make sure to put the images you want to use in a directory `\u003Clocation>\u002Finput`. Then, run the script `gaussian_splatting\u002Fconvert.py` from the original Gaussian splatting implementation to compute the camera poses from the images using COLMAP. Please refer to the original \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting repository\u003C\u002Fa> for more details.\n\n```shell\npython gaussian_splatting\u002Fconvert.py -s \u003Clocation>\n```\n\nSometimes COLMAP fails to reconstruct all images into the same model and hence produces multiple sub-models. The smaller sub-models generally contain only a few images. However, by default, the script `convert.py` will apply Image Undistortion only on the first sub-model, which may contain only a few images.\n\nIf this is the case, a simple solution is to keep only the largest sub-model and discard the others. To do this, open the source directory containing your input images, then open the sub-directory `\u003CSource_directory>\u002Fdistorted\u002Fsparse\u002F`. You should see several sub-directories named `0\u002F`, `1\u002F`, etc., each containing a sub-model. Remove all sub-directories except the one containing the largest files, and rename it to `0\u002F`. Then, run the script `convert.py` one more time but skip the matching process:\n\n```shell\npython gaussian_splatting\u002Fconvert.py -s \u003Clocation> --skip_matching\n```\n\n_Note: If the sub-models have common registered images, they could be merged into a single model as post-processing step using COLMAP; However, merging sub-models requires to run another global bundle adjustment after the merge, which can be time consuming._\n\u003C\u002Fdetails>\n\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">3. DN-Consistency, Density or SDF? Choose a regularization method that fits your scene\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n**We recommend using the newer DN-Consistency regularization for best quality meshes**.\n\nHowever, the results presented in the paper were obtained with the Density regularization for object-centered scenes and the SDF regularization for scenes with a challenging background, such as the Mip-NeRF 360 dataset.\n\nAs we explain in the paper, the density regularization is the simplest one and works well with objects centered in the scene. The SDF provides a stronger regularization, especially in background regions. \nAs a consequence, the SDF regularization produces higher metrics on standard datasets. \nHowever, for reconstructing an object centered in the scene with images taken from all around the object, the simpler density regularization generally produces a better mesh than SDF.\n\nThe DN-Consistency regularization is a new regularization method that (a) enforces the Gaussians to align with the surface of the scene with the density regularization, while also (b) enforcing the consistency between the gradient of the depth and the normal maps, all rendered using the 3D Gaussians. \u003Cbr>\nAs described in the paper, the normal of a Gaussian is defined as the shortest axis of the covariance matrix of the Gaussian. \u003Cbr> \nThis regularization method provides the best quality meshes.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">4. I have holes in my mesh, what can I do?\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nIf you have holes in your mesh, this means the cleaning step of the Poisson mesh is too aggressive for your scene. You can reduce the treshold `vertices_density_quantile` used for cleaning by modifying line 43 of `sugar_extractors\u002Fcoarse_mesh.py`. For example, you can change this line from\n```python\n  vertices_density_quantile = 0.1\n```\nto\n```python\n  vertices_density_quantile = 0.\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">5. I have messy ellipsoidal bumps on the surface of my mesh, what can I do?\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nDepending on your scene, the default hyperparameters used for Poisson reconstruction may be too fine compared to the size of the Gaussians. Gaussian could then become visible on the mesh, which results in messy ellipsoidal bumps on the surface of the mesh.\nThis could happen if the camera trajectory is very close to a simple foreground object, for example.\u003Cbr>\nTo fix this, you can reduce the depth of Poisson reconstruction `poisson_depth` by modifying line 42 of `sugar_extractors\u002Fcoarse_mesh.py`. \u003Cbr>\nFor example, you can change line 42 from\n```python\n  poisson_depth = 10\n```\nto\n```python\n  poisson_depth = 7\n```\nYou may also try `poisson_depth = 6`, or `poisson_depth = 8` if the result is not satisfying.\n\n\u003C\u002Fdetails>\n\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">6. (Optional) Adapt the scale and the bounding box of the scene\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\nAs it is explained in the original \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting repository\u003C\u002Fa>, the method is expected to reconstruct a scene with reasonable scale. For reconstructing much larger datasets, like a city district, the original authors recommend to lower the learning rates of the positions and scaling factors of the Gaussians. The more extensive the scene, the lower these values should be.\n\nConcerning SuGaR, such learning rates should also be lowered when reconstructing a very large scene. Moreover, as we explain in the supplementary material of the paper, for extracting a mesh from the Gaussians with an optimal repartition of vertices, we apply two Poisson reconstructions in practice: one on _foreground_ Gaussians, and one on _background_ Gaussians. The foreground Gaussians are defined as the Gaussians located inside a predefined bounding box, and the background Gaussians are defined as the Gaussians located outside this bounding box. \n\nBy default, this bounding box is computed as the bounding box of all camera centers. This general approach is coherent with how the original 3D Gaussian Splatting scales the learning rates. We used this default bounding box for all the reconstructions shown in the paper and the presentation video.\n\nHowever, this bounding box might not be optimal in very specific cases, especially when the user wants to reconstruct with high details a very specific object located somewhere in the scene, or if the scene is very large, or if the camera centers are very far from the scene.\nThe user is free to provide a custom bounding box to the `train.py` script, using the parameters `--bboxmin` and `--bboxmax`. Please note that the bounding box must be provided as strings, formatted as `\"(x,y,z)\"`, where `x`, `y` and `z` are the coordinates of the min and max points of the bounding box.\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>","\u003Cdiv align=\"center\">\n\n# SuGaR: 基于表面对齐高斯泼溅的高效3D网格重建与高质量网格渲染\n\n\u003Cfont size=\"4\">\nCVPR 2024\n\u003C\u002Ffont>\n\u003Cbr>\n\n\u003Cfont size=\"4\">\n\u003Ca href=\"https:\u002F\u002Fanttwo.github.io\u002F\" style=\"font-size:100%;\">Antoine Guédon\u003C\u002Fa> \n\u003Ca href=\"https:\u002F\u002Fvincentlepetit.github.io\u002F\" style=\"font-size:100%;\">Vincent Lepetit\u003C\u002Fa> \n\u003C\u002Ffont>\n\u003Cbr>\n\n\u003Cfont size=\"4\">\nLIGM, Ecole des Ponts, Univ Gustave Eiffel, CNRS\n\u003C\u002Ffont>\n\n| \u003Ca href=\"https:\u002F\u002Fanttwo.github.io\u002Fsugar\u002F\">网页\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2311.12775\">arXiv\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender插件\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=MAkFyWfiBQo\">演示视频\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=YbjE0wnw67I\">查看器视频\u003C\u002Fa> |\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_f88c483a5a19.gif\" alt=\"walk.gif\" width=\"350\"\u002F>\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_32131941ca56.gif\" alt=\"attack.gif\" width=\"350\"\u002F> \u003Cbr>\n\u003Cb>我们的方法可以从3D高斯泼溅重建结果中提取网格，并构建混合表示，\u003Cbr>通过操作网格即可轻松地在高斯泼溅场景中进行合成和动画制作。\u003C\u002Fb>\n\u003C\u002Fdiv>\n\n## 摘要\n\n_我们提出了一种方法，能够从\u003Ca href=\"https:\u002F\u002Frepo-sam.inria.fr\u002Ffungraph\u002F3d-gaussian-splatting\u002F\">3D高斯泼溅（SIGGRAPH 2023）\u003C\u002Fa>中精确且极快速地提取网格。  \n高斯泼溅近年来因其在训练速度上显著快于NeRF的同时仍能生成逼真的渲染效果而广受欢迎。然而，从数百万个微小的3D高斯分布中提取网格却极具挑战性：这些高斯分布在优化后往往杂乱无章，目前尚未有相关方法被提出。  \n我们的首要贡献是一种正则化项，它促使3D高斯分布更好地与场景表面对齐。  \n随后，我们提出了一种利用这种对齐特性，在场景的真实表面上采样点，并采用泊松重建算法从高斯分布中提取网格的方法。该方法速度快、可扩展性强且能很好地保留细节，这与通常用于从神经SDF中提取网格的Marching Cubes算法形成了鲜明对比。  \n最后，我们引入了一种可选的精炼策略，将高斯分布绑定到网格表面，并通过高斯泼溅渲染联合优化这些高斯分布和网格。这样一来，用户便可以通过操作网格而非直接操作高斯分布本身，借助传统软件（如Blender、Unity、Unreal Engine等）轻松地对高斯分布进行编辑、雕刻、绑定骨骼、制作动画或重新打光。  \n使用我们的方法，只需几分钟即可获得可用于真实渲染的可编辑网格，而基于神经SDF的最先进方法则需要数小时；同时，我们在PSNR、SSIM和LPIPS等指标上均表现出更优的渲染质量。_\n\n\u003Cdiv align=\"center\">\n\u003Cb>混合表示（网格 + 表面高斯分布）\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_d4d0b3b22fbd.gif\" alt=\"garden_hybrid.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_f5a25af6a79c.gif\" alt=\"kitchen_hybrid.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_0a2030aeeab8.gif\" alt=\"counter_hybrid.gif\" width=\"250\"\u002F>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_bd9323a524ec.gif\" alt=\"playroom_hybrid.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_6b38f719abc4.gif\" alt=\"qant03_hybrid.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_2d289293c862.gif\" alt=\"_hybrid.gif\" width=\"102\"\u002F>\u003Cbr>\n\u003Cb>底层网格（无纹理）\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_771ddc756807.gif\" alt=\"garden_notex.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_28cfe88f2c00.gif\" alt=\"kitchen_notex.gif\" width=\"250\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_aa75a773a3fe.gif\" alt=\"counter_notex.gif\" width=\"250\"\u002F>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_75b219b4162c.gif\" alt=\"playroom_notex.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_a8eafc9ed3dd.gif\" alt=\"qant03_notex.gif\" width=\"323\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_d2d22b7d61a9.gif\" alt=\"dukemon_notex.gif\" width=\"102\"\u002F>\u003Cbr>\n\u003C\u002Fdiv>\n\n\n## BibTeX\n\n```\n@article{guedon2023sugar,\n  title={SuGaR: Surface-Aligned Gaussian Splatting for Efficient 3D Mesh Reconstruction and High-Quality Mesh Rendering},\n  author={Gu{\\'e}don, Antoine and Lepetit, Vincent},\n  journal={CVPR},\n  year={2024}\n}\n```\n\n## 更新与待办事项\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">更新\u003C\u002Fspan>\u003C\u002Fsummary>\n\u003Cul>\n  \u003Cli>\u003Cb>[2024年9月18日]\u003C\u002Fb> 通过新的`dn_consistency`正则化方法提升了提取网格的质量，并增加了与用于合成和动画的新Blender插件的兼容性。\u003C\u002Fli>\n  \u003Cli>\u003Cb>[2024年1月9日]\u003C\u002Fb> 添加了一个专用的实时查看器，供用户可视化并导航重建后的场景（混合表示、带纹理的网格和线框网格）。\u003C\u002Fli>\n  \u003Cli>\u003Cb>[2023年12月20日]\u003C\u002Fb> 添加了一个简短的笔记本示例，展示如何使用高斯泼溅光栅化器渲染混合表示图像。\u003C\u002Fli>\n  \u003Cli>\u003Cb>[2023年12月18日]\u003C\u002Fb> 代码发布。\u003C\u002Fli>\n\u003C\u002Ful>\n\u003C\u002Fdetails>\u003Cbr>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">待办事项\u003C\u002Fspan>\u003C\u002Fsummary>\n\u003Cul>\n  \u003Cli>\u003Cb>查看器：\u003C\u002Fb>增加加载后处理网格的选项。\u003C\u002Fli>\n  \u003Cli>\u003Cb>网格提取：\u003C\u002Fb>增加编辑背景包围盒范围的功能。\u003C\u002Fli>\n  \u003Cli>\u003Cb>技巧与窍门：\u003C\u002Fb>在README.md文件（以及网页）中添加一些关于如何在自有数据上使用SuGaR以获得更好重建效果的技巧与窍门（参考用户kitmallet提供的建议）。\u003C\u002Fli>\n  \u003Cli>\u003Cb>改进：\u003C\u002Fb>在`sugar_extractors\u002Fcoarse_mesh.py`中添加一个`if`语句块，用于跳过前景网格重建，避免在前景包围盒内未检测到表面点时触发错误。这对于希望重建“背景场景”的用户可能很有用。\u003C\u002Fli>\n  \u003Cli>\u003Cb>使用预计算掩码与SuGaR：\u003C\u002Fb>为SuGaR优化过程增加掩码功能，允许用户在训练图像中遮挡部分像素（例如合成数据集中的白色背景）。\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>在Windows上使用SuGaR：\u003C\u002Fb>调整代码使其兼容Windows系统。由于路径书写规范的不同，当前代码无法在Windows上运行。\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>合成数据集：\u003C\u002Fb>增加支持NeRF合成数据集的功能（其格式与COLMAP场景不同）。\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>合成与动画：\u003C\u002Fb>完成合成与动画相关代码的清理工作，并将其整合到`sugar_scene\u002Fsugar_compositor.py`脚本中。\n  \u003C\u002Fli>\n  \u003Cli>\u003Cb>合成与动画：\u003C\u002Fb>制作教程，介绍如何使用`blender`目录下的脚本以及`sugar_scene\u002Fsugar_compositor.py`类，将合成与动画数据导入PyTorch，并应用于SuGaR混合表示。\n  \u003C\u002Fli>\n  \u003C!-- \u003Cli>\u003Cb>改进：\u003C\u002Fb>实现一种简单方法，以避免在重建覆盖\u002F可见度较差的薄型物体时出现伪影。\u003C\u002Fli>\n  \u003C\u002Fli> -->\n\u003C\u002Ful>\n\u003C\u002Fdetails>\n\n## 概述\n\n如我们在论文中所述，SuGaR 优化首先对 3D 高斯溅射模型进行 7000 次迭代的优化，期间不添加任何额外的正则化项。因此，当前实现包含原始 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D 高斯溅射代码\u003C\u002Fa>的一个版本，并且我们将我们的模型构建为一个原生 3D 高斯溅射模型的封装器。\n\n请注意，尽管这种封装实现因多种原因非常方便，但它在内存使用方面可能并非最优。\n\n完整的 SuGaR 流程由四个主要步骤和一个可选步骤组成：\n1. **简短的原生 3DGS 优化**：对原生 3D 高斯溅射模型进行 7000 次迭代的优化，以使高斯分布能够正确地定位在场景中。\n2. **SuGaR 优化**：优化高斯分布与场景表面的对齐。\n3. **网格提取**：从优化后的高斯分布中提取网格。\n4. **SuGaR 精修**：同时精修高斯分布和网格，构建混合的网格+高斯表示。\n5. **纹理网格提取（可选）**：从精修后的 SuGaR 模型中提取传统的带纹理网格，作为在 Blender 中进行可视化、合成和动画制作的工具，借助我们的 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender 插件\u003C\u002Fa>。\n\n我们为每个步骤都提供了专用脚本，同时还提供了一个运行整个流程的脚本 `train_full_pipeline.py`。我们将在后续章节中说明如何使用该脚本。\u003Cbr>\n\n\u003Cdiv align=\"center\">\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_7573cc8f9ed4.png\" alt=\"blender_edit.png\" height=\"200\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_32131941ca56.gif\" alt=\"attack.gif\" height=\"200\"\u002F>\n\u003Cbr>\u003Cb>您可以在 Blender 中可视化、编辑、组合或为重建的带纹理网格制作动画\u003Ci>(左)\u003C\u002Fi>\u003Cbr>并借助我们的 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender 插件\u003C\u002Fa>用 SuGaR 渲染结果\u003Ci>(右)\u003C\u002Fi>。\u003C\u002Fb>\u003Cbr>\n\u003C\u002Fdiv>\u003Cbr>\n\n请注意，最后一步——_纹理网格提取_——是可选的，但在 `train_full_pipeline.py` 脚本中默认启用。事实上，拥有一个传统的带纹理网格对于使用传统软件（如 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender\u003C\u002Fa>）进行可视化、合成和动画制作非常方便。如果您已按照下文所述安装了 Nvdiffrast，那么这一步骤通常只需几秒钟即可完成。\n\n\u003Cdiv align=\"center\">\n\u003Cb>混合表示（网格 + 表面的高斯分布）\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_c93a15ea88b9.png\" alt=\"garden_hybrid.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_00fcce24199f.png\" alt=\"kitchen_hybrid.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_4ce70cff4b3c.png\" alt=\"qant03_hybrid.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_9c06f29fc1f7.png\" alt=\"_hybrid.gif\" height=\"135\"\u002F>\u003Cbr>\n\u003Cb>底层网格与传统的彩色 UV 纹理\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_86b89032627d.png\" alt=\"garden_notex.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_1db4ecff95d4.png\" alt=\"kitchen_notex.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_7d48eaf3b2d3.png\" alt=\"qant03_notex.gif\" height=\"135\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_d36d6c222154.png\" alt=\"dukemon_notex.gif\" height=\"135\"\u002F>\u003Cbr>\n\u003C\u002Fdiv>\u003Cbr>\n\n下面是一个展示黑色镜面材质机器人的场景示例。以下图片分别展示了混合表示（网格 + 表面的高斯分布）、带有传统彩色 UV 纹理的网格，以及网格的深度图：\n\u003Cdiv align=\"center\">\n\u003Cb>混合表示 - 带纹理网格 - 网格深度图\u003C\u002Fb>\u003Cbr>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_2c257f1378d2.png\" alt=\"alpha_hybrid.png\" height=\"400\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_80a222e655d9.png\" alt=\"alpha_texture.gif\" height=\"400\"\u002F>\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_e8f00083db7b.png\" alt=\"alpha_depth.gif\" height=\"400\"\u002F>\n\u003C\u002Fdiv>\n\n## 安装\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">点击此处查看内容。\u003C\u002Fspan>\u003C\u002Fsummary>\n\n### 0. 要求\n\n软件要求如下：\n- Conda（推荐用于简化安装）\n- 用于 PyTorch 扩展的 C++ 编译器\n- 用于 PyTorch 扩展的 CUDA 工具包 11.8\n- C++ 编译器和 CUDA SDK 必须兼容\n\n有关详细信息，请参阅原始 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D 高斯溅射仓库\u003C\u002Fa>。\n\n### 1. 克隆仓库\n\n首先克隆本仓库：\n\n```shell\n# HTTPS\ngit clone https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR.git --recursive\n```\n\n或\n\n```shell\n# SSH\ngit clone git@github.com:Anttwo\u002FSuGaR.git --recursive\n```\n\n### 2. 创建 Conda 环境\n\n要创建并激活包含所有所需包的 Conda 环境，请进入 `SuGaR\u002F` 目录并运行以下命令：\n\n```shell\npython install.py\nconda activate sugar\n```\n\n该脚本将自动创建名为 `sugar` 的 Conda 环境，并安装所有必需的包。它还会自动安装 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D 高斯溅射\u003C\u002Fa>光栅化器以及用于加速网格光栅化的 \u003Ca href=\"https:\u002F\u002Fnvlabs.github.io\u002Fnvdiffrast\u002F\">Nvdiffrast\u003C\u002Fa> 库。\n\n如果在安装过程中遇到任何问题，您可以按照下面的详细说明手动安装所需的包。\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">\n手动安装的详细说明\n\u003C\u002Fspan>\u003C\u002Fsummary>\n\n#### a) 安装所需的 Python 包\n要安装所需的 Python 包并激活环境，请进入 `SuGaR\u002F` 目录并运行以下命令：\n\n```shell\nconda env create -f environment.yml\nconda activate sugar\n```\n\n如果此命令未能成功创建可用环境，您可以尝试手动安装所需的包，方法是运行以下命令：\n```shell\nconda create --name sugar -y python=3.9\nconda activate sugar\nconda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.8 -c pytorch -c nvidia\nconda install -c fvcore -c iopath -c conda-forge fvcore iopath\nconda install pytorch3d==0.7.4 -c pytorch3d\nconda install -c plotly plotly\nconda install -c conda-forge rich\nconda install -c conda-forge plyfile==0.8.1\nconda install -c conda-forge jupyterlab\nconda install -c conda-forge nodejs\nconda install -c conda-forge ipywidgets\npip install open3d\npip install --upgrade PyMCubes\n```\n\n#### b) 安装高斯溅射光栅化器\n\n在 `SuGaR` 目录内运行以下命令，以安装高斯溅射所需的额外 Python 子模块：\n\n```shell\ncd gaussian_splatting\u002Fsubmodules\u002Fdiff-gaussian-rasterization\u002F\npip install -e .\ncd ..\u002Fsimple-knn\u002F\npip install -e .\ncd ..\u002F..\u002F..\u002F\n```\n\n更多详情请参阅 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D 高斯溅射仓库\u003C\u002Fa>。\n\n#### c) （可选）安装 Nvdiffrast 以加快网格光栅化速度\n\n安装 Nvdiffrast 是可选的，但可以显著加快纹理网格提取步骤，从几分钟缩短到不到 10 秒。\n\n```shell\ngit clone https:\u002F\u002Fgithub.com\u002FNVlabs\u002Fnvdiffrast\ncd nvdiffrast\npip install .\ncd ..\u002F\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n\n## 快速入门\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">点击此处查看内容。\u003C\u002Fspan>\u003C\u002Fsummary>\n\n### 从头开始训练\n\n你可以运行以下单个脚本，使用 COLMAP 数据集从头优化一个完整的 SuGaR 模型：\n\n```shell\npython train_full_pipeline.py -s \u003CCOLMAP 数据集路径> -r \u003C\"dn_consistency\", \"density\" 或 \"sdf\"> --high_poly True --export_obj True\n```\n\n你可以通过 `-r` 参数选择正则化方法，可选值为 `\"dn_consistency\"`、`\"density\"` 或 `\"sdf\"`。我们推荐使用较新的 `\"dn_consistency\"` 正则化以获得最佳质量的网格，不过论文中展示的结果是使用 `\"density\"` 正则化处理以物体为中心的场景，而使用 `\"sdf\"` 正则化处理具有挑战性背景的场景，例如 Mip-NeRF 360 数据集。\n\n你还可以将 `--high_poly True` 参数替换为 `--low_poly True`，以提取一个包含 20 万顶点而非 100 万顶点的网格，并且每个三角形使用 6 个高斯分布而非 1 个。\n\n此外，你可以添加 `--refinement_time \"short\"`、`\"medium\"` 或 `\"long\"` 来设置细化步骤所花费的时间。默认是 `\"long\"`（1.5 万次迭代），但 `\"short\"`（2 千次迭代）通常足以生成外观良好的混合表示。\n\n最后，你可以通过 `--export_obj` 参数选择导出传统的带纹理网格。这一步骤是可选的，但在 `train_full_pipeline.py` 脚本中默认启用，因为该网格是使用 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender 插件\u003C\u002Fa>以及在 Blender 中编辑、组合或制作动画场景所必需的。\n\n结果会保存在 `output\u002F` 目录中。\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">请点击此处查看 `train_full_pipeline.py` 脚本中的重要参数。\u003C\u002Fspan>\u003C\u002Fsummary>\n\n| 参数 | 类型 | 描述 |\n| :-------: | :--: | :---------: |\n| `--scene_path` \u002F `-s`   | `str` | 包含 COLMAP 数据集的源目录路径。|\n| `--gs_output_dir` | `str` | 原始 3D 高斯泼溅模型的检查点目录路径。如果未提供路径，脚本将从头开始，并首先优化一个原始的 3DGS 模型。 |\n| `--regularization_type` \u002F `-r` | `str` | 用于对齐高斯分布的正则化类型。可为 `\"dn_consistency\"`、`\"density\"` 或 `\"sdf\"`。我们建议使用较新的 `\"dn_consistency\"` 正则化以获得最佳质量的网格。 |\n| `--eval` | `bool` | 如果为真，则会对训练图像进行评估划分。默认为 `True`。 |\n| `--low_poly` | `bool` | 如果为真，则使用低多边形网格的标准配置，即 20 万个顶点和每个三角形 6 个高斯分布。 |\n| `--high_poly` | `bool` | 如果为真，则使用高多边形网格的标准配置，即 100 万个顶点和每个三角形 1 个高斯分布。 |\n| `--refinement_time` | `str` | 细化步骤所用时间的默认配置。可为 `\"short\"`（2 千次迭代）、`\"medium\"`（7 千次迭代）或 `\"long\"`（1.5 万次迭代）。 |\n| `--export_ply` | `bool` | 如果为真，在训练结束时会导出包含细化后 3D 高斯分布的 `.ply` 文件。该文件可能较大（约 500MB），但它是使用 3DGS 查看器所必需的。默认为 `True`。 |\n| `--export_obj` \u002F `-t` | `bool` | 如果为真，在细化完成后，将从细化后的 SuGaR 模型中优化并导出一个传统的带纹理网格作为 `.obj` 文件。使用 Nvdiffrast 计算传统颜色 UV 纹理只需几秒钟。默认为 `True`。 |\n| `--square_size` | `int` | UV 纹理中每对三角形分配的正方形大小。增大此值可提高纹理分辨率。如果遇到内存问题，请减小此值。默认为 `8`。 |\n| `--white_background` | `bool` | 如果为真，图像的背景将被设置为白色。默认为 `False`。 |\n\n\n\u003C\u002Fdetails>\n\u003Cbr>\n\n正如我们在论文中所解释的那样，该脚本平均在单个 GPU 上 30 分钟内提取出网格。网格提取完成后，使用 `--refinement_time \"short\"` 时，细化过程仅需几分钟；而使用 `--refinement_time \"long\"` 时，则可能需要更长时间。在大多数情况下，短时间的细化就足以生成外观良好的混合表示。\n\n请注意，优化时间可能会因场景复杂性和所使用的 GPU 而有所不同。此外，当前实现将优化过程拆分为多个模块化脚本，这些脚本可以单独运行，因此每次都会重新加载数据，这并不理想，且会耗费数分钟时间。\n\n有关所有命令行参数的更多详细信息，请参阅 `train_full_pipeline.py`。\n\n### 从原始高斯泼溅模型开始训练\n\n如果你已经为某个场景训练了一个 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">原始高斯泼溅模型\u003C\u002Fa>（我们建议训练 7 千次迭代），你可以使用 `--gs_output_dir` 参数提供原始高斯泼溅模型输出目录的路径。这样将跳过优化的第一部分，直接从原始模型加载高斯分布：\n\n```shell\npython train_full_pipeline.py -s \u003CCOLMAP 数据集路径> -r \u003C\"dn_consistency\", \"density\" 或 \"sdf\"> --high_poly True --export_obj True --gs_output_dir \u003C高斯泼溅输出目录路径>\n```\n\n\u003C\u002Fdetails>\n\n\n## 实时可视化 SuGaR 模型\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">点击此处查看内容。\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n优化完 SuGaR 模型后，你可以使用任意 3D 高斯泼溅查看器实时可视化该模型。\u003Cbr>\n事实上，优化完成后，我们会自动在 `.\u002Foutput\u002Frefined_ply\u002F` 目录中导出一个 `.ply` 文件，其中包含 SuGaR 混合表示的细化后的 3D 高斯分布，且与任何 3DGS 查看器兼容。\n例如，你可以使用 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D 高斯泼溅\u003C\u002Fa>原始实现中提供的查看器，或者使用出色的 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fplaycanvas\u002Fsupersplat\">SuperSplat 查看器\u003C\u002Fa>。\u003Cbr>\n此外，还提供了一个在线的 \u003Ca href=\"https:\u002F\u002Fplaycanvas.com\u002Fsupersplat\u002Feditor\">SuperSplat 浏览器版\u003C\u002Fa>。\n\n我们还提供了一个专用的实时查看器，不仅可以可视化细化后的 3D 高斯分布，还可以同时显示带纹理的网格和线框网格。请参阅下方说明以安装并使用此查看器。\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">请点击此处查看我们实时查看器的安装和使用说明。\u003C\u002Fspan>\u003C\u002Fsummary>\n\n请在此处观看 \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=YbjE0wnw67I\">简短视频\u003C\u002Fa>,了解如何使用该查看器。\n\n### 1. 安装\n\n*该查看器目前适用于 Linux 和 Mac OS，不支持 Windows。对于 Windows 用户，我们建议使用 WSL2（Windows Sub系统 for Linux），因为它安装和使用都非常方便。更多详情请参阅 \u003Ca href=\"https:\u002F\u002Fdocs.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall-win10\">官方文档\u003C\u002Fa>。\u003Cbr> 我们感谢 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fmkkellogg\u002FGaussianSplats3D\">Mark Kellogg 为 Three.js 提供的出色的 3D 高斯泼溅实现\u003C\u002Fa>, 我们正是基于此实现构建了这款查看器。*\n\n首先，请安装最新版本的 Node.js（例如 21.x）和 npm。\n一种简单的方法是运行以下命令（使用 aptitude）：\n\n```shell\ncurl -fsSL https:\u002F\u002Fdeb.nodesource.com\u002Fsetup_21.x | sudo -E bash -\nsudo apt-get install -y nodejs\nsudo apt-get install aptitude\nsudo aptitude install -y npm\n```\n\n然后，进入 `.\u002Fsugar_viewer\u002F` 目录并运行以下命令：\n\n```shell\nnpm install\ncd ..\n```\n\n### 2. 使用\n\n首先，请确保您已使用 `train.py` 脚本导出 `.ply` 文件和 `.obj` 文件。`.ply` 文件包含优化后的 3D 高斯点云，而 `.obj` 文件则包含带纹理的网格。默认情况下，运行 `train.py` 脚本时会导出这些文件，因此如果您在运行代码时使用了 `--export_ply` 和 `--export_obj` 的默认值，那么您应该可以直接使用。\n\n`.ply` 文件应位于 `.\u002Foutput\u002Frefined_ply\u002F\u003C您的场景名称>\u002F` 目录中。然后，在根目录下运行以下命令即可启动查看器：\n\n```shell\npython run_viewer.py -p \u003C.ply 文件路径>\n```\n\n请确保您的 `.ply` 文件位于正确的位置，并使用以 `.\u002Foutput\u002Frefined_ply` 开头的相对路径。该命令将重定向到本地 URL。点击链接即可在浏览器中打开查看器。单击右上角的图标可在不同表示形式之间切换（混合表示、带纹理的网格、线框网格）。使用鼠标旋转场景，使用鼠标滚轮进行缩放。\n\n\u003C\u002Fdetails>\n\n\u003Cdiv align=\"center\" >\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_readme_756ea471a36b.png\" alt=\"viewer_example.png\" width=\"800\"\u002F>\n\u003C\u002Fdiv>\u003Cbr>\n\n我们还推荐使用我们的 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender 插件\u003C\u002Fa> 来创建 SuGaR 表示的动画和视频片段。\n具体来说，该插件允许您导入 SuGaR 网格，并在 Blender 中对其进行可视化、编辑、组合或动画制作。\n最后，您可以使用 3DGS 光栅化器渲染结果，它能够高质量且逼真地呈现 SuGaR 的混合表示。\n\n\u003C\u002Fdetails>\n\n\n## 使用 Blender 进行渲染、合成与动画制作\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">点击此处查看内容。\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n`view_sugar_results.ipynb` 笔记本和 `metrics.py` 脚本提供了如何加载优化后的 SuGaR 模型来渲染场景的示例。\n\n我们还提供一个 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F\">Blender 插件\u003C\u002Fa>，用于在 Blender 内编辑、组合和动画化 SuGaR 网格，并使用 SuGaR 的混合表示进行渲染。网格位于 `.\u002Foutput\u002Frefined_mesh\u002F` 目录中。\n\n有关如何使用该插件以及如何为 SuGaR 创建渲染包的更多详细信息，请参阅 Blender 插件仓库。\n准备好使用 Blender 制作的渲染包后——该包应为位于 `.\u002Foutput\u002Fblender\u002Fpackage\u002F` 目录中的 `.JSON` 文件——您可以使用 `render_blender_scene.py` 脚本渲染场景：\n\n```shell\npython render_blender_scene.py -p \u003C渲染包路径>\n```\n\n渲染后的图像将保存在 `.\u002Foutput\u002Fblender\u002Frenders\u002F` 目录中。\u003Cbr>\n如果在图像中观察到伪影，您可以调整脚本的参数以提高渲染质量。\n具体而言，您可以切换到 `--adaptation_method simple` 或降低 `deformation_threshold` 来减少渲染中的伪影。\n有关命令行参数的更多信息，请参阅脚本。\n\n\u003C\u002Fdetails>\n\n\n## 评估\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">点击此处查看内容。\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n为了评估重建的质量，我们提供了一个 `metrics.py` 脚本，用于计算测试图像上的 PSNR、SSIM 和 LPIPS 指标。首先，针对所需的场景和正则化方法（`dn_consistency`、`density` 或 `sdf`）优化 SuGaR 模型，然后创建一个包含场景路径的 `.json` 配置文件，格式如下：`{source_images_dir_path: vanilla_gaussian_splatting_checkpoint_path}`。\n\n最后，按如下方式运行脚本：\n\n```shell\npython metrics.py --scene_config \u003C.json 文件路径> -r \u003C\"sdf\" 或 \"density\">\n```\n\n结果将保存在 `output\u002Fmetrics\u002F` 目录下的 `.json` 文件中。\u003Cbr>\n有关命令行参数的更多信息，请参阅脚本。\n\n\u003C\u002Fdetails>\n\n## 使用 SuGaR 处理您自己的数据以获得更好重建效果的提示\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">点击此处查看内容。\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">1. 拍摄覆盖场景整个表面的图片或视频\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n使用智能手机或相机拍摄覆盖您想要重建的 3D 场景整个表面的图片或视频。最简单的方法是在场景周围移动并录制视频。尽量缓慢平稳地移动，以避免运动模糊。为了实现一致的重建效果，并便于 COLMAP 进行相机位姿估计，保持统一的焦距和恒定的曝光时间也很重要。我们建议关闭智能手机的自动对焦功能，以确保焦距不变。\n\n为了获得更好的重建效果，尽量从多个不同的角度拍摄物体，尤其是场景中细小而复杂的部分。\u003Cbr>\n事实上，SuGaR 能够重建非常细小和复杂的物体，但如果这些细小物体在训练图像中没有被充分覆盖，只从一个方向可见，则可能会出现一些伪影。\n\n要将视频转换为图片，您可以安装 `ffmpeg` 并运行以下命令：\n```shell\nffmpeg -i \u003C视频文件路径> -qscale:v 1 -qmin 1 -vf fps=\u003CFPS> %04d.jpg\n```\n其中 `\u003CFPS>` 是您希望的视频图像采样率。FPS 值为 1 表示每秒采样一张图像。我们建议根据视频长度调整采样率，使采样的图像数量在 100 到 300 张之间。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">2. 使用 COLMAP 估计相机位姿\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n请先安装最新版本的 COLMAP（最好支持 CUDA），并将您想要使用的图像放入目录 `\u003Clocation>\u002Finput` 中。然后，从原始的 Gaussian Splatting 实现中运行脚本 `gaussian_splatting\u002Fconvert.py`，以使用 COLMAP 从图像中计算相机位姿。更多详情请参阅原始的 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting 仓库\u003C\u002Fa>。\n\n```shell\npython gaussian_splatting\u002Fconvert.py -s \u003Clocation>\n```\n\n有时 COLMAP 无法将所有图像重建为同一个模型，从而产生多个子模型。较小的子模型通常只包含少数几张图像。然而，默认情况下，脚本 `convert.py` 只会对第一个子模型应用去畸变处理，而这个子模型可能只包含少量图像。\n\n如果是这种情况，一个简单的解决方法是只保留最大的子模型，丢弃其他子模型。为此，请打开包含输入图像的源目录，然后进入子目录 `\u003CSource_directory>\u002Fdistorted\u002Fsparse\u002F`。您应该会看到几个名为 `0\u002F`、`1\u002F` 等的子目录，每个子目录都包含一个子模型。删除除包含最大文件的子目录之外的所有子目录，并将其重命名为 `0\u002F`。然后再次运行 `convert.py` 脚本，但跳过匹配步骤：\n\n```shell\npython gaussian_splatting\u002Fconvert.py -s \u003Clocation> --skip_matching\n```\n\n_注意：如果这些子模型有共同的已注册图像，可以在后处理阶段使用 COLMAP 将它们合并为一个模型；然而，合并子模型需要在合并后运行另一次全局光束平差，这可能会非常耗时。_\n\n\u003C\u002Fdetails>\n\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">3. DN-一致性、密度还是 SDF？选择适合您场景的正则化方法\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n**我们建议使用较新的 DN-一致性正则化以获得最佳质量的网格**。\n\n不过，论文中展示的结果是在以下情况下得到的：对于以物体为中心的场景使用密度正则化，而对于背景较为复杂的场景（如 Mip-NeRF 360 数据集）则使用 SDF 正则化。\n\n正如我们在论文中所解释的那样，密度正则化最为简单，且在场景中物体居中时效果较好。SDF 提供了更强的正则化作用，尤其是在背景区域。因此，在标准数据集上，SDF 正则化的指标通常更高。然而，对于用环绕物体四周拍摄的图像来重建场景中居中的物体时，相对简单的密度正则化往往能生成比 SDF 更好的网格。\n\nDN-一致性正则化是一种新的正则化方法，它 (a) 在使用密度正则化的同时，强制高斯分布与场景表面对齐；同时 (b) 强制深度梯度与法线图之间的一致性——这两者都是通过 3D 高斯分布渲染出来的。\u003Cbr>\n如论文所述，高斯分布的法线被定义为该高斯分布协方差矩阵的最短轴。\u003Cbr>\n这种正则化方法能够生成最高质量的网格。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">4. 我的网格上有孔洞，该怎么办？\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n如果您发现网格上有孔洞，这意味着 Poisson 网格的清理步骤对您的场景过于激进。您可以通过修改 `sugar_extractors\u002Fcoarse_mesh.py` 文件第 43 行来降低用于清理的阈值 `vertices_density_quantile`。例如，您可以将这一行从\n```python\n  vertices_density_quantile = 0.1\n```\n改为\n```python\n  vertices_density_quantile = 0.\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">5. 我的网格表面出现了杂乱的椭圆形凸起，该怎么办？\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n根据您的场景，Poisson 重建所使用的默认超参数可能相对于高斯分布的尺寸来说过于精细。这样一来，高斯分布就有可能在网格上显现出来，从而导致网格表面出现杂乱的椭圆形凸起。\n这种情况可能发生在相机轨迹非常靠近简单的前景物体时。\u003Cbr>\n要解决这个问题，您可以降低 Poisson 重建的深度 `poisson_depth`，方法是修改 `sugar_extractors\u002Fcoarse_mesh.py` 文件第 42 行。\u003Cbr>\n例如，您可以将第 42 行从\n```python\n  poisson_depth = 10\n```\n改为\n```python\n  poisson_depth = 7\n```\n如果效果仍不理想，您也可以尝试 `poisson_depth = 6` 或 `poisson_depth = 8`。\n\n\u003C\u002Fdetails>\n\n\n\u003Cdetails>\n\u003Csummary>\u003Cspan style=\"font-weight: bold;\">6. （可选）调整场景的尺度和边界框\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cbr>\n\n正如原始 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting\">3D Gaussian Splatting 仓库\u003C\u002Fa> 所述，该方法适用于重建合理尺度的场景。对于重建规模更大的数据集（如城市街区），原作者建议降低高斯分布位置和缩放因子的学习率。场景越庞大，这些学习率就应该越低。\n\n对于 SuGaR 来说，当重建非常大的场景时，也应相应降低这些学习率。此外，正如我们在论文补充材料中所解释的那样，在从高斯分布中提取具有最优顶点分布的网格时，我们实际上会进行两次 Poisson 重建：一次针对“前景”高斯分布，一次针对“背景”高斯分布。“前景”高斯分布是指位于预定义边界框内的高斯分布，“背景”高斯分布则是指位于该边界框外的高斯分布。\n\n默认情况下，此边界框被计算为所有相机中心的包围盒。这种通用方法与原始 3D Gaussian Splatting 调整学习率的方式是一致的。我们在论文及演示视频中展示的所有重建均使用了这一默认边界框。\n\n然而，在某些特定情况下，此边界框可能并不理想，尤其是当用户希望以高细节重建场景中某个特定物体，或者场景非常庞大，又或者相机中心距离场景十分遥远时。用户可以自由地通过 `--bboxmin` 和 `--bboxmax` 参数向 `train.py` 脚本提供自定义边界框。请注意，边界框必须以字符串形式提供，格式为 `\"(x,y,z)\"`，其中 `x`、`y` 和 `z` 分别表示边界框最小和最大点的坐标。\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>","# SuGaR 快速上手指南\n\nSuGaR (Surface-Aligned Gaussian Splatting) 是一个用于从 3D 高斯泼溅（3DGS）重建中高效提取高质量网格 mesh 的工具。它通过正则化项使高斯点与表面对齐，利用泊松重建提取网格，并支持生成“网格 + 表面高斯”的混合表示，便于在 Blender 等软件中进行编辑、绑定和动画制作。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**: Linux (目前代码暂不兼容 Windows)\n*   **包管理器**: Conda (推荐用于简化环境配置)\n*   **编译器**: C++ 编译器 (用于编译 PyTorch 扩展)\n*   **GPU 驱动**: CUDA Toolkit 11.8 (必须与 PyTorch 版本及编译器兼容)\n*   **前置依赖**: 建议参考原版 [3D Gaussian Splatting](https:\u002F\u002Fgithub.com\u002Fgraphdeco-inria\u002Fgaussian-splatting) 仓库的详细依赖说明。\n\n> **注意**：C++ 编译器和 CUDA SDK 的版本必须相互兼容，否则会导致扩展编译失败。\n\n## 安装步骤\n\n### 1. 克隆仓库\n使用 `--recursive` 参数克隆仓库以包含所有子模块：\n\n```shell\n# HTTPS 方式\ngit clone https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR.git --recursive\n\n# 或者 SSH 方式\ngit clone git@github.com:Anttwo\u002FSuGaR.git --recursive\n```\n\n### 2. 创建并激活 Conda 环境\n进入项目目录并运行安装脚本。该脚本会自动创建名为 `sugar` 的 Conda 环境并安装所有必要的 Python 包及 PyTorch 扩展。\n\n```shell\ncd SuGaR\npython install.py\nconda activate sugar\n```\n\n> **提示**：如果下载速度慢，可在运行 `install.py` 前配置 Conda 使用国内镜像源（如清华源或中科大源），或在脚本内部修改 pip 源地址。\n\n## 基本使用\n\nSuGaR 的完整流程包含四个主要步骤（及一个可选步骤）。为了方便用户，项目提供了一个一键运行脚本 `train_full_pipeline.py`，可自动执行从初始训练到最终纹理网格提取的全过程。\n\n### 运行完整流程\n\n假设您已经准备好了 COLMAP 格式的数据集（位于 `path\u002Fto\u002Fyour\u002Fdata`），运行以下命令即可启动全流程：\n\n```shell\npython train_full_pipeline.py -s path\u002Fto\u002Fyour\u002Fdata\n```\n\n该脚本将依次执行：\n1.  **基础 3DGS 优化**：进行 7000 次迭代的基础训练，让高斯点在场景中初步定位。\n2.  **SuGaR 优化**：添加正则化项，优化高斯点使其与场景表面对齐。\n3.  **网格提取**：基于对齐后的高斯点采样，使用泊松重建算法提取网格。\n4.  **SuGaR 精修**：联合优化网格和表面高斯点，构建混合表示。\n5.  **纹理网格提取（可选但默认开启）**：提取带有传统 UV 纹理的网格，以便在 Blender 中使用。\n\n### 后续处理与可视化\n\n*   **查看结果**：训练完成后，您可以在输出目录中找到提取的网格文件（`.ply` 或 `.obj`）以及混合表示数据。\n*   **Blender 编辑**：若要利用提取的网格进行动画制作或场景合成，请安装配套的 [Blender 插件](https:\u002F\u002Fgithub.com\u002FAnttwo\u002Fsugar_frosting_blender_addon\u002F)。该插件允许您在 Blender 中加载混合表示，对网格进行雕刻、绑定骨骼或调整材质，并利用 SuGaR 渲染器进行高质量渲染。\n*   **实时预览**：项目包含专用的实时查看器，可用于导航和检查重建场景（包括混合表示、纹理网格和线框模式）。\n\n```shell\n# 示例：运行查看器（具体参数请参考输出目录中的说明或帮助文档）\npython viewer.py -m path\u002Fto\u002Foutput\u002Fmodel\n```\n\n通过以上步骤，您即可在几分钟内获得可编辑的高质量网格模型，并享受 3D 高斯泼溅带来的逼真渲染效果。","某游戏工作室的美术团队正试图将一段通过无人机拍摄的真实花园视频转化为可在 Unity 引擎中实时交互的 3D 资产。\n\n### 没有 SuGaR 时\n- **网格提取困难**：原始的 3D Gaussian Splatting 重建结果由数百万个无序的高斯点组成，无法直接导出为传统的三角网格模型，导致资产无法导入主流游戏引擎。\n- **细节丢失严重**：若强行使用传统的 Marching Cubes 算法从神经隐式场中提取网格，不仅耗时数小时，还会抹平花园中树叶和草丛的精细几何结构。\n- **编辑流程断裂**：由于缺乏明确的表面网格，美术师无法在 Blender 中对场景进行常规的拓扑修改、绑定骨骼或制作动画，只能面对不可编辑的点云束手无策。\n- **渲染与物理冲突**：纯高斯表示难以高效计算碰撞体积，导致角色在场景中行走时无法产生真实的物理遮挡和碰撞反馈。\n\n### 使用 SuGaR 后\n- **快速生成高质量网格**：SuGaR 利用表面正则化项引导高斯点对齐，仅需几分钟即可通过泊松重建提取出保留丰富细节的精确三角网格。\n- **构建混合表示**：工具自动将高斯点“冻结”在提取的网格表面，形成“网格 + 高斯”的混合架构，既保留了照片级的渲染质感，又拥有了清晰的几何边界。\n- **无缝接入传统管线**：导出的网格可直接在 Blender 中进行雕刻、重拓扑和骨骼绑定，让静态的花园场景瞬间变为可动画化的游戏关卡。\n- **高效物理交互**：基于提取的网格，引擎能快速构建碰撞体，实现角色在花丛中穿梭时的真实遮挡关系和物理反馈，同时维持高帧率渲染。\n\nSuGaR 成功打破了神经渲染与传统图形管线之间的壁垒，让高保真 3D 场景的获取从“仅能观看”变成了“可编辑、可交互”的生产级资产。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FAnttwo_SuGaR_3d71ddda.png","Anttwo","Antoine GUEDON","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FAnttwo_a7a9c855.jpg","Postdoctoral Researcher in computer vision at LIX, Ecole polytechnique\u002FCNRS\u002FInria.","Ecole des Ponts ParisTech","Paris, France",null,"antoine_guedon","https:\u002F\u002Fanttwo.github.io\u002F","https:\u002F\u002Fgithub.com\u002FAnttwo",[85,89,93,97,101,105,109,113,117,121],{"name":86,"color":87,"percentage":88},"C++","#f34b7d",45.8,{"name":90,"color":91,"percentage":92},"Python","#3572A5",23.5,{"name":94,"color":95,"percentage":96},"HTML","#e34c26",11.4,{"name":98,"color":99,"percentage":100},"CMake","#DA3434",8.2,{"name":102,"color":103,"percentage":104},"CSS","#663399",5.8,{"name":106,"color":107,"percentage":108},"GLSL","#5686a5",2.6,{"name":110,"color":111,"percentage":112},"Cuda","#3A4E3A",1.7,{"name":114,"color":115,"percentage":116},"C","#555555",0.4,{"name":118,"color":119,"percentage":120},"Jupyter Notebook","#DA5B0B",0.3,{"name":122,"color":123,"percentage":124},"JavaScript","#f1e05a",0.2,3303,292,"2026-04-17T15:18:20","NOASSERTION",4,"Linux","必需 NVIDIA GPU，需安装 CUDA Toolkit 11.8，C++ 编译器与 CUDA SDK 必须兼容（基于 3D Gaussian Splatting 需求）","未说明",{"notes":134,"python":135,"dependencies":136},"目前代码不兼容 Windows 系统（待办事项中明确提及）；推荐使用 Conda 管理环境；项目包含完整的 3D Gaussian Splatting 实现作为基础；若需进行纹理网格提取以在 Blender 中使用，需额外安装 nvdiffrast。","通过 Conda 环境自动安装（具体版本未在片段中明确，通常为 3.8+）",[137,138,139,140,141,142],"torch","CUDA Toolkit 11.8","C++ Compiler","Conda","nvdiffrast (可选，用于纹理网格提取)","3D Gaussian Splatting (内置封装)",[15,144],"其他",[146,147,148,149,150,151,152,153,154],"3d-gaussian-splatting","3dgs","gaussian-splatting","mesh","mesh-generation","nerf","neural-rendering","surface-reconstruction","cvpr2024","2026-03-27T02:49:30.150509","2026-04-18T22:33:49.324834",[158,163,168,172,177,182],{"id":159,"question_zh":160,"answer_zh":161,"source_url":162},40606,"显存不足（OOM）导致训练或后处理失败如何解决？","对于显存较小的显卡（如 12GB 或 8GB），可以采取以下措施：1. 在运行 SuGaR 训练前，降低输入图像的分辨率（例如从 1472x1472 降至 366x366），可以通过重命名文件夹仅保留低分辨率图像来实现；2. 尝试调整训练参数或使用更少的迭代次数；3. 确保在正确的 Conda 环境中运行脚本。","https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR\u002Fissues\u002F127",{"id":164,"question_zh":165,"answer_zh":166,"source_url":167},40607,"最终模型保存到了哪里？","当终端显示 \"Final model saved\" 时，模型通常保存在输出目录中。根据日志信息，细化后的模型路径类似于 `.\u002Foutput\u002Frefined\u002F\u003Cscene_name>\u002F...pt`，粗网格路径在 `.\u002Foutput\u002Fcoarse_mesh\u002F`，而最终带纹理的网格可能位于 `.\u002Foutput\u002Frefined_mesh\u002F` 目录下。具体路径取决于运行命令时指定的 `-c` (checkpoint) 和输出参数。","https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR\u002Fissues\u002F120",{"id":169,"question_zh":170,"answer_zh":171,"source_url":167},40602,"在 Windows 上如何安装 PyTorch3D？","该问题在讨论中未提供具体的命令行解决方案，维护者建议通过电子邮件联系以避免占用版面。通常建议在 Windows 上使用预编译的 wheel 文件或通过 conda 安装特定版本的 PyTorch3D，具体需参考 PyTorch3D 官方文档。",{"id":173,"question_zh":174,"answer_zh":175,"source_url":176},40603,"使用默认参数重建简单场景时效果不佳，如何调整？","建议按照以下步骤操作：1. 使用程序对某个 obj 文件生成图片；2. 使用调试过参数的脚本逐步执行以生成 COLMAP 数据；3. 运行 SuGaR 训练并等待结果。可以参考社区用户分享的参数配置文件（如 issue 中提到的 0.txt）进行尝试。","https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR\u002Fissues\u002F98",{"id":178,"question_zh":179,"answer_zh":180,"source_url":181},40604,"网格表面存在大量噪声或无法找到 points3D.ply 文件怎么办？","这是因为代码试图读取由 COLMAP 生成的 points3D.ply 文件，但在某些场景（如 Blender 合成数据）中该文件不存在。解决方法是修改 `sugar_trainers\u002Frefine.py` 第 290 行，将路径从 `sparse\u002F0\u002Fpoints3D.ply` 改为 `points3d.ply`，以使用 3DGS 生成的随机点云文件。此外，确保在 nerf_synthetic\u002Flego\u002F 路径下复制 test 文件夹并重命名为 images。","https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR\u002Fissues\u002F39",{"id":183,"question_zh":184,"answer_zh":185,"source_url":186},40605,"如何修复网格中的孔洞或表面奇怪的椭球凸起？","维护者建议修改 `sugar_extractors\u002Fcoarse_mesh.py` 脚本：1. 将第 43 行的 `vertices_density_quantile` 从 0.1 改为 0.0（或更低），以降低清理泊松网格的阈值，从而减少孔洞；2. 如果表面有奇怪的凸起，尝试将第 42 行的 `poisson_depth` 从 10 降低到 8、7 甚至 6。","https:\u002F\u002Fgithub.com\u002FAnttwo\u002FSuGaR\u002Fissues\u002F89",[]]