Créer un jeu de données maillé

Il existe deux méthodes pour créer et partager un jeu de données maillé. Ce guide vous montre comment :

• Créez un jeu de données maillé à partir de fichiers locaux en python avec Dataset.push_to_hub(). C’est une méthode simple qui ne nécessite que quelques étapes en python.

• Créez un jeu de données de maillage avec MeshFolder et quelques métadonnées. Il s’agit d’une solution sans code pour créer rapidement un jeu de données de maillage contenant plusieurs milliers de fichiers 3D.

Vous pouvez contrôler l'accès à votre jeu de données en exigeant que les utilisateurs partagent d'abord leurs coordonnées. Consultez le guide Gated datasets pour plus d'informations sur la manière d'activer cette fonctionnalité sur le Hub.

Fichiers locaux

Vous pouvez charger votre propre jeu de données en utilisant les chemins d’accès à vos fichiers de maillage. Utilisez la fonction cast_column() pour prendre une colonne de chemins d’accès aux fichiers de maillage et la convertir en fonctionnalité Mesh :

>>> 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)>

Ensuite, téléchargez le jeu de données sur le Hugging Face Hub à l'aide de Dataset.push_to_hub() :

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

Cela créera un dépôt de jeu de données contenant votre jeu de données de maillage :

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

MeshFolder

Le MeshFolder est un constructeur de jeu de données conçu pour charger rapidement un jeu de données de maillages contenant plusieurs milliers de fichiers de maillage, sans qu'il soit nécessaire d'écrire du code.

Consultez la hiérarchie des motifs de partitionnement pour en savoir plus sur la manière dont MeshFolder crée des partitions de jeu de données en fonction de la structure de votre dépôt de jeu de données.

MeshFolder infère automatiquement les étiquettes de classes de votre jeu de données en fonction du nom du répertoire. Stockez votre jeu de données dans une structure de répertoires de la forme :

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

Si le jeu de données suit la structure MeshFolder, vous pouvez le charger directement avec load_dataset() :

>>> from datasets import load_dataset

>>> dataset = load_dataset("path/to/folder")

Cela équivaut à passer meshfolder manuellement dans load_dataset() et le répertoire dans data_dir :

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

Vous pouvez également utiliser meshfolder pour charger des jeux de données impliquant plusieurs partitions. Pour ce faire, le répertoire de votre jeu de données doit avoir la structure suivante :

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

Si tous les fichiers de maillage sont contenus dans un seul répertoire ou s’ils ne sont pas au même niveau de la structure de répertoires, la colonne label ne sera pas ajoutée automatiquement. Si vous en avez besoin, définissez explicitement drop_labels=False.

Si vous souhaitez inclure des informations supplémentaires sur votre jeu de données, telles que des légendes de texte ou des métadonnées d’actifs 3D, ajoutez-les sous forme de fichier metadata.csv dans votre dossier. Vous pouvez également utiliser un fichier JSONL metadata.jsonl ou un fichier Parquet metadata.parquet.

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

Vous pouvez également compresser vos fichiers de maillage en archive zip, auquel cas chaque archive doit contenir à la fois les fichiers de maillage et les métadonnées.

folder/train.zip
folder/test.zip
folder/validation.zip

Votre fichier metadata.csv doit contenir un champ file_name ou *_file_name qui associe les fichiers de maillage à leurs métadonnées :

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

ou en utilisant metadata.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"}

Ici, file_name doit être le nom du fichier de maillage situé à côté du fichier de métadonnées. Plus généralement, il doit s’agir du chemin relatif depuis le répertoire contenant les métadonnées jusqu’au fichier de maillage.

Il est possible de pointer vers plusieurs maillages dans chaque ligne de votre jeu de données, par exemple si vos entrées et sorties sont des fichiers de maillage :

{"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"}

Vous pouvez également définir des listes de maillages. Dans ce cas, vous devez nommer le champ file_names ou *_file_names. Voici un exemple :

{"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"}

Légendes de maillage

Les jeux de données de légende de maillages contiennent du texte décrivant un maillage 3D. Un exemple de metadata.csv peut ressembler à :

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

Chargez le jeu de données avec MeshFolder, et il créera une colonne text pour les légendes des maillages :

>>> 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"

Téléverser le jeu de données sur le Hub

Une fois que vous avez créé un jeu de données, vous pouvez le partager sur le Hub à l’aide de la méthode push_to_hub(). Assurez-vous d’avoir installé la bibliothèque huggingface_hub et d’être connecté à votre compte Hugging Face (voir le tutoriel Upload with Python pour plus de détails).

Téléchargez votre jeu de données avec push_to_hub() :

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