fiftyone-dataset-export

What this skill does

# Export FiftyOne Datasets

## Key Directives

**ALWAYS follow these rules:**

### 1. Load and understand the dataset first
```python
set_context(dataset_name="my-dataset")
dataset_summary(name="my-dataset")
```

### 2. Confirm export settings with user
Before exporting, present:
- Dataset name and sample count
- Available label fields and their types
- Proposed export format
- Export directory path

### 3. Match format to label types
Different formats support different label types:

| Format | Label Types |
|--------|-------------|
| COCO | detections, segmentations, keypoints |
| YOLO (v4, v5) | detections |
| VOC | detections |
| CVAT | classifications, detections, polylines, keypoints |
| CSV | all (custom fields) |
| Image Classification Directory Tree | classification |

### 4. Use absolute paths
Always use absolute paths for export directories:
```python
params={
    "export_dir": {"absolute_path": "/path/to/export"}
}
```

### 5. Warn about overwriting
Check if export directory exists before exporting. If it does, ask user whether to overwrite.

## Complete Workflow

### Step 1: Load Dataset and Understand Content

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

# Get dataset summary to see fields and label types
dataset_summary(name="my-dataset")
```

Identify:
- Total sample count
- Media type (images, videos, point clouds)
- Available label fields and their types (Detections, Classifications, etc.)

### Step 2: Get Export Operator Schema

```python
# Discover export parameters dynamically
get_operator_schema(operator_uri="@voxel51/io/export_samples")
```

### Step 3: Present Export Options to User

Before exporting, confirm with the user:

```
Dataset: my-dataset (5,000 samples)
Media type: image

Available label fields:
  - ground_truth (Detections)
  - predictions (Detections)

Export options:
  - Format: COCO (recommended for detections)
  - Export directory: /path/to/export
  - Label field: ground_truth

Proceed with export?
```

### Step 4: Execute Export

**Export media and labels:**
```python
execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "MEDIA_AND_LABELS",
        "dataset_type": "COCO",
        "export_dir": {"absolute_path": "/path/to/export"},
        "label_field": "ground_truth"
    }
)
```

**Export labels only (no media copy):**
```python
execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "LABELS_ONLY",
        "dataset_type": "COCO",
        "labels_path": {"absolute_path": "/path/to/labels.json"},
        "label_field": "ground_truth"
    }
)
```

**Export media only (no labels):**
```python
execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "MEDIA_ONLY",
        "export_dir": {"absolute_path": "/path/to/media"}
    }
)
```

### Step 5: Verify Export

After export, verify the output:

```bash
ls -la /path/to/export
```

Report exported file count and structure to user.

## Supported Export Formats

### Detection Formats

| Format | `dataset_type` Value | Label Types | Labels-Only |
|--------|----------------------|-------------|-------------|
| COCO | `"COCO"` | detections, segmentations, keypoints | Yes |
| YOLOv4 | `"YOLOv4"` | detections | Yes |
| YOLOv5 | `"YOLOv5"` | detections | No |
| VOC | `"VOC"` | detections | Yes |
| KITTI | `"KITTI"` | detections | Yes |
| CVAT Image | `"CVAT Image"` | classifications, detections, polylines, keypoints | Yes |
| CVAT Video | `"CVAT Video"` | frame labels | Yes |
| TF Object Detection | `"TF Object Detection"` | detections | No |

### Classification Formats

| Format | `dataset_type` Value | Media Type | Labels-Only |
|--------|----------------------|------------|-------------|
| Image Classification Directory Tree | `"Image Classification Directory Tree"` | image | No |
| Video Classification Directory Tree | `"Video Classification Directory Tree"` | video | No |
| TF Image Classification | `"TF Image Classification"` | image | No |

### Segmentation Formats

| Format | `dataset_type` Value | Label Types | Labels-Only |
|--------|----------------------|-------------|-------------|
| Image Segmentation | `"Image Segmentation"` | segmentation | Yes |

### General Formats

| Format | `dataset_type` Value | Best For | Labels-Only |
|--------|----------------------|----------|-------------|
| CSV | `"CSV"` | Custom fields, spreadsheet analysis | Yes |
| GeoJSON | `"GeoJSON"` | Geolocation data | Yes |
| FiftyOne Dataset | `"FiftyOne Dataset"` | Full dataset backup with all metadata | Yes |

**Note:** Formats with "Labels-Only: No" require `export_type: "MEDIA_AND_LABELS"` (cannot export labels without media).

## Export Type Options

| `export_type` Value | Description |
|---------------------|-------------|
| `"MEDIA_AND_LABELS"` | Export both media files and labels |
| `"LABELS_ONLY"` | Export labels only (use `labels_path` instead of `export_dir`) |
| `"MEDIA_ONLY"` | Export media files only (no labels) |
| `"FILEPATHS_ONLY"` | Export CSV with filepaths only |

## Target Options

Export from different sources:

| `target` Value | Description |
|----------------|-------------|
| `"DATASET"` | Export entire dataset (default) |
| `"CURRENT_VIEW"` | Export current filtered view |
| `"SELECTED_SAMPLES"` | Export selected samples only |

## Common Use Cases

### Use Case 1: Export to COCO Format

For training with frameworks that use COCO format:

```python
set_context(dataset_name="my-dataset")

execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "MEDIA_AND_LABELS",
        "dataset_type": "COCO",
        "export_dir": {"absolute_path": "/path/to/coco_export"},
        "label_field": "ground_truth"
    }
)
```

Output structure:
```
coco_export/
├── data/
│   ├── image1.jpg
│   └── image2.jpg
└── labels.json
```

### Use Case 2: Export to YOLO Format

For training YOLOv5/v8 models:

```python
set_context(dataset_name="my-dataset")

execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "MEDIA_AND_LABELS",
        "dataset_type": "YOLOv5",
        "export_dir": {"absolute_path": "/path/to/yolo_export"},
        "label_field": "ground_truth"
    }
)
```

Output structure:
```
yolo_export/
├── images/
│   └── train/
│       └── image1.jpg
├── labels/
│   └── train/
│       └── image1.txt
└── dataset.yaml
```

### Use Case 3: Export Filtered View

Export only a subset of samples:

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

# Filter samples in the App
set_view(tags=["validated"])

# Export the filtered view
execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "target": "CURRENT_VIEW",
        "export_type": "MEDIA_AND_LABELS",
        "dataset_type": "COCO",
        "export_dir": {"absolute_path": "/path/to/validated_export"},
        "label_field": "ground_truth"
    }
)
```

### Use Case 4: Export Labels Only

When media should stay in place:

```python
set_context(dataset_name="my-dataset")

execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "LABELS_ONLY",
        "dataset_type": "COCO",
        "labels_path": {"absolute_path": "/path/to/annotations.json"},
        "label_field": "ground_truth"
    }
)
```

### Use Case 5: Export for Classification Training

For image classification datasets:

```python
set_context(dataset_name="my-classification-dataset")

execute_operator(
    operator_uri="@voxel51/io/export_samples",
    params={
        "export_type": "MEDIA_AND_LABELS",
        "dataset_type": "Image Classification Directory Tree",
        "export_dir": {"absolute_path": "/path/to/classification_export"},
        "label_field": "ground_truth"
    }
)
```

Output structure:
```
classification_export/
├── cat/
│   ├── cat1.jpg
│   └── cat2.jpg
└── dog/
    ├── dog1.jpg
    └── dog2.jpg
```

### Use Case 6: Export to C