FiftyOne 3D Visual AI 实战指南：点云、网格与 3D 标注的完整数据工作流

FiftyOne 3D Visual AI 实战指南点云、网格与 3D 标注的完整数据工作流【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone本指南基于 FiftyOne 官方 3D Visual AI Guide见 docs/source/getting_started/threed_visual_ai/index.rst系统讲解如何在 FiftyOne 中完成从原始 3D 数据LiDAR 点云、GLTF/OBJ/PLY/STL/FBX 网格的加载与可视化到 3D 边界框、3D 折线等标注的叠加、查询与校验的完整工作流。读完本文你将掌握fo.Scene()场景构建、FO3D 文件格式、3D 查看器交互导航以及 2D/3D 标注类自动切换的核心用法可直接应用于自动驾驶、机器人、AR/VR 等空间计算场景的数据整理与模型训练准备。指南概述一条完整的 3D 数据处理链路官方指南将整个 3D 工作流拆解为两个循序渐进的步骤对应两个 Jupyter Notebook入门 3D 数据集Getting Started with 3D Datasets——学习如何在 FiftyOne 中加载和可视化原始 3D 数据含点云在 3D 查看器中完成基本导航并围绕空间任务组织数据集。对应文件01_getting_started_3d.ipynb。加载 3D 标注Loading 3D Annotations——为点云添加边界框与标签等标注学习如何引入标注并使其无缝叠加到场景中用于检查与验证。对应文件02_loading_annotations.ipynb。两个 Notebook 均可独立运行——每个文件开头都包含必要的pip install命令无需预先配置任何环境。前置条件目标读者面向希望在 FiftyOne 中处理 3D 数据集的开发者与计算机视觉工程师。无论你面对的是 LiDAR 点云、体素网格还是 3D 边界框本系列都会介绍所需的工具与工作流。所需知识熟悉 FiftyOne 的数据集结构Dataset/Sample/ 标签字段体系与基础计算机视觉概念即可有 2D 检测标注经验会更快上手点云或 3D 标注经验非必需。主要依赖包包用途fiftyone核心库数据集管理、场景构建与 3D 可视化open3d3D 数据处理与点云操作可选辅助numpy数值运算与数组操作matplotlib可视化与绘图系统要求按官方指南操作系统LinuxUbuntu 24.04、macOSPython3.10、3.11、3.12内存3D 操作建议 8GB RAM存储预留 5GB 可用空间存放 3D 数据集显卡大型点云可视化建议配备 GPUNotebook 环境Jupyter、Google Colab、VS Code Notebook 均已验证3D 数据格式全景点云Point CloudsLiDAR 数据——来自自动驾驶车辆与机器人的原始传感器数据PLY 格式——带颜色与法线信息的标准点云格式亦可表示网格PCD 格式——面向高效存储的点云数据格式是 FiftyOnePointCloud对象直接支持的类型XYZ 格式——基于简单坐标系的点云表示3D 网格3D MeshesGLTF/GLB——现代 3D 格式支持材质与动画OBJ——Wavefront Object 格式常用于 3D 几何建模PLY——Stanford Triangle 格式可表示网格或点云STL——用于 3D 打印的立体光刻格式FBX——Autodesk 3D 内容交换格式支持 FBX 7.x3D 标注3D Annotations3D 边界框3D Bounding Boxes——目标检测包含位置、尺寸与旋转3D 折线3D Polylines——3D 空间中的路径与车道线标注3D 分割3D Segmentation——面向语义理解的点级标注核心工作流加载 → 场景管理 → 可视化 → 标注集成官方指南演示的完整 3D 数据工作流由四步组成数据加载Data Loading——以正确的坐标系与变换加载不同 3D 格式点云、网格场景管理Scene Management——使用 FiftyOne 的Scene类与 FO3D 文件格式创建、组织 3D 场景3D 可视化3D Visualization——在 FiftyOne 交互式 3D 查看器中导航与交互标注集成Annotation Integration——添加 3D 边界框、折线等标注支撑综合分析这套集成式方案不仅让你能加载3D 数据更能理解空间关系、管理复杂 3D 场景并面向 3D 计算机视觉应用准备数据集。Step 1入门 3D 数据集理解 FiftyOne Scene 与 FO3D 文件FiftyOne 通过fo.Scene()管理 3D 样本其序列化产物即FO3D 文件.fo3d后缀。从源码看Scene本质是一个场景图内部以 n 叉树结构组织 3D 对象每个对象是树中的一个节点参见 fiftyone/core/threed/scene_3d.py 中Scene类定义。一个 3D 对象可以是3D 网格Mesh——ObjMesh、GltfMesh、PlyMesh、StlMesh、FbxMesh点云Point Cloud——PointCloud3D 形状几何Shape Geometry——BoxGeometry、SphereGeometry等参见 fiftyone/core/threed/shape_3d.pyScene还可显式初始化camera、lights、background等附加属性。默认情况下场景使用中性光照一个环境光加六个不同角度的方向光并使用右手坐标系、up 轴为 Y 轴的透视相机——可通过PerspectiveCamera(upZ)等参数覆盖相机类定义见 fiftyone/core/threed/camera.py支持up/fov/near/far参数默认 fov50、near0.1、far2000。场景构建完成后必须调用scene.write()将其序列化为轻量级 FO3D 文件写入磁盘。从源码scene_3d.py可以看到write()会校验输出路径必须以.fo3d结尾、检查节点重名并支持resolve_relative_paths将资源相对路径解析为绝对路径与pprintJSON 美化输出两个选项。如何加载一个 3D 样本任何 filepath 以.fo3d结尾的 Sample 都会被识别为 3D 样本由 3D 样本组成的数据集其media_type为3d。你可以在一个.fo3d场景内存储多个 3D 对象用单个样本封装整个待覆盖的场景。import fiftyone as fo # 1. 构建场景设置相机 up 轴为 Z scene fo.Scene() scene.camera fo.PerspectiveCamera(upZ) # 2. 添加自定义网格对象 mesh fo.GltfMesh(mesh, mesh.glb) mesh.rotation fo.Euler(90, 0, 0, degreesTrue) # 3. 添加两个几何球体并自定义颜色与位置 sphere1 fo.SphereGeometry(sphere1, radius2.0) sphere1.position [-1, 0, 0] sphere1.default_material.color red sphere2 fo.SphereGeometry(sphere2, radius2.0) sphere2.position [1, 0, 0] sphere2.default_material.color blue scene.add(mesh, sphere1, sphere2) # 4. 写入 FO3D 文件 scene.write(/path/to/scene.fo3d) # 5. 作为样本加入数据集 sample fo.Sample(filepath/path/to/scene.fo3d) dataset fo.Dataset() dataset.add_sample(sample) print(dataset.media_type) # 3d上面这段代码中mesh.glb与两个球体被一并加入场景通过position校正各对象位置通过default_material.color定制颜色最后整体写出为 FO3D 文件。这正是 FiftyOne 的核心思路——一个.fo3d文件 一个完整 3D 场景 一个 Sample。修改既有场景若要修改已存在的场景使用Scene.from_fo3d()加载执行必要的更新后再写回磁盘scene fo.Scene.from_fo3d(/path/to/scene.fo3d) for node in scene.traverse(): if isinstance(node, fo.SphereGeometry): node.visible False scene.write(/path/to/scene.fo3d)其中traverse()是场景图的深度遍历接口源码见 scene_3d.py它递归产出场景中的所有Object3D节点是批量操作场景内对象的统一入口。与此配套的还有get_scene_summary()统计各类对象数量、get_asset_paths()列出全部资源路径与update_asset_paths()按映射批量改写资源路径等实用方法均有对应单元测试覆盖见 tests/unittests/threed/scene_3d_tests.py。3D 网格格式支持与材质处理3D 网格由顶点、边与面组成定义对象的几何形状。部分格式只存几何另一些则同时包含材质属性与纹理——若网格文件含材质与纹理FiftyOne 会自动加载并显示。你也可以通过设置网格的default_material属性来指定默认材质当文件不含任何材质信息时网格会被赋予一个默认的MeshStandardMaterial含color、roughness、metalness、opacity、emissive_color等参数见 fiftyone/core/threed/material_3d.py且可在 App 中动态调整。FiftyOne 当前支持GLTF、OBJ、PLY、STL、FBX 7.x网格格式对应类见 fiftyone/core/threed/mesh.pyimport fiftyone as fo scene fo.Scene() mesh1 fo.GltfMesh(mesh1, mesh.glb) mesh1.rotation fo.Euler(90, 0, 0, degreesTrue) mesh2 fo.ObjMesh(mesh2, mesh.obj) # 可选 mtl_path 参数加载 .mtl 材质 mesh3 fo.PlyMesh(mesh3, mesh.ply) # 可选 is_point_cloud / center_geometry mesh4 fo.StlMesh(mesh4, mesh.stl) mesh5 fo.FbxMesh(mesh5, mesh.fbx) scene.add(mesh1, mesh2, mesh3, mesh4, mesh5) scene.write(/path/to/scene.fo3d)几个值得注意的实现细节均可在 mesh.py 中验证路径校验ObjMesh要求obj_path以.obj结尾、mtl_path以.mtl结尾FbxMesh/PlyMesh/StlMesh分别要求.fbx/.ply/.stlGltfMesh要求.gltf或.glb否则抛出ValueError资源路径既可以是绝对路径也可以相对于.fo3d文件所在目录。PLY 的双重身份PlyMesh通过is_point_cloud参数区分网格与点云两种形态并默认center_geometryTrue自动居中几何体。OBJ 材质ObjMesh支持mtl_path显式关联.mtl材质文件若未提供或文件中找不到材质则回退到默认MeshStandardMaterial。3D 点云PCD 格式与材质控制FiftyOne 直接支持PCD 点云格式。创建一个可加入 3D 场景的 PCD 对象import fiftyone as fo pcd fo.PointCloud(my-pcd, point-cloud.pcd) pcd.default_material.shading_mode custom pcd.default_material.custom_color red pcd.default_material.point_size 2 scene fo.Scene() scene.add(pcd) scene.write(/path/to/scene.fo3d)PointCloud类见 fiftyone/core/threed/pointcloud.py要求pcd_path以.pcd结尾并支持center_geometry默认False与flag_for_projection标记用于正交投影每个场景最多一个等参数。其默认材质PointCloudMaterial提供以下可调项见 material_3d.py参数默认值说明shading_modeheight着色模式支持height按高度、intensity按强度、rgb按颜色、custom自定义色custom_color#ffffff自定义颜色仅当shading_modecustom时生效point_size1.0点的大小opacity1.0不透明度范围[0, 1]多传感器点云叠加3D 场景与点云的一大优势在于可以在同一场景中堆叠多个点云以镜像不同传感器的输出。例如一个 LiDAR 传感器与多个按相同时间间隔触发的 RADAR 传感器——用 FiftyOne 可同时可视化全部点云也可按需逐个开关。这一设计思路来自Scene的 n 叉树场景图结构任意数量的网格、点云与形状都可以作为独立节点挂载在同一场景下通过visible属性控制显示状态。Step 2加载 3D 标注3D 样本上的标注字段3D 样本可以包含任意类型与数量的自定义字段包括3D 检测与3D 折线它们可被 App 的 3D 可视化器原生显示。与几何数据不同的是3D 标注存储在数据集专门的字段中而非嵌入 FO3D 文件——因此它们可以像其他原始/标签字段一样通过数据集视图dataset views在 App 中进行查询与过滤。典型用法如下import fiftyone as fo scene fo.Scene() scene.add(fo.GltfMesh(mesh, mesh.gltf)) scene.write(/path/to/scene.fo3d) detection fo.Detection( labelvehicle, location[0.47, 1.49, 69.44], dimensions[2.85, 2.63, 12.34], rotation[0, -1.56, 0], ) sample fo.Sample( filepath/path/to/scene.fo3d, ground_truthfo.Detections(detections[detection]), )3D 边界框参数详解location / dimensions / rotation下面逐个拆解location、dimensions、rotation的含义这些参数在源码 fiftyone/core/labels.py 的Detection类文档中有明确定义import fiftyone as fo # 对象标签 label vehicle # 对象中心 [x, y, z]使用场景坐标 location [0.47, 1.49, 69.44] # 对象尺寸 [x, y, z]使用场景单位 dimensions [2.85, 2.63, 12.34] # 对象绕其中心的旋转 [x, y, z]取值范围 [-pi, pi] rotation [0, -1.56, 0] # 一个 3D 目标检测 detection fo.Detection( labellabel, locationlocation, dimensionsdimensions, rotationrotation, )关于坐标系的注意点这里的场景坐标从[0, 0, 0]开始该原点几乎总是自车ego位置即传感器开始采集的位置它并不映射到任何已知的全局坐标如 GPS/UTM。在做多帧数据融合或跨传感器标注对齐时务必确认各数据的坐标系约定一致。3D 折线Polylines3D 折线的用法与 3D 检测高度相似它同样作为数据集上的专用字段存储需要label与points3d两个参数# 对象标签 label lane # 一个列表的列表每个元素为场景坐标下的 [x, y, z] 顶点 # 描述折线中每条形状的顶点 points3d [[[-5, -99, -2], [-8, 99, -2]], [[4, -99, -2], [1, 99, -2]]] # 一组语义相关的 3D 折线 polyline fo.Polyline(labellabel, points3dpoints3d)即points3d是一个嵌套结构外层列表对应多条形状内层列表对应每条形状的顶点序列每个顶点是[x, y, z]三元组。这与 2DPolyline的points参数[0,1]×[0,1]归一化坐标在结构上类似但坐标语义从归一化平面坐标切换为场景三维坐标。自动的 2D / 3D 标注类型切换注意一个关键设计3D 场景下你并不使用Detection3D或Polyline3D类。FiftyOne 的Detection与Polyline标签类会根据输入参数自动适配 2D 或 3D 形态Detection提供bounding_box2D时按 2D 目标检测处理提供locationdimensionsrotation3D时按 3D 目标检测处理参见 labels.py 的类文档。Polyline提供points2D或points3d3D时分别对应 2D/3D 折线。这意味着你可以在同一数据集内混用 2D 与 3D 标注FiftyOne 自动完成区分与可视化无需维护两套标签体系。总结你已经掌握了什么完成上述两步后你已具备Step 1入门 3D 数据集加载并可视化原始 3D 数据含点云理解Scene类与 FO3D 文件格式处理 GLTF、OBJ、PLY、STL、FBX 等不同网格格式在 3D 查看器中完成基本导航围绕空间任务组织 3D 数据集并理解坐标系。Step 2加载 3D 标注为点云添加边界框与标签等标注理解 3D 边界框的location位置、dimensions尺寸、rotation旋转参数用 3D 折线做路径标注掌握 FiftyOne 如何自动处理 2D 与 3D 标注类型。建议练习多格式 3D 数据分别用 GLTF、OBJ、PLY、STL 加载同一对象对比其在 FiftyOne 中的加载与显示差异评估哪种格式最适合你的场景。3D 场景合成组合多个网格、点云与几何形状构建复杂 3D 场景观察场景组织方式对可视化效果的影响。3D 标注分析混用边界框、折线与分割等不同类型 3D 标注分析其空间关系。坐标系理解实验不同的坐标系与变换如Euler旋转、相机up轴设置观察它们如何影响 3D 可视化与标注精度。性能优化使用大型点云并调节不同可视化设置如point_size、着色模式观察数据规模对性能的影响。进一步方向评估 3D 目标检测模型引入预测结果与真值对 3D 边界框运行性能评估。可视化多模态传感器数据将点云与 2D 图像、分割掩码等结合获得全场景理解。构建自定义 3D 工作流针对自动驾驶、机器人、AR/VR 等具体领域创建专属工作流。延伸阅读仓库内资源指南索引页docs/source/getting_started/threed_visual_ai/index.rst配套 Notebook ①场景、网格、点云01_getting_started_3d.ipynb配套 Notebook ②3D 标注02_loading_annotations.ipynb指南总结与练习summary.rst核心源码场景与 FO3D 序列化见 fiftyone/core/threed/scene_3d.py网格类见 fiftyone/core/threed/mesh.py点云见 fiftyone/core/threed/pointcloud.py材质见 fiftyone/core/threed/material_3d.py相机见 fiftyone/core/threed/camera.py3D 标注定义见 fiftyone/core/labels.py单元测试tests/unittests/threed/scene_3d_tests.py覆盖 FO3D 写入/读取、资源路径解析、场景摘要、高斯溅射等、tests/unittests/threed/transformation_tests.py、tests/unittests/threed/material_3d_tests.py【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考