luxonis_ml.data.loaders.LuxonisLoader

class documentation

class LuxonisLoader(BaseLoader):

Constructor: LuxonisLoader(dataset, view, augmentation_engine, augmentation_config, ...)

Indexed loader for LuxonisDataset samples.

LuxonisLoader reads one split or multiple splits, loads image sources, assembles labels by task key, optionally applies augmentations, and returns LoaderOutput values with images, labels, and sample metadata.

Iterating a LoaderOutput 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".

Method	`__getitem__`	Load a sample and its annotations.
Method	`__init__`	Create a loader for a Luxonis dataset.
Method	`__len__`	Return the number of samples in the loader.
Instance Variable	`augmentations`	Optional augmentation engine.
Instance Variable	`classes`	Class-name mappings per task.
Instance Variable	`color_space`	Output color space per source.
Instance Variable	`dataset`	Dataset being loaded.
Instance Variable	`df`	Dataframe with records used by the loader.
Instance Variable	`exclude_empty_annotations`	Whether empty annotations are omitted.
Instance Variable	`filter_task_names`	Optional task-name allowlist.
Instance Variable	`height`	Optional output image height.
Instance Variable	`idx_to_df_row`	Mapping from loader index to dataframe row indices.
Instance Variable	`instances`	Group IDs included in the selected views.
Instance Variable	`keep_categorical_as_strings`	Whether categorical metadata remains as strings.
Instance Variable	`source_names`	Source names expected in each sample.
Instance Variable	`sync_mode`	Whether the dataset is remote and pulled before loading.
Instance Variable	`tasks_without_background`	Segmentation tasks where unassigned pixels are mapped to background class 0.
Instance Variable	`view`	Split names loaded by this loader.
Instance Variable	`width`	Optional output image width.
Static Method	`_merge_sample_metadata`	Undocumented
Method	`_add_empty_annotations`	Undocumented
Method	`_get_augmentation_pipeline_stage`	Undocumented
Method	`_init_augmentations`	Undocumented
Method	`_load_data`	Load image data and annotations by index.
Method	`_load_with_augmentations`	Undocumented
Method	`_precompute_image_paths`	Undocumented
Instance Variable	`_augmentations`	Undocumented
Instance Variable	`_autopopulate_metadata`	Undocumented
Instance Variable	`_classes`	Undocumented
Instance Variable	`_color_space`	Undocumented
Instance Variable	`_df`	Undocumented
Instance Variable	`_df_col_indices`	Undocumented
Instance Variable	`_exclude_empty_annotations`	Undocumented
Instance Variable	`_filter_task_names`	Undocumented
Instance Variable	`_height`	Undocumented
Instance Variable	`_idx_to_df_row`	Undocumented
Instance Variable	`_idx_to_img_paths`	Undocumented
Instance Variable	`_instances`	Undocumented
Instance Variable	`_keep_categorical_as_strings`	Undocumented
Instance Variable	`_source_names`	Undocumented
Instance Variable	`_tasks_without_background`	Undocumented
Instance Variable	`_view`	Undocumented
Instance Variable	`_width`	Undocumented

Inherited from BaseLoader:

Method __iter__ Iterate over the dataset.

@override

def __getitem__(self, idx: int) -> LoaderOutput: ¶

overrides luxonis_ml.data.loaders.BaseLoader.__getitem__

Load a sample and its annotations.

Parameters
idx:`int`	Index of the sample to retrieve.

Returns
`LoaderOutput`	Image data and annotation labels.

Raises
`ValueError`	If the selected views contain no records or a grayscale source has an unsupported image shape.
`FileNotFoundError`	If an image path cannot be found or read.

@typechecked

def __init__(self, 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

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` is neither a string nor a dictionary.
`ValueError`	If `filter_task_names` contains task names not present in the dataset.
`RuntimeError`	If split metadata is missing.

@override

def __len__(self) -> int: ¶

overrides luxonis_ml.data.loaders.BaseLoader.__len__

Return the number of samples in the loader.

Returns
`int`	Number of samples.

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.

@staticmethod

def _merge_sample_metadata(metadata_batch: list[Params]) -> Params: ¶

Undocumented

def _add_empty_annotations(self, img_dict: dict[str, np.ndarray], labels: Labels) -> tuple[dict[str, np.ndarray], Labels]: ¶

Undocumented

def _get_augmentation_pipeline_stage(self) -> str: ¶

Undocumented

def _init_augmentations(self, augmentation_engine: Literal['albumentations'] | str, augmentation_config: list[Params] | PathType, height: int | None, width: int | None, keep_aspect_ratio: bool, seed: int | None = None, min_bbox_visibility: float = 0.0, bbox_area_threshold: float = 0.0004) -> AugmentationEngine | None: ¶

Undocumented

def _load_data(self, idx: int) -> tuple[dict[str, np.ndarray], Labels, Params]: ¶

Load image data and annotations by index.

Parameters
idx:`int`	Index of the image.

Returns
`tuple[dict[str, np.ndarray], Labels, Params]`	Images, labels, and sample metadata present for the sample.

def _load_with_augmentations(self, idx: int) -> tuple[dict[str, np.ndarray], Labels, Params]: ¶

Undocumented

def _precompute_image_paths(self) -> dict[int, dict[str, Path]]: ¶

Undocumented

_augmentations = ¶

Undocumented

_autopopulate_metadata = ¶

Undocumented

_classes = ¶

Undocumented

_color_space = ¶

Undocumented

_df = ¶

Undocumented

_df_col_indices = ¶

Undocumented

_exclude_empty_annotations = ¶

Undocumented

_filter_task_names = ¶

Undocumented

_height = ¶

Undocumented

_idx_to_df_row = ¶

Undocumented

_idx_to_img_paths = ¶

Undocumented

_instances: list[str] = ¶

Undocumented

_keep_categorical_as_strings = ¶

Undocumented

_source_names = ¶

Undocumented

_tasks_without_background: set = ¶

Undocumented

_view = ¶

Undocumented

_width = ¶

Undocumented