LuxonisLoader

Overview

LuxonisLoader offers a simple and efficient way to load and iterate through data stored in the Luxonis Data Format (LDF), with support for on-the-fly data augmentation. Since it is also natively integrated with LuxonisTrain, this enables a smooth and seamless training workflow.

Dataset Loading

To load a dataset with LuxonisLoader, we first need an instance of LuxonisDataset. The loader is initialized with the dataset and the dataset view (i.e. the split) we intend to load.

Python

1from luxonis_ml.data.datasets import LuxonisDataset
2from luxonis_ml.data.loaders import LuxonisLoader
3
4dataset_name: str = ... # name of an existing LDF dataset, _e.g._ "parking_lot"
5dataset = LuxonisDataset(dataset_name)
6loader = LuxonisLoader(dataset, view="train")

The view can be either a single split or a list of splits.

The data can be iterated over using a simple for loop:

Python

1for images, labels in loader:
2    ...

For single-source datasets, images is typically a single image array. For multi-source datasets, it can also be a dictionary keyed by source or component name. The labels output is grouped by task name.

Augmentation

Augmentations are transformations applied to the data to increase the diversity of the dataset, thus improving the model training. We can define them by passing a list of Python dictionaries to the augmentation_config parameter of the LuxonisLoader constructor, each representing an individual augmentation:

Python

1{
2    "name": str,  # name of the augmentation
3    "params": dict  # parameters of the augmentation
4}

By default, we support most augmentations from the albumentations library. You can find the full list of augmentations and their parameters in the Albumentations documentation. On top of that, we provide a handful of custom batch augmentations:

Mosaic4 - Mosaic augmentation with 4 images. Combines crops of 4 images into a single image in a mosaic pattern.
MixUp - MixUp augmentation. Overlays two images with a random weight.

Each augmentation entry can also define use_for_resizing: true when you want that transform to handle resizing explicitly.

Example

The following example demonstrates a simple augmentation pipeline:

Python

1[
2  {
3    'name': 'HueSaturationValue',
4    'params': {
5      'p': 0.5,
6      'hue_shift_limit': 3,
7      'sat_shift_limit': 70,
8      'val_shift_limit': 40,
9    }
10  },
11  {
12    'name': 'Rotate',
13    'params': {
14      'p': 0.6,
15      'limit': 30,
16      'border_mode': 0,
17      'value': [0, 0, 0]
18    }
19  },
20  {
21    'name': 'Perspective',
22    'params': {
23      'p': 0.5,
24      'scale': [0.04, 0.08],
25      'keep_size': True,
26      'pad_mode': 0,
27      'pad_val': 0,
28      'mask_pad_val': 0,
29      'fit_output': False,
30      'interpolation': 1,
31      'always_apply': False,
32    }
33  },
34  {
35    'name': 'Affine',
36    'params': {
37      'p': 0.4,
38      'scale': None,
39      'translate_percent': None,
40      'translate_px': None,
41      'rotate': None,
42      'shear': 10,
43      'interpolation': 1,
44      'mask_interpolation': 0,
45      'cval': 0,
46      'cval_mask': 0,
47      'mode': 0,
48      'fit_output': False,
49      'keep_ratio': False,
50      'rotate_method': 'largest_box',
51      'always_apply': False,
52    }
53  },
54]

Let's assume the augmentation list above is stored as a YAML file named augmentations.yaml. We can then use it to create a loader:

Python

1from luxonis_ml.data.datasets import LuxonisDataset
2from luxonis_ml.data.loaders import LuxonisLoader
3
4dataset_name: str = ...
5dataset = LuxonisDataset(dataset_name)
6loader = LuxonisLoader(
7    dataset,
8    view="train", 
9    augmentation_config="augmentations.yaml", 
10    augmentation_engine="albumentations",  # default
11    height=256,
12    width=320,
13    keep_aspect_ratio=True, # default
14    color_space="RGB",  # default, can be also BGR
15)
16for img, labels in loader:
17    ...

The augmentations are not necessarily applied in the same order as defined in the list. Instead, an optimal order is determined based on the type of the augmentations to minimize computational cost.

Additional loader options

The current loader also supports several useful options that are important in larger training pipelines:

exclude_empty_annotations=True to drop empty label entries from the final label dictionary
filter_task_names=[...] to load only selected task groups from a multi-task dataset
keep_categorical_as_strings=True to keep categorical metadata values as strings instead of encoded integers
color_space={...} to set color space per source when working with multi-source datasets
update_mode="all" or "missing" to control local synchronization behavior for remote datasets

For the full constructor signature and return types, see the API reference.