lightly-studio 0.4.6__py3-none-any.whl

lightly_studio/examples/example_operators.py

@@ -0,0 +1,111 @@
+"""Example of how to register operators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from uuid import UUID
+
+from environs import Env
+from sqlmodel import Session
+
+import lightly_studio as ls
+from lightly_studio import db_manager
+from lightly_studio.plugins.base_operator import BaseOperator, OperatorResult
+from lightly_studio.plugins.operator_registry import operator_registry
+from lightly_studio.plugins.parameter import (
+    BaseParameter,
+    BoolParameter,
+    FloatParameter,
+    IntParameter,
+    StringParameter,
+)
+
+
+@dataclass
+class TestOperator(BaseOperator):
+    """Dummy Operator for demo purpose."""
+
+    name: str = "test operator"
+    description: str = "used to test the operator and registry system"
+
+    @property
+    def parameters(self) -> list[BaseParameter]:
+        """Return the list of parameters this operator expects."""
+        return [
+            BoolParameter(name="test flag", required=True),
+            StringParameter(name="test str", required=True, default="Good Morning"),
+            StringParameter(
+                name="test str 2", required=True, default="Another", description="Test Description"
+            ),
+            BoolParameter(
+                name="test flag 2", required=True, description="Test Description", default=True
+            ),
+            FloatParameter(name="test float", required=False, default=2.0, description="abc"),
+            IntParameter(name="test int", required=False, default=2),
+            IntParameter(name="test int 2", required=True, description="Yet another int"),
+            IntParameter(
+                name="test int 3",
+                required=True,
+                description=(
+                    "Yet another int with a very long description. this will show how we will "
+                    "overflow or what soever is happening to this text in the GUI. maybe it "
+                    "exceeds maybe not. only time will tell"
+                ),
+            ),
+        ]
+
+    def execute(
+        self,
+        *,
+        session: Session,
+        dataset_id: UUID,
+        parameters: dict[str, Any],
+    ) -> OperatorResult:
+        """Execute the operator with the given parameters.
+
+        Args:
+            session: Database session.
+            dataset_id: ID of the dataset to operate on.
+            parameters: Parameters passed to the operator.
+
+        Returns:
+            Dictionary with 'success' (bool) and 'message' (str) keys.
+        """
+        return OperatorResult(
+            success=bool(parameters.get("test flag")),
+            message=str(parameters.get("test str"))
+            + " "
+            + str(parameters.get("test str 2"))
+            + " "
+            + str(parameters.get("test flag 2"))
+            + " "
+            + str(parameters.get("test float"))
+            + " "
+            + str(parameters.get("test int"))
+            + " "
+            + str(dataset_id)
+            + str(session),
+        )
+
+
+# Read environment variables
+env = Env()
+env.read_env()
+
+# Cleanup an existing database
+db_manager.connect(cleanup_existing=True)
+
+# Setup dummy operators
+test = TestOperator()
+for i in range(20):
+    operator_registry.register(operator=TestOperator(name=f"test_{i}"))
+
+# Define data path
+dataset_path = env.path("EXAMPLES_DATASET_PATH", "/path/to/your/dataset")
+
+# Create a DatasetLoader from a path
+dataset = ls.Dataset.create()
+dataset.add_images_from_path(path=dataset_path)
+
+ls.start_gui()

lightly_studio/examples/example_selection.py

@@ -0,0 +1,28 @@
+"""Example of how to run selection class."""
+
+from environs import Env
+
+import lightly_studio as ls
+from lightly_studio import db_manager
+
+# Read environment variables
+env = Env()
+env.read_env()
+
+# Cleanup an existing database
+db_manager.connect(cleanup_existing=True)
+
+# Define the path to the dataset directory
+dataset_path = env.path("EXAMPLES_DATASET_PATH", "/path/to/your/dataset")
+
+# Create a Dataset from a path
+dataset = ls.Dataset.create()
+dataset.add_images_from_path(path=str(dataset_path))
+
+# Run selection via the dataset query
+dataset.query().selection().diverse(
+    n_samples_to_select=10,
+    selection_result_tag_name="diverse_selection",
+)
+
+ls.start_gui()

lightly_studio/examples/example_split_work.py

@@ -0,0 +1,48 @@
+"""Example of how to add tags to samples to set up a split review workflow."""
+
+import math
+
+from environs import Env
+
+import lightly_studio as ls
+from lightly_studio import db_manager
+
+# Read environment variables
+env = Env()
+env.read_env()
+
+# Cleanup an existing database
+db_manager.connect(cleanup_existing=True)
+
+# Create a Dataset instance
+dataset = ls.Dataset.create()
+
+# Define the path to the dataset (folder containing data.yaml)
+dataset_path = env.path("EXAMPLES_YOLO_YAML_PATH", "/path/to/your/yolo/dataset/data.yaml")
+input_split = env.str("EXAMPLES_YOLO_SPLIT", "test")
+
+# Load YOLO dataset using data.yaml path
+dataset.add_samples_from_yolo(
+    data_yaml=dataset_path,
+    input_split=input_split,
+)
+
+# Define the reviewers
+# This should be a comma-separated list of reviewers
+# we will then create a tag for each reviewer and assign them samples
+# to work on.
+reviewers = env.str("DATASET_REVIEWERS", "Alice, Bob, Charlie, David")
+
+# Create a tag for each reviewer to work on
+tags = [reviewer.strip() for reviewer in reviewers.split(",")]
+
+# Get all samples from the db
+samples = dataset.query().to_list()
+
+# Chunk the samples into portions equally divided among the reviewers.
+chunk_size = math.ceil(len(samples) / len(tags))
+for i, sample in enumerate(samples):
+    sample.add_tag(tags[i // chunk_size])
+
+# Launch the server to load data
+ls.start_gui()

lightly_studio/examples/example_video.py

@@ -0,0 +1,22 @@
+"""Example of how to load videos from path with the dataset class."""
+
+from environs import Env
+
+import lightly_studio as ls
+from lightly_studio import db_manager
+
+# Read environment variables
+env = Env()
+env.read_env()
+
+# Cleanup an existing database
+db_manager.connect(cleanup_existing=True)
+
+# Define the path to the dataset directory
+dataset_path = env.path("EXAMPLES_VIDEO_DATASET_PATH", "/path/to/your/dataset")
+
+# Create a Dataset from a path
+dataset = ls.Dataset.create(sample_type=ls.SampleType.VIDEO)
+dataset.add_videos_from_path(path=dataset_path)
+
+ls.start_gui()

lightly_studio/examples/example_video_annotations.py

@@ -0,0 +1,157 @@
+"""Example of how to load videos with annotations in YouTube-VIS format."""
+# ruff: noqa: D102, D107
+
+from __future__ import annotations
+
+import json
+from argparse import ArgumentParser
+from pathlib import Path
+from typing import Iterable
+from uuid import UUID
+
+import tqdm
+from environs import Env
+from labelformat.model.bounding_box import BoundingBox, BoundingBoxFormat
+from labelformat.model.category import Category
+from labelformat.model.image import Image
+from labelformat.model.object_detection import (
+    ImageObjectDetection,
+    ObjectDetectionInput,
+    SingleObjectDetection,
+)
+from sqlmodel import Session
+
+import lightly_studio as ls
+from lightly_studio import db_manager
+from lightly_studio.core import add_samples
+from lightly_studio.resolvers import video_resolver
+
+
+class YouTubeVISObjectDetectionInput(ObjectDetectionInput):
+    """Loads object detections from a modified YouTube-VIS format.
+
+    The annotation json format is without modification, but the images are loaded as videos.
+
+    This is a temporary hack until YouTubeVIS is supported natively in labelformat. The code
+    is adapted from labelformat's COCOObjectDetectionInput.
+    """
+
+    @staticmethod
+    def add_cli_arguments(parser: ArgumentParser) -> None:
+        raise NotImplementedError()
+
+    def __init__(self, input_file: Path) -> None:
+        with input_file.open() as file:
+            self._data = json.load(file)
+
+    def get_categories(self) -> Iterable[Category]:
+        for category in self._data["categories"]:
+            yield Category(
+                id=category["id"],
+                name=category["name"],
+            )
+
+    def get_images(self) -> Iterable[Image]:
+        for video in self._data["videos"]:
+            yield Image(
+                id=video["id"],
+                # The video name is <video_folder>.mp4
+                filename=Path(video["file_names"][0]).parent.name + ".mp4",
+                width=int(video["width"]),
+                height=int(video["height"]),
+            )
+
+    def get_labels(self) -> Iterable[ImageObjectDetection]:
+        video_id_to_video = {video.id: video for video in self.get_images()}
+        category_id_to_category = {category.id: category for category in self.get_categories()}
+
+        for annotation_json in self._data["annotations"]:
+            # Only extract bounding boxes, not segmentations. Every element in "bboxes"
+            # corresponds to one frame in the video.
+            frame_detections: list[SingleObjectDetection] = [
+                SingleObjectDetection(
+                    category=category_id_to_category[annotation_json["category_id"]],
+                    box=BoundingBox.from_format(bbox=bbox, format=BoundingBoxFormat.XYWH),
+                )
+                if bbox is not None
+                else SingleObjectDetection(
+                    category=Category(-1, "no segmentation"),
+                    box=BoundingBox.from_format(bbox=[0, 0, 0, 0], format=BoundingBoxFormat.XYWH),
+                )
+                for bbox in annotation_json["bboxes"]
+            ]
+            yield ImageObjectDetection(
+                image=video_id_to_video[annotation_json["video_id"]],
+                objects=frame_detections,
+            )
+
+
+def load_annotations(session: Session, dataset_id: UUID, annotations_path: Path) -> None:
+    """Loads video annotations from a YouTube-VIS format.
+
+    Temporarily use internal add_samples API until labelformat supports videos natively.
+    """
+    print("Loading video annotations...")
+    videos = video_resolver.get_all_by_dataset_id_with_frames(
+        session=session, dataset_id=dataset_id
+    )
+    video_name_to_video = {video.file_name: video for video in videos}
+    yvis_input = YouTubeVISObjectDetectionInput(input_file=annotations_path)
+    label_map = add_samples._create_label_map(  # noqa: SLF001
+        session=session,
+        input_labels=yvis_input,
+    )
+    for label in tqdm.tqdm(yvis_input.get_labels(), desc="Adding annotations", unit=" objects"):
+        video = video_name_to_video[label.image.filename]
+        assert len(label.objects) == len(video.frames), (
+            f"Number of frames in annotation ({len(label.objects)}) does not match "
+            f"number of frames in video ({len(video.frames)}) for video {label.image.filename}"
+        )
+        # Use frame index as path to match frames with annotations
+        path_to_id = {str(idx): frame.sample_id for idx, frame in enumerate(video.frames)}
+        path_to_anno_data = {
+            str(idx): ImageObjectDetection(
+                image=label.image,
+                objects=[obj],
+            )
+            if obj.category.id != -1
+            else ImageObjectDetection(
+                image=label.image,
+                objects=[],
+            )
+            for idx, obj in enumerate(label.objects)
+        }
+        add_samples._process_batch_annotations(  # noqa: SLF001
+            session=session,
+            created_path_to_id=path_to_id,
+            path_to_anno_data=path_to_anno_data,
+            dataset_id=dataset_id,
+            label_map=label_map,
+        )
+
+
+if __name__ == "__main__":
+    # Read environment variables
+    env = Env()
+    env.read_env()
+
+    # Cleanup an existing database
+    db_manager.connect(cleanup_existing=True)
+
+    # Define the path to the dataset directory
+    dataset_path = env.path("EXAMPLES_VIDEO_DATASET_PATH", "/path/to/your/dataset")
+    annotations_path = env.path(
+        "EXAMPLES_VIDEO_YVIS_JSON_PATH", "/path/to/your/dataset/instances.json"
+    )
+
+    # Create a Dataset from a path
+    dataset = ls.Dataset.create(sample_type=ls.SampleType.VIDEO)
+    dataset.add_videos_from_path(path=dataset_path)
+
+    # Load annotations
+    load_annotations(
+        session=dataset.session, dataset_id=dataset.dataset_id, annotations_path=annotations_path
+    )
+
+    # Start the GUI
+    ls.start_gui()

lightly_studio/examples/example_yolo.py

@@ -0,0 +1,22 @@
+"""Example of how to add samples in yolo format to a dataset."""
+
+from environs import Env
+
+import lightly_studio as ls
+from lightly_studio import db_manager
+
+# Read environment variables
+env = Env()
+env.read_env()
+
+# Cleanup an existing database
+db_manager.connect(cleanup_existing=True)
+
+# Define the path to the dataset directory
+dataset_path = env.path("EXAMPLES_YOLO_YAML_PATH", "/path/to/your/dataset/data.yaml")
+input_split = env.str("EXAMPLES_YOLO_SPLIT", "train")
+
+# Create a DatasetLoader from a path
+dataset = ls.Dataset.create()
+dataset.add_samples_from_yolo(data_yaml=dataset_path, input_split=input_split)
+ls.start_gui()

lightly_studio/export/coco_captions.py

@@ -0,0 +1,69 @@
+"""Helper module for exporting datasets in COCO captions format."""
+
+from __future__ import annotations
+
+from typing import Iterable, TypedDict
+
+from lightly_studio.core.image_sample import ImageSample
+
+
+class CocoCaptionImage(TypedDict):
+    """Image schema for COCO captions format."""
+
+    id: int
+    file_name: str
+    width: int
+    height: int
+
+
+class CocoCaptionAnnotation(TypedDict):
+    """Annotation schema for COCO captions format."""
+
+    id: int
+    image_id: int
+    caption: str
+
+
+class CocoCaptionsJson(TypedDict):
+    """COCO captions JSON schema."""
+
+    images: list[CocoCaptionImage]
+    annotations: list[CocoCaptionAnnotation]
+
+
+def to_coco_captions_dict(samples: Iterable[ImageSample]) -> CocoCaptionsJson:
+    """Convert samples with captions to a COCO captions dictionary.
+
+    Args:
+        samples: The samples to export.
+
+    Returns:
+        A dictionary in COCO captions format.
+    """
+    coco_images: list[CocoCaptionImage] = []
+    coco_annotations: list[CocoCaptionAnnotation] = []
+    annotation_id = 0
+
+    for image_id, image in enumerate(samples):
+        coco_images.append(
+            {
+                "id": image_id,
+                "file_name": image.file_path_abs,
+                "width": image.width,
+                "height": image.height,
+            }
+        )
+        for caption in image.captions:
+            coco_annotations.append(
+                {
+                    "id": annotation_id,
+                    "image_id": image_id,
+                    "caption": caption,
+                }
+            )
+            annotation_id += 1
+
+    return {
+        "images": coco_images,
+        "annotations": coco_annotations,
+    }

lightly_studio/export/export_dataset.py

@@ -0,0 +1,104 @@
+"""Exports datasets from Lightly Studio into various formats."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable
+
+from labelformat.formats import COCOObjectDetectionOutput
+from sqlmodel import Session
+
+from lightly_studio.core.image_sample import ImageSample
+from lightly_studio.export import coco_captions
+from lightly_studio.export.lightly_studio_label_input import LightlyStudioObjectDetectionInput
+from lightly_studio.type_definitions import PathLike
+
+DEFAULT_EXPORT_FILENAME = "coco_export.json"
+
+
+class DatasetExport:
+    """Provides methods to export a dataset or a subset of it.
+
+    This class is typically not instantiated directly but returned by `Dataset.export()`.
+    It allows exporting data in various formats.
+    """
+
+    def __init__(self, session: Session, samples: Iterable[ImageSample]):
+        """Initializes the DatasetExport object.
+
+        Args:
+            session: The database session.
+            samples: Samples to export.
+        """
+        self.session = session
+        self.samples = samples
+
+    def to_coco_object_detections(self, output_json: PathLike | None = None) -> None:
+        """Exports object detection annotations to a COCO format JSON file.
+
+        Args:
+            output_json: The path to the output COCO JSON file. If not provided,
+                defaults to "coco_export.json" in the current working directory.
+
+        Raises:
+            ValueError: If the annotation task with the given name does not exist.
+        """
+        if output_json is None:
+            output_json = DEFAULT_EXPORT_FILENAME
+        to_coco_object_detections(
+            session=self.session,
+            samples=self.samples,
+            output_json=Path(output_json),
+        )
+
+    def to_coco_captions(self, output_json: PathLike | None = None) -> None:
+        """Exports captions to a COCO format JSON file.
+
+        Args:
+            output_json: The path to the output COCO JSON file. If not provided,
+                defaults to "coco_export.json" in the current working directory.
+        """
+        if output_json is None:
+            output_json = DEFAULT_EXPORT_FILENAME
+        to_coco_captions(samples=self.samples, output_json=Path(output_json))
+
+
+def to_coco_object_detections(
+    session: Session,
+    samples: Iterable[ImageSample],
+    output_json: Path,
+) -> None:
+    """Exports object detection annotations to a COCO format JSON file.
+
+    This function is for internal use. Use `Dataset.query().export().to_coco_object_detections()`
+    instead.
+
+    Args:
+        session: The database session.
+        samples: The samples to export.
+        output_json: The path to save the output JSON file.
+    """
+    export_input = LightlyStudioObjectDetectionInput(
+        session=session,
+        samples=samples,
+    )
+    COCOObjectDetectionOutput(output_file=output_json).save(label_input=export_input)
+
+
+def to_coco_captions(
+    samples: Iterable[ImageSample],
+    output_json: Path,
+) -> None:
+    """Exports captions to a COCO format JSON file.
+
+    This function is for internal use. Use `Dataset.query().export().to_coco_captions()`
+    instead.
+
+    Args:
+        samples: The samples to export.
+        output_json: The path to save the output JSON file.
+    """
+    coco_captions_dict = coco_captions.to_coco_captions_dict(samples=samples)
+    with output_json.open("w") as f:
+        json.dump(coco_captions_dict, f, indent=2)

lightly_studio/export/lightly_studio_label_input.py

@@ -0,0 +1,120 @@
+"""Converts annotations from Lightly Studio to Labelformat format."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from typing import Iterable
+from uuid import UUID
+
+from labelformat.model.bounding_box import BoundingBox
+from labelformat.model.category import Category
+from labelformat.model.image import Image
+from labelformat.model.object_detection import (
+    ImageObjectDetection,
+    ObjectDetectionInput,
+    SingleObjectDetection,
+)
+from sqlmodel import Session
+
+from lightly_studio.core.image_sample import ImageSample
+from lightly_studio.models.annotation.annotation_base import AnnotationBaseTable, AnnotationType
+from lightly_studio.resolvers import annotation_label_resolver
+
+
+class LightlyStudioObjectDetectionInput(ObjectDetectionInput):
+    """Labelformat adapter backed by dataset samples and annotations."""
+
+    def __init__(self, session: Session, samples: Iterable[ImageSample]) -> None:
+        """Initializes the LightlyStudioObjectDetectionInput.
+
+        Args:
+            session: The SQLModel session to use for database access. Used only in the
+                constructor to fetch the labels for the given annotation task.
+            samples: Dataset samples.
+        """
+        self._samples = list(samples)
+        self._label_id_to_category = _build_label_id_to_category(session=session)
+
+    @staticmethod
+    def add_cli_arguments(parser: ArgumentParser) -> None:
+        """Adds CLI arguments."""
+        # Add CLI arguments implementation is not needed for this class. We need it only
+        # to satisfy the interface.
+        raise NotImplementedError()
+
+    def get_categories(self) -> Iterable[Category]:
+        """Returns the categories for export."""
+        return self._label_id_to_category.values()
+
+    def get_images(self) -> Iterable[Image]:
+        """Returns the images for export."""
+        for idx, sample in enumerate(self._samples):
+            yield _sample_to_image(sample=sample, image_id=idx)
+
+    def get_labels(self) -> Iterable[ImageObjectDetection]:
+        """Returns the labels for export."""
+        for idx, sample in enumerate(self._samples):
+            yield _sample_to_image_obj_det(
+                sample=sample,
+                image_id=idx,
+                label_id_to_category=self._label_id_to_category,
+            )
+
+
+def _build_label_id_to_category(session: Session) -> dict[UUID, Category]:
+    labels = annotation_label_resolver.get_all_sorted_alphabetically(
+        session=session,
+    )
+    # TODO(Horatiu, 09/2025): We should get only labels that are attached to Object Detection
+    # annotations.
+    return {
+        label.annotation_label_id: Category(id=idx, name=label.annotation_label_name)
+        for idx, label in enumerate(labels)
+    }
+
+
+def _sample_to_image(sample: ImageSample, image_id: int) -> Image:
+    return Image(
+        id=image_id,
+        filename=sample.file_path_abs,
+        width=sample.width,
+        height=sample.height,
+    )
+
+
+def _sample_to_image_obj_det(
+    sample: ImageSample,
+    image_id: int,
+    label_id_to_category: dict[UUID, Category],
+) -> ImageObjectDetection:
+    # TODO(Michal, 09/2025): We can optimise in the future to filter annotations in a DB query.
+    objects = [
+        _annotation_to_single_obj_det(
+            annotation=annotation,
+            label_id_to_category=label_id_to_category,
+        )
+        for annotation in sample.sample_table.annotations
+        if annotation.annotation_type == AnnotationType.OBJECT_DETECTION
+    ]
+    return ImageObjectDetection(
+        image=_sample_to_image(sample=sample, image_id=image_id),
+        objects=objects,
+    )
+
+
+def _annotation_to_single_obj_det(
+    annotation: AnnotationBaseTable, label_id_to_category: dict[UUID, Category]
+) -> SingleObjectDetection:
+    assert annotation.object_detection_details is not None
+    box = BoundingBox(
+        xmin=annotation.object_detection_details.x,
+        ymin=annotation.object_detection_details.y,
+        xmax=annotation.object_detection_details.x + annotation.object_detection_details.width,
+        ymax=annotation.object_detection_details.y + annotation.object_detection_details.height,
+    )
+    category = label_id_to_category[annotation.annotation_label.annotation_label_id]
+    return SingleObjectDetection(
+        category=category,
+        box=box,
+        confidence=annotation.confidence,
+    )