lightly-studio 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

lightly_studio/examples/example_split_work.py

@@ -4,25 +4,21 @@ import math
 
 from environs import Env
 
-from lightly_studio import DatasetLoader
-from lightly_studio.models.tag import TagCreate
-from lightly_studio.resolvers import (
-    tag_resolver,
-)
+import lightly_studio as ls
 
 # Read environment variables
 env = Env()
 env.read_env()
 
-# Create a DatasetLoader instance
-loader = DatasetLoader()
+# Create a Dataset instance
+dataset = ls.Dataset.create()
 
 # Define the path to the dataset (folder containing data.yaml)
 dataset_path = env.path("DATASET_PATH", "/path/to/your/yolo/dataset/data.yaml")
 
 # Load YOLO dataset using data.yaml path
-dataset = loader.from_yolo(
-    str(dataset_path),
+dataset.add_samples_from_yolo(
+    data_yaml=str(dataset_path),
     input_split=env.str("LIGHTLY_STUDIO_DATASET_SPLIT", "test"),
 )
 
@@ -32,36 +28,16 @@ dataset = loader.from_yolo(
 # to work on.
 reviewers = env.str("DATASET_REVIEWERS", "Alice, Bob, Charlie, David")
 
-# Get all samples from the db
-samples = dataset.get_samples()
-
 # Create a tag for each reviewer to work on
-tags = []
-for reviewer in reviewers.split(","):
-    tags.append(
-        tag_resolver.create(
-            session=loader.session,
-            tag=TagCreate(
-                dataset_id=dataset.dataset_id,
-                name=f"""{reviewer.strip()} tasks""",
-                kind="sample",
-            ),
-        )
-    )
+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, tag in enumerate(tags):
-    # allocate all samples for this tag
-    sample_ids = [sample.sample_id for sample in samples[i * chunk_size : (i + 1) * chunk_size]]
-
-    # Add sample_ids to the tag
-    tag_resolver.add_sample_ids_to_tag_id(
-        session=loader.session,
-        tag_id=tag.tag_id,
-        sample_ids=sample_ids,
-    )
-
+for i, sample in enumerate(samples):
+    sample.add_tag(tags[i // chunk_size])
 
 # Launch the server to load data
-loader.start_gui()
+ls.start_gui()

lightly_studio/examples/{example_v2.py → example_yolo.py}

@@ -1,4 +1,4 @@
-"""Example of how to load samples from path with the dataset class."""
+"""Example of how to add samples in yolo format to a dataset."""
 
 from pathlib import Path
 
@@ -12,10 +12,9 @@ env.read_env()
 
 # Define the path to the dataset directory
 dataset_path = Path(env.path("DATASET_PATH", "/path/to/your/dataset"))
-dataset_path = dataset_path.parent if dataset_path.is_file() else dataset_path
 
 # Create a DatasetLoader from a path
-dataset = ls.Dataset("clothing_small_test")
-dataset.add_samples_from_path(path=dataset_path)
+dataset = ls.Dataset.create()
+dataset.add_samples_from_yolo(data_yaml=dataset_path, input_split="train")
 
 ls.start_gui()

lightly_studio/export/export_dataset.py

@@ -0,0 +1,65 @@
+"""Exports datasets from Lightly Studio into various formats."""
+
+from pathlib import Path
+from typing import Iterable
+
+from labelformat.formats import COCOObjectDetectionOutput
+from sqlmodel import Session
+
+from lightly_studio.core.sample import Sample
+from lightly_studio.export.lightly_studio_label_input import LightlyStudioObjectDetectionInput
+
+
+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[Sample]):
+        """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: Path) -> None:
+        """Exports object detection annotations to a COCO format JSON file.
+
+        Args:
+            output_json: The path to the output COCO JSON file.
+
+        Raises:
+            ValueError: If the annotation task with the given name does not exist.
+        """
+        to_coco_object_detections(
+            session=self.session,
+            samples=self.samples,
+            output_json=output_json,
+        )
+
+
+def to_coco_object_detections(
+    session: Session,
+    samples: Iterable[Sample],
+    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)

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.sample import Sample
+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[Sample]) -> 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: Sample, 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: Sample,
+    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.inner.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,
+    )

lightly_studio/few_shot_classifier/classifier_manager.py

@@ -22,20 +22,16 @@ from lightly_studio.few_shot_classifier.random_forest_classifier import (
 )
 from lightly_studio.models.annotation.annotation_base import (
     AnnotationCreate,
+    AnnotationType,
 )
 from lightly_studio.models.annotation_label import (
     AnnotationLabelCreate,
 )
-from lightly_studio.models.annotation_task import (
-    AnnotationTaskTable,
-    AnnotationType,
-)
 from lightly_studio.models.classifier import EmbeddingClassifier
 from lightly_studio.models.sample import SampleTable
 from lightly_studio.resolvers import (
     annotation_label_resolver,
     annotation_resolver,
-    annotation_task_resolver,
     embedding_model_resolver,
     sample_embedding_resolver,
     sample_resolver,
@@ -92,7 +88,6 @@ class ClassifierEntry:
     # will be false.
     is_active: bool = False
 
-    annotation_task_id: UUID | None = None
     annotation_label_ids: list[UUID] | None = None
 
 
@@ -469,16 +464,14 @@ class ClassifierManager:
         embeddings = [se.embedding for se in sample_embeddings]
         predictions = classifier.few_shot_classifier.predict(embeddings)
         if len(predictions):
-            _create_annotation_task_and_labels_for_classifier(
+            _create_annotation_labels_for_classifier(
                 classifier=classifier,
                 session=session,
                 dataset_id=dataset_id,
             )
         else:
             raise ValueError(f"Predict returned empty list for classifier:'{classifier_id}'")
-        # Check if annotation task or labels are available
-        if not classifier.annotation_task_id:
-            raise ValueError(f"Classifier with ID '{classifier_id}' has no annotation task.")
+        # Check if annotation labels are available
         if not classifier.annotation_label_ids:
             raise ValueError(f"Classifier with ID '{classifier_id}' has no annotation labels")
 
@@ -490,7 +483,6 @@ class ClassifierManager:
             classification_annotations.append(
                 AnnotationCreate(
                     sample_id=sample_embedding.sample_id,
-                    annotation_task_id=classifier.annotation_task_id,
                     dataset_id=dataset_id,
                     annotation_label_id=classifier.annotation_label_ids[max_index],
                     annotation_type=AnnotationType.CLASSIFICATION,
@@ -500,7 +492,6 @@ class ClassifierManager:
         #  Clear previous annotations by this classifier
         annotation_resolver.delete_annotations(
             session=session,
-            annotation_task_ids=[classifier.annotation_task_id],
             annotation_label_ids=classifier.annotation_label_ids,
         )
         annotation_resolver.create_many(session=session, annotations=classification_annotations)
@@ -597,30 +588,18 @@ class ClassifierManager:
         return self._classifiers[classifier_id]
 
 
-def _create_annotation_task_and_labels_for_classifier(
+def _create_annotation_labels_for_classifier(
     session: Session,
     dataset_id: UUID,
     classifier: ClassifierEntry,
 ) -> None:
-    """Create annotation task and labels for the classifier.
+    """Create annotation labels for the classifier.
 
     Args:
         session: Database session.
         dataset_id: The dataset ID to which the samples belong.
         classifier: The classifier object to update.
     """
-    # Check if the annotation task exists and if not create it.
-    if classifier.annotation_task_id is None:
-        annotation_task = annotation_task_resolver.create(
-            session=session,
-            annotation_task=AnnotationTaskTable(
-                name=FSC_ANNOTATION_TASK_PREFIX + classifier.few_shot_classifier.name,
-                annotation_type=AnnotationType.CLASSIFICATION,
-                is_prediction=True,
-            ),
-        )
-        classifier.annotation_task_id = annotation_task.annotation_task_id
-
     # Check if the annotation label with the classifier name and class
     # names exists and if not create it.
     if classifier.annotation_label_ids is None:

lightly_studio/metadata/compute_typicality.py

@@ -0,0 +1,67 @@
+"""Computes typicality from embeddings."""
+
+from uuid import UUID
+
+from lightly_mundig import Typicality  # type: ignore[import-untyped]
+from sqlmodel import Session
+
+from lightly_studio.dataset.env import LIGHTLY_STUDIO_LICENSE_KEY
+from lightly_studio.resolvers import (
+    metadata_resolver,
+    sample_embedding_resolver,
+)
+
+DEFAULT_NUM_NEAREST_NEIGHBORS = 20
+
+
+def compute_typicality_metadata(
+    session: Session,
+    dataset_id: UUID,
+    embedding_model_id: UUID,
+    metadata_name: str = "typicality",
+) -> None:
+    """Computes typicality for each sample in the dataset from embeddings.
+
+    Typicality is a measure of how representative a sample is of the dataset.
+    It is calculated for each sample from its K-nearest neighbors in the
+    embedding space.
+
+    The computed typicality values are stored as metadata for each sample.
+
+    Args:
+        session:
+            The database session.
+        dataset_id:
+            The ID of the dataset for which to compute the typicality.
+        embedding_model_id:
+            The ID of the embedding model to use for the computation.
+        metadata_name:
+            The name of the metadata field to store the typicality values in.
+            Defaults to "typicality".
+    """
+    license_key = LIGHTLY_STUDIO_LICENSE_KEY
+    if license_key is None:
+        raise ValueError(
+            "LIGHTLY_STUDIO_LICENSE_KEY environment variable is not set. "
+            "Please set it to your LightlyStudio license key."
+        )
+
+    samples = sample_embedding_resolver.get_all_by_dataset_id(
+        session=session, dataset_id=dataset_id, embedding_model_id=embedding_model_id
+    )
+
+    embeddings = [sample.embedding for sample in samples]
+    typicality = Typicality(embeddings=embeddings, token=license_key)
+    typicality_values = typicality.calculate_typicality(
+        num_nearest_neighbors=DEFAULT_NUM_NEAREST_NEIGHBORS
+    )
+    assert len(samples) == len(typicality_values), (
+        "The number of samples and computed typicality values must match"
+    )
+
+    metadata = [
+        (sample.sample_id, {metadata_name: typicality})
+        for sample, typicality in zip(samples, typicality_values)
+    ]
+
+    metadata_resolver.bulk_set_metadata(session, metadata)

lightly_studio/models/annotation/annotation_base.py

@@ -1,10 +1,11 @@
 """This module defines the base annotation model."""
 
 from datetime import datetime, timezone
+from enum import Enum
 from typing import TYPE_CHECKING, List, Optional
 from uuid import UUID, uuid4
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from pydantic import Field as PydanticField
 from sqlalchemy.orm import Mapped
 from sqlmodel import Field, Relationship, SQLModel
@@ -22,10 +23,6 @@ from lightly_studio.models.annotation.semantic_segmentation import (
     SemanticSegmentationAnnotationTable,
     SemanticSegmentationAnnotationView,
 )
-from lightly_studio.models.annotation_task import (
-    AnnotationTaskTable,
-    AnnotationType,
-)
 
 if TYPE_CHECKING:
     from lightly_studio.models.annotation_label import (
@@ -41,6 +38,15 @@ else:
     AnnotationLabelTable = object
 
 
+class AnnotationType(str, Enum):
+    """The type of annotation task."""
+
+    CLASSIFICATION = "classification"
+    SEMANTIC_SEGMENTATION = "semantic_segmentation"
+    INSTANCE_SEGMENTATION = "instance_segmentation"
+    OBJECT_DETECTION = "object_detection"
+
+
 class AnnotationBaseTable(SQLModel, table=True):
     """Base class for all annotation models."""
 
@@ -51,9 +57,7 @@ class AnnotationBaseTable(SQLModel, table=True):
     annotation_id: UUID = Field(default_factory=uuid4, primary_key=True)
     annotation_type: AnnotationType
     annotation_label_id: UUID = Field(foreign_key="annotation_labels.annotation_label_id")
-    annotation_task_id: UUID = Field(
-        foreign_key="annotation_tasks.annotation_task_id",
-    )
+
     confidence: Optional[float] = None
     dataset_id: UUID = Field(foreign_key="datasets.dataset_id")
     sample_id: UUID = Field(foreign_key="samples.sample_id")
@@ -61,9 +65,6 @@ class AnnotationBaseTable(SQLModel, table=True):
     annotation_label: Mapped["AnnotationLabelTable"] = Relationship(
         sa_relationship_kwargs={"lazy": "select"},
     )
-    annotation_task: Mapped["AnnotationTaskTable"] = Relationship(
-        sa_relationship_kwargs={"lazy": "select"},
-    )
     sample: Mapped[Optional["SampleTable"]] = Relationship(
         sa_relationship_kwargs={"lazy": "select"},
     )
@@ -101,16 +102,15 @@ class AnnotationCreate(SQLModel):
     """ Required properties for all annotations. """
     annotation_label_id: UUID
     annotation_type: AnnotationType
-    annotation_task_id: UUID
     confidence: Optional[float] = None
     dataset_id: UUID
     sample_id: UUID
 
     """ Optional properties for object detection. """
-    x: Optional[float] = None
-    y: Optional[float] = None
-    width: Optional[float] = None
-    height: Optional[float] = None
+    x: Optional[int] = None
+    y: Optional[int] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
 
     """ Optional properties for instance and semantic segmentation. """
     segmentation_mask: Optional[List[int]] = None
@@ -140,7 +140,6 @@ class AnnotationView(SQLModel):
     annotation_id: UUID
     annotation_type: AnnotationType
     annotation_label: AnnotationLabel
-    annotation_task_id: UUID
     confidence: Optional[float] = None
 
     object_detection_details: Optional[ObjectDetectionAnnotationView] = None
@@ -157,13 +156,12 @@ class AnnotationWithSampleView(AnnotationView):
 class AnnotationViewsWithCount(BaseModel):
     """Response model for counted annotations."""
 
+    model_config = ConfigDict(populate_by_name=True)
+
     annotations: List[AnnotationWithSampleView] = PydanticField(..., alias="data")
     total_count: int
     next_cursor: Optional[int] = PydanticField(..., alias="nextCursor")
 
-    class Config:  # noqa: D106
-        populate_by_name = True
-
 
 class AnnotationDetailsView(AnnotationView):
     """Representing detailed view of an annotation."""

lightly_studio/models/annotation/instance_segmentation.py

@@ -34,10 +34,10 @@ class InstanceSegmentationAnnotationTable(SQLModel, table=True):
         back_populates="instance_segmentation_details"
     )
 
-    x: float
-    y: float
-    width: float
-    height: float
+    x: int
+    y: int
+    width: int
+    height: int
     # TODO(Kondrat 06/2025): We need to fix logic in the loader,
     # because it shouldn't be optional.
     # lightly_studio/dataset/loader.py#L148
@@ -49,8 +49,8 @@ class InstanceSegmentationAnnotationTable(SQLModel, table=True):
 class InstanceSegmentationAnnotationView(SQLModel):
     """API response model for instance segmentation annotations."""
 
-    x: float
-    y: float
-    width: float
-    height: float
+    x: int
+    y: int
+    width: int
+    height: int
     segmentation_mask: Optional[List[int]] = None

lightly_studio/models/annotation/object_detection.py

@@ -32,10 +32,10 @@ class ObjectDetectionAnnotationTable(SQLModel, table=True):
         back_populates="object_detection_details"
     )
 
-    x: float
-    y: float
-    width: float
-    height: float
+    x: int
+    y: int
+    width: int
+    height: int
 
 
 class ObjectDetectionAnnotationView(SQLModel):

lightly_studio/models/dataset.py

@@ -10,6 +10,7 @@ from uuid import UUID, uuid4
 from sqlalchemy.orm import Session as SQLAlchemySession
 from sqlmodel import Field, Session, SQLModel
 
+from lightly_studio.api.routes.api.validators import Paginated
 from lightly_studio.models.sample import SampleTable
 from lightly_studio.resolvers import sample_resolver
 from lightly_studio.resolvers.samples_filter import SampleFilter
@@ -73,11 +74,14 @@ class DatasetTable(DatasetBase, table=True):
         if session is None:
             raise RuntimeError("No database session found for this instance")
 
+        pagination = None
+        if limit is not None:
+            pagination = Paginated(offset=offset, limit=limit)
+
         return sample_resolver.get_all_by_dataset_id(
             session=session,
             dataset_id=self.dataset_id,
-            offset=offset,
-            limit=limit,
+            pagination=pagination,
             filters=filters,
             text_embedding=text_embedding,
             sample_ids=sample_ids,

lightly_studio/models/sample.py

@@ -4,6 +4,8 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, List, Literal, Optional
 from uuid import UUID, uuid4
 
+from pydantic import BaseModel, ConfigDict
+from pydantic import Field as PydanticField
 from sqlalchemy.orm import Mapped, Session
 from sqlmodel import Field, Relationship, SQLModel
 
@@ -44,7 +46,7 @@ class SampleBase(SQLModel):
     dataset_id: UUID = Field(default=None, foreign_key="datasets.dataset_id")
 
     """The dataset image path."""
-    file_path_abs: str
+    file_path_abs: str = Field(default=None, unique=True)
 
 
 class SampleCreate(SampleBase):
@@ -97,6 +99,7 @@ class SampleTable(SampleBase, table=True):
     embeddings: Mapped[List["SampleEmbeddingTable"]] = Relationship(back_populates="sample")
     metadata_dict: "SampleMetadataTable" = Relationship(back_populates="sample")
 
+    # TODO(Michal, 9/2025): Remove this function in favour of Sample.metadata.
     def __getitem__(self, key: str) -> Any:
         """Provides dict-like access to sample metadata.
 
@@ -111,6 +114,7 @@ class SampleTable(SampleBase, table=True):
             return None
         return self.metadata_dict.get_value(key)
 
+    # TODO(Michal, 9/2025): Remove this function in favour of Sample.metadata.
     def __setitem__(self, key: str, value: Any) -> None:
         """Sets a metadata key-value pair for this sample.
 
@@ -173,8 +177,11 @@ class SampleView(SQLModel):
     height: int
 
 
-class SampleViewsWithCount(SQLModel):
+class SampleViewsWithCount(BaseModel):
     """Response model for counted samples."""
 
-    data: List[SampleView]
+    model_config = ConfigDict(populate_by_name=True)
+
+    samples: List[SampleView] = PydanticField(..., alias="data")
     total_count: int
+    next_cursor: Optional[int] = PydanticField(None, alias="nextCursor")

lightly_studio/resolvers/annotation_label_resolver/__init__.py

@@ -2,7 +2,7 @@
 
 from .create import create
 from .delete import delete
-from .get_all import get_all
+from .get_all import get_all, get_all_sorted_alphabetically
 from .get_by_id import get_by_id
 from .get_by_ids import get_by_ids
 from .get_by_label_name import get_by_label_name
@@ -13,6 +13,7 @@ __all__ = [
     "create",
     "delete",
     "get_all",
+    "get_all_sorted_alphabetically",
     "get_by_id",
     "get_by_ids",
     "get_by_label_name",