# 创建网格数据集

创建和共享网格数据集有两种方法。本指南将向你展示如何：

* Create a mesh dataset from local files in python with [Dataset.push_to_hub()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.push_to_hub). This is an easy way that requires only a few steps in python.

* 使用 `MeshFolder` 创建包含一些元数据的网格数据集。这是一种无需编写代码的解决方案，可快速创建包含数千个 3D 文件的网格数据集。

> [!TIP]
> 您可以通过要求用户先共享其联系信息来控制对数据集的访问权限。有关如何在 Hub 上启用此功能的更多信息，请参阅 [Gated datasets](https://huggingface.co/docs/hub/datasets-gated) 指南。

## 本地文件

您可以使用网格文件的路径来加载自己的数据集。使用 [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) 特征：

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

>>> 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())
>>> mesh_dataset[0]["mesh"]
<trimesh.Scene(len(geometry)=33)>
```

然后使用 [Dataset.push_to_hub()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.push_to_hub) 将数据集上传到 Hugging Face Hub：

```py
mesh_dataset.push_to_hub("<username>/my_dataset")
```

这将创建一个包含您的网格数据集的数据集仓库：

```text
my_dataset/README.md
my_dataset/data/train-00000-of-00001.parquet
```

## MeshFolder

`MeshFolder` 是一个数据集构建器，旨在快速加载包含数千个网格文件的数据集，且无需编写任何代码。

> [!TIP]
> 查看 [Split pattern hierarchy](repository_structure#split-pattern-hierarchy) 以了解 `MeshFolder` 如何根据数据集仓库结构创建数据集拆分。

`MeshFolder` 会根据目录名称自动推断数据集的类别标签。请将数据集存储在如下目录结构中：

```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("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")
```

您还可以使用 `meshfolder` 来加载涉及多个数据划分的数据集。为此，您的数据集目录应具有以下结构：

```text
folder/train/diya/brass_diya.glb
folder/train/kalash/copper_kalash.glb
folder/test/diya/clay_diya.ply
folder/test/kalash/temple_kalash.stl
```

> [!WARNING]
> 如果所有网格文件都位于同一目录中，或者它们不在同一层级的目录结构中，则不会自动添加`label`列。如果需要该列，请显式设置`drop_labels=False`。

如果您希望提供有关数据集的额外信息，例如文本说明或 3D 资产元数据，请将其作为 `metadata.csv` 文件添加到您的文件夹中。您也可以使用 JSONL 文件 `metadata.jsonl` 或 Parquet 文件 `metadata.parquet`。

```text
folder/train/metadata.csv
folder/train/0001.glb
folder/train/0002.ply
folder/train/0003.stl
```

您也可以压缩网格文件，在这种情况下，每个压缩文件应同时包含网格文件和元数据。

```text
folder/train.zip
folder/test.zip
folder/validation.zip
```

您的 `metadata.csv` 文件必须包含一个 `file_name` 或 `*_file_name` 字段，用于将网格文件与其元数据关联起来：

```csv
file_name,caption
0001.glb,A brass diya with a small bowl and raised wick holder
0002.ply,A copper kalash with a rounded body and narrow neck
0003.stl,A carved jharokha window with an arched frame
```

或使用 `metadata.jsonl`：

```jsonl
{"file_name": "0001.glb", "caption": "A brass diya with a small bowl and raised wick holder"}
{"file_name": "0002.ply", "caption": "A copper kalash with a rounded body and narrow neck"}
{"file_name": "0003.stl", "caption": "A carved jharokha window with an arched frame"}
```

此处 `file_name` 必须是位于元数据文件旁边的网格文件的名称。更一般地，它必须是包含元数据的目录到网格文件的相对路径。

在数据集中的每一行中，可以指向多个网格，例如当输入和输出都是网格文件时：

```jsonl
{"input_file_name": "0001.glb", "output_file_name": "0001_output.glb"}
{"input_file_name": "0002.ply", "output_file_name": "0002_output.ply"}
{"input_file_name": "0003.stl", "output_file_name": "0003_output.stl"}
```

您还可以定义网格列表。在这种情况下，您需要将该字段命名为 `file_names` 或 `*_file_names`。以下是一个示例：

```jsonl
{"parts_file_names": ["0001_bowl.glb", "0001_wick_holder.glb"], "label": "diya"}
{"parts_file_names": ["0002_body.ply", "0002_neck.ply"], "label": "kalash"}
{"parts_file_names": ["0003_frame.stl", "0003_arch.stl"], "label": "jharokha"}
```

### 网格描述

网格描述数据集包含描述 3D 网格的文本。`metadata.csv` 示例可能如下所示：

```csv
file_name,text
0001.glb,A brass diya with a small bowl and raised wick holder
0002.ply,A copper kalash with a rounded body and narrow neck
0003.stl,A carved jharokha window with an arched frame
```

使用 `MeshFolder` 加载数据集，它将创建一个 `text` 列用于网格描述：

```py
>>> dataset = load_dataset("meshfolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"A brass diya with a small bowl and raised wick holder"
```

### 将数据集上传到 Hub

创建数据集后，您可以使用 [push_to_hub()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.DatasetDict.push_to_hub) 方法将其共享到 Hub。请确保已安装 [huggingface_hub](https://huggingface.co/docs/huggingface_hub/index) 库，并已登录您的 Hugging Face 账户（更多详情请参阅 [使用 Python 上传教程](upload_dataset#upload-with-python)）。

使用 [push_to_hub()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.DatasetDict.push_to_hub) 上传您的数据集：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("meshfolder", data_dir="/path/to/folder", split="train")
>>> dataset.push_to_hub("username/my-mesh-captioning-dataset")
```

