Export & conversion

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

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

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:

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.

Convert annotations offline

Source: 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.

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

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.

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

pictograph datasets import-coco road-signs instances_val.json

import_pascal_voc and import_yolo are the same shape.