lightly-studio 0.4.6__py3-none-any.whl

lightly_studio/core/dataset_query/sample_field.py

@@ -0,0 +1,37 @@
+"""Fields for querying sample properties in the dataset query system."""
+
+from __future__ import annotations
+
+from sqlmodel import col
+
+from lightly_studio.core.dataset_query.field import (
+    DatetimeField,
+    NumericalField,
+    StringField,
+)
+from lightly_studio.core.dataset_query.tags_expression import TagsAccessor
+from lightly_studio.models.image import ImageTable
+
+
+class SampleField:
+    """Providing access to predefined sample fields for queries.
+
+    It is used for the `query.match(...)` and `query.order_by(...)` methods of the
+    `DatasetQuery` class.
+
+    ```python
+    from lightly_studio.core.dataset_query import DatasetQuery, SampleField, OrderByField
+
+    query = dataset.query()
+    query.match(SampleField.tags.contains("cat"))
+    query.order_by(OrderByField(SampleField.file_path_abs))
+    samples = query.to_list()
+    ```
+    """
+
+    file_name = StringField(col(ImageTable.file_name))
+    width = NumericalField(col(ImageTable.width))
+    height = NumericalField(col(ImageTable.height))
+    file_path_abs = StringField(col(ImageTable.file_path_abs))
+    created_at = DatetimeField(col(ImageTable.created_at))
+    tags = TagsAccessor()

lightly_studio/core/dataset_query/tags_expression.py

@@ -0,0 +1,46 @@
+"""Tag field classes for building dataset queries on sample tags."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy import ColumnElement
+from sqlmodel import col
+
+from lightly_studio.core.dataset_query.match_expression import MatchExpression
+from lightly_studio.models.sample import SampleTable
+from lightly_studio.models.tag import TagTable
+
+
+class TagsAccessor:
+    """Provides access to tag operations for query building.
+
+    This class enables checking tag membership using the contains method:
+    SampleField.tags.contains("tag_name") returns a TagsContainsExpression.
+    """
+
+    def contains(self, tag_name: str) -> TagsContainsExpression:
+        """Check if a tag name is in the sample's tags.
+
+        Args:
+            tag_name: The name of the tag to check for.
+
+        Returns:
+            A TagsContainsExpression for building queries.
+        """
+        return TagsContainsExpression(tag_name=tag_name)
+
+
+@dataclass
+class TagsContainsExpression(MatchExpression):
+    """Expression for checking if a sample contains a specific tag."""
+
+    tag_name: str
+
+    def get(self) -> ColumnElement[bool]:
+        """Get the tag contains expression.
+
+        Returns:
+            The SQLAlchemy expression for this field expression.
+        """
+        return SampleTable.tags.any(col(TagTable.name) == self.tag_name)

lightly_studio/core/image_sample.py

@@ -0,0 +1,36 @@
+"""Definition of ImageSample class, representing a dataset image sample."""
+
+from sqlmodel import col
+
+from lightly_studio.core.sample import DBField, Sample
+from lightly_studio.models.image import ImageTable
+
+
+class ImageSample(Sample):
+    """Interface to a dataset image sample.
+
+    Many properties of the sample are directly accessible as attributes of this class.
+    ```python
+    print(f"Sample file name: {sample.file_name}")
+    print(f"Sample file path: {sample.file_path_abs}")
+    print(f"Sample width: {sample.width}")
+    print(f"Sample height: {sample.height}")
+    ```
+    """
+
+    file_name = DBField(col(ImageTable.file_name))
+    width = DBField(col(ImageTable.width))
+    height = DBField(col(ImageTable.height))
+    file_path_abs = DBField(col(ImageTable.file_path_abs))
+
+    created_at = DBField(col(ImageTable.created_at))
+    updated_at = DBField(col(ImageTable.updated_at))
+
+    def __init__(self, inner: ImageTable) -> None:
+        """Initialize the Sample.
+
+        Args:
+            inner: The ImageTable SQLAlchemy model instance.
+        """
+        self.inner = inner
+        super().__init__(sample_table=inner.sample)

lightly_studio/core/loading_log.py

@@ -0,0 +1,56 @@
+"""Functions to add samples and their annotations to a dataset in the database."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from uuid import UUID
+
+from sqlmodel import Session
+
+from lightly_studio.resolvers import (
+    sample_resolver,
+)
+
+logger = logging.getLogger(__name__)
+
+# Constants
+MAX_EXAMPLE_PATHS_TO_SHOW = 5
+
+
+@dataclass
+class LoadingLoggingContext:
+    """Context for the logging while loading data."""
+
+    n_samples_before_loading: int
+    n_samples_to_be_inserted: int = 0
+    example_paths_not_inserted: list[str] = field(default_factory=list)
+
+    def update_example_paths(self, example_paths_not_inserted: list[str]) -> None:
+        """Update the list of example paths that were not inserted."""
+        if len(self.example_paths_not_inserted) >= MAX_EXAMPLE_PATHS_TO_SHOW:
+            return
+        upper_limit = MAX_EXAMPLE_PATHS_TO_SHOW - len(self.example_paths_not_inserted)
+        self.example_paths_not_inserted.extend(example_paths_not_inserted[:upper_limit])
+
+
+def log_loading_results(
+    session: Session, dataset_id: UUID, logging_context: LoadingLoggingContext
+) -> None:
+    """Log the results of loading samples into a dataset.
+
+    Calculates how many samples were successfully inserted by comparing the
+    current sample count with the count before loading. Prints a summary message
+    and, if any paths failed to be inserted, prints examples of those paths.
+    """
+    n_samples_end = sample_resolver.count_by_dataset_id(session=session, dataset_id=dataset_id)
+    n_samples_inserted = n_samples_end - logging_context.n_samples_before_loading
+    logger.info(
+        f"Added {n_samples_inserted} out of {logging_context.n_samples_to_be_inserted} "
+        "new samples to the dataset."
+    )
+    if logging_context.example_paths_not_inserted:
+        logger.warning(
+            "Examples of paths that were not added: "
+            f"{', '.join(logging_context.example_paths_not_inserted)}"
+        )

lightly_studio/core/sample.py

@@ -0,0 +1,291 @@
+"""Interface for Sample objects."""
+
+from __future__ import annotations
+
+from abc import ABC
+from collections.abc import Iterable
+from typing import Any, Generic, Protocol, TypeVar, cast
+from uuid import UUID
+
+from sqlalchemy.orm import Mapped, object_session
+from sqlmodel import Session
+
+from lightly_studio.models.caption import CaptionCreate
+from lightly_studio.models.sample import SampleTable
+from lightly_studio.resolvers import caption_resolver, metadata_resolver, tag_resolver
+
+T = TypeVar("T")
+
+
+class _DBFieldOwner(Protocol):
+    inner: Any
+
+    def get_object_session(self) -> Session: ...
+
+
+class DBField(Generic[T]):
+    """Descriptor for a database-backed field.
+
+    Provides interface to a SQLAlchemy model field. Setting the field
+    immediately commits to the database. The owner class must implement
+    the inner attribute and the get_object_session() method.
+    """
+
+    __slots__ = ("_sqla_descriptor",)
+    """Store the SQLAlchemy descriptor for accessing the field."""
+
+    def __init__(self, sqla_descriptor: Mapped[T]) -> None:
+        """Initialize the DBField with a SQLAlchemy descriptor."""
+        self._sqla_descriptor = sqla_descriptor
+
+    def __get__(self, obj: _DBFieldOwner | None, owner: type | None = None) -> T:
+        """Get the value of the field from the database."""
+        assert obj is not None, "DBField must be accessed via an instance, not the class"
+        # Delegate to SQLAlchemy's descriptor.
+        value: T = self._sqla_descriptor.__get__(obj.inner, type(obj.inner))
+        return value
+
+    def __set__(self, obj: _DBFieldOwner, value: T) -> None:
+        """Set the value of the field in the database. Commits the session."""
+        # Delegate to SQLAlchemy's descriptor.
+        self._sqla_descriptor.__set__(obj.inner, value)
+        obj.get_object_session().commit()
+
+
+class Sample(ABC):
+    """Interface to a dataset sample.
+
+    It is usually returned by a query to the dataset.
+    ```python
+    for sample in dataset:
+        ...
+    ```
+
+    Access sample's metadata via the `metadata` property, which
+    provides a dictionary-like interface to get and set metadata key-value pairs.
+    ```python
+    some_value = sample.metadata["some_key"]
+    sample.metadata["another_key"] = "new_value"
+    ```
+
+    Access sample's tags via the `tags` property.
+    ```python
+    sample.tags = ["tag1", "tag2"]  # Replace all tags
+    print(f"Current tags: {sample.tags}")
+    sample.add_tag("tag_3")
+    sample.remove_tag("tag_1")
+    ```
+    """
+
+    _sample_table: SampleTable
+
+    @property
+    def sample_id(self) -> UUID:
+        """Sample ID."""
+        return self._sample_table.sample_id
+
+    def __init__(self, sample_table: SampleTable) -> None:
+        """Initialize the Sample.
+
+        Args:
+            sample_table: The SampleTable SQLAlchemy model instance.
+        """
+        self._sample_table = sample_table
+        self._metadata = SampleMetadata(self)
+
+    @property
+    def sample_table(self) -> SampleTable:
+        """Returns the SampleTable associated with this Sample."""
+        # TODO(lukas 12/2025): This should be later removed, as it exposes private implementation.
+        # Remove this once we add a `annotations` property and `embeddings` property.
+        return self._sample_table
+
+    def get_object_session(self) -> Session:
+        """Get the database session for this sample.
+
+        Returns:
+            The SQLModel session.
+
+        Raises:
+            RuntimeError: If no active session is found.
+        """
+        session = object_session(self._sample_table)
+        if session is None:
+            raise RuntimeError("No active session found for the sample")
+        # Cast from SQLAlchemy Session to SQLModel Session for mypy.
+        return cast(Session, session)
+
+    def add_tag(self, name: str) -> None:
+        """Add a tag to this sample.
+
+        If the tag doesn't exist, it will be created first.
+
+        Args:
+            name: The name of the tag to add.
+        """
+        session = self.get_object_session()
+
+        # Get or create the tag for this dataset.
+        tag = tag_resolver.get_or_create_sample_tag_by_name(
+            session=session, dataset_id=self.dataset_id, tag_name=name
+        )
+
+        # Add the tag to the sample if not already associated.
+        if tag not in self.sample_table.tags:
+            tag_resolver.add_tag_to_sample(
+                session=session, tag_id=tag.tag_id, sample=self.sample_table
+            )
+
+    def remove_tag(self, name: str) -> None:
+        """Remove a tag from this sample.
+
+        Args:
+            name: The name of the tag to remove.
+        """
+        session = self.get_object_session()
+
+        # Find the tag by name for this dataset.
+        existing_tag = tag_resolver.get_by_name(
+            session=session, tag_name=name, dataset_id=self.dataset_id
+        )
+
+        # Remove the tag from the sample if it exists and is associated
+        if existing_tag is not None and existing_tag in self.sample_table.tags:
+            tag_resolver.remove_tag_from_sample(
+                session=session, tag_id=existing_tag.tag_id, sample=self.sample_table
+            )
+
+    @property
+    def tags(self) -> set[str]:
+        """Get the tag names associated with this sample.
+
+        Returns:
+            A set of tag names as strings.
+        """
+        return {tag.name for tag in self.sample_table.tags}
+
+    @tags.setter
+    def tags(self, tags: Iterable[str]) -> None:
+        """Set the tags for this sample, replacing any existing tags.
+
+        Args:
+            tags: Iterable of tag names to associate with this sample.
+        """
+        # Get current tag names
+        current_tags = self.tags
+        new_tags = set(tags)
+
+        # Remove tags that are no longer needed
+        tags_to_remove = current_tags - new_tags
+        for tag_name in tags_to_remove:
+            self.remove_tag(tag_name)
+
+        # Add new tags
+        tags_to_add = new_tags - current_tags
+        for tag_name in tags_to_add:
+            self.add_tag(tag_name)
+
+    @property
+    def metadata(self) -> SampleMetadata:
+        """Get dictionary-like access to sample metadata.
+
+        Returns:
+            A dictionary-like object for accessing metadata.
+        """
+        return self._metadata
+
+    @property
+    def dataset_id(self) -> UUID:
+        """Get the dataset ID this sample belongs to.
+
+        Returns:
+            The UUID of the dataset.
+        """
+        return self.sample_table.dataset_id
+
+    def add_caption(self, text: str) -> None:
+        """Add a caption to this sample.
+
+        Args:
+            text: The text of the caption to add.
+        """
+        session = self.get_object_session()
+        caption_resolver.create_many(
+            session=session,
+            parent_dataset_id=self.dataset_id,
+            captions=[
+                CaptionCreate(
+                    parent_sample_id=self.sample_id,
+                    text=text,
+                ),
+            ],
+        )
+
+    @property
+    def captions(self) -> list[str]:
+        """Returns the text of all captions."""
+        return [caption.text for caption in self.sample_table.captions]
+
+    @captions.setter
+    def captions(self, captions: Iterable[str]) -> None:
+        """Set the captions for this sample, replacing any existing captions.
+
+        Args:
+            captions: Iterable of caption texts to associate with this sample.
+        """
+        session = self.get_object_session()
+
+        # Delete all existing captions for this sample
+        caption_sample_ids = [c.sample_id for c in self.sample_table.captions]
+        for caption_sample_id in caption_sample_ids:
+            caption_resolver.delete_caption(session=session, sample_id=caption_sample_id)
+
+        # Create new captions from the provided texts
+        if captions:
+            caption_resolver.create_many(
+                session=session,
+                parent_dataset_id=self.dataset_id,
+                captions=[
+                    CaptionCreate(parent_sample_id=self.sample_id, text=text) for text in captions
+                ],
+            )
+
+
+class SampleMetadata:
+    """Dictionary-like interface for sample metadata."""
+
+    def __init__(self, sample: Sample) -> None:
+        """Initialize SampleMetadata.
+
+        Args:
+            sample: The Sample instance this metadata belongs to.
+        """
+        self._sample = sample
+
+    def __getitem__(self, key: str) -> Any:
+        """Get a metadata value by key.
+
+        Args:
+            key: The metadata key to access.
+
+        Returns:
+            The metadata value for the given key, or None if the key doesn't exist.
+        """
+        if self._sample.sample_table.metadata_dict is None:
+            return None
+        return self._sample.sample_table.metadata_dict.get_value(key)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set a metadata key-value pair.
+
+        Args:
+            key: The metadata key.
+            value: The metadata value.
+        """
+        session = self._sample.get_object_session()
+        metadata_resolver.set_value_for_sample(
+            session=session,
+            sample_id=self._sample.sample_id,
+            key=key,
+            value=value,
+        )

lightly_studio/core/start_gui.py

@@ -0,0 +1,54 @@
+"""Module to launch the GUI."""
+
+from __future__ import annotations
+
+import logging
+
+from lightly_studio import db_manager
+from lightly_studio.api.server import Server
+from lightly_studio.dataset import env
+from lightly_studio.resolvers import dataset_resolver, sample_resolver
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_has_samples() -> None:
+    """Validate that there are samples in the database before starting GUI.
+
+    Raises:
+        ValueError: If no datasets are found or if no samples exist in any dataset.
+    """
+    session = db_manager.persistent_session()
+
+    # Check if any datasets exist
+    datasets = dataset_resolver.get_all(session=session, offset=0, limit=1)
+
+    if not datasets:
+        raise ValueError(
+            "No datasets found. Please load a dataset using Dataset class methods "
+            "(e.g., add_images_from_path(), add_samples_from_yolo(), etc.) "
+            "before starting the GUI."
+        )
+
+    # Check if there are any samples in the first dataset
+    first_dataset = datasets[0]
+    sample_count = sample_resolver.count_by_dataset_id(
+        session=session, dataset_id=first_dataset.dataset_id
+    )
+
+    if sample_count == 0:
+        raise ValueError(
+            "No images have been indexed for the first dataset. "
+            "Please ensure your dataset contains valid images and try loading again."
+        )
+
+
+def start_gui() -> None:
+    """Launch the web interface for the loaded dataset."""
+    _validate_has_samples()
+
+    server = Server(host=env.LIGHTLY_STUDIO_HOST, port=env.LIGHTLY_STUDIO_PORT)
+
+    logger.info(f"Open the LightlyStudio GUI under: {env.APP_URL}")
+
+    server.start()

lightly_studio/core/video_sample.py

@@ -0,0 +1,38 @@
+"""Definition of VideoSample class, representing a dataset video sample."""
+
+from sqlmodel import col
+
+from lightly_studio.core.sample import DBField, Sample
+from lightly_studio.models.video import VideoTable
+
+
+class VideoSample(Sample):
+    """Interface to a dataset video sample.
+
+    Many properties of the sample are directly accessible as attributes of this class.
+    ```python
+    print(f"Sample file name: {sample.file_name}")
+    print(f"Sample file path: {sample.file_path_abs}")
+    print(f"Sample width: {sample.width}")
+    print(f"Sample height: {sample.height}")
+    print(f"Sample duration (seconds): {sample.duration_s}")
+    print(f"Sample FPS: {sample.fps}")
+    ```
+    """
+
+    file_name = DBField(col(VideoTable.file_name))
+    width = DBField(col(VideoTable.width))
+    height = DBField(col(VideoTable.height))
+    file_path_abs = DBField(col(VideoTable.file_path_abs))
+
+    duration_s = DBField(col(VideoTable.duration_s))
+    fps = DBField(col(VideoTable.fps))
+
+    def __init__(self, inner: VideoTable) -> None:
+        """Initialize the Sample.
+
+        Args:
+            inner: The VideoTable SQLAlchemy model instance.
+        """
+        self.inner = inner
+        super().__init__(sample_table=inner.sample)