Detection Dataset Utilities

Three utility functions for working with detection datasets after collection: format conversion, multi-dataset merging, and visual inspection.

Install

For visualize(), FiftyOne must be installed:

pip install "telekinesis-dataengine[viz]"

convert_dataset() and merge_datasets() are available in the base install.

Import

from telekinesis.dataengine import convert_dataset, merge_datasets, visualize

---

convert_dataset()

Convert a dataset between YOLO and RF-DETR/COCO formats.

result = convert_dataset(
    src_dir,            # source dataset directory
    dst_dir,            # output directory
    to_format,          # "yolo" | "rfdetr"
    *,
    src_format=None,    # auto-detected if None
    task="detect",      # "detect" | "segment"
    overwrite=False,
)

Parameters

Parameter	Type	Description
src_dir	str | Path	Root of the source dataset.
dst_dir	str | Path	Output directory for the converted dataset.
to_format	str	Target format: "yolo" or "rfdetr".
src_format	str | None	Source format. Auto-detected from layout if not provided.
task	str	"detect" (bounding boxes) or "segment" (instance masks).
overwrite	bool	Overwrite dst_dir if it already exists.

Returns

{"counts": {"train": 16, "val": 2, "test": 2}, "num_classes": 2}

Example

from telekinesis.dataengine import convert_dataset

# ------------------------------------------------
# 1. Convert a YOLO dataset to RF-DETR/COCO format
# ------------------------------------------------
result = convert_dataset(
    src_dir="results/detection_yolo",
    dst_dir="results/detection_rfdetr",
    to_format="rfdetr",
)

print(result)
# {"counts": {"train": 16, "val": 2, "test": 2}, "num_classes": 2}

---

merge_datasets()

Merge two or more detection datasets (any mix of YOLO and RF-DETR) into a single output dataset. Category names are unified across sources — classes with the same name get the same id in the merged output.

result = merge_datasets(
    src_dirs,           # list of source dataset directories
    dst_dir,            # output directory
    *,
    to_format="coco",   # output format: "yolo" | "rfdetr"
    task="detect",
    overwrite=False,
)

Parameters

Parameter	Type	Description
src_dirs	list[str | Path]	Source dataset directories. Supports any mix of YOLO and RF-DETR.
dst_dir	str | Path	Output directory for the merged dataset.
to_format	str	Output format: "yolo" or "rfdetr". Default "rfdetr".
task	str	"detect" or "segment".
overwrite	bool	Overwrite dst_dir if it already exists.

Example

from telekinesis.dataengine import merge_datasets

# ------------------------------------------------
# 1. Merge two datasets collected at different times
# ------------------------------------------------
result = merge_datasets(
    src_dirs=[
        "results/session_monday",
        "results/session_tuesday",
    ],
    dst_dir="results/merged_dataset",
    to_format="yolo",
)

print(result)
# {"counts": {"train": 32, "val": 4, "test": 4}, "num_classes": 2}

---

visualize()

Open a dataset in FiftyOne for interactive visual inspection. Prints a per-split, per-class annotation summary and launches the FiftyOne app in your browser.

visualize(
    dataset_dir,            # dataset root directory
    dataset_format=None,    # "yolo" | "rfdetr" | None (auto-detected)
    *,
    name=None,              # FiftyOne dataset name
    max_samples=None,       # limit samples loaded
)

Parameters

Parameter	Type	Description
dataset_dir	str | Path	Root of the dataset to visualize.
dataset_format	str | None	Format hint. Auto-detected from layout if None.
name	str | None	Name shown in the FiftyOne UI.
max_samples	int | None	Maximum number of samples to load.

Example

from telekinesis.dataengine import visualize

# ------------------------------------------------
# 1. Visualize a YOLO dataset in FiftyOne
# ------------------------------------------------
visualize("results/detection_yolo")

# ------------------------------------------------
# 2. Limit samples and set a custom name
# ------------------------------------------------
visualize(
    "results/detection_rfdetr",
    name="warehouse_run_01",
    max_samples=500,
)

---

Full Pipeline Example

from telekinesis.dataengine import (
    DetectionLogger,
    convert_dataset,
    merge_datasets,
    visualize,
)

categories = [{"id": 1, "name": "box", "supercategory": "object"}]

# ------------------------------------------------
# 1. Log two sessions in different formats
# ------------------------------------------------
with DetectionLogger.create("yolo", "results/session_a", categories) as log_a:
    for image, anns in session_a_data:
        log_a.log(image, anns)

with DetectionLogger.create("rfdetr", "results/session_b", categories) as log_b:
    for image, anns in session_b_data:
        log_b.log(image, anns)

# ------------------------------------------------
# 2. Merge both sessions into one YOLO dataset
# ------------------------------------------------
merge_datasets(
    src_dirs=["results/session_a", "results/session_b"],
    dst_dir="results/merged",
    to_format="yolo",
)

# ------------------------------------------------
# 3. Visualize the merged dataset
# ------------------------------------------------
visualize("results/merged")