LightlyStudio

https://docs.lightly.ai/studio/
Admin
LightlyStudio is an open-source tool for unified data workflows including curation, annotation, and...
Tokens:52,262
Snippets:626
Trust Score:9.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quickstart: Video Dataset with LightlyStudio

Source: https://docs.lightly.ai/studio

Creates a VideoDataset, populates it with videos from a specified path, and starts the LightlyStudio GUI. Downloads example data if not already present.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

# Create a dataset and populate it with videos.
dataset = ls.VideoDataset.create()
dataset.add_videos_from_path(path=f"{dataset_path}/youtube_vis_50_videos/train/videos")

# Start the UI server.
ls.start_gui()

```

--------------------------------

### Quickstart: Image Dataset with LightlyStudio

Source: https://docs.lightly.ai/studio

Creates an ImageDataset, adds images from a specified path, and starts the LightlyStudio GUI. Downloads example data if not already present.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

# Indexes the dataset, creates embeddings and stores everything in the database.
dataset = ls.ImageDataset.create()
dataset.add_images_from_path(
    path=f"{dataset_path}/coco_subset_128_images/images",
)

# Start the UI server on localhost port 8001.
# Pass `host` and `port` parameters to customize.
ls.start_gui()

```

--------------------------------

### Quickstart: YOLO Object Detection Dataset with LightlyStudio

Source: https://docs.lightly.ai/studio

Creates an ImageDataset and adds samples from a YOLO format dataset specified by a data.yaml file. Downloads example data if not already present.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.create()
dataset.add_samples_from_yolo(
    data_yaml=f"{dataset_path}/road_signs_yolo/data.yaml",
)

ls.start_gui()

```

--------------------------------

### Quickstart: COCO Instance Segmentation Dataset with LightlyStudio

Source: https://docs.lightly.ai/studio

Creates an ImageDataset and adds samples from a COCO format dataset, specifying the annotations JSON, images path, and annotation type. Downloads example data if not already present.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.create()
dataset.add_samples_from_coco(
    annotations_json=f"{dataset_path}/coco_subset_128_images/instances_train2017.json",
    images_path=f"{dataset_path}/coco_subset_128_images/images",
    annotation_type=ls.AnnotationType.INSTANCE_SEGMENTATION,
)

ls.start_gui()

```

--------------------------------

### Install Cloud Storage Dependencies

Source: https://docs.lightly.ai/studio/enterprise/cloud_storage

Install the necessary dependencies for cloud storage integration with Lightly Studio.

```bash
pip install "lightly-studio[cloud-storage]"
```

--------------------------------

### Install LightlyStudio on Windows

Source: https://docs.lightly.ai/studio

Installs the LightlyStudio library using pip within a virtual environment. Ensure Python 3.9 to 3.14 is installed.

```bash
# 1. Create and activate a virtual environment (Recommended)
python -m venv venv
.\venv\Scripts\activate

# 2. Install LightlyStudio
pip install lightly_studio

```

--------------------------------

### Install LightlyStudio on Linux/macOS

Source: https://docs.lightly.ai/studio

Installs the LightlyStudio library using pip within a virtual environment. Ensure Python 3.9 to 3.14 is installed.

```bash
# 1. Create and activate a virtual environment (Recommended)
python3 -m venv venv
source venv/bin/activate

# 2. Install LightlyStudio
pip install lightly_studio

```

--------------------------------

### Register and Start Lightly AI Studio GUI

Source: https://docs.lightly.ai/studio/concepts_and_tools/plugins

Register a custom operator and then start the Lightly AI Studio GUI. Ensure the operator is defined before registration.

```python
operator_registry.register(LightlyTrainAutoLabelingODOperator())

ls.start_gui()
```

--------------------------------

### Start Lightly Studio GUI in Background

Source: https://docs.lightly.ai/studio/advanced/notebooks

Starts the Lightly Studio GUI in the background, allowing notebook execution to continue. For Colab, '0.0.0.0' is required to expose the port. This function does not block the notebook.

```python
# Colab needs 0.0.0.0 to expose the port.
server = ls.start_gui_background(host="0.0.0.0")

```

--------------------------------

### Launch Lightly Studio GUI

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Start the Lightly Studio GUI from your terminal to visualize and interact with your video dataset. The command will print a local URL to access the GUI in your browser.

```bash
lightly-studio gui
```

--------------------------------

### Launch Lightly Studio GUI

Source: https://docs.lightly.ai/studio/dataset_setup/image_dataset

Launches the Lightly Studio GUI from the terminal. The GUI can also be started programmatically.

```bash
lightly-studio gui

```

--------------------------------

### Install Cloud Storage Dependencies

Source: https://docs.lightly.ai/studio/api

Install the necessary dependencies for cloud storage integration using pip. This includes `s3fs`, `gcsfs`, and `adlfs`.

```bash
pip install "lightly-studio[cloud-storage]"

```

--------------------------------

### BaseOperator Startup Method

Source: https://docs.lightly.ai/studio/api/plugin

The `startup` method is called after operator registration for setup work like venv creation or model downloads. Simple operators may not need to override this.

```python
startup() -> None
```

--------------------------------

### Get Sample File Name

Source: https://docs.lightly.ai/studio/api/sample

Accesses the file name of the sample.

```python
file_name = DBField(col(file_name))
```

--------------------------------

### Import Lightly Studio Libraries

Source: https://docs.lightly.ai/studio/advanced/notebooks

Import the necessary Lightly Studio library and a utility for downloading example datasets. This is the first step before using any Lightly Studio functionalities.

```python
import lightly_studio as ls
from lightly_studio.utils import download_example_dataset

```

--------------------------------

### Connect to Lightly Studio and Load S3 Dataset

Source: https://docs.lightly.ai/studio/enterprise/cloud_storage

Connect to Lightly Studio and load or create an image dataset from an S3 bucket. Ensure cloud storage dependencies are installed.

```python
import lightly_studio as ls

ls.connect()

dataset = ls.ImageDataset.load_or_create("s3_dataset")
dataset.add_images_from_path(path="s3://my-bucket/images/")
```

--------------------------------

### Loading Images from Cloud Storage (S3)

Source: https://docs.lightly.ai/studio/api

Provides an example of loading images directly from an S3 bucket using the `lightly-studio[cloud-storage]` dependency.

```APIDOC
## Using Cloud Storage

### Description
Load images or videos directly from cloud storage providers like AWS S3 by installing the necessary dependencies (`pip install "lightly-studio[cloud-storage]"`). Ensure your cloud credentials are configured.

### Example: Loading images from S3
```python
import lightly_studio as ls

# Create a dataset and add images from an S3 path
dataset = ls.ImageDataset.create(name="s3_dataset")
dataset.add_images_from_path(path="s3://my-bucket/images/")

ls.start_gui()
```
```

--------------------------------

### Query Video Samples by Tags and Order by File Path

Source: https://docs.lightly.ai/studio/api/dataset_query

Example of querying video samples. Matches samples containing a specific tag and orders them by absolute file path. Requires importing VideoSampleField and OrderByField.

```python
from lightly_studio.core.dataset_query import VideoSampleField, OrderByField

query = dataset.query()
query.match(VideoSampleField.tags.contains("cat"))
query.order_by(OrderByField(VideoSampleField.file_path_abs))
samples = query.to_list()

```

--------------------------------

### Get Sample Metadata

Source: https://docs.lightly.ai/studio/api/sample

Provides dictionary-like access to the sample's metadata.

```python
metadata: SampleMetadata
```

--------------------------------

### Get Sample Absolute File Path

Source: https://docs.lightly.ai/studio/api/sample

Accesses the absolute file path to the sample.

```python
file_path_abs = DBField(col(file_path_abs))
```

--------------------------------

### Iterate Over Dataset Samples

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Once samples are added to the dataset, you can iterate through them to access individual `VideoSample` objects. This example shows how to print the file name of each video.

```python
for video in dataset:
    print(video.file_name)
```

--------------------------------

### Get Sample Creation Timestamp

Source: https://docs.lightly.ai/studio/api/sample

Accesses the creation timestamp of the sample.

```python
created_at = DBField(col(created_at))
```

--------------------------------

### Get Sample Class

Source: https://docs.lightly.ai/studio/api/dataset

Returns the sample class associated with the dataset.

```python
sample_class() -> type[VideoSample]
```

--------------------------------

### Get Sample Tags

Source: https://docs.lightly.ai/studio/api/sample

Retrieves the set of tag names associated with the sample.

```python
tags: set[str]
```

--------------------------------

### Get Sample Annotations

Source: https://docs.lightly.ai/studio/api/sample

Retrieves all annotations associated with a sample. Annotations are returned as a list of Annotation objects.

```python
annotations: list[Annotation]
```

--------------------------------

### Register and Run Operator Plugin

Source: https://docs.lightly.ai/studio/concepts_and_tools/plugins

Register a custom operator with the operator registry and start the Lightly Studio GUI. Ensure the operator class is imported.

```python
import lightly_studio as ls
from lightly_studio.plugins.operator_registry import operator_registry
from lightly_studio.utils import download_example_dataset
from greeting_operator import GreetingOperator

dataset_path = download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.create()
dataset.add_images_from_path(path=f"{dataset_path}/coco_subset_128_images/images")

# Register the operator to make it available to the application
operator_registry.register(GreetingOperator())

ls.start_gui()

```

--------------------------------

### Create Dataset from COCO Data

Source: https://docs.lightly.ai/studio/advanced/notebooks

Download an example dataset and create an ImageDataset object. Then, add samples to the dataset from a COCO annotations JSON file and its corresponding images directory.

```python
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")
dataset = ls.ImageDataset.load_or_create()
dataset.add_samples_from_coco(
    annotations_json=f"{dataset_path}/coco_subset_128_images/instances_train2017.json",
    images_path=f"{dataset_path}/coco_subset_128_images/images",
)

```

--------------------------------

### Get Sample Captions

Source: https://docs.lightly.ai/studio/api/sample

Retrieves the text of all captions associated with a sample. Captions are returned as a list of strings.

```python
captions: list[str]
```

--------------------------------

### VideoSample Class Properties and Methods

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Provides examples of accessing and modifying properties of a `VideoSample` object, including file information, tags, captions, and metadata.

```APIDOC
## VideoSample Class

### Description
The `VideoSample` class provides access to individual video data within a dataset. You can read properties like file name, dimensions, duration, and FPS, and also modify tags, captions, and metadata.

### Usage Examples
```python
# Grab one sample from the dataset
video = next(iter(dataset))

# Access video properties
print(f"File Name: {video.file_name}")
print(f"Absolute File Path: {video.file_path_abs}")
print(f"Width: {video.width}")
print(f"Height: {video.height}")
print(f"Duration (s): {video.duration_s}")
print(f"FPS: {video.fps}")

# Manage tags
video.tags = ["tag1", "tag2"]
video.add_tag("needs_review")
video.remove_tag("needs_review")
print(f"Tags: {video.tags}")

# Manage captions
video.captions = ["Caption 1", "Caption 2"]
video.add_caption("Caption 3")
print(f"Captions: {video.captions}")

# Manage metadata
video.metadata["my_key"] = "my_value"
print(f"Metadata['my_key']: {video.metadata['my_key']}")
```
```

--------------------------------

### Connect and Use API (Reads from .env)

Source: https://docs.lightly.ai/studio/enterprise/connect

Connect to the LightlyStudio Enterprise instance by calling `ls.connect()` without arguments; it automatically reads credentials from the `.env` file. After connecting, all dataset operations target the enterprise database, and the GUI is already running on the server.

```python
import lightly_studio as ls

# Reads LIGHTLY_STUDIO_API_URL and LIGHTLY_STUDIO_TOKEN from .env
ls.connect()

# From here on, the API works exactly as in the open-source version,
# but data is stored in the shared enterprise database.
dataset = ls.ImageDataset.load("my_dataset")
for sample in list(dataset)[:3]:
    print(f"{sample.file_name} has {len(sample.annotations)} annotations")

```

--------------------------------

### Create and Load VideoDataset

Source: https://docs.lightly.ai/studio/api/dataset

Demonstrates static methods for creating, loading, or creating and loading a VideoDataset. Use these to initialize your dataset.

```python
dataset = VideoDataset.create()
dataset = VideoDataset.load()
dataset = VideoDataset.load_or_create()
```

--------------------------------

### ls.connect()

Source: https://docs.lightly.ai/studio/enterprise/connect

Connect to a remote LightlyStudio enterprise instance. Exchanges the JWT token for the connection configuration via the enterprise API, applies any server-provided cloud storage credentials to the local environment, then sets up the global database connection using `db_manager.connect`. Parameters can be passed explicitly or read from environment variables `LIGHTLY_STUDIO_API_URL` and `LIGHTLY_STUDIO_TOKEN`. Explicit parameters take precedence.

```APIDOC
## ls.connect()

### Description
Connect to a remote LightlyStudio enterprise instance.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **api_url** (`str | None`) - Optional - Base URL of the LightlyStudio enterprise instance (e.g. `"http://10.0.0.5:8100"`). Falls back to the `LIGHTLY_STUDIO_API_URL` environment variable.
- **token** (`str | None`) - Optional - JWT token copied from the LightlyStudio enterprise GUI. Falls back to the `LIGHTLY_STUDIO_TOKEN` environment variable.

### Raises
- **ValueError**: If either `api_url` or `token` are not provided and the corresponding environment variables are not set.
- **ConnectionError**: If the enterprise instance is unreachable.
- **PermissionError**: If the token is invalid, expired, or lacks admin role.
- **RuntimeError**: If the server is not configured for remote connections.
```

--------------------------------

### Get Sample Type

Source: https://docs.lightly.ai/studio/api/dataset

Returns the SampleType enumeration for this dataset.

```python
sample_type() -> SampleType
```

--------------------------------

### Configure Environment with .env File

Source: https://docs.lightly.ai/studio/enterprise/connect

Use a `.env` file in your working directory to automatically configure connection credentials for LightlyStudio. Paste the API URL and token obtained from the GUI into this file.

```dotenv
LIGHTLY_STUDIO_API_URL="http://your-server:8100"
LIGHTLY_STUDIO_TOKEN="eyJhbGciOiJIUzI1NiIs..."

```

--------------------------------

### Get Dataset ID

Source: https://docs.lightly.ai/studio/api/dataset

Retrieve the unique identifier for the dataset.

```python
dataset_id: UUID
```

--------------------------------

### Get Sample Table Association

Source: https://docs.lightly.ai/studio/api/sample

Retrieves the `SampleTable` associated with this sample.

```python
sample_table: SampleTable
```

--------------------------------

### Creating and Loading Datasets

Source: https://docs.lightly.ai/studio/api

Demonstrates how to create a new dataset, add images from a local path, and load an existing dataset.

```APIDOC
## Creating and Loading Datasets

### Description
This section shows how to initialize and manage datasets using the `lightly_studio` Python library. You can create new datasets, add images from local directories, and load existing datasets from a database file.

### Usage
```python
import lightly_studio as ls

# Create a new dataset
dataset = ls.ImageDataset.create()

# Add images from a local folder
dataset.add_images_from_path(path="local-folder/some-local-data")

# Add more images later
dataset.add_images_from_path(path="local-folder/some-data-not-loaded-yet")

# Load an existing dataset (defaults to 'lightly_studio.db' in the working directory)
dataset = ls.ImageDataset.load()
```
```

--------------------------------

### Get Sample ID

Source: https://docs.lightly.ai/studio/api/sample

Retrieves the unique identifier (UUID) for the sample itself.

```python
sample_id: UUID
```

--------------------------------

### Selection Class Initialization

Source: https://docs.lightly.ai/studio/api/selection

Demonstrates how to create a Selection instance, either from the entire dataset or a filtered subset using DatasetQuery.match().

```APIDOC
## Selection Initialization

### Description
Instantiates a `Selection` object, which is used to select a subset of samples from a given set of input samples. It's recommended to create instances via the `DatasetQuery` class.

### Usage
```python
from lightly_studio.core.dataset_query import ImageSampleField

# Select from all samples in the dataset.
selection = dataset.query().selection()

# Select only from samples with width < 256.
query_narrow_images = dataset.query().match(ImageSampleField.width < 256)
selection_among_narrow_images = query_narrow_images.selection()
```

### Parameters
- `dataset_id` (UUID): Required. The dataset in which the selection is performed.
- `session` (Session): Required. Database session to resolve selection dependencies.
- `input_sample_ids` (Iterable[UUID]): Required. Candidate sample IDs considered for selection. The iterable is consumed immediately to capture a stable snapshot.
```

--------------------------------

### Loading Videos from Cloud Storage (S3)

Source: https://docs.lightly.ai/studio/api

Demonstrates how to load videos directly from an S3 bucket using the `lightly-studio[cloud-storage]` dependency.

```APIDOC
### Example: Loading videos from S3
```python
import lightly_studio as ls

# Create a video dataset and add videos from an S3 path
dataset = ls.VideoDataset.create(name="s3_video_dataset")
dataset.add_videos_from_path(path="s3://my-bucket/videos/")

ls.start_gui()
```
```

--------------------------------

### Get Sample Update Timestamp

Source: https://docs.lightly.ai/studio/api/sample

Accesses the timestamp of the latest update to the sample.

```python
updated_at = DBField(col(updated_at))
```

--------------------------------

### Sample Methods

Source: https://docs.lightly.ai/studio/api/sample

Methods available for Sample objects.

```APIDOC
## Sample Methods

### `add_annotation`

Add an annotation to this sample.

Parameters:
Name | Type | Description | Default
---|---|---|---
`annotation` | `CreateAnnotation` | The annotation to add. | _required_

### `add_annotations`

Add annotations to this sample.

Parameters:
Name | Type | Description | Default
---|---|---|---
`annotations` | `Iterable[CreateAnnotation]` | The annotations to add. | _required_

### `add_caption`

Add a caption to this sample.

Parameters:
Name | Type | Description | Default
---|---|---|---
`text` | `str` | The text of the caption to add. | _required_

### `add_captions`

Add captions to this sample.

Parameters:
Name | Type | Description | Default
---|---|---|---
`captions` | `Iterable[str]` | The texts of the captions to add. | _required_

### `add_tag`

Add a tag to this sample.
If the tag doesn't exist, it will be created first.

Parameters:
Name | Type | Description | Default
---|---|---|---
`name` | `str` | The name of the tag to add. | _required_

### `delete_annotation`

Delete an annotation from this sample.

Parameters:
Name | Type | Description | Default
---|---|---|---
`annotation` | `Annotation` | The annotation to delete. | _required_

### `get_object_session`

Get the database session for this sample.

Returns:
Type | Description
---|---
`Session` | The SQLModel session.

Raises:
Type | Description
---|---
`RuntimeError` | If no active session is found.

### `remove_tag`

Remove a tag from this sample.

Parameters:
Name | Type | Description | Default
---|---|---|---
`name` | `str` | The name of the tag to remove. | _required_
```

--------------------------------

### Get Sample Class Type

Source: https://docs.lightly.ai/studio/api/dataset

Returns the class type used for samples within this dataset.

```python
sample_class() -> type[ImageSample]
```

--------------------------------

### Create Dataset and Add Images

Source: https://docs.lightly.ai/studio/api

Initialize an ImageDataset and add images from a specified directory path.

```python
import lightly_studio as ls
from lightly_studio.core.annotation import CreateObjectDetection

dataset = ls.ImageDataset.create()
dataset.add_images_from_path(path="./path/to/image_folder")
```

--------------------------------

### Get Sample Collection ID

Source: https://docs.lightly.ai/studio/api/sample

Retrieves the unique identifier (UUID) of the collection to which the sample belongs.

```python
collection_id: UUID
```

--------------------------------

### Load or Create Dataset and Add Images

Source: https://docs.lightly.ai/studio/api

Load an existing dataset or create a new one, then add images from a specified path. This is a common pattern for managing datasets.

```python
import lightly_studio as ls

dataset = ls.ImageDataset.load_or_create(name="my_dataset")
dataset.add_images_from_path(path="path/to/images")


```

--------------------------------

### selection

Source: https://docs.lightly.ai/studio/api/dataset_query

Get the selection interface for the current query results. The selection snapshots the query results immediately.

```APIDOC
## selection

```python
selection() -> Selection
```

Selection interface for this query.
The returned Selection snapshots the current query results immediately. Mutating the query after calling this method will therefore not affect the samples used by that Selection instance.

### Returns

Type | Description
---|---
`Selection` | Selection interface operating on the current query result snapshot.
```

--------------------------------

### VideoDataset Creation and Loading

Source: https://docs.lightly.ai/studio/api/dataset

Demonstrates how to create or load a VideoDataset using static methods.

```APIDOC
## VideoDataset Creation and Loading

VideoDataset can be created or loaded using one of the static methods:

```python
dataset = VideoDataset.create()
dataset = VideoDataset.load()
dataset = VideoDataset.load_or_create()
```
```

--------------------------------

### Get Sample by ID

Source: https://docs.lightly.ai/studio/api/dataset

Retrieves a single sample from the dataset using its unique ID. Raises IndexError if no sample is found.

```python
get_sample(sample_id: UUID) -> VideoSample
```

--------------------------------

### Initialize Sample

Source: https://docs.lightly.ai/studio/api/sample

The Sample class is initialized with a SampleTable instance. It provides an interface to dataset samples, typically obtained from dataset queries.

```python
Sample(sample_table: SampleTable)
```

--------------------------------

### Querying with Field Conditions and Ordering

Source: https://docs.lightly.ai/studio/api/dataset_query

Demonstrates how to query samples by tag and order them by absolute file path. This is useful for specific data retrieval tasks.

```python
from lightly_studio.core.dataset_query import ImageSampleField, OrderByField

query = dataset.query()
query.match(ImageSampleField.tags.contains("cat"))
query.order_by(OrderByField(ImageSampleField.file_path_abs))
samples = query.to_list()
```

--------------------------------

### Get Classification Annotation Session

Source: https://docs.lightly.ai/studio/api/annotation

Retrieves the database session for a classification annotation. Raises RuntimeError if no active session is found.

```python
get_object_session() -> Session
```

--------------------------------

### Get Sample by ID

Source: https://docs.lightly.ai/studio/api/dataset

Retrieves a single sample from the dataset using its unique UUID. Raises IndexError if the sample ID is not found.

```python
get_sample(sample_id: UUID) -> ImageSample
```

--------------------------------

### Querying and Ordering Samples

Source: https://docs.lightly.ai/studio/api/dataset

Illustrates how to filter and order samples using the query interface.

```APIDOC
## Querying and Ordering Samples

For filtering or ordering samples first, use the query interface:

```python
from lightly_studio.core.dataset_query.video_sample_field import VideoSampleField

dataset = VideoDataset.load("my_dataset")
query = dataset.match(VideoSampleField.width > 10).order_by(VideoSampleField.file_name)
for sample in query:
    ...
```
```

--------------------------------

### Define a Custom Operator Plugin

Source: https://docs.lightly.ai/studio/concepts_and_tools/plugins

Define a custom operator by inheriting from BaseOperator and implementing its attributes and methods. This example shows a simple 'GreetingOperator'.

```python
from dataclasses import dataclass

from lightly_studio.plugins.base_operator import BaseOperator, OperatorResult
from lightly_studio.plugins.operator_context import OperatorScope
from lightly_studio.plugins.parameter import StringParameter


@dataclass
class GreetingOperator(BaseOperator):
    name: str = "GreetingOperator"
    description: str = "This operator greet you"

    @property
    def parameters(self):
        return [
            StringParameter(
                name="name",
                required=True,
                default="beautiful and smart person",
                description="your name"
            ),
        ]

    @property
    def supported_scopes(self) -> list[OperatorScope]:
        """Return the list of scopes this operator can be triggered from."""
        return [OperatorScope.ROOT]

    def execute(self, *, session, context, parameters):
        your_name = parameters.get("name", "")
        return OperatorResult(success=True, message=f"Hello {your_name}!")

```

--------------------------------

### Create or Load VideoDataset

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Demonstrates how to create a new video dataset or load an existing one using factory methods. The `load_or_create()` method is useful for ensuring a dataset exists before adding samples.

```APIDOC
## VideoDataset Factory Methods

### Description
These methods allow you to create a new video dataset, load an existing one, or create it if it doesn't exist.

### Methods
- `VideoDataset.create()`: Creates a new, empty video dataset.
- `VideoDataset.load()`: Loads an existing video dataset.
- `VideoDataset.load_or_create()`: Creates a new dataset if it doesn't exist, otherwise loads the existing one.

All these methods accept an optional `name` argument to manage multiple datasets.

### Usage Examples
```python
# Create a new dataset
dataset = ls.VideoDataset.create()

# Load an existing dataset
dataset = ls.VideoDataset.load()

# Load or create a dataset
dataset = ls.VideoDataset.load_or_create()
```
```

--------------------------------

### Stop Background GUI Server

Source: https://docs.lightly.ai/studio/advanced/notebooks

Stops the Lightly Studio GUI server that was started in the background. This should be called when the GUI is no longer needed to free up resources.

```python
ls.stop_gui_background()

```

--------------------------------

### ImageDataset Creation and Loading

Source: https://docs.lightly.ai/studio/api/dataset

Demonstrates how to create, load, or load-or-create an ImageDataset.

```APIDOC
## ImageDataset Creation and Loading

Image datasets can be created or loaded using the following static methods:

```python
dataset = ImageDataset.create()
dataset = ImageDataset.load()
dataset = ImageDataset.load_or_create()
```
```

--------------------------------

### Create and Add Images to Dataset

Source: https://docs.lightly.ai/studio/api

Use `ImageDataset.create()` to initialize a new dataset and `add_images_from_path()` to add images from local or cloud storage. Multiple calls can add data incrementally.

```python
import lightly_studio as ls

# Different loading options:
dataset = ls.ImageDataset.create()

# You can load data directly from a folder
dataset.add_images_from_path(path="local-folder/some-local-data")

# Or you can load more data at a later point (even across sources such as cloud)
dataset.add_images_from_path(path="local-folder/some-data-not-loaded-yet")
dataset.add_images_from_path(path="gcs://my-bucket-2/path/to/more-images/")

# You can also load a dataset from an .db file (default uses the `lightly_studio.db` file in the working directory)
dataset = ls.ImageDataset.load()

```

--------------------------------

### Add Images from Path Configuration

Source: https://docs.lightly.ai/studio/api/dataset

Configure adding images from a path, specifying allowed extensions, whether to embed images, and the depth for tag generation based on directory structure.

```python
add_images_from_path(
    path: PathLike,
    allowed_extensions: Iterable[str] | None = None,
    embed: bool = True,
    tag_depth: int = 0,
) -> None
```

--------------------------------

### Create or Load ImageDataset

Source: https://docs.lightly.ai/studio/api/dataset

Static methods to create, load, or load-or-create an ImageDataset. These are the entry points for initializing a dataset.

```python
dataset = ImageDataset.create()
dataset = ImageDataset.load()
dataset = ImageDataset.load_or_create()
```

--------------------------------

### Set Lightly Studio License Key

Source: https://docs.lightly.ai/studio/api

Sets the environment variable for the Lightly Studio license key, required for premium selection features. Use the appropriate command for your operating system.

```bash
export LIGHTLY_STUDIO_LICENSE_KEY="license_key_here"
```

```powershell
$env:LIGHTLY_STUDIO_LICENSE_KEY="license_key_here"
```

--------------------------------

### Load Videos from S3

Source: https://docs.lightly.ai/studio/api

Create a video dataset and load videos directly from an S3 bucket using `add_videos_from_path()` with an S3 URI.

```python
import lightly_studio as ls

dataset = ls.VideoDataset.create(name="s3_video_dataset")
dataset.add_videos_from_path(path="s3://my-bucket/videos/")

ls.start_gui()


```

--------------------------------

### Order Samples with order_by()

Source: https://docs.lightly.ai/studio/api/dataset_query

Order query results using order_by(). Provide multiple fields for tie-breaking. Use .desc() for descending order. Import OrderByField and relevant SampleField.

```python
from lightly_studio.core.dataset_query import OrderByField, ImageSampleField
query = query.order_by(
    OrderByField(ImageSampleField.width),
    OrderByField(ImageSampleField.file_name).desc()
)
```

--------------------------------

### Load Videos from YouTube-VIS Annotations (Instance Segmentation)

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Load videos and instance segmentation annotations from the YouTube-VIS format. Requires paths to the annotations JSON and video files. Embeddings are enabled by default.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.VideoDataset.create()
dataset.add_videos_from_youtube_vis(
    annotations_json=f"{dataset_path}/youtube_vis_50_videos/train/instances_50.json",
    videos_path=f"{dataset_path}/youtube_vis_50_videos/train/videos",
    annotation_type=ls.AnnotationType.INSTANCE_SEGMENTATION,
)


```

--------------------------------

### Export Image Dataset Annotations in Python

Source: https://docs.lightly.ai/studio/concepts_and_tools/export

Export image dataset annotations to COCO object detection, COCO instance segmentation, COCO captions, and Pascal VOC instance segmentation formats using the Python API. Ensure the 'lightly_studio' library is installed.

```python
import lightly_studio as ls

# Image dataset export
dataset = ls.ImageDataset.load()
dataset.export().to_coco_object_detections("detections.json")
dataset.export().to_coco_instance_segmentations("segmentations.json")
dataset.export().to_coco_captions("captions.json")
dataset.export().to_pascalvoc_instance_segmentation("pascalvoc_output_dir/")
```

--------------------------------

### Create Selection Instance

Source: https://docs.lightly.ai/studio/api/selection

Instantiate a Selection object. It's easiest to do this via the DatasetQuery class, optionally filtering samples first using match().

```python
from lightly_studio.core.dataset_query import ImageSampleField

# Select from all samples in the dataset.
selection = dataset.query().selection()

# Select only from samples with width < 256.
query_narrow_images = dataset.query().match(ImageSampleField.width < 256)
selection_among_narrow_images = query_narrow_images.selection()
```

--------------------------------

### Object Detection Auto-Labeling Plugin with LightlyTrain

Source: https://docs.lightly.ai/studio/concepts_and_tools/plugins

This Python code defines a custom operator plugin for Lightly Studio that uses LightlyTrain models for object detection auto-labeling. It requires `lightly-train` to be installed. The plugin accepts a model name and a confidence threshold as parameters to control the auto-labeling process.

```python
from dataclasses import dataclass

import lightly_train
from PIL import Image
from lightly_train._commands.predict_task_helpers import prepare_coco_entries as prepare_entries

from lightly_studio.models.annotation.annotation_base import AnnotationCreate, AnnotationType
from lightly_studio.models.annotation_label import AnnotationLabelCreate
from lightly_studio.plugins.base_operator import BaseOperator, OperatorResult
from lightly_studio.plugins.operator_context import OperatorScope
from lightly_studio.plugins.parameter import FloatParameter, StringParameter
from lightly_studio.resolvers.image_filter import ImageFilter
from lightly_studio.resolvers import annotation_label_resolver, annotation_resolver, image_resolver
from lightly_studio.resolvers.sample_resolver.sample_filter import SampleFilter


def _preload_label_map(session, dataset_id, class_names):
    """Pre-creates all necessary labels in the DB and returns a lookup map.

    Args:
        session: Database session.
        class_names: List of class names the model supports (e.g. ['car', 'person']).

    Returns:
        A dictionary mapping label names to their DB UUIDs.
    """
    label_map = {}

    for name in class_names:
        # Check if label exists in db
        label = annotation_label_resolver.get_by_label_name(session=session, dataset_id=dataset_id, label_name=name)

        # Create if missing
        if label is None:
            label_create = AnnotationLabelCreate(dataset_id=dataset_id, annotation_label_name=name)
            label = annotation_label_resolver.create(session=session, label=label_create)

        label_map[name] = label.annotation_label_id

    return label_map

@dataclass
class LightlyTrainAutoLabelingODOperator(BaseOperator):
    name: str = "LightlyTrain: OD auto-labeling"
    description: str = "This plugin allows to use pre-trained LightlyTrain models to perform auto-labeling for Object Detection."

    @property
    def parameters(self):
        return [
            StringParameter(
                name="Model",
                required=True,
                description="The name of the pre-trained model to be used.",
                default="dinov3/convnext-tiny-ltdetr-coco"
            ),
            FloatParameter(
                name="Threshold",
                default=0.4,
                description="The confidence threshold to be applied to the predictions."
            ),
        ]

    @property
    def supported_scopes(self) -> list[OperatorScope]:
        """Return the list of scopes this operator can be triggered from."""
        return [OperatorScope.IMAGE]

    def execute(self, *, session, context, parameters):
        try:
            model = lightly_train.load_model(parameters["Model"])
        except ValueError as e:
            return OperatorResult(success=False, message=f"Model load failed: {str(e)}")

        if (parameters["Threshold"] > 1.0) or (parameters["Threshold"] < 0.0):
            return OperatorResult(success=False, message="Threshold must be in range 0.0 to 1.0")

        raw_classes = getattr(model, "classes", {})
        label_map = _preload_label_map(session, context.collection_id, list(raw_classes.values()))

        # Getting all samples for the provided context
        context_filter = None
        if context.context_filter:
            if isinstance(context.context_filter, SampleFilter):
                context_filter = ImageFilter(sample_filter=context.context_filter)
            elif isinstance(context.context_filter, ImageFilter):
                context_filter = context.context_filter

        samples = image_resolver.get_all_by_collection_id(
            session=session,
            collection_id=context.collection_id,
            filters=context_filter
        )

        # Running inference
        annotations_buffer = []
        for sample in samples.samples:
            image = Image.open(sample.file_path_abs).convert("RGB")

            preds = model.predict(image, threshold=parameters["Threshold"])
            entries = prepare_entries(predictions=preds, image_size=(sample.width, sample.height))

            for entry in entries:
                annotations_buffer.append(
                    AnnotationCreate(
                        parent_sample_id=sample.sample_id,
                        annotation_label_id=label_map[raw_classes[entry["category_id"]]],
                        annotation_type=AnnotationType.OBJECT_DETECTION,

```

--------------------------------

### Load and Query VideoDataset

Source: https://docs.lightly.ai/studio/api/dataset

Shows how to load an existing dataset and access its samples. Samples can be iterated over or sliced directly. Metadata can be modified during iteration.

```python
dataset = VideoDataset.load("my_dataset")
first_ten_samples = dataset[:10]
for sample in dataset:
    print(sample.file_name)
    sample.metadata["new_key"] = "new_value"
```

--------------------------------

### Create or Load ImageDataset

Source: https://docs.lightly.ai/studio/dataset_setup/image_dataset

Instantiates an ImageDataset object. Use `create()` for a new dataset, `load()` to load an existing one, or `load_or_create()` to attempt loading and create if it doesn't exist.

```python
dataset = ls.ImageDataset.create()

```

```python
dataset = ls.ImageDataset.load()

```

```python
dataset = ls.ImageDataset.load_or_create()

```

--------------------------------

### Load Videos from Folder using Python

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Use `add_videos_from_path` to load videos from a specified folder. Supports recursive searching and remote paths. Embeddings are enabled by default.

```python
import lightly_studio as ls

# We download an example dataset for this guide.
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

# Create an empty dataset and add videos from a folder.
dataset = ls.VideoDataset.create()
dataset.add_videos_from_path(path=f"{dataset_path}/youtube_vis_50_videos/train/videos")

```

--------------------------------

### Access Image Sample Properties

Source: https://docs.lightly.ai/studio/dataset_setup/image_dataset

Demonstrates how to access various properties of an ImageSample object, including file name, absolute path, dimensions, tags, captions, metadata, and annotations.

```python
# Grab one sample
image = next(iter(dataset))

# Image properties
print(image.file_name)
print(image.file_path_abs)
print(image.width)
print(image.height)

# Tags
image.tags = ["tag1", "tag2"]
image.add_tag("needs_review")
image.remove_tag("needs_review")
print(image.tags)

# Captions
image.captions = ["Caption 1", "Caption 2"]
image.add_caption("Caption 3")
print(image.captions)

# Metadata
image.metadata["my_key"] = "my_value"
print(image.metadata["my_key"])

# Annotations
from lightly_studio.core.annotation import CreateObjectDetection
image.add_annotation(
    CreateObjectDetection(
        label="dog",
        x=10,
        y=20,
        width=30,
        height=40,
        confidence=0.9,
    )
)
for annotation in image.annotations:
    print(annotation.label)

```

--------------------------------

### Tag Samples Matching a Query

Source: https://docs.lightly.ai/studio/concepts_and_tools/tags

Applies a specified tag to all samples that satisfy a given query. The tag is created if it doesn't exist, and existing tags on samples are unaffected. Requires importing `lightly_studio` and `VideoSampleField`.

```python
import lightly_studio as ls
from lightly_studio.core.dataset_query import VideoSampleField

# The example query assumes `dataset` is a VideoDataset object
dataset = ls.VideoDataset.load()

# Tag all large videos
dataset.match(VideoSampleField.width > 1920).add_tag("high-res")


```

--------------------------------

### Sample Properties

Source: https://docs.lightly.ai/studio/api/sample

Access properties of a Sample object.

```APIDOC
## Sample Properties

### `sample_table` property

Returns the SampleTable associated with this Sample.

### `tags` property

Get the tag names associated with this sample.

Returns:
Type | Description
---|---
`set[str]` | A set of tag names as strings.
```

--------------------------------

### create

Source: https://docs.lightly.ai/studio/api/dataset

Creates a new dataset. Optionally, a name can be provided; otherwise, a default name is used.

```APIDOC
## create

### Description
Create a new dataset.

### Parameters
- **name** (str | None) - Optional - The name of the dataset. If None, a default name is used. Default: None
```

--------------------------------

### add_videos_from_youtube_vis

Source: https://docs.lightly.ai/studio/api/dataset

Load videos and YouTube-VIS annotations and store them in the database.

```APIDOC
## add_videos_from_youtube_vis

```python
add_videos_from_youtube_vis(
    annotations_json: PathLike,
    videos_path: PathLike,
    allowed_extensions: Iterable[str] | None = None,
    annotation_type: AnnotationType = OBJECT_DETECTION,
    embed: bool = True,
) -> None
```

### Parameters

- **annotations_json** (`PathLike`) - _required_ - Path to the YouTube-VIS annotations JSON file.
- **videos_path** (`PathLike`) - _required_ - Path to the folder containing the videos.
- **allowed_extensions** (`Iterable[str] | None`) - Optional - An iterable container of allowed video file extensions in lowercase, including the leading dot. If None, uses default VIDEO_EXTENSIONS. Note: This is used when a path in YouTube-VIS does not contain the file extension.
- **annotation_type** (`AnnotationType`) - Optional - The type of annotation to be loaded (e.g., 'ObjectDetection', 'InstanceSegmentation'). Default is OBJECT_DETECTION.
- **embed** (`bool`) - Optional - If True, generate embeddings for the newly added videos. Default is True.
```

--------------------------------

### Connect with Explicit Parameters

Source: https://docs.lightly.ai/studio/enterprise/connect

Pass the API URL and token directly as parameters to the `ls.connect()` function. Explicit parameters take precedence over environment variables.

```python
import lightly_studio as ls

ls.connect(
    api_url="http://your-server:8100",
    token="eyJhbGciOiJIUzI1NiIs...",
)

```

--------------------------------

### Configure Environment with Shell Export

Source: https://docs.lightly.ai/studio/enterprise/connect

Set connection credentials as environment variables in your shell using `export` commands. This method is an alternative to using a `.env` file.

```bash
export LIGHTLY_STUDIO_API_URL="http://your-server:8100"
export LIGHTLY_STUDIO_TOKEN="eyJhbGciOiJIUzI1NiIs..."

```

--------------------------------

### Iterate Over Dataset Samples

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Shows how to iterate through the samples (videos) within a loaded `VideoDataset` object. Each iteration yields a `VideoSample` object.

```APIDOC
## Iterate Over Dataset Samples

### Description
Once samples are added to the dataset, you can iterate over the dataset object to access individual `VideoSample` objects.

### Usage Example
```python
# Assuming 'dataset' is a loaded or created VideoDataset object
for video in dataset:
    print(video.file_name)
```
```

--------------------------------

### Accessing and Iterating Over Samples

Source: https://docs.lightly.ai/studio/api/dataset

Shows how to access samples by iterating over the dataset or using slicing.

```APIDOC
## Accessing and Iterating Over Samples

Samples can be queried directly by iterating over the dataset or slicing it:

```python
dataset = VideoDataset.load("my_dataset")
first_ten_samples = dataset[:10]
for sample in dataset:
    print(sample.file_name)
    sample.metadata["new_key"] = "new_value"
```
```

--------------------------------

### query

Source: https://docs.lightly.ai/studio/api/dataset

Initializes a DatasetQuery for the dataset, allowing for sample querying.

```APIDOC
## query

### Description
Create a DatasetQuery for this dataset.

### Method
`query`

### Response
#### Success Response
- **DatasetQuery[T]** - A DatasetQuery instance for querying samples in this dataset.
```

--------------------------------

### ImageDataset Class

Source: https://docs.lightly.ai/studio/dataset_setup/image_dataset

Demonstrates how to create or load an ImageDataset instance using factory methods.

```APIDOC
## ImageDataset Class

### Description

The `ImageDataset` class is the primary entry point for working with image datasets. You can create a new dataset or load an existing one using the provided factory methods.

### Methods

- `create()`: Creates a new, empty ImageDataset.
- `load()`: Loads an existing ImageDataset from storage.
- `load_or_create()`: Loads an existing ImageDataset or creates a new one if it doesn't exist.

### Usage

```python
import lightly_studio as ls

# Create a new ImageDataset
dataset = ls.ImageDataset.create()

# Load an existing ImageDataset
dataset = ls.ImageDataset.load()

# Load or create an ImageDataset
dataset = ls.ImageDataset.load_or_create()
```

### Iterating Over Samples

Once samples are added to the dataset, you can iterate over them to access individual `ImageSample` objects.

```python
for image in dataset:
    print(image.file_name)
```
```

--------------------------------

### Add Samples from COCO Configuration

Source: https://docs.lightly.ai/studio/api/dataset

Configure adding samples from COCO format, including paths to annotations and images, annotation type, optional split, and embedding option.

```python
add_samples_from_coco(
    annotations_json: PathLike,
    images_path: PathLike,
    annotation_type: AnnotationType = OBJECT_DETECTION,
    split: str | None = None,
    embed: bool = True,
) -> None
```

--------------------------------

### Load Pre-Existing Video Dataset from Database

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Load a previously created and indexed dataset directly from the database to skip re-indexing and embedding.

```python
import lightly_studio as ls

# Load an existing dataset from the database.
dataset = ls.VideoDataset.load()

```

--------------------------------

### Create or Load VideoDataset

Source: https://docs.lightly.ai/studio/dataset_setup/video_dataset

Use these factory methods to create a new VideoDataset or load an existing one. The `load_or_create()` method is convenient for ensuring a dataset exists before use.

```python
dataset = ls.VideoDataset.create()
```

```python
dataset = ls.VideoDataset.load()
```

```python
dataset = ls.VideoDataset.load_or_create()
```

--------------------------------

### Execute Query by Iteration or to_list()

Source: https://docs.lightly.ai/studio/api/dataset_query

Execute the query by iterating over the query object or by calling to_list(). Samples are returned as writable Sample instances.

```python
for sample in query:
    print(sample.file_name)
samples = query.to_list()
```

--------------------------------

### Display Lightly Studio GUI in IFrame (Colab)

Source: https://docs.lightly.ai/studio/advanced/notebooks

Embeds the Lightly Studio GUI into a Colab notebook using `output.serve_kernel_port_as_iframe`. This method uses the server port to display the GUI within the notebook.

```python
from google.colab import output

output.serve_kernel_port_as_iframe(server.port, width=1000, height=800)

```

--------------------------------

### Add Videos from YouTube-VIS Annotations

Source: https://docs.lightly.ai/studio/api/dataset

Loads videos and YouTube-VIS annotations from specified paths. Supports different annotation types and controls embedding generation.

```python
dataset.add_videos_from_youtube_vis(
    annotations_json: PathLike,
    videos_path: PathLike,
    allowed_extensions: Iterable[str] | None = None,
    annotation_type: AnnotationType = OBJECT_DETECTION,
    embed: bool = True,
)
```

--------------------------------

### Add Caption to Sample

Source: https://docs.lightly.ai/studio/api/sample

Adds a single caption string to a sample.

```python
add_caption(text: str) -> None
```

--------------------------------

### ImageSample Constructor

Source: https://docs.lightly.ai/studio/api/sample

Initializes an ImageSample object. Requires an `ImageTable` SQLAlchemy model instance.

```python
ImageSample(inner: ImageTable)
```

--------------------------------

### Initialize VideoDatasetExport

Source: https://docs.lightly.ai/studio/api/dataset

Provides methods to export a video dataset or a subset of it.

```python
VideoDatasetExport(session: Session, samples: Iterable[VideoSample])
```

--------------------------------

### Export selected samples to a file

Source: https://docs.lightly.ai/studio/api

This script demonstrates how to retrieve and export the file paths of selected samples to a text file.

```APIDOC
## Exporting Selected Samples

### Description
Retrieves selected samples based on tags and writes their absolute file paths to a specified text file.

### Method
`dataset.match(ImageSampleField.tags.contains(tag_name)).to_list()` followed by writing to a file.

### Parameters
- **dataset** (ImageDataset) - The dataset object from which to retrieve samples.
- **tag_name** (str) - The tag used to filter the samples.
- **output_file_path** (str) - The path to the text file where the sample paths will be written.

### Request Example
```python
import lightly_studio as ls
from lightly_studio.core.dataset_query import ImageSampleField

dataset = ls.ImageDataset.load("my-dataset")
selected_samples = (
    dataset.match(ImageSampleField.tags.contains("diverse_selection")).to_list()
)

with open("export.txt", "w") as f:
    for sample in selected_samples:
        f.write(f"{sample.file_path_abs}\n")
```
```

--------------------------------

### Create New Dataset

Source: https://docs.lightly.ai/studio/api/dataset

Creates a new dataset. Optionally provide a name; otherwise, a default name is used.

```python
create(name: str | None = None) -> Self
```

--------------------------------

### Configuring Database Connection

Source: https://docs.lightly.ai/studio/api

Explains how to configure the database manager to store the dataset's DuckDB file in a custom location.

```APIDOC
## Configuring Database Connection

### Description
Configure the database manager to specify a custom path for the DuckDB file, which stores metadata, tags, annotations, and embeddings.

### Usage
```python
from lightly_studio import db_manager

db_manager.connect(db_file="~/lightly_data/my-db-path.db")
```
```

--------------------------------

### add_samples_from_lightly

Source: https://docs.lightly.ai/studio/api/dataset

Loads a dataset in Lightly format and stores it in the database. Optionally generates embeddings for the newly added samples.

```APIDOC
## add_samples_from_lightly

### Description
Load a dataset in Lightly format and store in DB.

### Parameters
#### Path Parameters
- **input_folder** (PathLike) - Required - Path to the folder containing the annotations/predictions.

#### Query Parameters
- **images_rel_path** (str) - Optional - Relative path to images folder from label folder.
- **split** (str | None) - Optional - Optional split name to tag samples (e.g., 'train', 'val'). If provided, all samples will be tagged with this name.
- **embed** (bool) - Optional - If True, generate embeddings for the newly added samples.

### Returns
None
```

--------------------------------

### Add Samples from Label Format

Source: https://docs.lightly.ai/studio/api/dataset

Add samples to the dataset using a generic label format. This method is flexible for various custom labeling schemes.

```python
dataset.add_samples_from_labelformat(...)
```
Tokens:
Raw