| Name | luxonis-train JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Luxonis training framework for seamless training of various neural networks. |
| upload_time | 2024-12-10 08:19:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| keywords |
ml
training
luxonis
oak
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
blobconverter
lightning
luxonis-ml
onnx
onnxruntime
onnxsim
optuna
optuna-integration
parameterized
psycopg2-binary
pycocotools
rich
s3fs
tensorboard
torchvision
typer
mlflow
psutil
tabulate
grad-cam
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Luxonis Training Framework
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/astral-sh/ruff)
[](https://codecov.io/gh/luxonis/luxonis-train)
<a name="overview"></a>
## 🌟 Overview
`LuxonisTrain` is a user-friendly tool designed to streamline the training of deep learning models, especially for edge devices. Built on top of `PyTorch Lightning`, it simplifies the process of training, testing, and exporting models with minimal coding required.
### ✨ Key Features
- **No Coding Required**: Define your training pipeline entirely through a single `YAML` configuration file.
- **Predefined Configurations**: Utilize ready-made configs for common computer vision tasks to start quickly.
- **Customizable**: Extend functionality with custom components using an intuitive Python API.
- **Edge Optimized**: Focus on models optimized for deployment on edge devices with limited compute resources.
> \[!WARNING\]
> **The project is in a beta state and might be unstable or contain bugs - please report any feedback.**
<a name="quick-start"></a>
## 🚀 Quick Start
Get started with `LuxonisTrain` in just a few steps:
1. **Install `LuxonisTrain`**
```bash
pip install luxonis-train
```
This will create the `luxonis_train` executable in your `PATH`.
1. **Use the provided `configs/detection_light_model.yaml` configuration file**
You can download the file by executing the following command:
```bash
wget https://raw.githubusercontent.com/luxonis/luxonis-train/main/configs/detection_light_model.yaml
```
1. **Find a suitable dataset for your task**
We will use a sample COCO dataset from `RoboFlow` in this example.
1. **Start training**
```bash
luxonis_train train \
--config detection_light_model.yaml \
loader.params.dataset_dir "roboflow://team-roboflow/coco-128/2/coco"
```
1. **Monitor progress with `TensorBoard`**
```bash
tensorboard --logdir output/tensorboard_logs
```
Open the provided URL in your browser to visualize the training progress
## 📜 Table Of Contents
- [🌟 Overview](#overview)
- [✨ Key Features](#key-features)
- [🚀 Quick Start](#quick-start)
- [🛠️ Installation](#installation)
- [📝 Usage](#usage)
- [💻 CLI](#cli)
- [⚙️ Configuration](#configuration)
- [🗃️ Data Preparation](#data-preparation)
- [📂 Data Directory](#data-directory)
- [💾 `LuxonisDataset`](#luxonis-dataset)
- [🏋️♂️Training](#training)
- [✍ Testing](#testing)
- [🧠 Inference](#inference)
- [🤖 Exporting](#exporting)
- [🗂️ NN Archive](#nn-archive)
- [🔬 Tuning](#tuning)
- [🎨 Customizations](#customizations)
- [📚 Tutorials and Examples](#tutorials-and-examples)
- [🔑 Credentials](#credentials)
- [🤝 Contributing](#contributing)
<a name="installation"></a>
## 🛠️ Installation
`LuxonisTrain` requires **Python 3.10** or higher. We recommend using a virtual environment to manage dependencies.
**Install via `pip`**:
```bash
pip install luxonis-train
```
This will also install the `luxonis_train` CLI. For more information on how to use it, see [CLI Usage](#cli).
<a name="usage"></a>
## 📝 Usage
You can use `LuxonisTrain` either from the **command line** or via the **Python API**.
We will demonstrate both ways in the following sections.
<a name="cli"></a>
### 💻 CLI
The CLI is the most straightforward way how to use `LuxonisTrain`. The CLI provides several commands for training, testing, tuning, exporting and more.
**Available commands:**
- `train` - Start the training process
- `test` - Test the model on a specific dataset view
- `infer` - Run inference on a dataset, image directory, or a video file.
- `export` - Export the model to either `ONNX` or `BLOB` format that can be run on edge devices
- `archive` - Create an `NN Archive` file that can be used with our `DepthAI` API (coming soon)
- `tune` - Tune the hyperparameters of the model for better performance
- `inspect` - Inspect the dataset you are using and visualize the annotations
**To get help on any command:**
```bash
luxonis_train <command> --help
```
Specific usage examples can be found in the respective sections below.
<a name="configuration"></a>
## ⚙️ Configuration
`LuxonisTrain` uses `YAML` configuration files to define the training pipeline. Here's a breakdown of the key sections:
```yaml
model:
name: model_name
# Use a predefined detection model instead of defining
# the model architecture manually
predefined_model:
name: DetectionModel
params:
variant: light
# Download and parse the coco dataset from RoboFlow.
# Save it internally as `coco_test` dataset for future reference.
loader:
params:
dataset_name: coco_test
dataset_dir: "roboflow://team-roboflow/coco-128/2/coco"
trainer:
batch_size: 8
epochs: 200
n_workers: 8
validation_interval: 10
preprocessing:
train_image_size: [384, 384]
# Uses the imagenet normalization by default
normalize:
active: true
# Augmentations are powered by Albumentations
augmentations:
- name: Defocus
- name: Sharpen
- name: Flip
callbacks:
- name: ExportOnTrainEnd
- name: ArchiveOnTrainEnd
- name: TestOnTrainEnd
optimizer:
name: SGD
params:
lr: 0.02
scheduler:
name: ConstantLR
```
For an extensive list of all the available options, see [Configuration](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md).
We provide a set of predefined configuration files for the most common computer vision tasks.
You can find them in the `configs` directory.
<a name="data-preparation"></a>
## 🗃️ Data Preparation
`LuxonisTrain` supports several ways of loading data:
- using a data directory in one of the supported formats
- using an already existing dataset in our custom `LuxonisDataset` format
- using a custom loader
- to learn how to implement and use custom loaders, see [Customizations](#customizations)
<a name="data-directory"></a>
### 📂 Data Directory
The easiest way to load data is to use a directory with the dataset in one of the supported formats.
**Supported formats:**
- `COCO` - We support COCO JSON format in two variants:
- [`RoboFlow`](https://roboflow.com/formats/coco-json)
- [`FiftyOne`](https://docs.voxel51.com/user_guide/export_datasets.html#cocodetectiondataset-export)
- [`Pascal VOC XML`](https://roboflow.com/formats/pascal-voc-xml)
- [`YOLO Darknet TXT`](https://roboflow.com/formats/yolo-darknet-txt)
- [`YOLOv4 PyTorch TXT`](https://roboflow.com/formats/yolov4-pytorch-txt)
- [`MT YOLOv6`](https://roboflow.com/formats/mt-yolov6)
- [`CreateML JSON`](https://roboflow.com/formats/createml-json)
- [`TensorFlow Object Detection CSV`](https://roboflow.com/formats/tensorflow-object-detection-csv)
- `Classification Directory` - A directory with subdirectories for each class
```plaintext
dataset_dir/
├── train/
│ ├── class1/
│ │ ├── img1.jpg
│ │ ├── img2.jpg
│ │ └── ...
│ ├── class2/
│ └── ...
├── valid/
└── test/
```
- `Segmentation Mask Directory` - A directory with images and corresponding masks.
```plaintext
dataset_dir/
├── train/
│ ├── img1.jpg
│ ├── img1_mask.png
│ ├── ...
│ └── _classes.csv
├── valid/
└── test/
```
The masks are stored as grayscale `PNG` images where each pixel value corresponds to a class.
The mapping from pixel values to classes is defined in the `_classes.csv` file.
```csv
Pixel Value, Class
0, background
1, class1
2, class2
3, class3
```
#### Preparing your Data
1. Organize your dataset into one of the supported formats.
1. Place your dataset in a directory accessible by the training script.
1. Update the `dataset_dir` parameter in the configuration file to point to the dataset directory.
**The `dataset_dir` can be one of the following:**
- Local path to the dataset directory
- URL to a remote dataset
- The dataset will be downloaded to a `"data"` directory in the current working directory
- **Supported URL protocols:**
- `s3://bucket/path/to/directory` fo **AWS S3**
- `gs://buclet/path/to/directory` for **Google Cloud Storage**
- `roboflow://workspace/project/version/format` for **RoboFlow**
- `workspace` - name of the workspace the dataset belongs to
- `project` - name of the project the dataset belongs to
- `version` - version of the dataset
- `format` - one of `coco`, `darknet`, `voc`, `yolov4pytorch`, `mt-yolov6`, `createml`, `tensorflow`, `folder`, `png-mask-semantic`
- **example:** `roboflow://team-roboflow/coco-128/2/coco`
**Example:**
```yaml
loader:
params:
dataset_name: "coco_test"
dataset_dir: "roboflow://team-roboflow/coco-128/2/coco"
```
<a name="luxonis-dataset"></a>
### 💾 `LuxonisDataset`
`LuxonisDataset` is our custom dataset format designed for easy and efficient dataset management.
To learn more about how to create a dataset in this format from scratch, see the [Luxonis ML](https://github.com/luxonis/luxonis-ml) repository.
To use the `LuxonisDataset` as a source of the data, specify the following in the config file:
```yaml
loader:
params:
# name of the dataset
dataset_name: "dataset_name"
# one of local (default), s3, gcs
bucket_storage: "local"
```
> \[!TIP\]
> To inspect the loader output, use the `luxonis_train inspect` command:
>
> ```bash
> luxonis_train inspect --config configs/detection_light_model.yaml
> ```
>
> **The `inspect` command is currently only available in the CLI**
<a name="training"></a>
## 🏋️♂️ Training
Once your configuration file and dataset are ready, start the training process.
**CLI:**
```bash
luxonis_train train --config configs/detection_light_model.yaml
```
> \[!TIP\]
> To change a configuration parameter from the command line, use the following syntax:
>
> ```bash
> luxonis_train train \
> --config configs/detection_light_model.yaml \
> loader.params.dataset_dir "roboflow://team-roboflow/coco-128/2/coco"
> ```
**Python API:**
```python
from luxonis_train import LuxonisModel
model = LuxonisModel(
"configs/detection_light_model.yaml",
{"loader.params.dataset_dir": "roboflow://team-roboflow/coco-128/2/coco"}
)
model.train()
```
**Expected Output:**
```log
INFO Using predefined model: `DetectionModel`
INFO Main metric: `MeanAveragePrecision`
INFO GPU available: True (cuda), used: True
INFO TPU available: False, using: 0 TPU cores
INFO HPU available: False, using: 0 HPUs
...
INFO Training finished
INFO Checkpoints saved in: output/1-coral-wren
```
**Monitoring with `TensorBoard`:**
If not explicitly disabled, the training process will be monitored by `TensorBoard`. To start the `TensorBoard` server, run:
```bash
tensorboard --logdir output/tensorboard_logs
```
Open the provided URL to visualize training metrics.
<a name="testing"></a>
## ✍ Testing
Evaluate your trained model on a specific dataset view (`train`, `val`, or `test`).
**CLI:**
```bash
luxonis_train test --config configs/detection_light_model.yaml \
--view val \
--weights path/to/checkpoint.ckpt
```
**Python API:**
```python
from luxonis_train import LuxonisModel
model = LuxonisModel("configs/detection_light_model.yaml")
model.test(weights="path/to/checkpoint.ckpt")
```
The testing process can be started automatically at the end of the training by using the `TestOnTrainEnd` callback.
To learn more about callbacks, see [Callbacks](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/callbacks/README.md).
<a name="inference"></a>
## 🧠 Inference
Run inference on images, datasets, or videos.
**CLI:**
- **Inference on a Dataset View:**
```bash
luxonis_train infer --config configs/detection_light_model.yaml \
--view val \
--weights path/to/checkpoint.ckpt
```
- **Inference on a Video File:**
```bash
luxonis_train infer --config configs/detection_light_model.yaml \
--weights path/to/checkpoint.ckpt \
--source-path path/to/video.mp4
```
- **Inference on an Image Directory:**
```bash
luxonis_train infer --config configs/detection_light_model.yaml \
--weights path/to/checkpoint.ckpt \
--source-path path/to/images \
--save-dir path/to/save_directory
```
**Python API:**
```python
from luxonis_train import LuxonisModel
model = LuxonisModel("configs/detection_light_model.yaml")
# infer on a dataset view
model.infer(weights="path/to/checkpoint.ckpt", view="val")
# infer on a video file
model.infer(weights="path/to/checkpoint.ckpt", source_path="path/to/video.mp4")
# infer on an image directory and save the results
model.infer(
weights="path/to/checkpoint.ckpt",
source_path="path/to/images",
save_dir="path/to/save_directory",
)
```
<a name="exporting"></a>
## 🤖 Exporting
Export your trained models to formats suitable for deployment on edge devices.
Supported formats:
- **ONNX**: Open Neural Network Exchange format.
- **BLOB**: Format compatible with OAK-D cameras.
To configure the exporter, you can specify the [exporter](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#exporter) section in the config file.
You can see an example export configuration [here](https://github.com/luxonis/luxonis-train/blob/main/configs/example_export.yaml).
**CLI:**
```bash
luxonis_train export --config configs/example_export.yaml --weights path/to/weights.ckpt
```
**Python API:**
```python
from luxonis_train import LuxonisModel
model = LuxonisModel("configs/example_export.yaml")
model.export(weights="path/to/weights.ckpt")
```
Model export can be run automatically at the end of the training by using the `ExportOnTrainEnd` callback.
The exported models are saved in the export directory within your `output` folder.
<a name="nn-archive"></a>
## 🗂️ NN Archive
Create an `NN Archive` file for easy deployment with the `DepthAI` API.
The archive contains the exported model together with all the metadata needed for running the model.
**CLI:**
```bash
luxonis_train archive \
--config configs/detection_light_model.yaml \
--weights path/to/checkpoint.ckpt
```
**Python API:**
```python
from luxonis_train import LuxonisModel
model = LuxonisModel("configs/detection_light_model.yaml")
model.archive(weights="path/to/checkpoint.ckpt")
```
The archive can be created automatically at the end of the training by using the `ArchiveOnTrainEnd` callback.
<a name="tuning"></a>
## 🔬 Tuning
Optimize your model's performance using hyperparameter tuning powered by [`Optuna`](https://optuna.org/).
**Configuration:**
Include a [`tuner`](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#tuner) section in your configuration file.
```yaml
tuner:
study_name: det_study
n_trials: 10
storage:
storage_type: local
params:
trainer.optimizer.name_categorical: ["Adam", "SGD"]
trainer.optimizer.params.lr_float: [0.0001, 0.001]
trainer.batch_size_int: [4, 16, 4]
```
**CLI:**
```bash
luxonis_train tune --config configs/example_tuning.yaml
```
**Python API:**
```python
from luxonis_train import LuxonisModel
model = LuxonisModel("configs/example_tuning.yaml")
model.tune()
```
<a name="customizations"></a>
## 🎨 Customizations
`LuxonisTrain` is highly modular, allowing you to customize various components:
- [**Loaders**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/loaders/README.md): Handles data loading and preprocessing.
- [**Nodes**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/nodes/README.md): Represents computational units in the model architecture.
- [**Losses**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/losses/README.md): Define the loss functions used to train the model.
- [**Metrics**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/metrics/README.md): Measure the model's performance during training.
- [**Visualizers**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/visualizers/README.md): Visualize the model's predictions during training.
- [**Callbacks**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/callbacks/README.md): Allow custom code to be executed at different stages of training.
- [**Optimizers**](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#optimizer): Control how the model's weights are updated.
- [**Schedulers**](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#scheduler): Adjust the learning rate during training.
- [**Training Strategy**](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#training-strategy): Specify a custom combination of optimizer and scheduler to tailor the training process for specific use cases.
**Creating Custom Components:**
Implement custom components by subclassing the respective base classes and/or registering them.
Registered components can be referenced in the config file. Custom components need to inherit from their respective base classes:
- **Loaders** - [`BaseLoader`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/loaders/base_loader.py)
- **Nodes** - [`BaseNode`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/models/nodes/base_node.py)
- **Losses** - [`BaseLoss`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/losses/base_loss.py)
- **Metrics** - [`BaseMetric`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/metrics/base_metric.py)
- **Visualizers** - [`BaseVisualizer`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/visualizers/base_visualizer.py)
- **Callbacks** - [`lightning.pytorch.callbacks.Callback`](https://lightning.ai/docs/pytorch/stable/extensions/callbacks.html), requires manual registration to the `CALLBACKS` registry
- **Optimizers** - [`torch.optim.Optimizer`](https://pytorch.org/docs/stable/optim.html#torch.optim.Optimizer), requires manual registration to the `OPTIMIZERS` registry
- **Schedulers** - [`torch.optim.lr_scheduler.LRScheduler`](https://pytorch.org/docs/stable/optim.html#how-to-adjust-learning-rate), requires manual registration to the `SCHEDULERS` registry
- **Training Strategy** - [`BaseTrainingStrategy`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/strategies/base_strategy.py)
**Examples:**
**Custom Callback:**
```python
import lightning.pytorch as pl
from luxonis_train import LuxonisLightningModule
from luxonis_train.utils.registry import CALLBACKS
@CALLBACKS.register_module()
class CustomCallback(pl.Callback):
def __init__(self, message: str, **kwargs):
super().__init__(**kwargs)
self.message = message
# Will be called at the end of each training epoch.
# Consult the PyTorch Lightning documentation for more callback methods.
def on_train_epoch_end(
self,
trainer: pl.Trainer,
pl_module: LuxonisLightningModule,
) -> None:
print(self.message)
```
**Custom Loss:**
```python
from torch import Tensor
from luxonis_train import BaseLoss, TaskType
# Subclasses of `BaseNode`, `BaseLoss`, `BaseMetric`
# and `BaseVisualizer` are registered automatically.
class CustomLoss(BaseLoss):
supported_tasks = [TaskType.CLASSIFICATION, TaskType.SEGMENTATION]
def __init__(self, smoothing: float, **kwargs):
super().__init__(**kwargs)
self.smoothing = smoothing
def forward(self, predictions: Tensor, targets: Tensor) -> Tensor:
# Implement the actual loss logic here
value = predictions.sum() * self.smoothing
return value.abs()
```
**Using custom components in the configuration file:**
```yaml
model:
nodes:
- name: SegmentationHead
losses:
- name: CustomLoss
params:
smoothing: 0.0001
trainer:
callbacks:
- name: CustomCallback
params:
lr: "Hello from the custom callback!"
```
> \[!NOTE\]
> Files containing the custom components must be sourced before the training script is run.
> To do that in CLI, you can use the `--source` argument:
>
> ```bash
> luxonis_train --source custom_components.py train --config config.yaml
> ```
**Python API:**
You have to import the custom components before creating the `LuxonisModel` instance.
```python
from custom_components import *
from luxonis_train import LuxonisModel
model = LuxonisModel("config.yaml")
model.train()
```
For more information on how to define custom components, consult the respective in-source documentation.
<a name="tutorials-and-examples"></a>
## 📚 Tutorials and Examples
We are actively working on providing examples and tutorials for different parts of the library which will help you to start more easily. The tutorials can be found [here](https://github.com/luxonis/depthai-ml-training/tree/main/training) and will be updated regularly.
<a name="credentials"></a>
## 🔑 Credentials
When using cloud services, avoid hard-coding credentials or placing them directly in your configuration files.
Instead:
- Use environment variables to store sensitive information.
- Use a `.env` file and load it securely, ensuring it's excluded from version control.
**Supported Cloud Services:**
- **AWS S3**, requires:
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `AWS_S3_ENDPOINT_URL`
- **Google Cloud Storage**, requires:
- `GOOGLE_APPLICATION_CREDENTIALS`
- **RoboFlow**, requires:
- `ROBOFLOW_API_KEY`
**For logging and tracking, we support:**
- **MLFlow**, requires:
- `MLFLOW_S3_BUCKET`
- `MLFLOW_S3_ENDPOINT_URL`
- `MLFLOW_TRACKING_URI`
- **WandB**, requires:
- `WANDB_API_KEY`
**For remote database storage, we support:**
- `POSTGRES_PASSWORD`
- `POSTGRES_HOST`
- `POSTGRES_PORT`
- `POSTGRES_DB`
<a name="contributing"></a>
## 🤝 Contributing
We welcome contributions! Please read our [Contribution Guide](https://github.com/luxonis/luxonis-train/blob/main/CONTRIBUTING.md) to get started. Whether it's reporting bugs, improving documentation, or adding new features, your help is appreciated.
Raw data
{
"_id": null,
"home_page": null,
"name": "luxonis-train",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Luxonis <support@luxonis.com>",
"keywords": "ml, training, luxonis, oak",
"author": null,
"author_email": "Luxonis <support@luxonis.com>",
"download_url": "https://files.pythonhosted.org/packages/93/c8/16f3a65eb388c16711c0eb3b7fad5b8f9db560c877f67691b7aa080f6bc8/luxonis_train-0.2.1.tar.gz",
"platform": null,
"description": "# Luxonis Training Framework\n\n\n\n\n\n[](https://opensource.org/licenses/Apache-2.0)\n\n[](https://github.com/astral-sh/ruff)\n\n[](https://codecov.io/gh/luxonis/luxonis-train)\n\n<a name=\"overview\"></a>\n\n## \ud83c\udf1f Overview\n\n`LuxonisTrain` is a user-friendly tool designed to streamline the training of deep learning models, especially for edge devices. Built on top of `PyTorch Lightning`, it simplifies the process of training, testing, and exporting models with minimal coding required.\n\n### \u2728 Key Features\n\n- **No Coding Required**: Define your training pipeline entirely through a single `YAML` configuration file.\n- **Predefined Configurations**: Utilize ready-made configs for common computer vision tasks to start quickly.\n- **Customizable**: Extend functionality with custom components using an intuitive Python API.\n- **Edge Optimized**: Focus on models optimized for deployment on edge devices with limited compute resources.\n\n> \\[!WARNING\\]\n> **The project is in a beta state and might be unstable or contain bugs - please report any feedback.**\n\n<a name=\"quick-start\"></a>\n\n## \ud83d\ude80 Quick Start\n\nGet started with `LuxonisTrain` in just a few steps:\n\n1. **Install `LuxonisTrain`**\n\n ```bash\n pip install luxonis-train\n ```\n\n This will create the `luxonis_train` executable in your `PATH`.\n\n1. **Use the provided `configs/detection_light_model.yaml` configuration file**\n\n You can download the file by executing the following command:\n\n ```bash\n wget https://raw.githubusercontent.com/luxonis/luxonis-train/main/configs/detection_light_model.yaml\n ```\n\n1. **Find a suitable dataset for your task**\n\n We will use a sample COCO dataset from `RoboFlow` in this example.\n\n1. **Start training**\n\n ```bash\n luxonis_train train \\\n --config detection_light_model.yaml \\\n loader.params.dataset_dir \"roboflow://team-roboflow/coco-128/2/coco\"\n ```\n\n1. **Monitor progress with `TensorBoard`**\n\n ```bash\n tensorboard --logdir output/tensorboard_logs\n ```\n\n Open the provided URL in your browser to visualize the training progress\n\n## \ud83d\udcdc Table Of Contents\n\n- [\ud83c\udf1f Overview](#overview)\n - [\u2728 Key Features](#key-features)\n- [\ud83d\ude80 Quick Start](#quick-start)\n- [\ud83d\udee0\ufe0f Installation](#installation)\n- [\ud83d\udcdd Usage](#usage)\n - [\ud83d\udcbb CLI](#cli)\n- [\u2699\ufe0f Configuration](#configuration)\n- [\ud83d\uddc3\ufe0f Data Preparation](#data-preparation)\n - [\ud83d\udcc2 Data Directory](#data-directory)\n - [\ud83d\udcbe `LuxonisDataset`](#luxonis-dataset)\n- [\ud83c\udfcb\ufe0f\u200d\u2642\ufe0fTraining](#training)\n- [\u270d Testing](#testing)\n- [\ud83e\udde0 Inference](#inference)\n- [\ud83e\udd16 Exporting](#exporting)\n- [\ud83d\uddc2\ufe0f NN Archive](#nn-archive)\n- [\ud83d\udd2c Tuning](#tuning)\n- [\ud83c\udfa8 Customizations](#customizations)\n- [\ud83d\udcda Tutorials and Examples](#tutorials-and-examples)\n- [\ud83d\udd11 Credentials](#credentials)\n- [\ud83e\udd1d Contributing](#contributing)\n\n<a name=\"installation\"></a>\n\n## \ud83d\udee0\ufe0f Installation\n\n`LuxonisTrain` requires **Python 3.10** or higher. We recommend using a virtual environment to manage dependencies.\n\n**Install via `pip`**:\n\n```bash\npip install luxonis-train\n```\n\nThis will also install the `luxonis_train` CLI. For more information on how to use it, see [CLI Usage](#cli).\n\n<a name=\"usage\"></a>\n\n## \ud83d\udcdd Usage\n\nYou can use `LuxonisTrain` either from the **command line** or via the **Python API**.\nWe will demonstrate both ways in the following sections.\n\n<a name=\"cli\"></a>\n\n### \ud83d\udcbb CLI\n\nThe CLI is the most straightforward way how to use `LuxonisTrain`. The CLI provides several commands for training, testing, tuning, exporting and more.\n\n**Available commands:**\n\n- `train` - Start the training process\n- `test` - Test the model on a specific dataset view\n- `infer` - Run inference on a dataset, image directory, or a video file.\n- `export` - Export the model to either `ONNX` or `BLOB` format that can be run on edge devices\n- `archive` - Create an `NN Archive` file that can be used with our `DepthAI` API (coming soon)\n- `tune` - Tune the hyperparameters of the model for better performance\n- `inspect` - Inspect the dataset you are using and visualize the annotations\n\n**To get help on any command:**\n\n```bash\nluxonis_train <command> --help\n```\n\nSpecific usage examples can be found in the respective sections below.\n\n<a name=\"configuration\"></a>\n\n## \u2699\ufe0f Configuration\n\n`LuxonisTrain` uses `YAML` configuration files to define the training pipeline. Here's a breakdown of the key sections:\n\n```yaml\nmodel:\n name: model_name\n\n # Use a predefined detection model instead of defining\n # the model architecture manually\n predefined_model:\n name: DetectionModel\n params:\n variant: light\n\n# Download and parse the coco dataset from RoboFlow.\n# Save it internally as `coco_test` dataset for future reference.\nloader:\n params:\n dataset_name: coco_test\n dataset_dir: \"roboflow://team-roboflow/coco-128/2/coco\"\n\ntrainer:\n batch_size: 8\n epochs: 200\n n_workers: 8\n validation_interval: 10\n\n preprocessing:\n train_image_size: [384, 384]\n\n # Uses the imagenet normalization by default\n normalize:\n active: true\n\n # Augmentations are powered by Albumentations\n augmentations:\n - name: Defocus\n - name: Sharpen\n - name: Flip\n\n callbacks:\n - name: ExportOnTrainEnd\n - name: ArchiveOnTrainEnd\n - name: TestOnTrainEnd\n\n optimizer:\n name: SGD\n params:\n lr: 0.02\n\n scheduler:\n name: ConstantLR\n```\n\nFor an extensive list of all the available options, see [Configuration](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md).\n\nWe provide a set of predefined configuration files for the most common computer vision tasks.\nYou can find them in the `configs` directory.\n\n<a name=\"data-preparation\"></a>\n\n## \ud83d\uddc3\ufe0f Data Preparation\n\n`LuxonisTrain` supports several ways of loading data:\n\n- using a data directory in one of the supported formats\n- using an already existing dataset in our custom `LuxonisDataset` format\n- using a custom loader\n - to learn how to implement and use custom loaders, see [Customizations](#customizations)\n\n<a name=\"data-directory\"></a>\n\n### \ud83d\udcc2 Data Directory\n\nThe easiest way to load data is to use a directory with the dataset in one of the supported formats.\n\n**Supported formats:**\n\n- `COCO` - We support COCO JSON format in two variants:\n - [`RoboFlow`](https://roboflow.com/formats/coco-json)\n - [`FiftyOne`](https://docs.voxel51.com/user_guide/export_datasets.html#cocodetectiondataset-export)\n- [`Pascal VOC XML`](https://roboflow.com/formats/pascal-voc-xml)\n- [`YOLO Darknet TXT`](https://roboflow.com/formats/yolo-darknet-txt)\n- [`YOLOv4 PyTorch TXT`](https://roboflow.com/formats/yolov4-pytorch-txt)\n- [`MT YOLOv6`](https://roboflow.com/formats/mt-yolov6)\n- [`CreateML JSON`](https://roboflow.com/formats/createml-json)\n- [`TensorFlow Object Detection CSV`](https://roboflow.com/formats/tensorflow-object-detection-csv)\n- `Classification Directory` - A directory with subdirectories for each class\n ```plaintext\n dataset_dir/\n \u251c\u2500\u2500 train/\n \u2502 \u251c\u2500\u2500 class1/\n \u2502 \u2502 \u251c\u2500\u2500 img1.jpg\n \u2502 \u2502 \u251c\u2500\u2500 img2.jpg\n \u2502 \u2502 \u2514\u2500\u2500 ...\n \u2502 \u251c\u2500\u2500 class2/\n \u2502 \u2514\u2500\u2500 ...\n \u251c\u2500\u2500 valid/\n \u2514\u2500\u2500 test/\n ```\n- `Segmentation Mask Directory` - A directory with images and corresponding masks.\n ```plaintext\n dataset_dir/\n \u251c\u2500\u2500 train/\n \u2502 \u251c\u2500\u2500 img1.jpg\n \u2502 \u251c\u2500\u2500 img1_mask.png\n \u2502 \u251c\u2500\u2500 ...\n \u2502 \u2514\u2500\u2500 _classes.csv\n \u251c\u2500\u2500 valid/\n \u2514\u2500\u2500 test/\n ```\n The masks are stored as grayscale `PNG` images where each pixel value corresponds to a class.\n The mapping from pixel values to classes is defined in the `_classes.csv` file.\n ```csv\n Pixel Value, Class\n 0, background\n 1, class1\n 2, class2\n 3, class3\n ```\n\n#### Preparing your Data\n\n1. Organize your dataset into one of the supported formats.\n1. Place your dataset in a directory accessible by the training script.\n1. Update the `dataset_dir` parameter in the configuration file to point to the dataset directory.\n\n**The `dataset_dir` can be one of the following:**\n\n- Local path to the dataset directory\n- URL to a remote dataset\n - The dataset will be downloaded to a `\"data\"` directory in the current working directory\n - **Supported URL protocols:**\n - `s3://bucket/path/to/directory` fo **AWS S3**\n - `gs://buclet/path/to/directory` for **Google Cloud Storage**\n - `roboflow://workspace/project/version/format` for **RoboFlow**\n - `workspace` - name of the workspace the dataset belongs to\n - `project` - name of the project the dataset belongs to\n - `version` - version of the dataset\n - `format` - one of `coco`, `darknet`, `voc`, `yolov4pytorch`, `mt-yolov6`, `createml`, `tensorflow`, `folder`, `png-mask-semantic`\n - **example:** `roboflow://team-roboflow/coco-128/2/coco`\n\n**Example:**\n\n```yaml\nloader:\n params:\n dataset_name: \"coco_test\"\n dataset_dir: \"roboflow://team-roboflow/coco-128/2/coco\"\n```\n\n<a name=\"luxonis-dataset\"></a>\n\n### \ud83d\udcbe `LuxonisDataset`\n\n`LuxonisDataset` is our custom dataset format designed for easy and efficient dataset management.\nTo learn more about how to create a dataset in this format from scratch, see the [Luxonis ML](https://github.com/luxonis/luxonis-ml) repository.\n\nTo use the `LuxonisDataset` as a source of the data, specify the following in the config file:\n\n```yaml\nloader:\n params:\n # name of the dataset\n dataset_name: \"dataset_name\"\n\n # one of local (default), s3, gcs\n bucket_storage: \"local\"\n```\n\n> \\[!TIP\\]\n> To inspect the loader output, use the `luxonis_train inspect` command:\n>\n> ```bash\n> luxonis_train inspect --config configs/detection_light_model.yaml\n> ```\n>\n> **The `inspect` command is currently only available in the CLI**\n\n<a name=\"training\"></a>\n\n## \ud83c\udfcb\ufe0f\u200d\u2642\ufe0f Training\n\nOnce your configuration file and dataset are ready, start the training process.\n\n**CLI:**\n\n```bash\nluxonis_train train --config configs/detection_light_model.yaml\n```\n\n> \\[!TIP\\]\n> To change a configuration parameter from the command line, use the following syntax:\n>\n> ```bash\n> luxonis_train train \\\n> --config configs/detection_light_model.yaml \\\n> loader.params.dataset_dir \"roboflow://team-roboflow/coco-128/2/coco\"\n> ```\n\n**Python API:**\n\n```python\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\n \"configs/detection_light_model.yaml\",\n {\"loader.params.dataset_dir\": \"roboflow://team-roboflow/coco-128/2/coco\"}\n)\nmodel.train()\n```\n\n**Expected Output:**\n\n```log\nINFO Using predefined model: `DetectionModel`\nINFO Main metric: `MeanAveragePrecision`\nINFO GPU available: True (cuda), used: True\nINFO TPU available: False, using: 0 TPU cores\nINFO HPU available: False, using: 0 HPUs\n...\nINFO Training finished\nINFO Checkpoints saved in: output/1-coral-wren\n```\n\n**Monitoring with `TensorBoard`:**\n\nIf not explicitly disabled, the training process will be monitored by `TensorBoard`. To start the `TensorBoard` server, run:\n\n```bash\ntensorboard --logdir output/tensorboard_logs\n```\n\nOpen the provided URL to visualize training metrics.\n\n<a name=\"testing\"></a>\n\n## \u270d Testing\n\nEvaluate your trained model on a specific dataset view (`train`, `val`, or `test`).\n\n**CLI:**\n\n```bash\nluxonis_train test --config configs/detection_light_model.yaml \\\n --view val \\\n --weights path/to/checkpoint.ckpt\n```\n\n**Python API:**\n\n```python\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\"configs/detection_light_model.yaml\")\nmodel.test(weights=\"path/to/checkpoint.ckpt\")\n```\n\nThe testing process can be started automatically at the end of the training by using the `TestOnTrainEnd` callback.\nTo learn more about callbacks, see [Callbacks](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/callbacks/README.md).\n\n<a name=\"inference\"></a>\n\n## \ud83e\udde0 Inference\n\nRun inference on images, datasets, or videos.\n\n**CLI:**\n\n- **Inference on a Dataset View:**\n\n```bash\nluxonis_train infer --config configs/detection_light_model.yaml \\\n --view val \\\n --weights path/to/checkpoint.ckpt\n```\n\n- **Inference on a Video File:**\n\n```bash\nluxonis_train infer --config configs/detection_light_model.yaml \\\n --weights path/to/checkpoint.ckpt \\\n --source-path path/to/video.mp4\n```\n\n- **Inference on an Image Directory:**\n\n```bash\nluxonis_train infer --config configs/detection_light_model.yaml \\\n --weights path/to/checkpoint.ckpt \\\n --source-path path/to/images \\\n --save-dir path/to/save_directory\n```\n\n**Python API:**\n\n```python\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\"configs/detection_light_model.yaml\")\n\n# infer on a dataset view\nmodel.infer(weights=\"path/to/checkpoint.ckpt\", view=\"val\")\n\n# infer on a video file\nmodel.infer(weights=\"path/to/checkpoint.ckpt\", source_path=\"path/to/video.mp4\")\n\n# infer on an image directory and save the results\nmodel.infer(\n weights=\"path/to/checkpoint.ckpt\",\n source_path=\"path/to/images\",\n save_dir=\"path/to/save_directory\",\n)\n```\n\n<a name=\"exporting\"></a>\n\n## \ud83e\udd16 Exporting\n\nExport your trained models to formats suitable for deployment on edge devices.\n\nSupported formats:\n\n- **ONNX**: Open Neural Network Exchange format.\n- **BLOB**: Format compatible with OAK-D cameras.\n\nTo configure the exporter, you can specify the [exporter](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#exporter) section in the config file.\n\nYou can see an example export configuration [here](https://github.com/luxonis/luxonis-train/blob/main/configs/example_export.yaml).\n\n**CLI:**\n\n```bash\nluxonis_train export --config configs/example_export.yaml --weights path/to/weights.ckpt\n```\n\n**Python API:**\n\n```python\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\"configs/example_export.yaml\")\nmodel.export(weights=\"path/to/weights.ckpt\")\n```\n\nModel export can be run automatically at the end of the training by using the `ExportOnTrainEnd` callback.\n\nThe exported models are saved in the export directory within your `output` folder.\n\n<a name=\"nn-archive\"></a>\n\n## \ud83d\uddc2\ufe0f NN Archive\n\nCreate an `NN Archive` file for easy deployment with the `DepthAI` API.\n\nThe archive contains the exported model together with all the metadata needed for running the model.\n\n**CLI:**\n\n```bash\nluxonis_train archive \\\n --config configs/detection_light_model.yaml \\\n --weights path/to/checkpoint.ckpt\n```\n\n**Python API:**\n\n```python\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\"configs/detection_light_model.yaml\")\nmodel.archive(weights=\"path/to/checkpoint.ckpt\")\n```\n\nThe archive can be created automatically at the end of the training by using the `ArchiveOnTrainEnd` callback.\n\n<a name=\"tuning\"></a>\n\n## \ud83d\udd2c Tuning\n\nOptimize your model's performance using hyperparameter tuning powered by [`Optuna`](https://optuna.org/).\n\n**Configuration:**\n\nInclude a [`tuner`](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#tuner) section in your configuration file.\n\n```yaml\n\ntuner:\n study_name: det_study\n n_trials: 10\n storage:\n storage_type: local\n params:\n trainer.optimizer.name_categorical: [\"Adam\", \"SGD\"]\n trainer.optimizer.params.lr_float: [0.0001, 0.001]\n trainer.batch_size_int: [4, 16, 4]\n```\n\n**CLI:**\n\n```bash\nluxonis_train tune --config configs/example_tuning.yaml\n```\n\n**Python API:**\n\n```python\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\"configs/example_tuning.yaml\")\nmodel.tune()\n```\n\n<a name=\"customizations\"></a>\n\n## \ud83c\udfa8 Customizations\n\n`LuxonisTrain` is highly modular, allowing you to customize various components:\n\n- [**Loaders**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/loaders/README.md): Handles data loading and preprocessing.\n- [**Nodes**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/nodes/README.md): Represents computational units in the model architecture.\n- [**Losses**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/losses/README.md): Define the loss functions used to train the model.\n- [**Metrics**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/metrics/README.md): Measure the model's performance during training.\n- [**Visualizers**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/visualizers/README.md): Visualize the model's predictions during training.\n- [**Callbacks**](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/callbacks/README.md): Allow custom code to be executed at different stages of training.\n- [**Optimizers**](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#optimizer): Control how the model's weights are updated.\n- [**Schedulers**](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#scheduler): Adjust the learning rate during training.\n- [**Training Strategy**](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#training-strategy): Specify a custom combination of optimizer and scheduler to tailor the training process for specific use cases.\n\n**Creating Custom Components:**\n\nImplement custom components by subclassing the respective base classes and/or registering them.\nRegistered components can be referenced in the config file. Custom components need to inherit from their respective base classes:\n\n- **Loaders** - [`BaseLoader`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/loaders/base_loader.py)\n- **Nodes** - [`BaseNode`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/models/nodes/base_node.py)\n- **Losses** - [`BaseLoss`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/losses/base_loss.py)\n- **Metrics** - [`BaseMetric`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/metrics/base_metric.py)\n- **Visualizers** - [`BaseVisualizer`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/attached_modules/visualizers/base_visualizer.py)\n- **Callbacks** - [`lightning.pytorch.callbacks.Callback`](https://lightning.ai/docs/pytorch/stable/extensions/callbacks.html), requires manual registration to the `CALLBACKS` registry\n- **Optimizers** - [`torch.optim.Optimizer`](https://pytorch.org/docs/stable/optim.html#torch.optim.Optimizer), requires manual registration to the `OPTIMIZERS` registry\n- **Schedulers** - [`torch.optim.lr_scheduler.LRScheduler`](https://pytorch.org/docs/stable/optim.html#how-to-adjust-learning-rate), requires manual registration to the `SCHEDULERS` registry\n- **Training Strategy** - [`BaseTrainingStrategy`](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/strategies/base_strategy.py)\n\n**Examples:**\n\n**Custom Callback:**\n\n```python\nimport lightning.pytorch as pl\n\nfrom luxonis_train import LuxonisLightningModule\nfrom luxonis_train.utils.registry import CALLBACKS\n\n\n@CALLBACKS.register_module()\nclass CustomCallback(pl.Callback):\n def __init__(self, message: str, **kwargs):\n super().__init__(**kwargs)\n self.message = message\n\n # Will be called at the end of each training epoch.\n # Consult the PyTorch Lightning documentation for more callback methods.\n def on_train_epoch_end(\n self,\n trainer: pl.Trainer,\n pl_module: LuxonisLightningModule,\n ) -> None:\n print(self.message)\n```\n\n**Custom Loss:**\n\n```python\nfrom torch import Tensor\n\nfrom luxonis_train import BaseLoss, TaskType\n\n# Subclasses of `BaseNode`, `BaseLoss`, `BaseMetric`\n# and `BaseVisualizer` are registered automatically.\nclass CustomLoss(BaseLoss):\n supported_tasks = [TaskType.CLASSIFICATION, TaskType.SEGMENTATION]\n\n def __init__(self, smoothing: float, **kwargs):\n super().__init__(**kwargs)\n self.smoothing = smoothing\n\n def forward(self, predictions: Tensor, targets: Tensor) -> Tensor:\n # Implement the actual loss logic here\n value = predictions.sum() * self.smoothing\n return value.abs()\n```\n\n**Using custom components in the configuration file:**\n\n```yaml\nmodel:\n nodes:\n - name: SegmentationHead\n losses:\n - name: CustomLoss\n params:\n smoothing: 0.0001\n\ntrainer:\n callbacks:\n - name: CustomCallback\n params:\n lr: \"Hello from the custom callback!\"\n```\n\n> \\[!NOTE\\]\n> Files containing the custom components must be sourced before the training script is run.\n> To do that in CLI, you can use the `--source` argument:\n>\n> ```bash\n> luxonis_train --source custom_components.py train --config config.yaml\n> ```\n\n**Python API:**\n\nYou have to import the custom components before creating the `LuxonisModel` instance.\n\n```python\nfrom custom_components import *\nfrom luxonis_train import LuxonisModel\n\nmodel = LuxonisModel(\"config.yaml\")\nmodel.train()\n```\n\nFor more information on how to define custom components, consult the respective in-source documentation.\n\n<a name=\"tutorials-and-examples\"></a>\n\n## \ud83d\udcda Tutorials and Examples\n\nWe are actively working on providing examples and tutorials for different parts of the library which will help you to start more easily. The tutorials can be found [here](https://github.com/luxonis/depthai-ml-training/tree/main/training) and will be updated regularly.\n\n<a name=\"credentials\"></a>\n\n## \ud83d\udd11 Credentials\n\nWhen using cloud services, avoid hard-coding credentials or placing them directly in your configuration files.\nInstead:\n\n- Use environment variables to store sensitive information.\n- Use a `.env` file and load it securely, ensuring it's excluded from version control.\n\n**Supported Cloud Services:**\n\n- **AWS S3**, requires:\n - `AWS_ACCESS_KEY_ID`\n - `AWS_SECRET_ACCESS_KEY`\n - `AWS_S3_ENDPOINT_URL`\n- **Google Cloud Storage**, requires:\n - `GOOGLE_APPLICATION_CREDENTIALS`\n- **RoboFlow**, requires:\n - `ROBOFLOW_API_KEY`\n\n**For logging and tracking, we support:**\n\n- **MLFlow**, requires:\n - `MLFLOW_S3_BUCKET`\n - `MLFLOW_S3_ENDPOINT_URL`\n - `MLFLOW_TRACKING_URI`\n- **WandB**, requires:\n - `WANDB_API_KEY`\n\n**For remote database storage, we support:**\n\n- `POSTGRES_PASSWORD`\n- `POSTGRES_HOST`\n- `POSTGRES_PORT`\n- `POSTGRES_DB`\n\n<a name=\"contributing\"></a>\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please read our [Contribution Guide](https://github.com/luxonis/luxonis-train/blob/main/CONTRIBUTING.md) to get started. Whether it's reporting bugs, improving documentation, or adding new features, your help is appreciated.\n",
"bugtrack_url": null,
"license": "Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. \"License\" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. \"Licensor\" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. \"Legal Entity\" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, \"control\" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. \"You\" (or \"Your\") shall mean an individual or Legal Entity exercising permissions granted by this License. \"Source\" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. \"Object\" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. \"Work\" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). \"Derivative Works\" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. \"Contribution\" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, \"submitted\" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as \"Not a Contribution.\" \"Contributor\" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a \"NOTICE\" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets \"[]\" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same \"printed page\" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "Luxonis training framework for seamless training of various neural networks.",
"version": "0.2.1",
"project_urls": {
"issues": "https://github.com/luxonis/luxonis-train/issues",
"repository": "https://github.com/luxonis/luxonis-train"
},
"split_keywords": [
"ml",
" training",
" luxonis",
" oak"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd3109a15a14e5d72f6aef587150117386b56614674b3c18cdfa9d536eb765cf",
"md5": "4fc255b9d1fd9f65982fa852418d130c",
"sha256": "a6480989d84e7fb478ff2fd61114508d99a586796db08b2fd22202292790e21b"
},
"downloads": -1,
"filename": "luxonis_train-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4fc255b9d1fd9f65982fa852418d130c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 260929,
"upload_time": "2024-12-10T08:19:29",
"upload_time_iso_8601": "2024-12-10T08:19:29.956987Z",
"url": "https://files.pythonhosted.org/packages/dd/31/09a15a14e5d72f6aef587150117386b56614674b3c18cdfa9d536eb765cf/luxonis_train-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "93c816f3a65eb388c16711c0eb3b7fad5b8f9db560c877f67691b7aa080f6bc8",
"md5": "6fda170d7f8af3a4758bd904bad3580b",
"sha256": "eefbab43c00c8f7f9885249a547df4f1ca98c54714197b1f0f4486246d1961d9"
},
"downloads": -1,
"filename": "luxonis_train-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "6fda170d7f8af3a4758bd904bad3580b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 194466,
"upload_time": "2024-12-10T08:19:31",
"upload_time_iso_8601": "2024-12-10T08:19:31.578954Z",
"url": "https://files.pythonhosted.org/packages/93/c8/16f3a65eb388c16711c0eb3b7fad5b8f9db560c877f67691b7aa080f6bc8/luxonis_train-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-10 08:19:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "luxonis",
"github_project": "luxonis-train",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "blobconverter",
"specs": [
[
">=",
"1.4.2"
]
]
},
{
"name": "lightning",
"specs": [
[
">=",
"2.4.0"
]
]
},
{
"name": "luxonis-ml",
"specs": [
[
">=",
"0.5.1"
]
]
},
{
"name": "onnx",
"specs": [
[
">=",
"1.12.0"
]
]
},
{
"name": "onnxruntime",
"specs": [
[
">=",
"1.13.1"
]
]
},
{
"name": "onnxsim",
"specs": [
[
">=",
"0.4.10"
]
]
},
{
"name": "optuna",
"specs": [
[
">=",
"3.6.0"
]
]
},
{
"name": "optuna-integration",
"specs": [
[
">=",
"3.6.0"
]
]
},
{
"name": "parameterized",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "psycopg2-binary",
"specs": [
[
">=",
"2.9.1"
]
]
},
{
"name": "pycocotools",
"specs": [
[
">=",
"2.0.7"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "s3fs",
"specs": [
[
">=",
"2023.0.0"
]
]
},
{
"name": "tensorboard",
"specs": [
[
">=",
"2.10.1"
]
]
},
{
"name": "torchvision",
"specs": [
[
">=",
"0.16.0"
]
]
},
{
"name": "typer",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "mlflow",
"specs": [
[
">=",
"2.10.0"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "grad-cam",
"specs": [
[
">=",
"1.5.4"
]
]
}
],
"lcname": "luxonis-train"
}
