sindre.utils3d 三维工具包文档

本模块为三维数据处理与深度学习的全功能工具包，涵盖网格/点云处理、牙科专用算法、三维增强、可视化、以及三维深度学习网络。

模块概览

子模块	主要功能描述
mesh	通用三维网格处理与格式互转
dental_tools	牙齿/口腔mesh专用算法
algorithm	三维几何/网格算法与优化
vedo_tools	基于vedo的三维可视化与交互
pointcloud_augment	点云增强与预处理工具
networks	三维深度学习网络与损失函数（重点）

mesh 网格处理

核心类：SindreMesh

通用三维网格对象，支持多格式互转（trimesh、vedo、open3d、pytorch3d等）
支持属性：顶点、面、法线、标签、颜色、曲率等
主要方法：
clone()：快速克隆网格
set_vertex_labels()：设置顶点标签并自动着色
update_geometry()：几何结构更新
compute_normals()：法线计算
apply_transform()：应用变换矩阵
show()：三维可视化
sample()：网格采样点云
to_trimesh()/to_open3d()/to_dict()/to_json()：格式互转
save()/load()：文件读写

示例：

from sindre.utils3d.mesh import SindreMesh
import numpy as np

vertices = np.array([[0,0,0],[1,0,0],[0,1,0]])
faces = np.array([[0,1,2]])
mesh = SindreMesh([vertices,faces])
mesh.get_curvature()
mesh.show()

dental_tools 牙科专用工具

FDI编号与索引转换、标签转颜色、牙冠变换、牙齿mesh切割等
主要函数：
convert_fdi2idx(labels)：FDI编号转索引
convert_labels2color(data)：标签转颜色
transform_crown(near_mesh, jaw_mesh)：牙冠坐标系调整
cut_mesh_point_loop_crow(mesh, pts)：牙冠分割

示例：

from sindre.utils3d.dental_tools import convert_fdi2idx, convert_labels2color
labels = [11, 12, 13, 21, 22]
idx = convert_fdi2idx(labels)
colors = convert_labels2color(labels)

algorithm 三维算法库

三维标签与颜色映射、法线/曲率/边界/体素/采样/重建/分割/优化等
主要函数：
labels2colors(labels)：标签转颜色
compute_vertex_normals(vertices, faces)：顶点法线
compute_face_normals(vertices, faces)：面法线
farthest_point_sampling(vertices, n_sample)：最远点采样
remesh()、fix_invalid_by_meshlab()、A_Star、GraphCutRefiner等高级算法

示例：

from sindre.utils3d.algorithm import labels2colors, compute_vertex_normals
import numpy as np
vertices = np.random.rand(100,3)
faces = np.random.randint(0,100,(50,3))
colors = labels2colors(np.arange(100))
normals = compute_vertex_normals(vertices, faces)

vedo_tools 三维可视化

基于vedo的三维体数据切片与交互、矩阵可视化
主要类/函数：
matrix3d_by_vedo：三维体数据切片窗口
show_matrix_by_vedo(data)：矩阵可视化

示例：

from sindre.utils3d.vedo_tools import matrix3d_by_vedo
import numpy as np
vol = np.random.rand(64,64,64)
viewer = matrix3d_by_vedo(vol)
viewer.show()

pointcloud_augment 点云增强

点云的随机旋转、缩放、平移、抖动、归一化、随机丢弃、裁剪、张量转换等
支持numpy和torch两套API
主要类：
Flip_np、Scale_np、RotateAxis_np、RotateXYZ_np、Jitter_np、Translate_np、RandomDropout_np、Normalize_np、ToTensor、RandomCrop

示例：

from sindre.utils3d.pointcloud_augment import Flip_np, Scale_np
import numpy as np
points = np.random.rand(100,3)
flipper = Flip_np(axis_x=True, axis_y=False)
points_flipped = flipper(points)
scaler = Scale_np(lo=0.9, hi=1.1)
points_scaled = scaler(points)



# 示例
from torchvision import transforms
# torch风格增强流水线
transforms_torch = transforms.Compose([
    ToTensor(device="cuda:0"),
    Normalize(method="MaxMix", v_range=[0,1]),
    RotateAxis(axis=[0,1,0]),
    RotateXYZ(angle_sigma=0.05, angle_clip=0.15),
    Scale(lo=0.8, hi=1.25),
    Translate(translate_range=0.1),
    Jitter(std=0.01, clip=0.05),
    RandomDropout(max_dropout_ratio=0.2),
    Flip(axis_x=False, axis_y=False, axis_z=True),
])

# numpy风格增强流水线
transforms_np = transforms.Compose([
    Normalize_np(method="MaxMix", v_range=[0,1]),
    RotateAxis_np(axis=[0,1,0]),
    RotateXYZ_np(angle_sigma=0.05, angle_clip=0.15),
    Scale_np(lo=0.8, hi=1.25),
    Translate_np(translate_range=0.1),
    Jitter_np(std=0.01, clip=0.05),
    RandomDropout_np(max_dropout_ratio=0.2),
    Flip_np(axis_x=False, axis_y=False, axis_z=True),
    ToTensor(device="cuda:0"),
])

# 示例数据
points = np.random.randn(1024, 6)
points[:,3:6] = np.random.rand(1024,3)

# 批量增强
transformed_points = transforms_torch(points)
transformed_points_np = transforms_np(points)

networks 三维深度学习工具包（重点）

本子包专为三维点云/网格任务设计，包含多种主流深度学习网络结构、损失函数及相关工具。

主要内容

点云/网格神经网络：
pointnet2.py：PointNet++
dgcnn.py：DGCNN
point_transformerV3.py：Point Transformer V3
conv_occ.py：体素卷积/占用网络
Reconstruct3D.py：三维重建网络
image_text_net.py：图像-文本多模态网络
embed_attention.py：嵌入式注意力机制
体素/稀疏卷积：
point2voxel.py、minkowski_utils.py
网络通用工具与损失：
network_utils.py、losses.py

典型用法

from sindre.utils3d.networks.pointnet2 import PointNet2
import torch
model = PointNet2(num_classes=40)
points = torch.rand(8, 1024, 3)
logits = model(points)

from sindre.utils3d.networks.dgcnn import DGCNN
model = DGCNN(num_classes=40)
logits = model(points)

from sindre.utils3d.networks.losses import get_loss
loss = get_loss(logits, labels)

适用场景

三维点云分类/分割/重建/配准/多模态等任务
支持主流三维深度学习研究与工程落地

FAQ

Q: networks子包适合哪些三维任务？
A: 适合点云/网格的分类、分割、重建、配准、占用预测、多模态等主流三维深度学习任务。
Q: 如何自定义自己的三维网络？
A: 可参考networks子包内的网络结构，继承torch.nn.Module，灵活组合已有模块。

如需详细API和参数说明，请查阅完整API文档。

sindre.utils3d 三维工具包文档

目录

模块概览

mesh 网格处理

dental_tools 牙科专用工具

algorithm 三维算法库

vedo_tools 三维可视化

pointcloud_augment 点云增强

networks 三维深度学习工具包（重点）

主要内容

典型用法

适用场景

FAQ