HUSKYLENS 2 Custom Model Deployment

By the end of this guide, you will know how to deploy your own object detection, image classification, and instance segmentation models to HUSKYLENS 2 so that the device can recognize custom objects. The guide covers the complete workflow: preparing a dataset, training a model, exporting it to ONNX, generating an installation package, and installing it on HUSKYLENS 2. All you need is a computer running Windows 10 or later. Even if you have no previous experience training AI models, you can complete the process by following the steps below.

Before using Model Installation, we recommend updating HUSKYLENS 2 to the latest firmware. For instructions on checking and flashing the firmware, see the firmware tutorial.

1. Introduction to Installing Custom-Trained Models

In addition to more than 20 built-in vision models, HUSKYLENS 2 lets you deploy custom-trained object detection, image classification, and instance segmentation models through its Model Installation feature. This makes it possible to build vision projects tailored to your own requirements.

For example, if you want HUSKYLENS 2 to recognize something that its built-in models do not support, such as your pet, a particular toy, or a specific component, you can collect relevant photos, train a model, and install it on the device. After installation, the custom model can be used in the same way as a built-in model.

If you want to get started quickly without training a model yourself, you can download ready-to-use custom-trained models directly from the Model Hub.

Deploying a custom-trained model involves five main steps:

1. Prepare the dataset: Collect and organize images of the objects to be recognized in the required format.
2. Train the model: Train a supported model on your computer. HUSKYLENS 2 supports only the architectures listed in this guide.
3. Export the model: Convert the trained model to ONNX format.
4. Generate an installation package: Use the official Model Installation Package Generator to package the ONNX model.
5. Install and deploy: Copy the package to HUSKYLENS 2 and perform a local installation.

The following sections explain how to deploy custom-trained object detection, image classification, and instance segmentation models to HUSKYLENS 2.

2. Installing an Object Detection Model

2.1 What Is an Object Detection Model?

Object detection is a common computer vision task. It identifies the objects in an image, draws a bounding box around each one, and reports its class name and confidence score. The confidence score indicates how certain the model is about its prediction. You can think of object detection as recognizing and locating objects at the same time. For example, when a cat and a dog appear in front of the camera, the model draws a separate box around each animal and may label them as cat 0.92 and dog 0.88.

An object detection model:

• Can recognize multiple objects in the same image and locate each one with a bounding box.
• Returns a class name, bounding box, and confidence score for every detection, making the results easy to use in later logic or control tasks.
• Is well suited to applications that need to determine both what an object is and where it is, such as waste sorting, component recognition, and animal recognition.

YOLO (You Only Look Once) is a popular object detection algorithm because it is fast, accurate, and easy to use. HUSKYLENS 2 supports two lightweight YOLO object detection architectures: YOLOv8n and YOLO11n. The following steps use a YOLO object detection model to demonstrate the training and deployment workflow.

2.2 Preparing a YOLO Object Detection Dataset

The first step in training an object detection model is preparing a dataset. A dataset is the training material presented to the model. It contains images together with labels that describe the class and position of each object. By repeatedly learning from these image-label pairs, the model gradually learns to recognize the objects.

The HUSKYLENS 2 Model Installation Package Generator requires a standard YOLO-format dataset. A typical object detection dataset has the following folder structure:

dataset_dir
├── data.yaml
├── images
│   ├── train
│   │   ├── image_001.jpg
│   │   └── ...
│   └── val                     # Optional; not used during conversion
│       └── ...
└── labels
    ├── train
    │   ├── image_001.txt
    │   └── ...
    └── val                     # Optional; not used during conversion
        └── ...

The files and folders serve the following purposes:

• data.yaml: The dataset configuration file. It defines the dataset paths and class names used for training and validation.
• images/train: Stores the original training images.
• labels/train: Stores the annotation file for each image. Each annotation file must have the same base name as its corresponding image, but use the .txt extension. For example, image_001.jpg corresponds to image_001.txt.

An example dataset.yaml file, also commonly named data.yaml, is shown below:

path: ./      # Optional: dataset root relative to this YAML file
train: ./images/train  # Path to the training images
val: ./images/val
names:
  0: person
  1: car

The fields mean:

• path: The dataset root directory. This field is optional. If omitted, paths are resolved relative to the directory containing the YAML file.
• train: The relative path to the training image directory.
• names: A mapping between class IDs and class names. IDs must start at 0 and increase sequentially.

We provide a standard YOLO-format cat-and-dog dataset that you can use directly for object detection training and as a reference: Sample datasets and models.

Tip: If you use an annotation tool such as LabelImg or Roboflow, export the annotations in YOLO format. Each image must have a corresponding TXT annotation file.

For detailed YOLO object detection dataset specifications, additional examples, and instructions for converting formats such as COCO, see the official Ultralytics guide: Object Detection Datasets.

2.3 Training an Object Detection Model

After preparing the dataset, you can train the model. Training requires a Python environment and the Ultralytics library. If you are not familiar with the setup, start with the official Ultralytics Quickstart guide.

Pay particular attention to these two requirements:

1. HUSKYLENS 2 supports only custom-trained YOLOv8n and YOLO11n models. Other architectures, including YOLOv8s, YOLO11s, and YOLOv5, are not supported.
2. HUSKYLENS 2 supports only three input sizes: 224 × 224, 320 × 320, and 640 × 640.

The following example shows the complete training code. Replace the example paths with your actual paths:

from ultralytics import YOLO

if __name__ == "__main__":
    # Load a pretrained model.
    # HUSKYLENS 2 supports only "yolov8n.pt" and "yolo11n.pt".
    model = YOLO("yolov8n.pt")   # You can also use "yolo11n.pt".

    # Train the model.
    # data: Path to your dataset.yaml file.
    # epochs: Number of training epochs. More epochs may improve accuracy but take longer.
    # imgsz: Input image size. HUSKYLENS 2 supports only 224, 320, or 640.
    results = model.train(
        data="path/to/your_dataset.yaml",   # For example: r"D:\datasets\mydata\dataset.yaml"
        epochs=30,
        imgsz=640,
    )

When training is complete, Ultralytics saves the model weights in runs/detect/train/weights/. The best.pt file is the best-performing checkpoint.

Because HUSKYLENS 2 requires an ONNX model, the trained .pt file must be exported to .onnx format:

from ultralytics import YOLO

if __name__ == "__main__":
    # Load the trained weights. Replace this with the actual path to best.pt.
    model = YOLO("path/to/best.pt")   # For example: r"D:\...\runs\detect\train\weights\best.pt"

    # Export to ONNX. best.onnx will be created in the same directory.
    # imgsz must match the input size used during training: 224, 320, or 640.
    model.export(format="onnx", imgsz=640)

After a successful export, best.onnx appears in the same directory as best.pt. You will use this file when generating the installation package.

You can use the sample datasets and models to train a cat-and-dog object detection model with the code above. The download also includes a pretrained ONNX model.

For more information, see the official Ultralytics guides for Model Training and Model Export.

2.4 Generating an Installation Package

You cannot copy the exported ONNX model directly to HUSKYLENS 2. A custom-trained model must be deployed as an installation package through the Model Installation feature. The official HUSKYLENS 2 Model Installation Package Generator packages the ONNX model as a ZIP file that the device can recognize.

2.4.1 Downloading the HUSKYLENS 2 Model Installation Package Generator

Before using the generator, prepare the following environment:

1. A computer running Windows 10 or later.
2. The .NET 7.0 runtime required by the application. Open the .NET 7.0 download page. If you use 64-bit Windows, download and install the Windows x64 version.

3. Download the HUSKYLENS 2 Model Installation Package Generator. You can also view the source code and deploy it yourself.

2.4.2 Generating an Object Detection Model Installation Package

After downloading and extracting the tool, double-click HUSKYLENS2_Package_Generator.exe. The main interface is shown below.

The functional areas of the generator are shown below.

The following example generates an object detection package for recognizing cats and dogs. Download the sample datasets and models if you want to follow along.

Before starting, configure the following three options at the top of the tool:

1. Interface language: Select your preferred language. Eight languages are supported, including English, Simplified Chinese, and Traditional Chinese.
2. Output directory: Select where the generated ZIP package will be saved.
3. Data source: Keep the default value, YOLO.

Step 1: Select the dataset folder

Click Dataset Folder, locate the YOLO-format dataset used to train the model, and load it.

For the sample dataset, extract the download and select sample_datasets/Object Detection/Cat and Dog Object Detection Dataset.

Step 2: Select the ONNX model

Click ONNX Model, select the ONNX model trained with the dataset, and load it.

For the sample model, select sample_datasets/Object Detection/cat_and_dog-det.onnx.

Step 3: Verify the model parameters

After the model is loaded, the tool automatically detects and displays its parameters. Verify that they are correct and match the training configuration.

Step 4: Configure the model application for HUSKYLENS 2

• In App Name, enter the name that will appear after the model is deployed, such as Cat_Dog_Detection.
• To insert a manual line break, press Enter in the name field. This inserts a \n character.
• Automatic wrapping allows up to 12 English letters or 6 Chinese characters per line. Longer names wrap automatically and can occupy up to two lines.
• Click Add to enter application names for other languages. You can add names for any of the eight supported languages. Languages without a specific name use the current default. The displayed name changes when the HUSKYLENS 2 system language changes.

The generator assigns a default icon to the model application. To use your own icon, click Choose Icon and select an image from your computer.

• A square image with a transparent background and white lines is recommended so that it matches the built-in HUSKYLENS 2 icons. Color icons are also supported. The recommended size is 60 × 60 pixels; other sizes are automatically converted to 60 × 60.

You can also set the default confidence threshold used by the model on HUSKYLENS 2.

Step 5: Generate the model installation package

When all settings are complete, click Start. Do not close the tool until generation is finished.

The following message appears when the object detection package has been generated successfully.

The package is saved in the selected output directory. Its filename follows the format AppName-ModelVersion-TaskType-InputSize.Checksum.zip, for example, Cat-YOLO11n-det-320.a1b2.zip.

Do not modify the generated ZIP package, any file inside it, or the package filename. Otherwise, HUSKYLENS 2 will not recognize it.

2.4.3 Deploying the Custom Object Detection Model to HUSKYLENS 2

Connect HUSKYLENS 2 to the computer with a USB cable. A USB drive named HUSKYLENS 2 appears in Windows.

Copy the generated ZIP package to:

Huskylens\storage\installation_package

On HUSKYLENS 2, open Model Installation, and then select Local Installation.

After installation, the custom object detection model appears in the function list.

Tap the model icon to view the detection results. The following example shows the cat-and-dog detection model.

The test images are shown below.

To delete the model, locate the deployed custom model on the screen, press and hold its application icon, and tap Confirm.

3. Installing an Image Classification Model

3.1 What Is an Image Classification Model?

Image classification is a basic computer vision task that assigns a class to an entire image. In other words, it answers the question, “What category does this image belong to?” The output contains only a class name and a confidence score. It does not locate the object or return multiple objects at the same time.

An image classification model:

• Returns one class label and confidence score, making the result simple and easy to understand.
• Does not require bounding-box annotations, so the dataset is inexpensive and quick to prepare.
• Is suitable when you need to know what something is but do not need its location, such as waste sorting, fruit and vegetable classification, or pet breed recognition.

HUSKYLENS 2 supports two lightweight classification architectures: YOLOv8n-cls and YOLO11n-cls. The following steps use a YOLO classification model to demonstrate the training and deployment workflow.

3.2 Preparing a YOLO Image Classification Dataset

An image classification dataset is simpler than an object detection dataset because it does not require bounding-box annotations. Place the images for each class in a separate folder. The folder name becomes the class name, and the model learns the categories from this structure.

A standard YOLO image classification dataset has the following folder structure:

dataset_dir
├── train
│   ├── class_1
│   │   ├── image_001.jpg
│   │   └── ...
│   └── class_2
│       ├── image_002.jpg
│       └── ...
└── val                       # Optional; not used during conversion
    └── ...

The folders serve the following purposes:

• train: Stores the training images.
• class_1 and class_2: Class folders. Each folder name is used as the class name, and the folder contains images of that class.
• val (optional): Stores test images and uses the same structure as train. The package conversion process does not read this folder.

An image classification dataset does not need a data.yaml configuration file or separate annotation files. During training, point data directly to the dataset root that contains the train folder.

We provide a Cat and Dog Classification Dataset that can be used directly for training: Sample datasets and models.

For more details about the dataset format, see the official Ultralytics guide: Image Classification Datasets.

3.3 Training an Image Classification Model

Classification model training also uses the Ultralytics library. If you are unfamiliar with the environment, see the official Quickstart guide first.

Pay particular attention to these two requirements:

1. HUSKYLENS 2 supports only custom-trained YOLOv8n-cls and YOLO11n-cls models. Other architectures are not supported.
2. HUSKYLENS 2 supports only 224 × 224, 320 × 320, and 640 × 640 input sizes.

Replace the example paths in the following training code with your actual paths:

from ultralytics import YOLO

if __name__ == "__main__":
    # Load a pretrained classification model.
    # HUSKYLENS 2 supports only "yolov8n-cls.pt" and "yolo11n-cls.pt".
    model = YOLO("yolov8n-cls.pt")   # You can also use "yolo11n-cls.pt".

    # Train the model.
    # data: Dataset root containing the train folder, not a YAML file.
    # epochs: Number of training epochs. Start with 30 if you are unsure.
    # imgsz: Input image size. HUSKYLENS 2 supports only 224, 320, or 640.
    results = model.train(
        data="path/to/Cat and Dog Classification Dataset",   # For example: r"D:\...\Cat and Dog Classification Dataset"
        epochs=30,
        imgsz=640,
    )

When training is complete, Ultralytics saves the weights in runs/classify/train/weights/. The best.pt file is the best-performing checkpoint.

Export the trained .pt model to ONNX format before installing it on HUSKYLENS 2:

from ultralytics import YOLO

if __name__ == "__main__":
    # Load the trained classification weights.
    model = YOLO("path/to/best.pt")   # For example: r"D:\...\runs\classify\train\weights\best.pt"

    # Export to ONNX. best.onnx will be created in the same directory.
    # imgsz must match the input size used during training: 224, 320, or 640.
    model.export(format="onnx", imgsz=640)

After a successful export, best.onnx appears in the same directory as best.pt.

You can use the sample datasets and models to train a cat-and-dog classification model with the code above. The download also includes a pretrained ONNX model.

For more information, see the official Ultralytics Image Classification guide.

3.4 Generating an Installation Package

The exported ONNX model must be packaged as a ZIP file that HUSKYLENS 2 can recognize. This section uses the same HUSKYLENS 2 Model Installation Package Generator introduced in Section 2.

3.4.1 Downloading the HUSKYLENS 2 Model Installation Package Generator

If you have already installed .NET 7.0 and downloaded HUSKYLENS2_Package_Generator.exe as described in Section 2.4.1, skip to Section 3.4.2. Otherwise:

1. Use a computer running Windows 10 or later.
2. Install the .NET 7.0 runtime from the .NET 7.0 download page. Select Windows x64 for 64-bit Windows.
3. Download the HUSKYLENS 2 Model Installation Package Generator.

3.4.2 Generating an Image Classification Model Installation Package

Double-click HUSKYLENS2_Package_Generator.exe after extracting the download.

The functional areas of the generator are shown below.

The following example generates a cat-and-dog classification package. Download the sample datasets and models if you want to follow along.

Before starting, configure these options at the top of the tool:

1. Interface language: Select your preferred language.
2. Output directory: Select where the generated ZIP package will be saved.
3. Data source: Keep the default value, YOLO.

Step 1: Select the dataset folder

Click Dataset Folder and load the classification dataset. For the sample dataset, select sample_datasets/Classification/Cat and Dog Classification Dataset.

Step 2: Select the ONNX model

Click ONNX Model and load the classification model trained with the dataset. For the sample model, select sample_datasets/Classification/cat_and_dog-cls.onnx.

Step 3: Verify the model parameters

Verify that the automatically detected parameters match the training configuration. For a classification model, confirm that Task Type is Classification.

Step 4: Configure the model application for HUSKYLENS 2

• In App Name, enter the displayed name, such as Cat_Dog_Classification.
• Press Enter in the name field to insert a manual \n line break.
• Names wrap automatically after 12 English letters or 6 Chinese characters per line, with a maximum of two lines.
• Click Add to enter application names for other supported languages. Unspecified languages use the current default name.

The generator assigns a default icon. Click Choose Icon to select a custom image.

• A square, transparent image with white lines is recommended. Color icons are also supported. The recommended size is 60 × 60 pixels; other sizes are converted automatically.

Set the default confidence threshold if necessary.

Step 5: Generate the model installation package

Click Start and do not close the tool until generation is complete.

The following message appears when generation is complete.

The package filename follows the format AppName-ModelVersion-TaskType-InputSize.Checksum.zip. The task type is cls, for example, Cat_Dog-YOLO11n-cls-640.xxxx.zip.

Do not modify the generated ZIP package, its contents, or its filename.

3.4.3 Deploying the Custom Image Classification Model to HUSKYLENS 2

Connect HUSKYLENS 2 to the computer with a USB cable. A USB drive named HUSKYLENS 2 appears in Windows.

Copy the generated ZIP package to:

Huskylens\storage\installation_package

On HUSKYLENS 2, open Model Installation, and then select Local Installation.

After installation, the custom image classification model appears in the function list.

Tap the model icon to view the classification results.

The test images are shown below.

To delete the model, press and hold the deployed application icon, and then tap OK.

4. Installing an Instance Segmentation Model

4.1 What Is an Instance Segmentation Model?

Instance segmentation goes one step beyond object detection. In addition to recognizing and locating every object in an image, it uses a mask to trace the precise outline of each object.

For example, object detection draws a rectangular box around each flower in an image. Instance segmentation instead creates a colored mask along the edge of each flower and reports its class and confidence score. You can think of it as identifying both an object's location and its exact shape.

An instance segmentation model:

• Returns a bounding box, precise mask, class name, and confidence score for each object.
• Describes object shapes more accurately and provides richer information than object detection.
• Is suitable for applications that require an exact outline, such as flower segmentation or component contour inspection.

HUSKYLENS 2 supports two lightweight segmentation architectures: YOLOv8n-seg and YOLO11n-seg. The following steps demonstrate how to train and deploy a YOLO instance segmentation model.

4.2 Preparing a YOLO Instance Segmentation Dataset

The structure of an instance segmentation dataset is similar to that of an object detection dataset. Both contain images, labels, and a data.yaml file. The key difference is that an instance segmentation label stores polygon vertices describing the object's outline instead of a bounding box.

A standard YOLO instance segmentation dataset has the following folder structure:

dataset_dir
├── data.yaml
├── images
│   ├── train
│   │   ├── image_001.jpg
│   │   └── ...
│   └── val                     # Optional; not used during conversion
│       └── ...
└── labels
    ├── train
    │   ├── image_001.txt
    │   └── ...
    └── val                     # Optional; not used during conversion
        └── ...

An example data.yaml file is shown below:

path: ./
train: ./images/train
val: ./images/val
names:
  0: flower

An instance segmentation label file differs from an object detection label file. Each object detection label contains a class ID, bounding-box center coordinates, width, and height, for a total of five values. Each instance segmentation label contains a class ID followed by a series of polygon vertices in the format class x1 y1 x2 y2 ... xn yn. At least three points are required to outline an object.

We provide a Flower Segmentation Dataset that you can use directly for training: Sample datasets and models.

For detailed format specifications, see the official Ultralytics guide: Instance Segmentation Datasets.

4.3 Training an Instance Segmentation Model

Instance segmentation training also uses the Ultralytics library. If you are unfamiliar with the environment, start with the official Quickstart guide.

Pay particular attention to these two requirements:

1. HUSKYLENS 2 supports only custom-trained YOLOv8n-seg and YOLO11n-seg models. Other architectures are not supported.
2. HUSKYLENS 2 supports only 224 × 224, 320 × 320, and 640 × 640 input sizes. The input size used for training must match the size used when generating the package.

Replace the example paths in the following code with your actual paths:

from ultralytics import YOLO

if __name__ == "__main__":
    # Load a pretrained segmentation model.
    # HUSKYLENS 2 supports only "yolov8n-seg.pt" and "yolo11n-seg.pt".
    model = YOLO("yolov8n-seg.pt")   # You can also use "yolo11n-seg.pt".

    # Train the model.
    # data: Path to the dataset configuration file, data.yaml.
    # epochs: Number of training epochs. Start with 30 if you are unsure.
    # imgsz: Input image size. HUSKYLENS 2 supports only 224, 320, or 640.
    results = model.train(
        data="path/to/data.yaml",   # For example: r"D:\...\Flower Segmentation Dataset\data.yaml"
        epochs=30,
        imgsz=640,
    )

When training is complete, Ultralytics saves the weights in runs/segment/train/weights/. The best.pt file is the best-performing checkpoint.

Export the trained .pt model to ONNX format:

from ultralytics import YOLO

if __name__ == "__main__":
    # Load the trained segmentation weights.
    model = YOLO("path/to/best.pt")   # For example: r"D:\...\runs\segment\train\weights\best.pt"

    # Export to ONNX. best.onnx will be created in the same directory.
    # imgsz must match the input size used during training: 224, 320, or 640.
    model.export(format="onnx", imgsz=640)

After a successful export, best.onnx appears in the same directory as best.pt.

You can use the sample datasets and models to train a flower segmentation model with the code above. The download also includes a pretrained ONNX model.

For more information, see the official Ultralytics Instance Segmentation guide.

4.4 Generating an Installation Package

The exported ONNX model must be packaged as a ZIP file that HUSKYLENS 2 can recognize. This section uses the same HUSKYLENS 2 Model Installation Package Generator introduced earlier.

4.4.1 Downloading the HUSKYLENS 2 Model Installation Package Generator

If you have already installed .NET 7.0 and downloaded HUSKYLENS2_Package_Generator.exe, skip to Section 4.4.2. Otherwise:

1. Use a computer running Windows 10 or later.
2. Install the .NET 7.0 runtime from the .NET 7.0 download page. Select Windows x64 for 64-bit Windows.
3. Download the HUSKYLENS 2 Model Installation Package Generator.

4.4.2 Generating an Instance Segmentation Model Installation Package

Double-click HUSKYLENS2_Package_Generator.exe after extracting the download.

The functional areas of the generator are shown below.

The following example generates a flower instance segmentation package. Download the sample datasets and models if you want to follow along.

Before starting, configure these options at the top of the tool:

1. Interface language: Select your preferred language.
2. Output directory: Select where the generated ZIP package will be saved.
3. Data source: Keep the default value, YOLO.

Step 1: Select the dataset folder

Click Dataset Folder and load the segmentation dataset that contains data.yaml. For the sample dataset, select sample_datasets/Instance Segmentation/Flower Segmentation Dataset.

Step 2: Select the ONNX model

Click ONNX Model and load the segmentation model trained with the dataset. For the sample model, select sample_datasets/Instance Segmentation/flower-seg.onnx.

Step 3: Verify the model parameters

Verify that the automatically detected parameters match the training configuration. For an instance segmentation model, confirm that Task Type is Segmentation.

Step 4: Configure the model application for HUSKYLENS 2

• In App Name, enter the displayed name, such as Flower_Segmentation.
• Press Enter in the name field to insert a manual \n line break.
• Names wrap automatically after 12 half-width characters or 6 full-width characters per line, with a maximum of two lines displayed.
• Click Add to enter application names for other supported languages. Unspecified languages use the current default name.

The generator assigns a default icon. Click Choose Icon to select a custom image.

• A square, transparent image with white lines is recommended. Color icons are also supported. The recommended size is 60 × 60 pixels; other sizes are converted automatically.

You can also configure the default confidence threshold.

Step 5: Generate the model installation package

Click Start and do not close the tool until generation is complete.

The following message appears when generation is complete.

The package filename follows the format AppName-ModelVersion-TaskType-InputSize.Checksum.zip. The task type is seg, for example, Flower-YOLO11n-seg-640.xxxx.zip.

Do not modify the generated ZIP package, its contents, or its filename.

4.4.3 Deploying the Custom Instance Segmentation Model to HUSKYLENS 2

Connect HUSKYLENS 2 to the computer with a USB cable. A USB drive named HUSKYLENS 2 appears in Windows.

Copy the generated ZIP package to:

Huskylens\storage\installation_package

On HUSKYLENS 2, open Model Installation, and then select Local Installation.

After installation, the custom instance segmentation model appears in the function list.

Tap the model icon to view the segmentation result. The following example shows the flower segmentation model.

To delete the model, press and hold the deployed application icon, and then tap OK.

The test image is shown below.