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

lightly_studio/resolvers/samples_filter.py

@@ -33,20 +33,15 @@ class SampleFilter(BaseModel):
     annotation_label_ids: Optional[List[UUID]] = None
     tag_ids: Optional[List[UUID]] = None
     metadata_filters: Optional[List[MetadataFilter]] = None
+    sample_ids: Optional[List[UUID]] = None
 
     def apply(self, query: QueryType) -> QueryType:
         """Apply the filters to the given query."""
+        if self.sample_ids:
+            query = query.where(col(SampleTable.sample_id).in_(self.sample_ids))
+
         # Apply dimension-based filters to the query.
-        if self.width:
-            if self.width.min is not None:
-                query = query.where(SampleTable.width >= self.width.min)
-            if self.width.max is not None:
-                query = query.where(SampleTable.width <= self.width.max)
-        if self.height:
-            if self.height.min is not None:
-                query = query.where(SampleTable.height >= self.height.min)
-            if self.height.max is not None:
-                query = query.where(SampleTable.height <= self.height.max)
+        query = self._apply_dimension_filters(query)
 
         # Apply annotation label filters to the query.
         if self.annotation_label_ids:
@@ -79,3 +74,16 @@ class SampleFilter(BaseModel):
                 metadata_join_condition=SampleMetadataTable.sample_id == SampleTable.sample_id,
             )
         return query
+
+    def _apply_dimension_filters(self, query: QueryType) -> QueryType:
+        if self.width:
+            if self.width.min is not None:
+                query = query.where(SampleTable.width >= self.width.min)
+            if self.width.max is not None:
+                query = query.where(SampleTable.width <= self.width.max)
+        if self.height:
+            if self.height.min is not None:
+                query = query.where(SampleTable.height >= self.height.min)
+            if self.height.max is not None:
+                query = query.where(SampleTable.height <= self.height.max)
+        return query

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/type_definitions.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 from typing import TypeVar, Union
+from uuid import UUID
 
 from sqlmodel.sql.expression import SelectOfScalar
 
@@ -14,6 +15,7 @@ QueryType = TypeVar(
     SelectOfScalar[AnnotationBaseTable],
     SelectOfScalar[SampleTable],
     SelectOfScalar[int],
+    SelectOfScalar[UUID],
 )
 
 PathLike = Union[str, Path]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightly-studio
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -10,7 +10,8 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.8
 Requires-Dist: annotated-types==0.7.0
 Requires-Dist: duckdb-engine<0.17,>=0.15.0
 Requires-Dist: duckdb<1.3,>=1.2.2
@@ -20,16 +21,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">
@@ -53,7 +61,7 @@ Description-Content-Type: text/markdown
 
 We at **[Lightly](https://lightly.ai)** created **LightlyStudio**, an open-source tool
 designed to supercharge your data curation workflows for computer vision datasets. Explore
-your data, visualize annotations and crops, tag samples, and export curated lists to improve
+your data, visualize captions, annotations and crops, tag samples, and export curated lists to improve
 your machine learning pipelines. And much more!
 
 LightlyStudio runs entirely locally on your machine, keeping your data private. It consists
@@ -65,7 +73,7 @@ Using LightlyStudio typically involves these steps:
 
 1.  **Index Your Dataset:** Run a Python script using the `lightly_studio` library to process your local dataset (images and annotations) and save metadata into a local `lightly_studio.db` file.
 2.  **Launch the UI:** The script then starts a local web server.
-3.  **Explore & Curate:** Use the UI to visualize images, annotations, and object crops. Filter and search your data (experimental text search available). Apply tags to interesting samples (e.g., "mislabeled", "review").
+3.  **Explore & Curate:** Use the UI to visualize images, annotations, captions, and object crops. Filter and search your data (experimental text search available). Apply tags to interesting samples (e.g., "mislabeled", "review").
 4.  **Export Curated Data:** Export information (like filenames) for your tagged samples from the UI to use downstream.
 5.  **Stop the Server:** Close the terminal running the script (Ctrl+C) when done.
 
@@ -104,7 +112,7 @@ The library is OS-independent and works on Windows, Linux, and macOS.
 
 ```shell
 # 1. Create and activate a virtual environment (Recommended)
-# On Linux/macOS:
+# On Linux/MacOS:
 python3 -m venv venv
 source venv/bin/activate
 
@@ -113,41 +121,44 @@ 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
 
 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,
-    input_split="test",
+    data_yaml="dataset_examples/road_signs_yolo/data.yaml",
 )
 
 # 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 +194,20 @@ 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
 
 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 +215,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>
 
@@ -230,6 +243,56 @@ COCO uses a single JSON file containing all annotations. The format consists of
 
 </details>
 
+### COCO Captions
+
+To run a caption example using a COCO dataset, create a file named
+`example_coco_captions.py` with the following contents in the same directory that contains
+the `dataset_examples/` folder:
+
+```python
+# example_coco_captions.py
+
+import lightly_studio as ls
+
+# Create a dataset and add the samples from the coco format
+dataset = ls.Dataset.create()
+dataset.add_samples_from_coco_caption(
+    annotations_json="dataset_examples/coco_subset_128_images/captions_train2017.json",
+    images_path="dataset_examples/coco_subset_128_images/images",
+)
+
+# Start the UI application on the port 8001.
+ls.start_gui()
+```
+
+Run the script:
+
+```
+python example_coco_captions.py
+```
+
+Now you can inspect samples with their assigned captions in the app. When you are done,
+stop the app by pressing Ctrl+C in the terminal.
+
+<details>
+<summary>The COCO format details:</summary>
+
+```
+coco_subset_128_images/
+├── images/
+│   ├── image1.jpg
+│   ├── image2.jpg
+│   └── ...
+└── captions_train2017.json        # Single JSON file containing all captions
+```
+
+COCO uses a single JSON file containing all captions. The format consists of three main components:
+
+- Images: Defines metadata for each image in the dataset.
+- Annotations: Defines the captions.
+
+</details>
+
 ## 🔍 How It Works
 
 1.  Your **Python script** uses the `lightly_studio` **Dataset**.
@@ -253,6 +316,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:
@@ -268,7 +378,6 @@ import lightly_studio as ls
 dataset = ls.Dataset.create()
 dataset.add_samples_from_yolo(
     data_yaml="my_yolo_dataset/data.yaml",
-    input_split="val",
 )
 
 ls.start_gui()
@@ -564,6 +673,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 and only annotations
+of type object detection are exported. The following example exports the samples in the query
+to a COCO JSON file named `coco_export.json`:
+
+```py
+query.export().to_coco_object_detections()
+```
+
 ### Examples
 
 #### Add Custom Metadata
@@ -625,7 +744,11 @@ samples.
 Set the `LIGHTLY_STUDIO_LICENSE_KEY` environment variable before using selection features:
 
 ```bash
+# On Linux/MacOS
 export LIGHTLY_STUDIO_LICENSE_KEY="license_key_here"
+
+# On Windows (PowerShell)
+$env:LIGHTLY_STUDIO_LICENSE_KEY="license_key_here"
 ```
 
 Alternatively, set it inside your Python script:
@@ -635,7 +758,15 @@ 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.
+Or in a `.env` file:
+
+```
+LIGHTLY_STUDIO_LICENSE_KEY="license_key_here"
+```
+
+#### 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 +784,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
@@ -671,19 +853,27 @@ with open("export.txt", "w") as f:
 
 ## 📚 **FAQ**
 
-### Are the datasets persistent?
+### Does LightlyStudio persist the datasets?
 
-Yes, the information about datasets is persistent and stored in the db file. You can see it after the dataset is processed.
-If you rerun the loader it will create a new dataset representing the same dataset, keeping the previous dataset information untouched.
+Yes, the information about datasets is persisted in a database file. You can see inspect
+it after the dataset is processed. Use `Dataset.load()` to load a dataset from a pre-existing
+database.
 
 ### Can I change the database path?
 
-Not yet. The database is stored in the working directory by default.
+Yes, the database can be selected as follows:
+```py
+import lightly_studio as ls
+
+ls.db_manager.connect(db_file="custom.db")
+```
 
-### Can I launch in another Python script or do I have to do it in the same script?
+### Can I use LightlyStudio from two scripts in parallel?
 
-It is possible to use only one script at the same time because we lock the db file for the duration of the script.
+Only one script can be run at one time as the app uses a database lock for data integrity.
 
-### Can I change the API backend port?
+### Can I change the API backend host and port?
 
-Yes. To change the port set the LIGHTLY_STUDIO_PORT variable to your preffered value. If at runtime the port is unavailable it will try to set it to a random value.
+Yes, by setting environment variables. For the host set the LIGHTLY_STUDIO_HOST variable,
+to change the port set the LIGHTLY_STUDIO_PORT variable. Note that if the port is unavailable
+at runtime the app uses a random port number.