3D 数据集

本指南介绍了 3D 文件在 Hub 上的预览方式，以及如何构建包含 OpenUSD 资产的数据集，例如用于机器人仿真的 SimReady 包。您可以在每个 3D 文件的页面上进行预览。在 Dataset Viewer 中，Mesh 列会显示一个缩略图，点击后可在 3D 中打开，并且数据集页面会展示这些资产的图库。包含 .glb、.ply 或 .stl 文件的仓库会自动获得一个 Mesh 列。SimReady 数据集也会获得其资产的图库。

预览 3D 文件

在数据集的 Files and versions 选项卡或 Storage Bucket 中，点击一个 3D 文件即可在交互式 3D 查看器中打开它。您可以旋转、缩放以及全屏查看器。

超过 100 MB 的 glTF、网格、点云和高斯泼溅文件会在您点击 Load 3D preview 时加载，而超过 1 GB 的文件则无法预览。

OpenUSD 图层和纹理

USD 资产通常分布在多个文件中：一个根文件引用子层、负载、材质和纹理。查看器会从同一仓库中加载这些被引用的文件，因此请保留创建资产时的文件夹结构，并使用相对路径进行引用。无法加载指向绝对路径或仓库外文件的引用。

数据集查看器中的 3D 文件

数据集查看器会为 Mesh 列中的每个单元格显示缩略图。点击缩略图即可在 3D 中打开该文件。缩略图支持渲染 .glb、.ply、.stl 和 .obj 文件。

数据集页面还会显示一个 3D Assets 卡片，其中包含所选子集和拆分中前几行数据生成的最多 15 个缩略图。请确保前几行数据包含网格，否则该卡片将不会显示。

3D 文件仓库

如果您的数据集仅包含 .glb、.ply 或 .stl 文件，则无需执行任何操作：它们会自动获得一个 mesh 列。请参阅 创建网格数据集 以添加元数据。

包含 3D 文件的 Parquet 数据集

如果您的数据集以 Parquet 格式存储，Dataset Viewer 会读取 Parquet 文件，并且不会将仓库中的 3D 文件作为一列添加。要在其他列旁边显示 3D 文件，请将文件保留在仓库中，并添加一个引用它们的 Mesh 列：

import json
import pyarrow as pa
import pyarrow.parquet as pq
from datasets import Features, Mesh, Value

table = pq.read_table("train.parquet")

cells = [
    {"bytes": None, "path": f"meshes/{row_id}.glb"}  # relative path from parquet directory to meshes
    for row_id in table["id"].to_pylist()
]
table = table.append_column("mesh", pa.array(cells, type=Mesh().pa_type))

# List all the columns of your dataset
features = Features({"id": Value("string"), "prompt": Value("string"), "mesh": Mesh()})
table = table.replace_schema_metadata(
    {"huggingface": json.dumps({"info": {"features": features.to_dict()}})}
)
pq.write_table(table, "train.parquet")

• 路径必须是相对于包含 Parquet 文件的目录的相对路径。
• 对于没有 3D 文件的行，请使用 None。
• 一个文件夹最多可包含 10,000 个文件，因此请将较大的文件集合分组到子文件夹中。

SimReady 数据集

SimReady 是一项针对 OpenUSD 资产的规范，要求这些资产可直接用于仿真，并包含物理属性、材质和语义标签。包含 SimReady 包的数据集会在其页面上显示一张 3D Assets 卡片，其中列出了包的数量，并展示从整个数据集中采样的最多 15 张缩略图。点击缩略图即可在查看器中打开其 USD 文件。

例如，参见 nvidia/simready-assets 或 nvidia/PhysicalAI-SimReady-Warehouse-01。

这些数据集还会获得 simready 标签，因此在筛选数据集时它们会显示出来。

包结构

包是一个包含 com.nvidia.simready.packaging.json 文件的文件夹。包可以位于仓库中的任意深度，包内的文件夹属于该包的一部分。

每个包都需要其根 USD 文件的缩略图才能在卡片中显示。根据 SimReady 对缩略图的要求，<folder>/<file>.usd 的缩略图为 <folder>/.thumbs/256x256/<file>.usd.png（或 .usda.png、.usdc.png、.usdz.png），位于包文件夹内或其下一层文件夹中：

my_dataset_repository/
├── IV_pole_a01
│   ├── com.nvidia.simready.packaging.json
│   └── simready_usd
│       ├── .thumbs
│       │   └── 256x256
│       │       ├── sm_IV_pole_a01_01.usd.png
│       │       └── sm_IV_pole_a01_01.usd_light.png
│       ├── sm_IV_pole_a01_01.usd
│       └── payloads
│           └── ...
└── IV_pole_a02
    ├── com.nvidia.simready.packaging.json
    └── ...

• 可选的 <file>.usd_light.png 在浅色模式下显示，而 <file>.usd.png 在深色模式下显示。
• 大于 4 MB 的缩略图将被跳过。

每次向数据集推送后，卡片都会更新。

模态标签

包含 3D 文件的数据集会被赋予 3d 模态，因此在使用按模态筛选数据集时会出现。你也可以在数据集卡片中设置该模态，参见强制设置数据集模态。