# data

Python API: `luxonis_ml.data`

Public entry point for Luxonis Data Format workflows.

The luxonis_ml.data package brings together the high-level APIs used to create, convert, load, and augment datasets in the Luxonis
Data Format (LDF). LDF is the dataset representation used across the Luxonis training stack for vision datasets with one or more
media sources, task groups, annotation types, metadata fields, local files, and remote object storage.

This module is intentionally a map of the package rather than the canonical home for every detailed contract. Details live next to
the implementation that owns them:

 * [luxonis_ml.data.datasets](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
   documents dataset lifecycle, storage layout, splits, cloning, merging, remote synchronization, and dataset plugins.
 * [luxonis_ml.data.datasets.annotation](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md)
   documents
   [DatasetRecord](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md),
   [Detection](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md),
   [Category](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md),
   and all annotation payload schemas.
 * [luxonis_ml.data.parsers](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers.md)
   documents
   [LuxonisParser](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/luxonis_parser.md),
   supported external formats, split-ratio modes, and parser-specific caveats.
 * [luxonis_ml.data.loaders](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
   documents
   [LuxonisLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md),
   loader outputs, label key conventions, color spaces, filtering, and preprocessing.
 * [luxonis_ml.data.augmentations](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
   documents
   [AlbumentationsEngine](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md),
   transform ordering, resizing, batch transforms, and custom transforms.

Table of Contents

 * [Core
   Workflow](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [Tutorial
   Dataset](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [Records, Tasks, and
   Labels](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [Annotation
   Payloads](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [Command Line
   Interface](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [Extension
   Points](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)

## Core Workflow

Most data pipelines follow the same sequence:

 1. Create or open a
    [LuxonisDataset](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md).
 2. Add records from an iterable or parse an external dataset with
    [LuxonisParser](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/luxonis_parser.md).
 3. Define dataset splits.
 4. Load one or more splits with
    [LuxonisLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md).
 5. Optionally apply augmentations through
    [AlbumentationsEngine](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md).
 6. Optionally clone, merge, export, push, pull, inspect, sanitize, or delete the dataset.

High-level APIs

| API | Use it when you need to | More detail |
| --- | --- | --- |
|
[LuxonisDataset](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
| Create, mutate, split, clone, merge, export, synchronize, or delete LDF datasets. |
[luxonis_ml.data.datasets](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
|
|
[LuxonisParser](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/luxonis_parser.md)
| Convert a supported external dataset layout into LDF. |
[luxonis_ml.data.parsers](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers.md)
|
|
[LuxonisLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
| Iterate image-like inputs and labels from one or more dataset splits. |
[luxonis_ml.data.loaders](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
|
|
[AlbumentationsEngine](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
| Apply runtime image and label augmentation while loading samples. |
[luxonis_ml.data.augmentations](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
|

> **Example**
> A minimal flow starts with the dataset, then constructs a loader.

```python
from luxonis_ml.data import LuxonisDataset, LuxonisLoader

dataset = LuxonisDataset("parking_lot")
loader = LuxonisLoader(dataset, view="train")

for inputs, labels in loader:
    ...
```

> **Note**
> Importing from luxonis_ml.data is the recommended public API for common workflows. Import from lower modules when you need implementation-specific models such as annotation schemas, parser classes, or loader base classes.

## Tutorial Dataset

Most examples in the data package use a small `parking_lot` dataset with cars and motorcycles. It contains object-detection boxes,
instance keypoints, semantic segmentation masks for color/type/brand/binary vehicle classes, and metadata suitable for trying the
full LDF workflow.

The dataset can be used to exercise task naming conventions:

 * keypoint annotations for classes with different skeletons should be separated into task groups such as
   `"instance_keypoints_car"` and `"instance_keypoints_motorbike"`;
 * semantic segmentation is usually placed in its own task group, such as `"segmentation"`, because loaders add a background class
   for segmentation tasks.

Hands-on notebooks and scripts for preparing and interacting with LuxonisML datasets are maintained in the Luxonis AI tutorials
repository: `https://github.com/luxonis/ai-tutorials/tree/main/training`.

The original `parking_lot` sample archive used by these examples is available at
`https://drive.google.com/uc?export=download&id=1OAuLlL_4wRSzZ33BuxM6Uw2QYYgv_19N`.

## Records, Tasks, and Labels

Dataset ingestion is record-based. A record points to one file or to multiple synchronized files, optionally assigns a task name,
and optionally provides an annotation payload.

> **Example**
> The two supported media-key styles are easy to distinguish.

```pycon
>>> single_source = {"file": "image.jpg", "annotation": None}
>>> multi_source = {"files": {"rgb": "rgb.png", "depth": "depth.png"}}
>>> "file" in single_source, "files" in multi_source
(True, True)
```

Task names group annotations that should be consumed together by a model or loader. Loader label keys use `"task_name/task_type"`.
If no task name is provided, the task name is the empty string and keys start with `"/"`.

> **Example**
> ```pycon
>>> task_name = "detection"
>>> task_type = "boundingbox"
>>> f"{task_name}/{task_type}"
'detection/boundingbox'
>>> f"{''}/segmentation"
'/segmentation'
```

> **See Also**
> [luxonis_ml.data.datasets.annotation](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md) for the exact record model, annotation payload schemas, normalized coordinate conventions, metadata categories, and instance-association rules.

## Annotation Payloads

LDF supports a small set of annotation payload families:

 * classification through a `"class"` value;
 * normalized `xywh` bounding boxes through `"boundingbox"`;
 * normalized `(x, y, visibility)` keypoint triplets through `"keypoints"`;
 * semantic segmentation masks through polygon points, binary masks, or COCO RLE values under `"segmentation"`;
 * instance segmentation masks through the same mask encodings under `"instance_segmentation"`;
 * arbitrary `.npy` array targets through `"array"`;
 * flexible metadata values through `"metadata"`.

Any annotation with a class contributes a classification target. When separate records describe the same physical object, use the same `instance_id` so boxes, keypoints, and instance masks can be associated reliably.

> **See Also**
> [luxonis_ml.data.datasets.annotation](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md) for examples, exact field names, mask encoding details, metadata categories, and loader output shapes.

## Command Line Interface

The data package also provides dataset operations through `luxonis_ml data`. The CLI mirrors the Python APIs for parsing, listing, inspecting, validating, sanitizing, exporting, synchronizing, cloning, merging, and deleting datasets.

```bash
luxonis_ml data --help
luxonis_ml data parse --help
luxonis_ml data parse <data_directory>
luxonis_ml data ls
luxonis_ml data info <dataset_name>
luxonis_ml data inspect <dataset_name>
luxonis_ml data health <dataset_name>
luxonis_ml data sanitize <dataset_name>
luxonis_ml data export <dataset_name> --type ultralytics-ndjson
luxonis_ml data export <dataset_name> --type ultralytics-ndjson-instancesegmentation
luxonis_ml data export <dataset_name> --type ultralytics-ndjson-keypoints
luxonis_ml data push <dataset_name>
luxonis_ml data pull <dataset_name>
luxonis_ml data clone <dataset_name> <new_name>
luxonis_ml data merge <source_name> <target_name>
luxonis_ml data delete <dataset_name>
```

> **See Also**
> [luxonis_ml.data.main](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/__main__.md) for command implementation details.

## Extension Points

Datasets and loaders are registry-backed. Third-party packages can expose entry points in the `dataset_plugins` and `loader_plugins` groups. This module loads those plugins at import time and registers them in [DATASETS_REGISTRY](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md) and [LOADERS_REGISTRY](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md).

> **See Also**
> [BaseDataset](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md), [BaseLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md), [DatasetIterator](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md), [DATASETS_REGISTRY](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md), and [LOADERS_REGISTRY](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md).

## Child Pages

 * [augmentations](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
 * [datasets](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [exporters](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/exporters.md)
 * [loaders](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
 * [parsers](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers.md)
 * [utils](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils.md)
 * [Data CLI](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/__main__.md)