# luxonis_loader

Python API: `luxonis_ml.data.loaders.luxonis_loader`

## Classes

### LuxonisLoader

Indexed loader for
[LuxonisDataset](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
samples.

[LuxonisLoader](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
reads one split or multiple splits, loads image sources, assembles labels by task key, optionally applies augmentations, and
returns
[LoaderOutput](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
values with images, labels, and sample metadata.

Iterating a
[LoaderOutput](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
preserves the legacy tuple behavior: for a single-source dataset it yields `(image, labels)`. For a multi-source dataset it yields
`(images, labels)`, where `images` maps source names to arrays.

Label keys use `"task_name/task_type"`. If a dataset was created without a task name, the default task name is empty and keys look
like `"/boundingbox"` or `"/segmentation"`.

#### Methods

##### init

```python
def __init__(dataset: LuxonisDataset, view: str | list[str] = 'train', augmentation_engine: Literal['albumentations'] | str = 'albumentations', augmentation_config: list[Params] | PathType | None = None, height: int | None = None, width: int | None = None, keep_aspect_ratio: bool = True, exclude_empty_annotations: bool = False, color_space: dict[str, Literal['RGB', 'BGR', 'GRAY']] | Literal['RGB', 'BGR', 'GRAY'] | None = None, seed: int | None = None, min_bbox_visibility: float = 0.0, bbox_area_threshold: float = 0.0004, *, keep_categorical_as_strings: bool = False, update_mode: UpdateMode | Literal['all', 'missing'] = UpdateMode.ALL, filter_task_names: list[str] | None = None, autopopulate_metadata: bool = True):
```

Create a loader for a Luxonis dataset.

> **Example**
> ```python
augmentation_config = [
    {
        "name": "Defocus",
        "params": {"p": 1},
    },
    {
        "name": "RandomCrop",
        "params": {"height": 512, "width": 512, "p": 1},
    },
    {
        "name": "Mosaic4",
        "params": {
            "height": 256,
            "width": 256,
            "p": 1.0,
        },
    },
]

loader = LuxonisLoader(
    dataset,
    view="train",
    augmentation_config=augmentation_config,
    height=640,
    width=640,
)
```

Parameters

 * `dataset` (`LuxonisDataset`): Dataset to load from.
 * `view` (`str | list[str]`): Split name or split names to load.
 * `augmentation_engine` (`Literal['albumentations'] | str`): Augmentation engine registry name.
 * `augmentation_config` (`list[Params] | PathType | None`): Optional augmentation configuration or path to a configuration file. Each configuration item contains `name` and optional `params` keys.
 * `height` (`int | None`): Optional output image height. Required when augmentations are enabled.
 * `width` (`int | None`): Optional output image width. Required when augmentations are enabled.
 * `keep_aspect_ratio` (`bool`): Whether resizing should preserve image aspect ratio.
 * `exclude_empty_annotations` (`bool`): Whether to omit empty annotations from the returned label dictionary.
 * `color_space` (`dict[str, Literal['RGB', 'BGR', 'GRAY']] | Literal['RGB', 'BGR', 'GRAY'] | None`): Optional color space for each source. A single value applies to all sources; if omitted, all sources use `"RGB"`.
 * `seed` (`int | None`): Optional random seed for augmentations.
 * `min_bbox_visibility` (`float`): Minimum fraction of the original bounding box that must remain visible after augmentation.
 * `bbox_area_threshold` (`float`): Minimum normalized area for bounding boxes to remain valid. The default removes very small boxes and their associated keypoints.
 * `keep_categorical_as_strings` (`bool`): Whether to keep categorical metadata labels as strings instead of converting them to integers.
 * `update_mode` (`UpdateMode | Literal['all', 'missing']`): Sync mode for media files in remote datasets. Annotations and metadata are always overwritten.
 * `filter_task_names` (`list[str] | None`): Optional task names to include. If omitted, all tasks are included.
 * `autopopulate_metadata` (`bool`): Whether to add automatic sample metadata such as source filenames.

Raises

 * `ValueError`: If [color_space](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md) is neither a string nor a dictionary.
 * `ValueError`: If [filter_task_names](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md) contains task names not present in the dataset.
 * `RuntimeError`: If split metadata is missing.

#### Attributes

##### augmentations

Optional augmentation engine.

##### classes

Class-name mappings per task.

##### color_space

Output color space per source.

##### dataset

Dataset being loaded.

##### df

Dataframe with records used by the loader.

##### exclude_empty_annotations

Whether empty annotations are omitted.

##### filter_task_names

Optional task-name allowlist.

##### height

Optional output image height.

##### idx_to_df_row

Mapping from loader index to dataframe row indices.

##### instances

Group IDs included in the selected views.

##### keep_categorical_as_strings

Whether categorical metadata remains as strings.

##### source_names

Source names expected in each sample.

##### sync_mode

Whether the dataset is remote and pulled before loading.

##### tasks_without_background

Segmentation tasks where unassigned pixels are mapped to background class 0.

##### view

Split names loaded by this loader.

##### width

Optional output image width.