简介

PyTorch3D 为使用 PyTorch 进行 3D 计算机视觉研究提供了高效、可复用的组件。

其主要特性包括：

• 用于存储和操作三角网格的数据结构
• 针对三角网格的高效操作（投影变换、图卷积、采样、损失函数）
• 可微分的网格渲染器
• Implicitron，详见 其 README，一个基于隐式表示的新视角合成框架。(博客文章)

PyTorch3D 旨在与用于预测和操作 3D 数据的深度学习方法无缝集成。因此，PyTorch3D 中的所有算子：

• 均基于 PyTorch 张量实现
• 能够处理异构数据的小批量
• 支持自动微分
• 可利用 GPU 加速

在 FAIR 内部，PyTorch3D 已被用于支持诸如 Mesh R-CNN 等研究项目。

请参阅我们的 博客文章 ，以获取更多演示并了解 PyTorch3D。

安装

有关详细说明，请参阅 INSTALL.md。

许可证

PyTorch3D 采用 BSD 许可证 发布。

教程

通过尝试以下教程笔记本开始使用 PyTorch3D。

将球形网格变形为海豚	光束法平差

渲染纹理化网格	相机位置优化

渲染纹理化点云	拟合带纹理的网格

渲染 DensePose 数据	加载并渲染 ShapeNet 数据

拟合纹理化体积	拟合一个简单的神经辐射场

在 Implicitron 中拟合纹理化体积	Implicitron 配置系统

文档

通过阅读 PyTorch3D 的 文档，了解更多关于 API 的信息。

我们还针对多个 API 组件提供了深入解析笔记：

• 异构批处理
• 网格 I/O
• 可微分渲染

概览视频

我们制作了一段简短的（约 14 分钟）视频教程，概述了 PyTorch3D 的代码库，并包含多个代码示例。点击下方图片即可在 YouTube 上观看该视频：

开发

我们欢迎对 PyTorch3D 的新贡献，并将持续积极维护此库！请参阅 CONTRIBUTING.md ，以获取有关如何运行代码、测试和 linter，以及提交拉取请求的完整说明。

开发与兼容性

• main 分支：处于积极开发状态，不提供任何保证，随时可能引入破坏性变更。
  • 注意：这包括基于 main 分支构建的夜间版本。
  • 提示：可以通过提交历史来定位回归问题或相关更改。
• 版本间的向后兼容性：不保证。我们将尽最大努力提前通知破坏性变更，并协助用户迁移代码或数据（包括模型）。

贡献者

PyTorch3D 由 Facebook AI 研究院计算机视觉团队编写和维护。

按字母顺序排列如下：

• Amitav Baruah
• Steve Branson
• Krzysztof Chalupka
• Jiali Duan
• Luya Gao
• Georgia Gkioxari
• Taylor Gordon
• Justin Johnson
• Patrick Labatut
• Christoph Lassner
• Wan-Yen Lo
• David Novotny
• Nikhila Ravi
• Jeremy Reizenstein
• Dave Schnizlein
• Roman Shapovalov
• Olivia Wiles

引用

如果您在研究中使用了 PyTorch3D，请引用我们的技术报告：

@article{ravi2020pytorch3d,
    author = {Nikhila Ravi and Jeremy Reizenstein and David Novotny and Taylor Gordon
                  and Wan-Yen Lo and Justin Johnson and Georgia Gkioxari},
    title = {Accelerating 3D Deep Learning with PyTorch3D},
    journal = {arXiv:2007.08501},
    year = {2020},
}

如果您使用了用于球体渲染的 Pulsar 后端（即 PulsarPointRenderer 或 pytorch3d.renderer.points.pulsar.Renderer），请同时引用以下技术报告：

@article{lassner2020pulsar,
    author = {Christoph Lassner and Michael Zollh\"ofer},
    title = {Pulsar: Efficient Sphere-based Neural Rendering},
    journal = {arXiv:2004.07484},
    year = {2020},
}

最新动态

以下是代码库更新的时间线，按时间倒序排列。我们不仅会分享发布版本的更新信息，还会介绍基于 PyTorch3D 构建的研究项目。各版本的变更日志可在 Releases 页面查看，安装包则可通过 conda 按照 INSTALL.md 中的说明进行安装。

[2023年10月31日]: PyTorch3D 发布 v0.7.5。

[2023年5月10日]: PyTorch3D 发布 v0.7.4。

[2023年4月5日]: PyTorch3D 发布 v0.7.3。

[2022年12月19日]: PyTorch3D 发布 v0.7.2。

[2022年10月23日]: PyTorch3D 发布 v0.7.1。

[2022年8月10日]: PyTorch3D 发布 v0.7.0，新增 Implicitron 和 MeshRasterizerOpenGL 功能。

[2022年4月28日]: PyTorch3D 发布 v0.6.2。

[2021年12月16日]: PyTorch3D 发布 v0.6.1。

[2021年10月6日]: PyTorch3D 发布 v0.6.0。

[2021年8月5日]: PyTorch3D 发布 v0.5.0。

[2021年2月9日]: PyTorch3D 发布 v0.4.0，新增对隐式函数、体积渲染的支持，并包含 NeRF 的重新实现。

[2020年11月2日]: PyTorch3D 发布 v0.3.0，集成了 Pulsar 后端。

[2020年8月28日]: PyTorch3D 发布 v0.2.5。

[2020年7月17日]: PyTorch3D 的技术报告在 ArXiv 上发表：https://arxiv.org/abs/2007.08501。

[2020年4月24日]: PyTorch3D 发布 v0.2.0。

[2020年3月25日]: 使用 PyTorch3D 的 SynSin 代码库发布：https://github.com/facebookresearch/synsin。

[2020年3月8日]: PyTorch3D 发布 v0.1.1，为修复 bug 的版本。

[2020年1月23日]: PyTorch3D 发布 v0.1.0。同时发布了 Mesh R-CNN 的代码库：https://github.com/facebookresearch/meshrcnn。

PyTorch3D 快速上手指南

PyTorch3D 是 Facebook AI Research (FAIR) 开源的高效、可重用的 3D 计算机视觉组件库。它基于 PyTorch 构建，支持三角网格操作、可微分渲染器以及隐式表示新视图合成（Implicitron），所有算子均支持 GPU 加速和自动求导。

环境准备

在开始之前，请确保满足以下系统要求和依赖：

• 操作系统: Linux 或 macOS (Windows 支持有限，通常建议使用 WSL2)。
• Python: 推荐 Python 3.8 - 3.10。
• PyTorch: 必须预先安装与你的 CUDA 版本匹配的 PyTorch。
  • 访问 PyTorch 官网 获取安装命令。
  • 国内加速: 推荐使用清华源或阿里源安装 PyTorch。

  pip install torch torchvision torchaudio --index-url https://pypi.tuna.tsinghua.edu.cn/simple
  

• 编译依赖 (若从源码安装): gcc, g++, cmake。

安装步骤

PyTorch3D 推荐通过 conda 或 pip 进行安装。由于包含自定义 CUDA 算子，强烈建议预编译的二进制包版本与你的 PyTorch/CUDA 版本严格匹配。

方法一：使用 Conda 安装（推荐）

这是最稳定的方式。请访问 Anaconda PyTorch3D 页面 查找与你当前 PyTorch 和 CUDA 版本对应的具体版本号。

假设你已安装 PyTorch 1.13 + CUDA 11.7，示例命令如下：

conda install -c pytorch3d pytorch3d

注意：如果默认频道找不到对应版本，可能需要指定具体的 channel 或版本字符串，例如 conda install -c pytorch3d pytorch3d=0.7.5。

方法二：使用 Pip 安装（预编译轮文件）

如果你确定有匹配你环境的预编译 wheel 包，可以直接使用 pip。

pip install pytorch3d

国内用户若下载缓慢，可尝试指定清华源（需确认源中是否有对应版本的 wheel）：

pip install pytorch3d -i https://pypi.tuna.tsinghua.edu.cn/simple

方法三：从源码安装（适用于最新特性或无匹配包时）

如果没有预编译包，需要从源码编译。确保已安装 gcc 和 cuda-toolkit。

git clone https://github.com/facebookresearch/pytorch3d.git
cd pytorch3d
pip install -e .

基本使用

以下是一个最简单的示例，展示如何加载一个网格模型并使用可微分渲染器将其渲染为图像。

1. 导入依赖与加载数据

import torch
from pytorch3d.io import load_obj
from pytorch3d.structures import Meshes
from pytorch3d.vis.texture_vis import texturesuv_image_matplotlib
import matplotlib.pyplot as plt

# 加载 OBJ 文件 (替换为你的文件路径)
# verts: 顶点坐标, faces_idx: 面索引, aux: 包含纹理等辅助信息
verts, faces_idx, aux = load_obj("./data/cow.obj")

# 创建 Meshes 对象，支持批量处理
meshes = Meshes(
    verts=[verts],
    faces=[faces_idx.verts_idx],
    textures=aux.textures
)

# 可视化纹理
if meshes.textures is not None:
    plt.imshow(texturesuv_image_matplotlib(meshes.textures))
    plt.show()

2. 设置相机与渲染器并渲染

from pytorch3d.renderer import (
    look_at_view_transform,
    FoVPerspectiveCameras, 
    PointLights, 
    DirectionalLights, 
    Materials, 
    RasterizationSettings, 
    MeshRenderer, 
    MeshRasterizer, 
    SoftPhongShader,
)

# 设置相机位置
R, T = look_at_view_transform(2.0, 30, 30)
cameras = FoVPerspectiveCameras(device="cuda", R=R, T=T)

# 定义光照
lights = PointLights(device="cuda", location=[[2.0, 2.0, 2.0]])

# 配置光栅化设置
raster_settings = RasterizationSettings(
    image_size=512, 
    blur_radius=0.0, 
    faces_per_pixel=1, 
)

# 构建渲染器
renderer = MeshRenderer(
    rasterizer=MeshRasterizer(
        cameras=cameras, 
        raster_settings=raster_settings
    ),
    shader=SoftPhongShader(
        device="cuda", 
        cameras=cameras,
        lights=lights,
        materials=Materials(device="cuda"),
    )
)

# 执行渲染 (将 mesh 移动到 GPU)
images = renderer(meshes.to("cuda"))

# 显示结果 (images 形状为 [N, H, W, C])
plt.imshow(images[0, ..., :3].cpu().numpy())
plt.axis("off")
plt.show()

3. 利用可微分特性进行优化

由于渲染过程是可微分的，你可以直接对网格顶点或相机参数进行梯度下降优化。

# 开启梯度计算
meshes_verts = meshes.verts_packed()
meshes_verts.requires_grad = True

optimizer = torch.optim.SGD([meshes_verts], lr=0.05)

for i in range(100):
    optimizer.zero_grad()
    
    # 重新构建带有更新顶点的 Meshes 对象
    new_meshes = Meshes(
        verts=[meshes_verts],
        faces=[faces_idx.verts_idx],
        textures=aux.textures
    )
    
    # 渲染
    rendered_images = renderer(new_meshes.to("cuda"))
    
    # 计算损失 (例如：与目标图像的差异)
    # loss = ((rendered_images - target_images) ** 2).mean()
    loss = rendered_images.mean() # 仅作演示
    
    loss.backward()
    optimizer.step()
    
    if i % 10 == 0:
        print(f"Iteration {i}, Loss: {loss.item()}")