Learning3D：用于三维点云数据深度学习的现代库。

文档 | 博客 | 示例

Learning3D 是一个开源库，支持开发处理三维数据的深度学习算法。Learning3D 以 Python 提供了一系列最先进的深度神经网络。我们还提供了一个模块化的代码框架，方便进一步开发。欢迎开源社区贡献！

最新动态：

1. [2025年2月28日]：CurveNet 现已加入 Learning3D 库。
2. [2024年4月7日]：Learning3D 现已作为 PyPI 包发布。
3. [2023年10月24日]：MaskNet++ 现已加入 Learning3D 库。
4. [2022年5月12日]：ChamferDistance（fwilliams/fml）损失函数现已集成到 Learning3D 中。这是一个完全基于 PyTorch 的损失函数。
5. [2020年12月24日]：MaskNet 现已准备就绪，可提升 Learning3D 中针对遮挡点云的配准算法性能。
6. [2020年12月24日]：在考虑了 Correspondence Matrices are Underrated 论文后，Learning3D 增加了基于预测与真实对应关系的损失函数。
7. [2020年12月24日]：PointConv，利用点云上的卷积进行潜在特征估计的功能现已加入 Learning3D。
8. [2020年10月16日]：DeepGMR，基于高斯混合模型的配准功能现已加入 Learning3D。
9. [2020年10月14日]：现在，您可以在 Learning3D 中使用自己的数据。（请查看 UserData 功能！）

PyPI 包安装

从 PyPI 服务器安装

pip install learning3d

使用代码安装

git clone https://github.com/vinits5/learning3d.git
cd learning3d
git checkout pypi_v0.1.0
python3 -m pip install .

Learning3D 中可用的计算机视觉算法

序号	任务	算法
1	分类	PointNet, DGCNN, PPFNet, PointConv, CurveNet
2	分割	PointNet, DGCNN
3	重建	点云补全网络 (PCN)
4	配准	PointNetLK, PCRNet, DCP, PRNet, RPM-Net, DeepGMR
5	光流估计	FlowNet3D
6	内点估计	MaskNet, MaskNet++

可用的预训练模型

1. PointNet
2. PCN
3. PointNetLK
4. PCRNet
5. DCP
6. PRNet
7. FlowNet3D
8. RPM-Net (clean-trained.pth, noisy-trained.pth, partial-pretrained.pth)
9. DeepGMR
10. PointConv (从 此链接 下载）
11. MaskNet
12. MaskNet++ / MaskNet2
13. CurveNet

可用的数据集

1. ModelNet40

可用的损失函数

1. 分类损失（交叉熵）
2. 配准损失（FrobeniusNormLoss、RMSEFeaturesLoss）
3. 距离损失（Chamfer Distance、Earth Mover's Distance）
4. 对应关系损失（基于 这篇论文）

技术细节

支持的操作系统

1. Ubuntu 16.04
2. Ubuntu 18.04
3. Ubuntu 20.04.6
4. Linux Mint
5. macOS Sequoia 15.3.1

要求

1. CUDA 10.0 或更高版本
2. PyTorch 1.3 或更高版本
3. Python 3.8

如何使用这个库？

重要提示：请将本仓库克隆到您的项目中。请勿将您的代码添加到 "learning3d" 文件夹中。

1. 所有网络均定义在模块 "models" 中。
2. 所有损失函数均定义在模块 "losses" 中。
3. 数据加载器已在 data_utils/dataloaders.py 文件中预定义。
4. 所有预训练模型均提供在 learning3d/pretrained 文件夹中。

文档

B：批量大小，N：点数，C：通道。

点嵌入网络的使用：

from learning3d.models import PointNet, DGCNN, PPFNet
pn = PointNet(emb_dims=1024, input_shape='bnc', use_bn=False)
dgcnn = DGCNN(emb_dims=1024, input_shape='bnc')
ppf = PPFNet(features=['ppf', 'dxyz', 'xyz'], emb_dims=96, radius='0.3', num_neighbours=64)

序号	变量	数据类型	形状	选项	使用
1.	emb_dims	整数	标量	1024, 512	每个点的特征向量大小
2.	input_shape	字符串	-	'bnc', 'bcn'	输入点云的形状
3.	output	张量	BxCxN	-	每个点的高维嵌入
4.	features	字符串列表	-	['ppf', 'dxyz', 'xyz']	各种特征的使用
5.	radius	浮点数	标量	0.3	计算局部特征的聚类半径
6.	num_neighbours	整数	标量	64	每个聚类最多考虑的点数

分类/分割网络的使用：

from learning3d.models import Classifier, PointNet, Segmentation
classifier = Classifier(feature_model=PointNet(), num_classes=40)
seg = Segmentation(feature_model=PointNet(), num_classes=40)

序号	变量	数据类型	形状	选项	使用
1.	feature_model	对象	-	PointNet / DGCNN	点云嵌入网络
2.	num_classes	整数	标量	10, 40	要分类的对象类别数
3.	output	张量	分类：Bx40，分割：BxNx40	10, 40	每个类别或每个点的概率

配准网络的使用：

from learning3d.models import PointNet, PointNetLK, DCP, iPCRNet, PRNet, PPFNet, RPMNet
pnlk = PointNetLK(feature_model=PointNet(), delta=1e-02, xtol=1e-07, p0_zero_mean=True, p1_zero_mean=True, pooling='max')
dcp = DCP(feature_model=PointNet(), pointer_='transformer', head='svd')
pcrnet = iPCRNet(feature_moodel=PointNet(), pooling='max')
rpmnet = RPMNet(feature_model=PPFNet())
deepgmr = DeepGMR(use_rri=True, feature_model=PointNet(), nearest_neighbors=20)

序号	变量	数据类型	选项	用途	算法
1.	feature_model	对象	PointNet / DGCNN	点云嵌入网络	PointNetLK
2.	delta	浮点数	标量	用于计算近似雅可比矩阵的参数	PointNetLK
3.	xtol	浮点数	标量	迭代停止时的检查容差	PointNetLK
4.	p0_zero_mean	布尔值	真/假	从模板点云中减去均值	PointNetLK
5.	p1_zero_mean	布尔值	真/假	从源点云中减去均值	PointNetLK
6.	pooling	字符串	'max' / 'avg'	用于获取全局特征向量的池化类型	PointNetLK
7.	pointer_	字符串	'transformer' / 'identity'	Transformer/注意力网络的选择	DCP
8.	head	字符串	'svd' / 'mlp'	用于估计配准参数的模块选择	DCP
9.	use_rri	布尔值	真/假	使用最近邻来估计点云特征	DeepGMR
10.	nearest_neighbores	整数	20/任意整数	指定用于估计特征的最近邻数量	DeepGMR

内部点估计网络（MaskNet）的使用：

from learning3d.models import MaskNet, PointNet, MaskNet2
masknet = MaskNet(feature_model=PointNet(), is_training=True) masknet2 = MaskNet2(feature_model=PointNet(), is_training=True)

序号	变量	数据类型	选项	用途
1.	feature_model	对象	PointNet / DGCNN	点云嵌入网络
2.	is_training	布尔值	真 / 假	指定网络是进行训练还是测试

点云补全网络的使用：

from learning3d.models import PCN
pcn = PCN(emb_dims=1024, input_shape='bnc', num_coarse=1024, grid_size=4, detailed_output=True)

序号	变量	数据类型	选项	用途
1.	emb_dims	整数	1024, 512	每个点的特征向量大小
2.	input_shape	字符串	'bnc' / 'bcn'	输入点云的形状
3.	num_coarse	整数	1024	输出点云的形状
4.	grid_size	整数	4, 8, 16	用于生成详细输出的网格大小
5.	detailed_output	布尔值	真 / 假	是否选择附加模块以生成详细的输出点云

PointConv的使用：

使用以下代码创建作者提供的预训练模型。

from learning3d.models import create_pointconv
PointConv = create_pointconv(classifier=True, pretrained='checkpoint路径')
ptconv = PointConv(emb_dims=1024, input_shape='bnc', input_channel_dim=6, classifier=True)

或者
使用以下代码创建您自己的PointConv模型。

PointConv = create_pointconv(classifier=False, pretrained=None)
ptconv = PointConv(emb_dims=1024, input_shape='bnc', input_channel_dim=3, classifier=True)

PointConv变量是一个类。用户可以使用它创建子类，以覆盖create_classifier和create_structure方法，从而改变PointConv的网络架构。

序号	变量	数据类型	选项	用途
1.	emb_dims	整数	1024, 512	每个点的特征向量大小
2.	input_shape	字符串	'bnc' / 'bcn'	输入点云的形状
3.	input_channel_dim	整数	3/6	指定点云是否仅包含xyz坐标，或同时包含法线和颜色
4.	classifier	布尔值	真 / 假	是否希望在PointConv中使用分类器
5.	pretrained	布尔值	字符串	提供预训练分类器模型的路径（仅用于作者提供的权重）

流场估计网络的使用：

from learning3d.models import FlowNet3D
flownet = FlowNet3D()

数据加载器的使用：

from learning3d.data_utils import ModelNet40Data, ClassificationData, RegistrationData, FlowData
modelnet40 = ModelNet40Data(train=True, num_points=1024, download=True)
classification_data = ClassificationData(data_class=ModelNet40Data())
registration_data = RegistrationData(algorithm='PointNetLK', data_class=ModelNet40Data(), partial_source=False, partial_template=False, noise=False)
flow_data = FlowData()

序号	变量	数据类型	选项	用途
1.	train	布尔值	真 / 假	将数据划分为训练集和测试集
2.	num_points	整数	1024	每个点云中的点数
3.	download	布尔值	真 / 假	如果数据不存在则下载
4.	data_class	对象	-	指定使用哪个数据集
5.	algorithm	字符串	'PointNetLK', 'PCRNet', 'DCP', 'iPCRNet'	用于配准的算法
6.	partial_source	布尔值	真 / 假	创建部分源点云
7.	partial_template	布尔值	真 / 假	创建部分模板点云
8.	noise	布尔值	真 / 假	在源点云中添加噪声

使用您自己的数据：

from learning3d.data_utils import UserData
dataset = UserData(application, data_dict)

序号	应用	必需键	对应值
1.	'classification'	'pcs'	点云（BxNx3）
		'labels'	真实类别标签（BxN）
2.	'registration'	'template'	模板点云（BxNx3）
		'source'	源点云（BxNx3）
		'transformation'	真实变换矩阵（Bx4x4）
3.	'flow_estimation'	'frame1'	点云（BxNx3）
		'frame2'	点云（BxNx3）
		'flow'	真实流场向量（BxNx3）

损失函数的使用：

from learning3d.losses import RMSEFeaturesLoss, FrobeniusNormLoss, ClassificationLoss, EMDLoss, ChamferDistanceLoss, CorrespondenceLoss
rmse = RMSEFeaturesLoss()
fn_loss = FrobeniusNormLoss()
classification_loss = ClassificationLoss()
emd = EMDLoss()
cd = ChamferDistanceLoss()
corr = CorrespondenceLoss()

序号	损失类型	用途
1.	RMSEFeaturesLoss	用于计算两个点云全局特征向量之间的均方根值
2.	FrobeniusNormLoss	用于计算两个变换矩阵之间的弗罗贝尼乌斯范数
3.	ClassificationLoss	用于计算交叉熵损失
4.	EMDLoss	两个给定点云之间的地球移动距离
5.	ChamferDistanceLoss	两个给定点云之间的切比雪夫距离
6.	CorrespondenceLoss	使用预测对应关系和真实对应关系，为每个源点计算交叉熵损失

运行示例代码：

1. 将“examples”文件夹中的文件复制到“learning3d”目录之外。
2. 现在运行该文件。（例如：python test_pointnet.py）

• 您的目录/位置
  • learning3d
  • test_pointnet.py

参考文献：

1. PointNet： 用于三维分类与分割的点集深度学习
2. 动态图CNN 用于点云学习
3. PPFNet： 全局上下文感知的局部特征，用于鲁棒的三维点匹配
4. PointConv： 三维点云上的深度卷积网络
5. PointNetLK： 使用PointNet实现鲁棒且高效的点云配准
6. PCRNet： 基于PointNet编码的点云配准网络
7. 深度最近点： 用于点云配准的表示学习
8. PRNet： 部分到部分配准的自监督学习
9. FlowNet3D： 三维点云中场景流的学习
10. PCN： 点云补全网络
11. RPM-Net： 使用学习特征的鲁棒点匹配
12. 3D ShapeNets： 体素形状的深度表示
13. DeepGMR： 学习潜在高斯混合模型用于配准
14. CMU： 对应矩阵被低估了
15. MaskNet： 一种全卷积网络用于估计内点
16. MaskNet++： 两组点云的内点/外点识别
17. CurveNet： 在点云中漫步：用于点云形状分析的曲线学习

Learning3D 快速上手指南

环境准备

• 操作系统：Ubuntu 16.04/18.04/20.04.6、Linux Mint、macOS Sequoia 15.3.1
• CUDA：10.0 或更高版本
• PyTorch：1.3 或更高版本
• Python：3.8

推荐使用 NVIDIA 显卡 + CUDA 环境以获得最佳性能。如需加速下载，可配置 PyPI 镜像源（如清华源）：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple learning3d

安装步骤

方式一：通过 PyPI 安装（推荐）

pip install learning3d

方式二：从源码安装

git clone https://github.com/vinits5/learning3d.git
cd learning3d
git checkout pypi_v0.1.0
python3 -m pip install .

基本使用

1. 点云分类（使用 PointNet）

from learning3d.models import PointNet, Classifier
from learning3d.data_utils import ModelNet40Data

# 加载数据
dataset = ModelNet40Data(train=True, num_points=1024, download=True)

# 创建 PointNet 特征提取器
pointnet = PointNet(emb_dims=1024, input_shape='bnc')

# 创建分类器（40 类）
classifier = Classifier(feature_model=pointnet, num_classes=40)

# 示例输入（B=1, N=1024, C=3）
import torch
points = torch.randn(1, 1024, 3)
logits = classifier(points)
print(logits.shape)  # 输出: torch.Size([1, 40])

2. 点云配准（使用 PointNetLK）

from learning3d.models import PointNet, PointNetLK
from learning3d.data_utils import RegistrationData

# 加载配准数据
data = RegistrationData(algorithm='PointNetLK', data_class=ModelNet40Data())

# 创建 PointNetLK 配准网络
pointnet = PointNet(emb_dims=1024, input_shape='bnc')
pnlk = PointNetLK(feature_model=pointnet, delta=1e-2, xtol=1e-7, pooling='max')

# 输入：源点云和目标点云（均为 BxNx3）
source = torch.randn(1, 1024, 3)
target = torch.randn(1, 1024, 3)
transform = pnlk(source, target)
print(transform.shape)  # 输出: torch.Size([1, 4, 4]) —— 4x4 变换矩阵

所有模型均位于 learning3d.models，数据加载器位于 learning3d.data_utils，预训练模型存于 learning3d/pretrained。
请勿将自定义代码直接写入 learning3d 文件夹内，建议在项目根目录下独立编写。