# LuxonisML

## Overview

[LuxonisML](https://github.com/luxonis/luxonis-ml) is the core library of the Luxonis machine learning stack. It defines the
Luxonis Data Format (LDF) and provides the shared data, tracking, model archive, telemetry, and utility layers used by tools such
as [LuxonisTrain](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train.md).

Its main capabilities include:

 * creating, managing, synchronizing, and exporting LDF datasets with
   [`LuxonisDataset`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-dataset.md)
 * converting supported third-party dataset formats into LDF with
   [`LuxonisParser`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-parser.md)
 * loading images, labels, and sample metadata with optional augmentation through
   [`LuxonisLoader`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-loader.md)
 * logging experiments to TensorBoard, Weights & Biases, and MLflow through a common tracking API
 * creating and inspecting [NN Archives](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md)
 * working with local files, Google Cloud Storage, and S3-compatible storage through common filesystem utilities

## Installation

LuxonisML requires Python 3.10 or newer. Install the `data` extra for the dataset, parser, loader, and augmentation APIs covered
by these guides:

```bash
python -m pip install "luxonis-ml[data]"
```

Install only the extras required by your application:

| Extra | Adds support for |
| --- | --- |
| `ldf` | LDF annotation schemas |
| `data` | Datasets, parsers, loaders, augmentations, and LDF |
| `tracker` | Experiment tracking API; individual backends can require additional packages |
| `telemetry` | The PostHog telemetry backend |
| `nn_archive` | NN Archive utilities |
| `utils` | Configuration, filesystem, logging, and registry utilities |
| `gcs` | Google Cloud Storage |
| `s3` | S3-compatible storage |
| `roboflow` | Roboflow dataset downloads |
| `mlflow` | MLflow tracking and artifact storage |
| `all` | All published extras |

For example, install the data module together with explicit Roboflow and Google Cloud Storage support using:

```bash
python -m pip install "luxonis-ml[data,roboflow,gcs]"
```

The `tracker` extra supplies the shared tracking dependencies. Install `luxonis-ml[mlflow]` and `opencv-python` for MLflow,
`torch` for TensorBoard, or `wandb` for Weights & Biases as required by the selected backend. See the [tracker API
reference](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)
for backend configuration.

## Quick Start

Convert a supported dataset into LDF with the command-line interface:

```bash
luxonis_ml data parse path/to/dataset --name my_dataset
luxonis_ml data info my_dataset
luxonis_ml data inspect my_dataset
```

The parser detects the source format from its directory structure. Pass `--type` when the structure is ambiguous or when one
layout can represent several task types.

Load a split in Python:

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

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

for sample in loader:
    images = sample.images
    labels = sample.labels
    metadata = sample.metadata
```

`sample.images` is always a dictionary keyed by source name. A standard single-image record uses the `"image"` key. Label keys use
the `"task_name/task_type"` convention, such as `"detection/boundingbox"`.

## Guides and Reference

### Create and manage datasets

Add LDF records, define splits, synchronize storage, clone, merge, and export datasets.

[Open LuxonisDataset guide](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-dataset.md)

### Convert existing datasets

Parse local, cloud-hosted, Roboflow, and Ultralytics datasets into LDF.

[Open LuxonisParser guide](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-parser.md)

### Load and augment data

Read images, labels, and metadata, and configure Albumentations-based pipelines.

[Open LuxonisLoader guide](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-loader.md)

Use the [LuxonisML API
reference](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference.md) for
complete class signatures, annotation schemas, return types, and lower-level extension points.