---
title: Export & Format Conversion
description: Export a Pictograph dataset to any of 12 annotation formats, and convert COCO, YOLO and Pascal VOC annotations offline with no API call and no third-party library.
section: Guides
order: 6
---
Two different jobs, and it is worth being clear which one you want.

**Export** builds a downloadable ZIP of a whole dataset, server-side, in the format your
trainer expects. **Conversion** turns individual annotations to and from COCO / YOLO /
Pascal VOC in memory, on your machine, with no API call.

Training runs read an export, so if you are heading for a training run, you want the
first one.

## Export a dataset

Source: [`resources/exports.py`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.67/src/pictograph/resources/exports.py)

Any of the 12 formats - `pictograph`, `coco`, `yolo`, `yolo_obb`, `yolo_pose`, `dota`,
`pascal_voc`, `darwin`, `cvat`, `datumaro`, `labelme`, `csv` - built by Pictograph's own
converters, with no extra dependency.

`yolo_obb` and `dota` carry **oriented (rotated) boxes**; `coco` and `yolo_pose` carry
**multi-joint pose** (keypoints grouped by `instance_id`).

```python
from pictograph import Client, Export

client = Client()
export: Export = client.exports.create(
    dataset_name="road-signs",
    name="road-signs-coco",
    format="coco",
    include_images=True,
    wait=True,
)
client.exports.download(
    dataset_name="road-signs",
    export_name=export.name,
    output_path="road-signs-coco.zip",
)
```

Or from the CLI:

```bash
pictograph datasets export road-signs --format yolo --include-images -o ./out
```

An export is also what a training run trains on - see [Train a model](/docs/guides/train.md).

## Convert annotations offline

Source: [`formats/`](https://github.com/pictograph-io/pictograph-sdk/tree/v1.69.43/src/pictograph/formats)

`pictograph.formats` converts between external COCO / YOLO / Pascal VOC annotations and
Pictograph's typed models entirely on your machine. Pure in-memory functions over the
same annotation objects the rest of the SDK uses.

```python
from pictograph.formats import from_coco, to_yolo

# Parse a local COCO file into Pictograph's typed models.
imp = from_coco("instances_val.json")   # -> CocoImport(annotations, class_names)

# Emit YOLO label text for one image (normalized to its pixel size).
yolo_txt = to_yolo(
    imp.annotations["a.jpg"],
    imp.class_names,
    image_width=640,
    image_height=480,
)
```

`from_coco` / `to_coco` handle bounding boxes (exact round-trip), polygon segmentation
and keypoints; `from_yolo` / `to_yolo` handle detection and segmentation labels;
`from_pascal_voc` / `to_pascal_voc` handle the per-image XML. For hole-accurate COCO
(RLE) or a downloadable ZIP, use the export above.

## Import a file straight onto a dataset

Source: [`resources/annotations.py`](https://github.com/pictograph-io/pictograph-sdk/blob/v1.69.67/src/pictograph/resources/annotations.py)

One call: creates missing classes, matches images by filename, bulk-saves in chunks, and
returns a per-image report. The dataset must already hold the images the file references.

```python
from pictograph import Client, AnnotationImportReport

client = Client()
report: AnnotationImportReport = client.annotations.import_coco(
    dataset_name="road-signs",
    coco="instances_val.json",
)
print(report.images_saved, "images annotated;", len(report.unmatched_files), "unmatched")
```

```bash
pictograph datasets import-coco road-signs instances_val.json
```

`import_pascal_voc` and `import_yolo` are the same shape.