# Import Labels

## Overview

The Import Labels Plugin allows you to import pre-labels into a project from a CSV file. This plugin is designed to support bulk ingestion of labels generated by external tools, models, or annotation pipelines and map them correctly to existing assets in your project.

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td align="center">Import Labels</td><td data-object-fit="contain"><a href="https://angohub-docs-assets.s3.eu-central-1.amazonaws.com/plugin-icons-banners/csv-import-labels.png">https://angohub-docs-assets.s3.eu-central-1.amazonaws.com/plugin-icons-banners/csv-import-labels.png</a></td></tr></tbody></table>

## Plugin Functionality

The plugin reads a CSV file where each row represents a single asset and imports labels based on the configured parameters. Depending on the configuration, it can:

* Match CSV rows to existing project assets using an external ID column
* Import classification labels from one or more CSV columns
* Import segmentation/polygon annotations from mask files referenced in the CSV
* Map mask values to label classes using project colors or custom mappings
* Overwrite existing labels or append new ones
* Process imports in customized batches for better performance.

<figure><img src="https://3895963154-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTcOUG6rfWxqGM0N4db2P%2Fuploads%2F4zU5xnprp7FvzxOfNrZk%2Fimage.png?alt=media&#x26;token=b260ed23-967f-4089-9439-20e97f3fb645" alt=""><figcaption></figcaption></figure>

#### Example Configurations <a href="#supported-data-types" id="supported-data-types"></a>

**Import Classification Annotations**

{% code title="Config JSON" fullWidth="false" %}

```json
{
  "external_id_column": "External ID",
  "classification_columns": ["Color", "Category", "Image Type"],
  "classification_schema_ids": ["8c481a58f4c68e5db0a5016", "12a20f8061c044bcff26688", "1976d3fc0fa1429e23f7171"],
  "mask_column": "",
  "mask_color_mapping": "project_colors",
  "segmentation_mode": "instance_segmentation",
  "polygon_simplification_tolerance": 0.1,
  "storage_id": "",
  "overwrite": true,
  "ignored_schema_ids": [],
  "upload_batch_size": 100
}
```

{% endcode %}

{% file src="<https://3895963154-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTcOUG6rfWxqGM0N4db2P%2Fuploads%2FAHuZJGXuDYNZI7YxTmac%2Fprelabels.csv?alt=media&token=57347896-b7ef-4dfe-b7e4-0889295316ac>" %}

<details>

<summary>Category Schema</summary>

```json
{
  "tools": [],
  "classifications": [
    {
      "title": "Color",
      "tool": "text",
      "required": false,
      "schemaId": "8c481a58f4c68e5db0a5016",
      "frameSpecific": false,
      "richText": false,
      "regex": "",
      "classifications": [],
      "multiple": false,
      "options": [],
      "shortcutKey": "1"
    },
    {
      "title": "Type",
      "tool": "radio",
      "required": false,
      "schemaId": "12a20f8061c044bcff26688",
      "frameSpecific": false,
      "classifications": [],
      "multiple": false,
      "options": [
        {
          "value": "A",
          "schemaId": "0ab9ff484461bb8d5952369"
        },
        {
          "value": "B",
          "schemaId": "23b5e8770c797a9ad036777"
        },
        {
          "value": "C",
          "schemaId": "64989cbf9f9ddd38b882118"
        }
      ],
      "shortcutKey": "2"
    },
    {
      "title": "Question",
      "tool": "checkbox",
      "required": false,
      "schemaId": "1976d3fc0fa1429e23f7171",
      "frameSpecific": false,
      "classifications": [],
      "multiple": false,
      "options": [
        {
          "value": "Option1",
          "schemaId": "1c00ef1ec8bca05c3550770"
        },
        {
          "value": "Option2",
          "schemaId": "b90770265328965f1f7c070"
        }
      ],
      "shortcutKey": "3"
    }
  ],
  "relations": []
}
```

</details>

***

**Import Segmentation Annotations**

{% code title="Config JSON" fullWidth="false" %}

```json
{
  "external_id_column": "External ID",
  "classification_columns": ["Color", "Category", "Image Type"],
  "classification_schema_ids": ["8c481a58f4c68e5db0a5016", "12a20f8061c044bcff26688", "1976d3fc0fa1429e23f7171"],
  "mask_column": "Mask",
  "mask_color_mapping": "project_colors",
  "segmentation_mode": "instance_segmentation",
  "polygon_simplification_tolerance": 0.1,
  "storage_id": "",
  "overwrite": true,
  "ignored_schema_ids": [],
  "upload_batch_size": 100
}
```

{% endcode %}

{% file src="<https://3895963154-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTcOUG6rfWxqGM0N4db2P%2Fuploads%2FMm43OQ5KCM3u9qJ5Um56%2Fprelabels.csv?alt=media&token=cc86afb0-e8e5-47fb-81be-f69aca8c63d1>" %}

<details>

<summary>Category Schema</summary>

```json
{
  "tools": [
    {
      "title": "Car",
      "tool": "segmentation",
      "required": false,
      "schemaId": "f104b6b9cdb84966812b002",
      "classifications": [],
      "multiple": false,
      "color": "#f44336",
      "shortcutKey": "4"
    },
    {
      "title": "Person",
      "tool": "segmentation",
      "required": false,
      "schemaId": "c6faa323be0cbb84634f566",
      "classifications": [],
      "multiple": false,
      "color": "#03a9f4",
      "shortcutKey": "5"
    },
    {
      "title": "Other",
      "tool": "segmentation",
      "required": false,
      "schemaId": "b34867a913e35379d100997",
      "classifications": [],
      "multiple": false,
      "color": "#9c27b0",
      "shortcutKey": "6"
    }
  ],
  "classifications": [
    {
      "title": "Color",
      "tool": "text",
      "required": false,
      "schemaId": "8c481a58f4c68e5db0a5016",
      "frameSpecific": false,
      "richText": false,
      "regex": "",
      "classifications": [],
      "multiple": false,
      "options": [],
      "shortcutKey": "1"
    },
    {
      "title": "Type",
      "tool": "radio",
      "required": false,
      "schemaId": "12a20f8061c044bcff26688",
      "frameSpecific": false,
      "classifications": [],
      "multiple": false,
      "options": [
        {
          "value": "A",
          "schemaId": "0ab9ff484461bb8d5952369"
        },
        {
          "value": "B",
          "schemaId": "23b5e8770c797a9ad036777"
        },
        {
          "value": "C",
          "schemaId": "64989cbf9f9ddd38b882118"
        }
      ],
      "shortcutKey": "2"
    },
    {
      "title": "Question",
      "tool": "checkbox",
      "required": false,
      "schemaId": "1976d3fc0fa1429e23f7171",
      "frameSpecific": false,
      "classifications": [],
      "multiple": false,
      "options": [
        {
          "value": "Option1",
          "schemaId": "1c00ef1ec8bca05c3550770"
        },
        {
          "value": "Option2",
          "schemaId": "b90770265328965f1f7c070"
        }
      ],
      "shortcutKey": "3"
    }
  ],
  "relations": []
}
```

</details>

### Supported Data Types <a href="#supported-data-types" id="supported-data-types"></a>

* Compatible with all data types available in AngoHub.

### Supported Annotation Tools <a href="#supported-annotation-tools" id="supported-annotation-tools"></a>

* Classifications
  * Radio
  * Checkbox
  * Single-Select Dropdown
  * Multi-Select Dropdown
  * Text
* Tools
  * Segmentation
  * Polygon

{% hint style="danger" %}
Following tools are not supported by the plugin:

* Nested classifications, multiple classifications, frame specific classifications
* Frame-specific segmentation and polygon tools
* Nested classifications within tools
  {% endhint %}

## Plugin Configuration <a href="#plugin-configuration" id="plugin-configuration"></a>

You may vary a number of settings related to your export from the **Config JSON** field. Each option is detailed below:

```json
{
  "external_id_column": "",
  "classification_columns": [],
  "classification_schema_ids": [],
  "mask_column": "",
  "mask_color_mapping": "project_colors",
  "segmentation_mode": "instance_segmentation",
  "polygon_simplification_tolerance": 0.1,
  "storage_id": "",
  "overwrite": true,
  "ignored_schema_ids": [],
  "upload_batch_size": 100
}
```

* **"external\_id\_column":** Name of the CSV column that contains external IDs used to match imported labels to existing assets in the project.
  * Example:
    * <kbd>"external\_id\_column": "External ID"</kbd>&#x20;

* **"classification\_columns":** List of CSV column names that contain classification values to import. Each column is mapped to a classification schema.
  * Example:
    * <kbd>"classification\_columns": \["Color", "Category"]</kbd>

* **"classification\_schema\_ids":** List of classification schema IDs that define how values from classification\_columns are interpreted and mapped during import. The order must match classification\_columns.
  * Example:
    * <kbd>"classification\_schema\_ids": \["12345", "12346"]</kbd>

* **"mask\_column":** Name of the CSV column that contains segmentation mask references. The value can be a file path or URL pointing to the mask file.
  * Example:
    * <kbd>"mask\_column": "Mask"</kbd>

* **"mask\_color\_mapping":** Defines how colors in segmentation masks are mapped to label classes. Use project colors or provide a custom mapping.&#x20;
  * Options:&#x20;
    * <kbd>"mask\_color\_mapping": "project\_colors"</kbd>
    * <kbd>"mask\_color\_mapping": {"Car" : \[244, 67, 54], "Person" : \[3, 169, 244]}</kbd>
    * <kbd>"mask\_color\_mapping": {"Car" : \[1], "Person" : \[2]}</kbd>

* **"segmentation\_mode":** Controls how segmentation annotations are created from masks. "instance\_segmentation" creates a separate object for each connected region per class and "semantic\_segmentation" creates a single object for each class.
  * Options:
    * <kbd>"segmentation\_mode": "instance\_segmentation"</kbd>
    * <kbd>"segmentation\_mode": "semantic\_segmentation"</kbd>

* **"polygon\_simplification\_tolerance":** Tolerance used when converting masks to polygons. Higher values reduce the number of polygon points at the cost of geometric precision.
  * Example:
    * <kbd>"polygon\_simplification\_tolerance": 0.1</kbd>&#x20;

* **"storage\_id":** Identifier of the storage location where mask files referenced in the CSV are stored. Used to resolve file paths or storage keys during import.
  * Example:
    * <kbd>"storage\_id": "1234"</kbd>&#x20;

* **"overwrite":** If true, existing labels for matching assets will be replaced by the imported labels. If false, imported labels are added while preserving existing labels.
  * Example:
    * <kbd>"overwrite": true</kbd>
    * <kbd>"overwrite": false</kbd>

* **"ignored\_schema\_ids":** List of schema IDs to ignore during import. Any tools or classifications associated with these schemas will be skipped, even if present in the CSV.
  * Example:
    * <kbd>"ignored\_schema\_ids": \["1234", "1235"]</kbd>

* **"upload\_batch\_size":** Number of rows from the CSV to process per batch. Larger batch sizes improve throughput but increase memory usage and may hit API limits.
  * Example:
    * <kbd>"upload\_batch\_size": 100</kbd>