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

lightly_studio/resolvers/annotation_resolver/__init__.py

@@ -3,7 +3,6 @@
 from lightly_studio.resolvers.annotation_resolver.count_annotations_by_dataset import (
     count_annotations_by_dataset,
 )
-from lightly_studio.resolvers.annotation_resolver.create import create
 from lightly_studio.resolvers.annotation_resolver.create_many import create_many
 from lightly_studio.resolvers.annotation_resolver.delete_annotation import (
     delete_annotation,
@@ -12,7 +11,7 @@ from lightly_studio.resolvers.annotation_resolver.delete_annotations import (
     delete_annotations,
 )
 from lightly_studio.resolvers.annotation_resolver.get_all import get_all
-from lightly_studio.resolvers.annotation_resolver.get_by_id import get_by_id
+from lightly_studio.resolvers.annotation_resolver.get_by_id import get_by_id, get_by_ids
 from lightly_studio.resolvers.annotation_resolver.update_annotation_label import (
     update_annotation_label,
 )
@@ -22,12 +21,12 @@ from lightly_studio.resolvers.annotation_resolver.update_bounding_box import (
 
 __all__ = [
     "count_annotations_by_dataset",
-    "create",
     "create_many",
     "delete_annotation",
     "delete_annotations",
     "get_all",
     "get_by_id",
+    "get_by_ids",
     "update_annotation_label",
     "update_bounding_box",
 ]

lightly_studio/resolvers/annotation_resolver/create_many.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
+from uuid import UUID
 
 from sqlmodel import Session
 
@@ -24,7 +25,7 @@ from lightly_studio.models.annotation.semantic_segmentation import (
 def create_many(
     session: Session,
     annotations: list[AnnotationCreate],
-) -> Sequence[AnnotationBaseTable]:
+) -> Sequence[UUID]:
     """Create many annotations with object detection details in bulk."""
     # Step 1: Create all base annotations
     base_annotations = []
@@ -37,7 +38,6 @@ def create_many(
         db_base_annotation = AnnotationBaseTable(
             annotation_label_id=annotation_create.annotation_label_id,
             annotation_type=annotation_create.annotation_type,
-            annotation_task_id=annotation_create.annotation_task_id,
             confidence=annotation_create.confidence,
             dataset_id=annotation_create.dataset_id,
             sample_id=annotation_create.sample_id,
@@ -93,4 +93,4 @@ def create_many(
     # Commit everything
     session.commit()
 
-    return base_annotations
+    return [annotation.annotation_id for annotation in base_annotations]

lightly_studio/resolvers/annotation_resolver/delete_annotation.py

@@ -26,7 +26,7 @@ def delete_annotation(
         annotation_id=annotation_id,
     )
     if not annotation:
-        return
+        raise ValueError(f"Annotation {annotation_id} not found")
     if annotation.object_detection_details:
         session.delete(annotation.object_detection_details)
     if annotation.instance_segmentation_details:

lightly_studio/resolvers/annotation_resolver/delete_annotations.py

@@ -18,14 +18,12 @@ from lightly_studio.resolvers.annotations.annotations_filter import (
 
 def delete_annotations(
     session: Session,
-    annotation_task_ids: list[UUID] | None,
     annotation_label_ids: list[UUID] | None,
 ) -> None:
     """Delete all annotations and their tag links using filters.
 
     Args:
         session: Database session.
-        annotation_task_ids: List of annotation task IDs to filter by.
         annotation_label_ids: List of annotation label IDs to filter by.
     """
     # Find annotation_ids to delete
@@ -33,9 +31,15 @@ def delete_annotations(
         session,
         filters=AnnotationsFilter(
             annotation_label_ids=annotation_label_ids,
-            annotation_task_ids=annotation_task_ids,
         ),
     ).annotations
+    for annotation in annotations:
+        if annotation.object_detection_details:
+            session.delete(annotation.object_detection_details)
+        if annotation.instance_segmentation_details:
+            session.delete(annotation.instance_segmentation_details)
+        if annotation.semantic_segmentation_details:
+            session.delete(annotation.semantic_segmentation_details)
     annotation_ids = [annotation.annotation_id for annotation in annotations]
     # TODO(Horatiu, 06/2025): Check if there is a way to delete the links
     # automatically using SQLModel/SQLAlchemy.

lightly_studio/resolvers/annotation_resolver/get_by_id.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from uuid import UUID
 
-from sqlmodel import Session, select
+from sqlmodel import Session, col, select
 
 from lightly_studio.models.annotation.annotation_base import (
     AnnotationBaseTable,
@@ -16,3 +17,20 @@ def get_by_id(session: Session, annotation_id: UUID) -> AnnotationBaseTable | No
     return session.exec(
         select(AnnotationBaseTable).where(AnnotationBaseTable.annotation_id == annotation_id)
     ).one_or_none()
+
+
+def get_by_ids(session: Session, annotation_ids: Sequence[UUID]) -> Sequence[AnnotationBaseTable]:
+    """Retrieve multiple annotations by their IDs.
+
+    Args:
+        session: The database session to use for the query.
+        annotation_ids: A list of annotation IDs to retrieve.
+
+    Returns:
+        A list of annotations matching the provided IDs.
+    """
+    return session.exec(
+        select(AnnotationBaseTable).where(
+            col(AnnotationBaseTable.annotation_id).in_(annotation_ids)
+        )
+    ).all()

lightly_studio/resolvers/annotation_resolver/update_annotation_label.py

@@ -111,7 +111,6 @@ def update_annotation_label(
             annotation_id=annotation_copy.annotation_id,
             annotation_label_id=annotation_copy.annotation_label_id,
             annotation_type=annotation_copy.annotation_type,
-            annotation_task_id=annotation_copy.annotation_task_id,
             confidence=annotation_copy.confidence,
             created_at=annotation_copy.created_at,
             dataset_id=annotation_copy.dataset_id,

lightly_studio/resolvers/annotations/annotations_filter.py

@@ -7,8 +7,7 @@ from uuid import UUID
 from pydantic import BaseModel, Field
 from sqlmodel import col
 
-from lightly_studio.models.annotation.annotation_base import AnnotationBaseTable
-from lightly_studio.models.annotation_task import AnnotationType
+from lightly_studio.models.annotation.annotation_base import AnnotationBaseTable, AnnotationType
 from lightly_studio.models.sample import SampleTable
 from lightly_studio.models.tag import TagTable
 from lightly_studio.type_definitions import QueryType
@@ -30,9 +29,6 @@ class AnnotationsFilter(BaseModel):
         default=None,
         description="List of sample tag UUIDs to filter annotations by",
     )
-    annotation_task_ids: list[UUID] | None = Field(
-        default=None, description="List of annotation task UUIDs"
-    )
 
     def apply(
         self,
@@ -51,12 +47,6 @@ class AnnotationsFilter(BaseModel):
         if self.dataset_ids:
             query = query.where(col(AnnotationBaseTable.dataset_id).in_(self.dataset_ids))
 
-        # Filter by annotation task
-        if self.annotation_task_ids:
-            query = query.where(
-                col(AnnotationBaseTable.annotation_task_id).in_(self.annotation_task_ids)
-            )
-
         # Filter by annotation label
         if self.annotation_label_ids:
             query = query.where(

lightly_studio/selection/mundig.py

@@ -10,29 +10,26 @@ from typing import Iterable
 # Or remove the type ignore once typing stubs were added manually.
 import lightly_mundig  # type: ignore[import-untyped]
 import numpy as np
-from environs import Env
+
+from lightly_studio.dataset.env import LIGHTLY_STUDIO_LICENSE_KEY
 
 
 class Mundig:
-    """Python wrapper for the Mundig selection algorithm.
+    """Python interface for the Mundig selection algorithm.
 
     This class provides a Python interface to the lightly_mundig Rust library
-    for sample selection.
+    for sample selection. It allows combining different selection strategies
+    such as diversity and weighting.
     """
 
     def __init__(self) -> None:
         """Initialize the Mundig selection interface."""
-        # Read LIGHTLY_STUDIO_LICENSE_KEY with .env file support
-        env = Env()
-        env.read_env()
-        license_key = env.str("LIGHTLY_STUDIO_LICENSE_KEY", default=None)
-        if license_key is None:
+        if LIGHTLY_STUDIO_LICENSE_KEY is None:
             raise ValueError(
                 "LIGHTLY_STUDIO_LICENSE_KEY environment variable is not set. "
                 "Please set it to your LightlyStudio license key."
             )
-
-        self.mundig = lightly_mundig.Selection(token=license_key)
+        self.mundig = lightly_mundig.Selection(token=LIGHTLY_STUDIO_LICENSE_KEY)
 
         self.n_input_samples: int | None = None
 

lightly_studio/selection/selection_config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from typing import Literal, Sequence
 from uuid import UUID
 
 from pydantic import BaseModel
@@ -13,7 +14,7 @@ class SelectionConfig(BaseModel):
     dataset_id: UUID
     n_samples_to_select: int
     selection_result_tag_name: str
-    strategies: list[SelectionStrategy]
+    strategies: Sequence[SelectionStrategy]
 
 
 class SelectionStrategy(BaseModel):
@@ -25,10 +26,12 @@ class SelectionStrategy(BaseModel):
 class EmbeddingDiversityStrategy(SelectionStrategy):
     """Selection strategy based on embedding diversity."""
 
+    strategy_name: Literal["diversity"] = "diversity"
     embedding_model_name: str | None
 
 
 class MetadataWeightingStrategy(SelectionStrategy):
     """Selection strategy based on metadata weighting."""
 
+    strategy_name: Literal["weights"] = "weights"
     metadata_key: str

lightly_studio/services/annotations_service/__init__.py

@@ -1,5 +1,11 @@
 """Services for annotations operations."""
 
+from lightly_studio.services.annotations_service.create_annotation import (
+    create_annotation,
+)
+from lightly_studio.services.annotations_service.delete_annotation import (
+    delete_annotation,
+)
 from lightly_studio.services.annotations_service.get_annotation_by_id import (
     get_annotation_by_id,
 )
@@ -17,6 +23,8 @@ from lightly_studio.services.annotations_service.update_annotations import (
 )
 
 __all__ = [
+    "create_annotation",
+    "delete_annotation",
     "get_annotation_by_id",
     "update_annotation",
     "update_annotation_bounding_box",

lightly_studio/services/annotations_service/create_annotation.py

@@ -0,0 +1,63 @@
+"""Create annotation."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel
+from sqlmodel import Session
+
+from lightly_studio.models.annotation.annotation_base import (
+    AnnotationBaseTable,
+    AnnotationCreate,
+    AnnotationType,
+)
+from lightly_studio.resolvers import annotation_resolver
+
+
+class AnnotationCreateParams(BaseModel):
+    """Input model for create annotation service."""
+
+    annotation_label_id: UUID
+    annotation_type: AnnotationType
+    dataset_id: UUID
+    sample_id: UUID
+
+    x: int | None = None
+    y: int | None = None
+    width: int | None = None
+    height: int | None = None
+
+    segmentation_mask: list[int] | None = None
+
+
+def create_annotation(session: Session, annotation: AnnotationCreateParams) -> AnnotationBaseTable:
+    """Create a new annotation.
+
+    Args:
+        session: Database session for executing the operation.
+        annotation: Annotation data to create.
+
+    Returns:
+        The retrieved annotation.
+    """
+    annotation_create = AnnotationCreate(
+        **annotation.model_dump(),
+    )
+    new_annotation_ids = annotation_resolver.create_many(
+        session=session,
+        annotations=[annotation_create],
+    )
+
+    if not new_annotation_ids:
+        raise ValueError("Failed to create annotation.")
+
+    created_annotation = annotation_resolver.get_by_id(
+        session=session,
+        annotation_id=new_annotation_ids[0],
+    )
+
+    if created_annotation is None:
+        raise ValueError(f"Failed to create annotation: {annotation}")
+
+    return created_annotation

lightly_studio/services/annotations_service/delete_annotation.py

@@ -0,0 +1,22 @@
+"""Delete an annotation by its ID."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from sqlmodel import Session
+
+from lightly_studio.resolvers import annotation_resolver
+
+
+def delete_annotation(session: Session, annotation_id: UUID) -> None:
+    """Delete an annotation by its ID.
+
+    Args:
+        session: Database session for executing the operation.
+        annotation_id: ID of the annotation to delete.
+
+    Raises:
+        ValueError: If the annotation with the given ID is not found.
+    """
+    annotation_resolver.delete_annotation(session=session, annotation_id=annotation_id)

{lightly_studio-0.3.2.dist-info → lightly_studio-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightly-studio
-Version: 0.3.2
+Version: 0.3.3
 Summary: LightlyStudio is a lightweight, fast, and easy-to-use data exploration tool for data scientists and engineers.
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
@@ -20,16 +20,23 @@ Requires-Dist: fastapi>=0.115.5
 Requires-Dist: faster-coco-eval>=1.6.5
 Requires-Dist: fsspec>=2023.1.0
 Requires-Dist: labelformat>=0.1.7
-Requires-Dist: lightly-mundig==0.1.3
+Requires-Dist: lightly-mundig==0.1.4
 Requires-Dist: open-clip-torch>=2.20.0
+Requires-Dist: pyarrow>=17.0.0
 Requires-Dist: python-multipart>=0.0.20
 Requires-Dist: scikit-learn==1.3.2
 Requires-Dist: sqlmodel>=0.0.22
-Requires-Dist: torchmetrics>=1.5.2
 Requires-Dist: tqdm>=4.65.0
 Requires-Dist: typing-extensions>=4.12.2
 Requires-Dist: uvicorn>=0.32.1
 Requires-Dist: xxhash>=3.5.0
+Provides-Extra: cloud-storage
+Requires-Dist: adlfs>=2023.1.0; extra == 'cloud-storage'
+Requires-Dist: gcsfs>=2023.1.0; extra == 'cloud-storage'
+Requires-Dist: s3fs>=2023.1.0; extra == 'cloud-storage'
+Provides-Extra: lightly-edge
+Requires-Dist: lightly-edge-sdk>=1.0.1b2; extra == 'lightly-edge'
+Requires-Dist: opencv-python; extra == 'lightly-edge'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -113,42 +120,47 @@ python -m venv venv
 .\venv\Scripts\activate
 
 # 2. Install LightlyStudio
-pip install lightly_studio
+pip install lightly-studio
 ```
 
 ## **Quickstart**
 
-Download the dataset and run a quickstart script to load your dataset and launch the app.
-
-### YOLO Object Detection
-
-To run an example using a yolo dataset, clone the example repository and run the example script from below:
+Download example datasets by cloning the example repository:
 
 ```shell
 git clone https://github.com/lightly-ai/dataset_examples dataset_examples
 ```
 
-**`example_yolo.py` script to explore the dataset:**
+### YOLO Object Detection
+
+To run an example using a YOLO dataset, create a file named `example_yolo.py` with the
+following contents in the same directory that contains the `dataset_examples/` folder:
 
 ```python
-from pathlib import Path
+# example_yolo.py
 
+from pathlib import Path
 import lightly_studio as ls
 
-data_yaml_path = Path(__file__).resolve().parent / "data.yaml"
-
 # Create a dataset and add the samples from the yolo format
 dataset = ls.Dataset.create()
 dataset.add_samples_from_yolo(
-    data_yaml=data_yaml_path,
+    data_yaml="dataset_examples/road_signs_yolo/data.yaml",
     input_split="test",
 )
 
 # Start the UI application on the port 8001.
 ls.start_gui()
+```
 
+Run the script:
+
+```
+python example_yolo.py
 ```
 
+When you are done, stop the app by pressing Ctrl+C in the terminal.
+
 <details>
 <summary>The YOLO format details:</summary>
 
@@ -183,26 +195,21 @@ Where coordinates are normalized between 0 and 1.
 
 ### COCO Instance Segmentation
 
-To run an instance segmentation example using a COCO dataset, clone the example repository and run the example script from below:
-
-```shell
-git clone https://github.com/lightly-ai/dataset_examples dataset_examples
-```
-
-**`example_coco.py` script to explore the dataset:**
+To run an instance segmentation example using a COCO dataset, create a file named
+`example_coco.py` with the following contents in the same directory that contains
+the `dataset_examples/` folder:
 
 ```python
-from pathlib import Path
+# example_coco.py
 
+from pathlib import Path
 import lightly_studio as ls
 
-current_dir = Path(__file__).resolve().parent
-
 # Create a dataset and add the samples from the coco format
 dataset = ls.Dataset.create()
 dataset.add_samples_from_coco(
-    annotations_json=current_dir / "instances_train2017.json",
-    images_path=current_dir / "images",
+    annotations_json="dataset_examples/coco_subset_128_images/instances_train2017.json",
+    images_path="dataset_examples/coco_subset_128_images/images",
     annotation_type=ls.AnnotationType.INSTANCE_SEGMENTATION,
 )
 
@@ -210,6 +217,14 @@ dataset.add_samples_from_coco(
 ls.start_gui()
 ```
 
+Run the script:
+
+```
+python example_coco.py
+```
+
+When you are done, stop the app by pressing Ctrl+C in the terminal.
+
 <details>
 <summary>The COCO format details:</summary>
 
@@ -253,6 +268,53 @@ dataset.add_samples_from_path(path="/path/to/image_dataset")
 ls.start_gui()
 ```
 
+#### ☁️ Cloud Storage Support
+
+#### Installation with Cloud Storage Support
+
+```shell
+pip install lightly-studio[cloud-storage]
+```
+
+#### Example: Loading Dataset from Cloud Storage
+
+```python
+import lightly_studio as ls
+
+dataset = ls.Dataset.create()
+
+# Load dataset from S3
+dataset.add_samples_from_path(path="s3://my-bucket/path/to/images/")
+
+# You can use glob pattern in the file path
+dataset.add_samples_from_path(path="s3://my-bucket/path/to/images/**/*.jpg") # matches all .jpg files recursively
+
+# Load dataset from gcs
+dataset.add_samples_from_path(path="gs://path/to/images/")
+
+ls.start_gui()
+```
+
+**Note**: Currently, cloud storage support is limited to loading images only. Annotation files (YOLO labels, COCO JSON files, etc.) cannot be loaded directly from cloud storage paths.
+
+#### Authentication
+
+**Important**: Cloud storage authentication must be configured before running LightlyStudio. The application relies on your existing cloud storage credentials and will not prompt for authentication.
+
+#### AWS S3
+
+You can use either of the following two options:
+
+- **Set environment variables manually**: Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (LightlyStudio uses `s3fs` under the hood to connect to S3)
+- **Authenticate using AWS CLI**: Run `aws configure` (this will automatically set the environment variables that LightlyStudio can access)
+
+#### Google Cloud Storage
+
+You can use either of the following two options:
+
+- **Set environment variable manually**: Set `GOOGLE_APPLICATION_CREDENTIALS` pointing to your service account key file (LightlyStudio uses `gcsfs` under the hood to connect to GCS)
+- **Authenticate using gcloud CLI**: Run `gcloud auth application-default login` (this will automatically set the environment variables that LightlyStudio can access)
+
 #### Load Images With Annotations
 
 The `Dataset` currently supports:
@@ -564,6 +626,16 @@ In some use cases, one might want to assign a tag to the samples that are the re
 query.add_tag("tag_name")
 ```
 
+#### Export Samples
+
+Currently, exporting to the COCO object detection format is supported. The following example shows how to export the samples in the query to a COCO JSON file:
+
+```py
+from pathlib import Path
+
+query.export().to_coco_object_detections(Path("coco_export.json"))
+```
+
 ### Examples
 
 #### Add Custom Metadata
@@ -635,7 +707,9 @@ import os
 os.environ["LIGHTLY_STUDIO_LICENSE_KEY"] = "license_key_here"
 ```
 
-The selection can be configured directly from a `DatasetQuery`. The example below showcases a simple case of selecting diverse samples.
+#### Diversity Selection
+
+Diversity selection can be configured directly from a `DatasetQuery`. The example below showcases a simple case of selecting diverse samples.
 
 ```py
 import lightly_studio as ls
@@ -653,6 +727,57 @@ dataset.query().selection().diverse(
 ls.start_gui()
 ```
 
+#### Metadata Weighting Selection
+
+You can select samples based on the values of a metadata field. The example below showcases a simple case of selecting samples with the highest metadata value.
+
+```py
+import lightly_studio as ls
+
+# Load your dataset
+dataset = ls.Dataset.load_or_create()
+dataset.add_samples_from_path(path="/path/to/image_dataset")
+# Compute and store 'typicality' metadata.
+dataset.compute_typicality_metadata(metadata_name="typicality")
+
+# Select the 5 samples with the highest 'typicality' scores.
+dataset.query().selection().metadata_weighting(
+    n_samples_to_select=5,
+    selection_result_tag_name="metadata_weighting_selection",
+    metadata_key="typicality",
+)
+```
+
+#### Selection Based on Multiple Strategies
+
+You can configure multiple strategies, the selection takes into account all of them at the same time, weighted by the `strength` parameter.
+
+```py
+import lightly_studio as ls
+from lightly_studio.selection.selection_config import (
+    MetadataWeightingStrategy,
+    EmbeddingDiversityStrategy,
+)
+
+# Load your dataset
+dataset = ls.Dataset.load_or_create()
+dataset.add_samples_from_path(path="/path/to/image_dataset")
+# Compute typicality and store it as `typicality` metadata
+dataset.compute_typicality_metadata(metadata_name="typicality")
+
+# Select 10 samples by combining typicality and diversity, diversity having double the strength.
+dataset.query().selection().multi_strategies(
+    n_samples_to_select=10,
+    selection_result_tag_name="multi_strategy_selection",
+    selection_strategies=[
+        MetadataWeightingStrategy(metadata_key="typicality", strength=1.0),
+        EmbeddingDiversityStrategy(embedding_model_name="my_model_name", strength=2.0),
+    ],
+)
+```
+
+#### Exporting Selected Samples
+
 The selected sample paths can be exported via the GUI, or by a script:
 
 ```py