fiftyone-dataset-import

FiftyOne の汎用データセットインポート

重要な指示

必ず以下のルールに従ってください。

1. まずフォルダーをスキャンする

インポートを始める前に、ディレクトリを詳細にスキャンして構造を把握してください。

# Use bash to explore
find /path/to/data -type f | head -50
ls -la /path/to/data

2. すべてを自動検出する

メディアの種類、ラベル形式、グループ化のパターンを自動的に検出してください。推測できる形式について、ユーザーに指定を求めてはいけません。

3. マルチモーダルグループを検出する

データがグループ化されていることを示すパターンを探してください。

• 複数のメディアファイルを含むシーンフォルダー
• 共通のプレフィックスを持つファイル名のパターン（例：scene_001_left.jpg、scene_001_right.jpg）
• グループ化すべき異なるメディアの種類（画像＋ポイントクラウド）

4. 必要なパッケージを検出してインストールする

名前が指定された自動運転開発キット形式（PandaSet、nuScenes、Waymo Open、Argoverse、KITTI 3D、 Lyft L5、A2D2）には、外部 Python パッケージが必要です。pip show <package> で確認し、インストール前に ユーザーに尋ねてから、スモークテスト用のインポートで検証してください。パッケージの完全な一覧、ディレクトリパターンの 検出方法、変換ワークフローの全体については、 SPECIALIZED-3D-FORMATS.md を参照してください。

MCAP（.mcap/.bag/.rrd）ファイルのインポートやレンダリングにパッケージは不要です。 ファイルの 拡張子だけで media_type == "multimodal" が設定され、チャンネルのデコードとレンダリングは FiftyOne App で クライアント側にて行われます。このために pip install mcap をユーザーに案内してはいけません。Python 側の パッケージが役立つのは、App を開く前にチャンネルスキーマを読み取る任意の用途のみで、これは以下のステップ 9D で説明します。

3D 処理に必要な追加パッケージ： open3d（PCD 変換）、pyntcloud、laspy （LAS/LAZ）。Hugging Face Hub 用： huggingface_hub、pyarrow、Pillow。

5. インポート前に確認を取る

調査結果をユーザーに提示し、データセットを作成する前に必ず明示的に確認を求めてください。 スキャン結果の要約は、必ず次のような明確な質問で締めくくってください。

• 「インポートを進めますか？」
• 「この設定でデータセットを作成しますか？」

続行する前に、ユーザーの返答を待ってください。 ユーザーが確認するまでデータセットを作成してはいけません。

6. 既存のデータセットを確認し、名前を生成する

データセットを作成する前に、指定された名前がすでに存在するか確認してください。

list_datasets()

データセット名がすでに存在する場合は、ユーザーに次の選択肢を提示してください。

• 上書き：既存のデータセットを削除して新規作成する
• 名前を変更：別の名前を使用する（dataset-name-v2 などの代替案を提示）
• 中止：インポートをキャンセルする

ユーザーがデータセット名を指定していない場合は、{ADJECTIVE}_{NOUN}_{VERB} のパターンで楽しくユニークな名前を生成してください。

• squiggly_sky_floats
• droopy_horse_slams
• smooth_grass_grumbles
• nervous_hamburger_yodels

list_datasets() と照合して、一意であることを確認してください。続行する前に、生成した名前を必ずユーザーに伝えてください。

7. インポート後に検証する

インポートしたサンプル数をソースファイル数と比較してください。不一致があれば報告してください。

8. エラーは簡潔にユーザーへ報告する

エラーメッセージはユーザーにわかりやすく簡潔にしてください。問題の診断には、詳細なエラー情報を内部で使用してください。

完全なワークフロー

スキャンを始める前に、対象のソースがどの種類か確認してください — ほとんどのソースはローカルディレクトリで、以下のステップ 1〜12 に従います。ただし、次の 2 つの形式はファイルを個別にスキャンする前に検出します。

• lerobot/... 形式の Hugging Face Hub リポジトリ ID、またはルートに meta/info.json があるローカルディレクトリ → LeRobot です。ステップ 9E と LEROBOT-IMPORT.md に直接進んでください。まずステップ 1 のフォルダースキャンを実行してはいけません。裸のリポジトリ ID は、ダウンロードされるまでローカルにスキャン対象がないためです。
• それ以外の Hugging Face Hub リポジトリ ID（owner/name）、または huggingface.co/datasets/... URL → 以下のHugging Face Hub からのインポートを参照してください。
• .mcap／.bag／.rrd ファイルを含むローカルディレクトリ → スキャン／確認／作成の手順にはステップ 1〜8 を適用し、インポートそのものはステップ 9Dに進んでください。
• その他すべて（画像、動画、点群、または既存のラベル形式へのローカルパス）→ ステップ 1 に進んでください。

ステップ 1：詳細なフォルダースキャン

対象ディレクトリをスキャンして、その構造を把握します。

# Count files by extension
find /path/to/data -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn

# List directory structure (2 levels deep)
find /path/to/data -maxdepth 2 -type d

# Sample some files
ls -la /path/to/data/* | head -20

# IMPORTANT: Scan for ALL annotation/label directories
ls -la /path/to/data/annotations/ 2>/dev/null || ls -la /path/to/data/labels/ 2>/dev/null

以下の項目の一覧を作成します。

• メディアファイルの種類（画像、動画、点群、3D）
• ラベルファイルの形式（JSON、XML、TXT、YAML、PKL）
• ディレクトリ構造（フラット、ネスト、シーンベース）
• 存在するすべてのアノテーションの種類（直方体、セグメンテーション、トラッキングなど）

3D／自動運転データセットでは、特に次の項目を確認してください。

# List all annotation subdirectories
find /path/to/data -type d -name "annotations" -o -name "labels" | xargs -I {} ls -la {}

# Sample an annotation file to understand its structure
python3 -c "import pickle, gzip; print(pickle.load(gzip.open('path/to/annotation.pkl.gz', 'rb'))[:2])"

ステップ 2：メディアの種類を特定する

拡張子ごとにファイルを分類します。

拡張子	メディアの種類	FiftyOne の種類
.jpg, .jpeg, .png, .gif, .bmp, .webp, .tiff	画像	image
.mp4, .avi, .mov, .mkv, .webm	動画	video
.pcd, .ply, .las, .laz	点群	point-cloud
.fo3d, .obj, .gltf, .glb	3D シーン	3d
.mcap, .bag, .rrd	マルチモーダル（ロボティクス／AV センサーログ）	multimodal

MCAP の記録は特別なケースです。 1 つの .mcap ファイルは自己完結型のマルチモーダルエピソードであり、内部に多くの時刻同期されたストリーム（カメラ画像、LIDAR、IMU、GPS、変換、診断情報など）を、それぞれ独自のチャネル／トピックとして格納できます。MCAP 専用のデータセット形式はなく、インポートするラベルファイルもありません。1 つの .mcap ファイルが 1 つのサンプルです。詳しくは、以下のステップ 9Dを参照してください。

LeRobot データセットも特別なケースです。 LeRobot のソースは、ルートに meta/info.json があるディレクトリ（または lerobot/... 形式の Hugging Face Hub リポジトリ）であり、メディアファイルが個別に集められたものではありません。前述のパターンのように、ファイルを 1 つずつスキャンしてはいけません。1 つのサンプルは 1 つのエピソードであり、fo.Dataset.from_dir(..., dataset_type=fo.types.LeRobotDataset) で作成します。add_samples は使用しません。詳しくは、以下のステップ 9Eを参照してください。

ステップ 3：ラベル形式を検出する

ファイルパターンからラベル形式を特定します。

パターン	形式	データセットの種類
COCO 構造を持つ annotations.json または instances*.json	COCO	COCO
Pascal VOC 構造を持つ *.xml ファイル	VOC	VOC
画像ごとの *.txt ＋ classes.txt	YOLOv4	YOLOv4
data.yaml ＋ labels/*.txt	YOLOv5	YOLOv5
画像ごとの *.txt（KITTI 形式）	KITTI	KITTI
単一の annotations.xml（CVAT 形式）	CVAT	CVAT Image
OpenLABEL 構造を持つ *.json	OpenLABEL	OpenLABEL Image
クラスごとのフォルダー構造	分類	Image Classification Directory Tree
ファイルパス列を含む *.csv	CSV	CSV
GeoJSON 構造を持つ *.json	GeoJSON	GeoJSON
.dcm DICOM ファイル	DICOM	DICOM
地理空間メタデータを含む .tiff	GeoTIFF	GeoTIFF
ソースルートにある meta/info.json ＋ meta/episodes/*.parquet（または lerobot/... HF リポジトリ）	LeRobot	LeRobotDataset

LeRobot のロボット学習データセットはファイル単位ではなく、ディレクトリ単位です。上記のパターンに該当するか確認する前に、ソースルートにある meta/info.json（または lerobot/ 名前空間にある HF リポジトリ ID）の存在で検出します。別途インポートするラベルファイルはありません。エピソード、タスク、observation.state／action データはすべて LeRobot インポーターから取得されます。 ステップ 9Eを参照してください。

自動運転に特化した形式（PandaSet、nuScenes、Waymo Open、Argoverse、KITTI 3D、 Lyft L5、A2D2）には、外部開発キットと変換ステップが必要です。ディレクトリパターンによる検出、パッケージ一覧、変換ワークフロー全体については SPECIALIZED-3D-FORMATS.mdを参照してください。

ステップ 4：必要なパッケージを確認する

検出した形式のパッケージがすでにインストールされているか（pip show <package>）を確認し、何がなぜ必要かをユーザーに伝えて、インストール前に許可を求めてから、スモークテストのインポートで確認します。詳細は SPECIALIZED-3D-FORMATS.mdを参照してください。

ステップ 5：グループ化パターンを検出する

データをグループ化すべきかどうかを判断します。

パターン A：シーンフォルダー（マルチモーダルで最も一般的）

/data/
├── scene_001/
│   ├── left.jpg
│   ├── right.jpg
│   ├── lidar.pcd
│   └── labels.json
├── scene_002/
│   └── ...

検出：各サブフォルダーが 1 つのグループで、その中のファイルがスライスです。

パターン B：ファイル名のプレフィックス

/data/
├── 001_left.jpg
├── 001_right.jpg
├── 001_lidar.pcd
├── 002_left.jpg
├── 002_right.jpg
├── 002_lidar.pcd

検出：共通のプレフィックスがグループ ID、サフィックスがスライス名です。

パターン C：グループ化なし（フラット）

/data/
├── image_001.jpg
├── image_002.jpg
├── image_003.jpg

検出：メディアタイプが 1 種類で、明確なグループ化パターンがありません。

パターン D：MCAP マルチモーダル録画（グループ化不要）

/data/
├── episode-0001.mcap
├── episode-0002.mcap
├── episode-0003.mcap

検出：各 .mcap／.bag／.rrd ファイルは、すでに単独で完結したマルチモーダル録画です（カメラ、LIDAR、IMU、GPS などはファイル内の内部チャンネルです）。これらを他のファイルとグループ化しようとしないでください。各録画を 1 つのサンプルとしてインポートします。詳しくは ステップ 9Dを参照してください。

ステップ 6：検出結果をユーザーに提示する

インポートする前に、検出したすべてのラベルを含む明確な概要を提示します。

Scan Results for /path/to/data:

Media Found:
  - 3,000 images (.jpg, .png)
  - 1,000 point clouds (.pkl.gz → will convert to .pcd)
  - 0 videos

Grouping Detected:
  - Pattern: Scene folders
  - Groups: 1,000 scenes
  - Slices: left (image), right (image), front (image), lidar (point-cloud)

ALL Labels Detected:
  ├── cuboids/           (3D bounding boxes, 1,000 files)
  │   └── Format: pickle, Fields: label, position, dimensions, rotation, track_id
  ├── semseg/            (Semantic segmentation, 1,000 files)
  │   └── Format: pickle, point-wise class labels
  └── instances.json     (2D detections, COCO format)
      └── Classes: 10 (car, pedestrian, cyclist, ...)

Required Packages:
  - ✅ pandaset (installed)
  - ⚠️ open3d (needed for PCD conversion) → pip install open3d

Proposed Configuration:
  - Dataset name: my-dataset
  - Type: Grouped (multimodal)
  - Default slice: front_camera
  - Labels to import:
    - detections_3d (from cuboids/)
    - point_labels (from semseg/)
    - detections (from instances.json)

Proceed with import? (yes/no)

重要：

• スキャン中に見つかった注釈タイプをすべて列挙します。
• 各ラベルタイプの形式／構造を示します。
• どのラベルをどのようにインポートするかを示します。
• 続行する前にユーザーの確認を待ちます。

ステップ 7：既存のデータセットを確認し、名前を生成する

作成前に、データセット名がすでに存在するか確認します。

# Check existing datasets
list_datasets()

ユーザーが名前を指定していない場合は、{ADJECTIVE}_{NOUN}_{VERB} のパターン（例：smooth_grass_grumbles）を使って名前を生成します。一意性を確認するため、list_datasets() と照合します。続行する前に、生成した名前を必ずユーザーに伝えてください。

提案したデータセット名が一覧にある場合：

1. ユーザーに伝えます：「'my-dataset' という名前のデータセットはすでに存在し、サンプルが X 個あります。」
2. 希望する対応を尋ねます。
   • 上書き：既存のデータセットを先に削除します。
   • 名前変更：代替名を提案します（例：my-dataset-v2、my-dataset-20240107）。
   • 中止：インポートをキャンセルします。

ユーザーが上書きを選択した場合：

# Delete existing dataset
set_context(dataset_name="my-dataset")
execute_operator(
    operator_uri="@voxel51/utils/delete_dataset",
    params={"name": "my-dataset"}
)

ステップ 8：データセットを作成する

# Create the dataset
execute_operator(
    operator_uri="@voxel51/utils/create_dataset",
    params={
        "name": "my-dataset",
        "persistent": true
    }
)

# Set context
set_context(dataset_name="my-dataset")

ステップ 9A：シンプルなデータセットをインポートする（グループなし）

グループ化されていないフラットなデータセットの場合：

# Import media only
execute_operator(
    operator_uri="@voxel51/io/import_samples",
    params={
        "import_type": "MEDIA_ONLY",
        "style": "DIRECTORY",
        "directory": {"absolute_path": "/path/to/images"}
    }
)

# Import with labels
execute_operator(
    operator_uri="@voxel51/io/import_samples",
    params={
        "import_type": "MEDIA_AND_LABELS",
        "dataset_type": "COCO",
        "data_path": {"absolute_path": "/path/to/images"},
        "labels_path": {"absolute_path": "/path/to/annotations.json"},
        "label_field": "ground_truth"
    }
)

ステップ 9B：グループ化されたデータセットをインポートする（マルチモーダル）

グループを含むマルチモーダルデータの場合は、Python を直接使用してください。ユーザーに次のように案内します。

import fiftyone as fo

# Create dataset
dataset = fo.Dataset("multimodal-dataset", persistent=True)

# Add group field
dataset.add_group_field("group", default="front")

# Create samples for each group
import os
from pathlib import Path

data_dir = Path("/path/to/data")
samples = []

for scene_dir in sorted(data_dir.iterdir()):
    if not scene_dir.is_dir():
        continue

    # Create a group for this scene
    group = fo.Group()

    # Add each file as a slice
    for file in scene_dir.iterdir():
        if file.suffix in ['.jpg', '.png']:
            # Determine slice name from filename
            slice_name = file.stem  # e.g., "left", "right", "front"
            samples.append(fo.Sample(
                filepath=str(file),
                group=group.element(slice_name)
            ))
        elif file.suffix == '.pcd':
            samples.append(fo.Sample(
                filepath=str(file),
                group=group.element("lidar")
            ))
        elif file.suffix == '.mp4':
            samples.append(fo.Sample(
                filepath=str(file),
                group=group.element("video")
            ))

# Add all samples
dataset.add_samples(samples)
print(f"Added {len(dataset)} samples in {len(dataset.distinct('group.id'))} groups")

ステップ 9C：特殊形式のデータセットをインポートする（3D／自動運転）

外部の開発キットが必要なデータセット（PandaSet、nuScenes、Waymo、Argoverse、KITTI 3D、Lyft L5、A2D2）の場合は、開発キットを使って生データを読み込み、点群を PCD に変換し、3D 可視化用の fo.Scene オブジェクトを作成して、検出されたすべてのラベルタイプ（直方体、セグメンテーション、 トラッキング）をインポートします。ワークフロー全体、PCD 変換コード、ラベルタイプのマッピング、完全な PandaSet の実例については、SPECIALIZED-3D-FORMATS.md を参照してください。

ステップ 9D：マルチモーダル（MCAP）録画をインポートする

MCAP は、時間同期されたロボットおよび自動運転車両のセンサーログ（カメラ画像、LIDAR／点群、IMU、GPS、座標フレーム変換、 診断情報などをすべて 1 つのファイル内のチャンネル／トピックとして格納する）に FiftyOne が使用するコンテナ形式です。上記の特殊な 3D 形式とは異なり、インポート時に開発キットも、ラベル変換も、追加の Python パッケージも必要ありません。サンプルの filepath の拡張子だけで、FiftyOne はそのサンプルを media_type == "multimodal" として分類できます。チャンネルスキーマ（ROS 1/2、Foxglove、JSON）のデコードとタイル表示ビューアーの描画は、サンプルを開いたときに App 側で行われます。

このセクションでは、動作する .mcap ファイルがすでにあり、それをデータセットに取り込む必要がある一般的なケースを扱います。 さらに詳しい情報については、リンク先の 3 つのリファレンスファイルを参照してください。実際の状況に合ったものを選んでください。

状況	参照先
タイルが描画されない、または App が「壊れているように見える」	MCAP-TROUBLESHOOTING.md。バグだと判断する前に、症状一覧を確認してください。スキーマをデコードできない場合、ビューアーは仕様上エラーを表示せずに失敗するため、「インポートが動作しない」という報告のほとんどは、実際にはインポートのバグではありません
foxglove-sdk を使って生のセンサーデータ（ROS bag、Zarr、HDF5、PCD、CSV、画像フォルダー）から .mcap を作成する場合、または既存の MCAP ファイルを変換／結合／分割／修正する場合	MCAP-AUTHORING.md
完成したエピソードから FiftyOne データセットを構築する場合、またはインポートの完了を宣言する前	MCAP-DATASET-AND-VALIDATION.md

1. インポート。 各 .mcap ファイルは、必ず 1 つのサンプルになります。パッケージのインストールは不要です。 ユースケース 3（点群）と同じ MEDIA_ONLY ＋ glob パターンの方法を使います。

execute_operator(
    operator_uri="@voxel51/utils/create_dataset",
    params={"name": "robot-teleop-episodes", "persistent": true}
)

set_context(dataset_name="robot-teleop-episodes")

execute_operator(
    operator_uri="@voxel51/io/import_samples",
    params={
        "import_type": "MEDIA_ONLY",
        "style": "GLOB_PATTERN",
        "glob_patt": {"absolute_path": "/path/to/recordings/*.mcap"}
    }
)

または、より細かく制御する場合は Python から直接インポートします（例：エピソードにソース別のタグを付ける、ファイル名から抽出したカスタムメタデータフィールドを追加する）。

import fiftyone as fo
from pathlib import Path

dataset = fo.Dataset("robot-teleop-episodes", persistent=True)

recordings_dir = Path("/path/to/recordings")
samples = [
    fo.Sample(filepath=str(mcap_file))
    for mcap_file in sorted(recordings_dir.glob("*.mcap"))
]

dataset.add_samples(samples)

print(dataset.media_type)  # "multimodal"

2. MCAP サンプルを他のスライスとグループ化しないでください。 各 .mcap ファイルには、すべてのセンサーストリームがすでに含まれています。別途エクスポートしたカメラまたは LiDAR ファイルと一緒に fo.Group() の 1 つのスライスとして追加すると、録画内にすでに含まれているデータが重複します。

2b. トピック名ではなくスキーマで機能を検出し、フィールドとして保存してください。 トピック名は、どのように描画されるかを確実に示すものではありません。/livox/lidar や /os_node/imu_packets という名前のトピックは LiDAR または IMU データのように見えますが、実際のメッセージスキーマがベンダー固有の形式（Livox の livox_ros_driver/msg/CustomMsg や、Ouster の生の ouster_ros/msg/PacketMsg）の場合、FiftyOne には組み込みのデコーダーがありません。トピック名にかかわらず、3D タイルやプロットタイルには描画されず、常に生のメッセージタイルにフォールバックします。各タイルタイプで描画できるのは、決められたスキーマのみです。全リストについては MCAP-TROUBLESHOOTING.md のスキーマからタイルへの対応表を参照してください。カスタムまたは独自仕様の LiDAR メッセージはリストに含まれていないため、メッセージタイルに表示されるのが想定どおりです。 軽量な mcap パッケージ（pip install mcap でインストールでき、ROS のインストールとは無関係な小型の純粋な Python リーダー）を使って、ファイルから実際のスキーマを確認し、結果をブール値のフィールド（has_pointcloud、has_image、has_gps、has_imu など）として保存します。これにより、ユーザーやエージェントは各ファイルを App で開かなくても、多数の記録にわたって機能を照会できます。より限定的なバージョンを再実装するのではなく、 MCAP-DATASET-AND-VALIDATION.md にある完全な mcap_stats()／build_sample() ヘルパーを使用してください。同じ処理で検証に必要な duration_s、message_count、topics、schemas も取得できるため、すべてのサンプルを開いて確認しなくても、dataset.match(F("has_pointcloud")) を使って「このファイルにはポイントクラウドが表示されるか」を判断できます。

3. 検証します。 dataset.media_type == "multimodal" であり、サンプル数がスキャン中に見つかった記録ファイルの数と一致することを確認します。個々のチャンネル、トピック、アノテーション、時間トラックは、Python のインポート手順ではなく、App のマルチモーダルビューアーで確認します。ファイルが数個を超える場合は、 MCAP-DATASET-AND-VALIDATION.md にある低コストの構造チェック validate_mcap() も実行してください。ここでの件数に基づくチェックをすべて通過したファイルでも、サンプルを実際に開いたときに初めて明らかになる形で、ひそかに破損している場合があります。

4. App を起動してストリームを確認します。FiftyOne はマルチモーダルサンプルを、再生クロックを共有するタイル形式のビューアー（画像、3D、地図、プロット、メッセージ、ログの各タイル）で開きます。

launch_app(dataset_name="robot-teleop-episodes")

再生開始時に「データなし」と表示される場合の注意： メッセージ、プロット、3D、地図の各タイルには、現在の再生ヘッド時点での最新メッセージが表示されます。トピックの最初のメッセージが t=0 から始まらない場合（センサーの起動に遅延があるため、よくあります）、そのトピックに紐づいたタイルには、再生をスクラブするか再生して、そのトピックの最初のタイムスタンプを過ぎるまで、たとえば「このトピックの再生ヘッド以前にメッセージがありません」と正しく表示されます。これは想定された動作であり、インポートが壊れているわけではありません。タイルが壊れていると判断する前に、再生ボタンを押すか、先に進むようスクラブして確認してください。それでもタイルがおかしく見える場合は、インポートに失敗したと決めつける前に、 MCAP-TROUBLESHOOTING.md の症状一覧を確認してください。

注意： 時間タグ（dataset.temporal_tags.add(...) で追加する、記録内の時間区間に付けるタグ）は、Enterprise を必要とせずローカルで使用できます。使用例については、 MCAP-DATASET-AND-VALIDATION.md を参照してください。チャンネルを検索可能な Parquet テーブルに変換し、記録をまたいで検索できるようにする MCAP インデックス作成は Enterprise 専用の機能であり、ローカルインポートの範囲外です。ユーザーから質問があった場合は、 FiftyOne Multimodal guide を参照してください。

ステップ 9E：LeRobot のロボット学習データセットをインポートする

LeRobot は、ディレクトリベースのロボット学習データセット形式です（ローカル、または Hugging Face Hub の lerobot/... リポジトリからダウンロードできます。例：lerobot/aloha_sim_insertion_human）。1 サンプルは 1 ファイルではなく、1 つのエピソードです。また、fo.types.LeRobotDataset は v3 レイアウトのみをサポートします。

ワークフロー全体、STOP ゲート、トラブルシューティングについては LEROBOT-IMPORT.md を参照してください。LeRobot のソースをインポートする前に必ずお読みください。 概要：

1. ソース（ローカルパスまたは HF リポジトリ ID）を特定し、Hub 上にある場合はダウンロードします。
2. meta/info.json を確認して codebase_version を検出します。必要に応じて lerobot のコンバーターで v2.x → v3 に変換します（fo.types.LeRobotDataset は v2.x に対して UnsupportedLeRobotVersionError を発生させます）。
3. STOP ゲート： インストールを始める前に、必要なパッケージ（pyarrow>=10.0.0、huggingface_hub、lerobot）がそろっていることを確認します。
4. STOP ゲート： インポート計画（エピソード数、fps、robot_type、カメラ／状態／アクションの形状）を提示し、データセットを作成する前に確認を待ちます。
5. fo.list_datasets() で名前の重複を確認してから、インポートします。

import fiftyone as fo

dataset = fo.Dataset.from_dir(
    dataset_dir="/abs/path/lerobot/<name>",
    dataset_type=fo.types.LeRobotDataset,
    name="<name>",
    persistent=True,
)

6. インポートしたエピソード数を meta/info.json の total_episodes と照合し、dataset.info["lerobot"]["skipped_episodes"] を報告します。どちらかが一致しない場合は、成功と宣言しないでください。
7. App を起動します。エピソードは、カメラごとの Image タイル、State & Action タイル、状態／アクションの各次元を示す Plot タイル、および Streams タブとともに表示されます。

ここでは add_samples は使用しないでください。LeRobot のソースを追加できないためです。既存のデータセットに LeRobot のソースを追加するには、dataset.add_dir(..., dataset_type=fo.types.LeRobotDataset) を使用してください。

ステップ 10：追加のラベルをインポートする（任意）

ラベルが専用形式と一緒にインポートされなかった場合は、別途追加します。

# For COCO labels that reference filepaths
execute_operator(
    operator_uri="@voxel51/io/import_samples",
    params={
        "import_type": "LABELS_ONLY",
        "dataset_type": "COCO",
        "labels_path": {"absolute_path": "/path/to/annotations.json"},
        "label_field": "ground_truth"
    }
)

ステップ 11：インポートを検証する

# Load and verify
load_dataset(name="my-dataset")

# Check counts match
dataset_summary(name="my-dataset")

以下を比較します：

• インポートしたサンプルとソースファイル
• 作成されたグループと想定されるグループ
• インポートしたラベルとアノテーション数

ステップ 12：App を起動して表示する

launch_app(dataset_name="my-dataset")

# For grouped datasets, view different slices
# In the App, use the slice selector dropdown

サポートされているデータセットの種類

メディアの種類

種類	拡張子	説明
image	.jpg, .jpeg, .png, .gif, .bmp, .webp, .tiff	静止画像
video	.mp4, .avi, .mov, .mkv, .webm	フレームを含む動画ファイル
point-cloud	.pcd, .ply, .las, .laz	3D 点群データ
3d	.fo3d, .obj, .gltf, .glb	3D シーンとメッシュ
multimodal	.mcap, .bag, .rrd	時刻同期されたロボティクス／AV センサーの記録（MCAP コンテナ形式）

ラベル形式

形式	データセットタイプの値	ラベルの種類	ファイルパターン
COCO	COCO	検出、セグメンテーション、キーポイント	*.json
VOC/Pascal	VOC	検出	画像ごとに *.xml
KITTI	KITTI	検出	画像ごとに *.txt
YOLOv4	YOLOv4	検出	*.txt + classes.txt
YOLOv5	YOLOv5	検出	data.yaml + labels/*.txt
CVAT Image	CVAT Image	分類、検出、ポリライン、キーポイント	単一の *.xml
CVAT Video	CVAT Video	フレームラベル	XML ディレクトリ
OpenLABEL Image	OpenLABEL Image	すべての種類	*.json ディレクトリ
OpenLABEL Video	OpenLABEL Video	すべての種類	*.json ディレクトリ
TF Object Detection	TF Object Detection	検出	TFRecords
TF Image Classification	TF Image Classification	分類	TFRecords
Image Classification Tree	Image Classification Directory Tree	分類	クラスごとのフォルダー
Video Classification Tree	Video Classification Directory Tree	分類	クラスごとのフォルダー
Image Segmentation	Image Segmentation	セグメンテーション	マスク画像
CSV	CSV	カスタムフィールド	*.csv
DICOM	DICOM	医療メタデータ	.dcm ファイル
GeoJSON	GeoJSON	地理位置情報	*.json
GeoTIFF	GeoTIFF	地理位置情報	地理情報付きの .tiff
FiftyOne Dataset	FiftyOne Dataset	すべての種類	エクスポート形式
LeRobot	LeRobotDataset	エピソードのメタデータ（タスク、状態、アクション、期間）	meta/info.json + meta/episodes/*.parquet

よくあるユースケース

COCO、YOLO、点群、自動運転グループ、分類ツリー、複合メディアのコピー＆ペースト用の出発点は、USE-CASE-EXAMPLES.md にあります。

グループの操作

グループ構造を理解する

グループ化されたデータセットでは：

• 各 グループ は1つのシーン／瞬間（例：1つのタイムスタンプ）を表します
• 各 スライス は1つのモダリティ（例：左カメラ、ライダー）を表します
• グループ内のすべてのサンプルは、同じ group.id を共有します
• 各サンプルには、そのスライスを示す group.name があります

# Access group information
print(dataset.group_slices)        # ['front_camera', 'left_camera', 'lidar']
print(dataset.group_media_types)   # {'front_camera': 'image', 'lidar': 'point-cloud'}
print(dataset.default_group_slice) # 'front_camera'

# Iterate over groups
for group in dataset.iter_groups():
    print(f"Group has {len(group)} slices")
    for slice_name, sample in group.items():
        print(f"  {slice_name}: {sample.filepath}")

# Get specific slice view
front_images = dataset.select_group_slices("front_camera")
all_point_clouds = dataset.select_group_slices(media_type="point-cloud")

アプリでグループを表示する

アプリの起動後：

1. スライスセレクターのドロップダウンがトップバーに表示されます
2. 異なるスライスを選択して各モダリティを表示します
3. サンプルは同期されており、サンプルを選択すると、そのグループ内のすべてのサンプルが表示されます
4. グリッド表示を使うと、複数のスライスを横に並べて表示できます

Hugging Face Hub からインポートする

HF Hub からのインポートに関する完全なドキュメントは、HF-HUB-IMPORT.md を参照してください。

クイックリファレンス：

データセットタイプ	方法
FiftyOne 形式（fiftyone.yml）	load_from_hub("repo_id")
Parquet ベース	load_from_hub("repo_id", format="ParquetFilesDataset", filepath="image")
HF 上の COCO/YOLO/VOC	snapshot_download() → ローカルインポート
レート制限あり（>10K）	Parquet 抽出による代替手段（HF-HUB-IMPORT.md を参照）
LeRobot（lerobot/...）	hf download の後、fo.Dataset.from_dir(..., dataset_type=fo.types.LeRobotDataset) を実行 — ステップ9E を参照

クイックスタート：

from fiftyone.utils.huggingface import load_from_hub

# FiftyOne-formatted dataset
dataset = load_from_hub("Voxel51/VisDrone2019-DET", persistent=True)

# Generic parquet dataset
dataset = load_from_hub(
    "username/dataset",
    format="ParquetFilesDataset",
    filepath="image",
    classification_fields="label",
    persistent=True,
)

LeRobot リポジトリ（lerobot/...）は例外です — load_from_hub() 経由で処理しないでください。 hf download でダウンロードし、代わりに fo.Dataset.from_dir(..., dataset_type=fo.types.LeRobotDataset) でインポートしてください。ステップ9E および LEROBOT-IMPORT.md を参照してください。

トラブルシューティング

エラー：「Dataset already exists」

• 別のデータセット名を使用してください
• または、既存のデータセットを削除してください：execute_operator("@voxel51/utils/delete_dataset", {"name": "dataset-name"})

エラー：「No samples found」

• ディレクトリのパスが正しく、アクセス可能であることを確認してください
• ファイル拡張子がサポートされていることを確認してください
• ネストされたディレクトリの場合は、再帰スキャンが有効になっていることを確認してください

エラー：「Labels path not found」

• ラベルファイルまたはディレクトリが存在することを確認してください
• パスが相対パスではなく、絶対パスであることを確認してください
• 正しい形式が検出されていることを確認してください

エラー：「Invalid group configuration」

• 各グループには少なくとも1つのサンプルが必要です
• スライス名はグループ間で統一する必要があります
• グループごとに許可される3dスライスは1つだけです

インポートに時間がかかる

• 大規模なデータセットでは、委譲実行を使用してください
• 必要に応じて、バッチに分けてインポートしてください
• globパターンを使ってファイルを絞り込むことを検討してください

ポイントクラウドがレンダリングされない

• .pcdファイルが有効であることを確認してください
• FiftyOneの3D可視化が有効になっていることを確認してください
• ポイントクラウドのプラグインがインストールされていることを確認してください

MCAPサンプルを追加したのに、dataset.media_typeが"multimodal"にならない

• ファイルパスの拡張子が正確に.mcap、.bag、または.rrd（小文字）であることを確認してください
• データセットのメディアタイプは、すべてのサンプルの拡張子を反映します。同じ（非グループ化）データセットに.mcapファイルと画像／動画を混在させると、メディアタイプの競合が発生します。MCAPの記録は専用のデータセットまたはグループスライスに保存してください

マルチモーダルタイル（画像／3D／マップ／プロット／ログ）が想定どおりにレンダリングされない

• インポートが壊れているケースはほとんどありません。スキーマをデコードできない場合や、トピックのデータがt=0から始まらない場合、ビューアーは設計上、エラーを表示せずに失敗します。まずMCAP-TROUBLESHOOTING.mdの症状一覧を確認してください
• 既存の.mcapファイルをインポートするだけでなく、ファイル自体を作成、変換、または修正する場合は、代わりにMCAP-AUTHORING.mdを参照してください

グループが検出されない

• フォルダー構造が想定されるパターンと一致していることを確認してください
• シーン間で命名規則が統一されていることを確認してください
• グループ化を手動で指定する必要がある場合があります

LeRobotソースでUnsupportedLeRobotVersionErrorまたはMalformedMediaSourceErrorが発生する

• ソースがv2.xです（meta/episodes/*.parquetではなくmeta/episodes.jsonlを使用しています）。まずv3に変換してください。LEROBOT-IMPORT.mdのステップ4と、トラブルシューティングの全項目を参照してください
• add_samplesではLeRobotソースを追加できません。dataset_type=fo.types.LeRobotDatasetを指定してfrom_dir／add_dirを使用してください

ベストプラクティス

1. 必ず最初にスキャンする - インポート前にデータを把握してください
2. ユーザーに確認する - データセットを作成する前に、確認結果を提示してください
3. わかりやすい名前を付ける - データセット名とラベルフィールドには、意味がわかる名前を使用してください
4. 件数を検証する - インポートしたサンプル数がソースファイル数と一致することを確認してください
5. エラーに適切に対処する - 問題を明確に報告し、有効なファイルの処理を続行してください
6. マルチモーダルデータにはグループを使用する - グループ化すべきデータをフラット化しないでください
7. 適切なデフォルトスライスを設定する - 最もよく表示するモダリティを選択してください
8. インポートにタグを付ける - タグを使ってインポートのバッチやソースを追跡してください

パフォーマンスに関する注意事項

インポート時間の目安：

• 1,000枚の画像：約10～30秒
• 10,000枚の画像：約2～5分
• 100,000枚の画像：約20～60分
• ポイントクラウド：画像の約2倍の時間
• 動画：フレーム抽出の設定によって異なります

メモリ要件：

• サンプルのメタデータ1件あたり約1KB
• メディアファイルはメモリに読み込まず、参照します
• 大規模なデータセットでは、MongoDBの制限値を引き上げる必要がある場合があります

リソース

• FiftyOne データセットのインポートガイド
• グループ化されたデータセットのガイド
• 点群のサポート
• FiftyOne マルチモーダル（MCAP）ガイド
• サポートされているデータセット形式
• FiftyOne I/O プラグイン
• FiftyOne と Hugging Face の統合
• Hugging Face Hub ドキュメント
• LeRobot GitHub リポジトリ — データセット形式、v2→v3 変換スクリプト
• LeRobot データセット形式のドキュメント — エピソード／チャンクの構成、meta/info.json スキーマ

このスキルディレクトリには、毎回すべてを読み込むのではなく、必要に応じて読み込むリファレンスファイルが含まれています。

• HF-HUB-IMPORT.md：Hugging Face Hub の詳細
• SPECIALIZED-3D-FORMATS.md：PandaSet／nuScenes／Waymo／Argoverse／KITTI 3D／Lyft L5／A2D2 の開発キットのワークフロー
• USE-CASE-EXAMPLES.md：一般的なインポート形式のコピー＆ペースト可能な出発点
• MCAP-TROUBLESHOOTING.md：症状の一覧とタイルがレンダリングされない理由
• MCAP-AUTHORING.md：生データからの MCAP 作成、ROS バッグの変換、マージ／パッチ適用
• MCAP-DATASET-AND-VALIDATION.md：機能フラグ、検証、 MCAP インポートのプロセス管理
• LEROBOT-IMPORT.md：LeRobot の完全なワークフロー — HF Hub からのダウンロード、v2.x → v3 変換、STOP ゲート、検証、トラブルシューティング