# 加载网格数据

网格数据集包含 [Mesh](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Mesh) 类型的列，其中包含 `trimesh.Trimesh` 或 `trimesh.Scene` 对象。

> [!TIP]
> 要处理网格数据集，您需要安装 `mesh` 依赖项。请参阅 [安装](./installation#mesh) 指南了解如何安装。

加载网格数据集并调用网格列时，网格会通过`trimesh`进行解码：

```py
>>> from datasets import load_dataset, Mesh

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train")
>>> dataset[0]["mesh"]
<trimesh.Scene(len(geometry)=33)>
```

根据文件内容，`trimesh` 可能返回一个 `trimesh.Trimesh` 对象或一个 `trimesh.Scene` 对象。

> [!WARNING]
> 使用行索引先索引到网格数据集，然后索引到 `mesh` 列 - `dataset[0]["mesh"]` - 以避免解码数据集中的所有网格文件。否则，如果数据集较大，这可能是一个缓慢且耗时的过程。

如需了解如何加载任意类型的数据集，请参阅通用加载指南。

## 本地文件

您可以从网格路径加载数据集。使用 [cast_column()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.cast_column) 函数接受一列网格文件路径，并使用 [Mesh](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Mesh) 特征将其解码为 `trimesh` 对象：

```py
>>> from datasets import Dataset, Mesh

>>> dataset = Dataset.from_dict({"mesh": ["path/to/model_1.glb", "path/to/model_2.ply", "path/to/model_3.stl"]}).cast_column("mesh", Mesh())
>>> dataset[0]["mesh"]
<trimesh.Scene(len(geometry)=33)>
```

如果只想加载网格数据集的底层路径或字节，而不解码网格对象，请在 [Mesh](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Mesh) 特征中设置 `decode=False`：

```py
>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train").cast_column("mesh", Mesh(decode=False))
>>> dataset[0]["mesh"]
{'bytes': b'...',
 'path': '00001.glb'}
```

[Mesh](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Mesh) 功能支持 `.glb`、`.ply` 和 `.stl` 文件。根据文件内容，`trimesh` 可能返回 `trimesh.Trimesh` 对象或 `trimesh.Scene` 对象。

## MeshFolder

您也可以通过 `MeshFolder` 数据集构建器加载数据集，这无需编写自定义的数据加载器。这使得 `MeshFolder` 非常适合快速创建和加载包含数千个 3D 文件的网格数据集。您的网格数据集结构应如下所示：

```text
folder/train/diya/brass_diya.glb
folder/train/diya/clay_diya.ply
folder/train/diya/festival_diya.stl

folder/train/kalash/copper_kalash.glb
folder/train/kalash/pooja_kalash.ply
folder/train/kalash/temple_kalash.stl
```

如果数据集遵循 `MeshFolder` 结构，则可以直接使用 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 加载：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_name")
>>> # OR locally:
>>> dataset = load_dataset("/path/to/folder")
```

对于本地数据集，这相当于在 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 中手动传入 `meshfolder` 以及 `data_dir` 中的目录：

```py
>>> dataset = load_dataset("meshfolder", data_dir="/path/to/folder")
```

然后，您可以将网格作为 `trimesh` 对象进行访问：

```py
>>> dataset["train"][0]
{"mesh": <trimesh.Scene(len(geometry)=33)>, "label": 0}
```

若要忽略元数据文件中的信息，请在 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 中设置 `drop_metadata=True`：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_with_metadata", drop_metadata=True)
```

如果没有元数据文件，`MeshFolder` 会自动从目录名称推断标签名称。如果要丢弃自动创建的标签，请设置 `drop_labels=True`。在这种情况下，您的数据集将仅包含一个网格列：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("username/dataset_without_metadata", drop_labels=True)
```

最后，`filters` 参数允许你基于标签或元数据中的条件，仅加载数据集的一个子集。如果元数据采用 Parquet 格式，这一点尤其有用，因为该格式支持快速过滤。同时，建议将此参数与 `streaming=True` 一起使用，因为默认情况下，数据集会在过滤之前被完整下载。

```python
>>> filters = [("label", "=", 0)]
>>> dataset = load_dataset("username/dataset_name", streaming=True, filters=filters)
```

> [!TIP]
> 有关创建自定义 `MeshFolder` 数据集的更多信息，请参阅 [创建网格数据集](./mesh_dataset) 指南。

## 网格解码

默认情况下，当您在数据集上迭代时，网格会按顺序解码为 `trimesh.Trimesh` 或 `trimesh.Scene` 对象。

如果您对解码为 `trimesh` 对象的网格不感兴趣，而是希望访问其路径或字节数据，则可以禁用解码：

```python
>>> dataset = dataset.decode(False)
```

注意：[IterableDataset.decode()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.IterableDataset.decode) 目前仅适用于流式数据集。