lightly-studio 0.4.6__py3-none-any.whl

lightly_studio/__init__.py

@@ -0,0 +1,12 @@
+# Set up logging before importing any other modules.
+# Add noqa to silence unused import and unsorted imports linter warnings.
+from . import setup_logging  # noqa: F401 I001
+from lightly_studio.core.dataset import Dataset
+from lightly_studio.core.start_gui import start_gui
+from lightly_studio.models.dataset import SampleType
+
+
+# TODO (Jonas 08/25): This will be removed as soon as the new interface is used in the examples
+from lightly_studio.models.annotation.annotation_base import AnnotationType
+
+__all__ = ["AnnotationType", "Dataset", "SampleType", "start_gui"]

lightly_studio/api/app.py

@@ -0,0 +1,131 @@
+"""This module contains the FastAPI app configuration."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import APIRouter, Depends, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.routing import APIRoute
+from sqlmodel import Session
+from typing_extensions import Annotated
+
+from lightly_studio import db_manager
+from lightly_studio.api.routes import (
+    healthz,
+    images,
+    video_frames_media,
+    video_media,
+    webapp,
+)
+from lightly_studio.api.routes.api import (
+    annotation,
+    annotation_label,
+    caption,
+    classifier,
+    dataset,
+    dataset_tag,
+    embeddings2d,
+    export,
+    features,
+    frame,
+    image,
+    metadata,
+    operator,
+    sample,
+    selection,
+    settings,
+    text_embedding,
+    video,
+)
+from lightly_studio.api.routes.api.exceptions import (
+    register_exception_handlers,
+)
+from lightly_studio.dataset.env import LIGHTLY_STUDIO_DEBUG
+
+SessionDep = Annotated[Session, Depends(db_manager.session)]
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
+    """Lifespan context for initializing and cleaning up resources.
+
+    Args:
+        _: The FastAPI application instance.
+
+    Yields:
+        None when the application is ready.
+    """
+    yield
+
+
+if LIGHTLY_STUDIO_DEBUG:
+    import logging
+
+    # TODO(Lukas, 12/2025): move this into setup_logging.py, drop `basicConfig()`. Also everything
+    # seems to be on the INFO level. `logging.DEBUG` maybe doesn't make a difference.
+    logging.basicConfig()
+    logger = logging.getLogger("sqlalchemy.engine")
+    logger.setLevel(logging.DEBUG)
+
+"""Create the FastAPI app."""
+app = FastAPI(lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def use_route_names_as_operation_ids(app: FastAPI) -> None:
+    """Use API function name for operation IDs.
+
+    Should be called only after all routes have been added.
+    """
+    for route in app.routes:
+        if isinstance(route, APIRoute):
+            route.operation_id = route.name  # in this case, 'read_items'
+
+
+register_exception_handlers(app)
+
+# api routes
+api_router = APIRouter(prefix="/api", tags=["api"])
+
+api_router.include_router(dataset.dataset_router)
+api_router.include_router(dataset_tag.tag_router)
+api_router.include_router(export.export_router)
+api_router.include_router(image.image_router)
+api_router.include_router(sample.sample_router)
+api_router.include_router(annotation_label.annotations_label_router)
+api_router.include_router(annotation.annotations_router)
+api_router.include_router(caption.captions_router)
+api_router.include_router(text_embedding.text_embedding_router)
+api_router.include_router(settings.settings_router)
+api_router.include_router(classifier.classifier_router)
+api_router.include_router(embeddings2d.embeddings2d_router)
+api_router.include_router(features.features_router)
+api_router.include_router(metadata.metadata_router)
+api_router.include_router(selection.selection_router)
+api_router.include_router(operator.operator_router)
+api_router.include_router(frame.frame_router)
+api_router.include_router(video.video_router)
+
+app.include_router(api_router)
+
+# images serving
+app.include_router(images.app_router, prefix="/images")
+app.include_router(video_frames_media.frames_router)
+app.include_router(video_media.app_router)
+
+# health status check
+app.include_router(healthz.health_router)
+
+# webapp routes
+app.include_router(webapp.app_router)
+
+use_route_names_as_operation_ids(app)

lightly_studio/api/cache.py

@@ -0,0 +1,77 @@
+"""This module contains the FastAPI cache configuration for static files."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from os import PathLike, stat_result
+
+from fastapi import Response
+from fastapi.staticfiles import StaticFiles
+from starlette.types import Scope
+
+from .routes.api.status import HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE
+
+
+class StaticFilesCache(StaticFiles):
+    """StaticFiles class with cache headers."""
+
+    days_to_expire = 1
+
+    def __init__(  # noqa: PLR0913 (too-many-arguments)
+        self,
+        *,
+        directory: str | PathLike[str] | None = None,
+        packages: list[str | tuple[str, str]] | None = None,
+        html: bool = False,
+        check_dir: bool = True,
+        follow_symlink: bool = False,
+        cachecontrol: str | None = None,
+    ) -> None:
+        """Initialize the StaticFilesCache class."""
+        self.cachecontrol = cachecontrol or f"private, max-age={self.days_to_expire * 24 * 60 * 60}"
+        super().__init__(
+            directory=directory,
+            packages=packages,
+            html=html,
+            check_dir=check_dir,
+            follow_symlink=follow_symlink,
+        )
+
+    def file_response(
+        self,
+        full_path: str | PathLike[str],
+        stat_result: stat_result,
+        scope: Scope,
+        status_code: int = 200,
+    ) -> Response:
+        """Override the file_response method to add cache headers."""
+        allowed_extensions = (
+            # Images
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".webp",
+            ".bmp",
+            ".tiff",
+            # Movies
+            ".mov",
+            ".mp4",
+            ".avi",
+        )
+
+        if not str(full_path).lower().endswith(allowed_extensions):
+            return Response(
+                status_code=HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE
+            )  # Unsupported Media Type
+        resp: Response = super().file_response(full_path, stat_result, scope, status_code)
+        resp.headers.setdefault("Cache-Control", self.cachecontrol)
+
+        # Calculate expiration date
+        expire_date = datetime.now(timezone.utc) + timedelta(days=self.days_to_expire)
+        resp.headers.setdefault("Expires", expire_date.strftime("%a, %d %b %Y %H:%M:%S GMT"))
+
+        # Add Vary header to make sure caches respect the query parameters
+        resp.headers.setdefault("Vary", "Accept-Encoding, Origin, v")
+
+        return resp

lightly_studio/api/db_tables.py

@@ -0,0 +1,35 @@
+"""Module provides functions to initialize and manage the DuckDB."""
+
+from lightly_studio.models.annotation.annotation_base import (
+    AnnotationBaseTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.annotation_label import (
+    AnnotationLabelTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.dataset import (
+    DatasetTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.embedding_model import (
+    EmbeddingModelTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.image import (
+    ImageTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.metadata import (
+    SampleMetadataTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.sample import (
+    SampleTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.sample_embedding import (
+    SampleEmbeddingTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.settings import (
+    SettingTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.tag import (
+    TagTable,  # noqa: F401, required for SQLModel to work properly
+)
+from lightly_studio.models.two_dim_embedding import (
+    TwoDimEmbeddingTable,  # noqa: F401, required for SQLModel to work properly
+)

lightly_studio/api/features.py

@@ -0,0 +1,5 @@
+"""Global list of the active features."""
+
+from __future__ import annotations
+
+lightly_studio_active_features: list[str] = []

lightly_studio/api/routes/api/annotation.py

@@ -0,0 +1,305 @@
+"""This module contains the API routes for managing annotations."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Path
+from fastapi.params import Query
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api import annotations as annotations_module
+from lightly_studio.api.routes.api.dataset import get_and_validate_dataset_id
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_CREATED,
+    HTTP_STATUS_NOT_FOUND,
+)
+from lightly_studio.api.routes.api.validators import Paginated, PaginatedWithCursor
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.annotation.annotation_base import (
+    AnnotationBaseTable,
+    AnnotationDetailsWithPayloadView,
+    AnnotationView,
+    AnnotationViewsWithCount,
+    AnnotationWithPayloadAndCountView,
+)
+from lightly_studio.models.dataset import DatasetTable
+from lightly_studio.resolvers import annotation_resolver, tag_resolver
+from lightly_studio.resolvers.annotation_resolver.get_all import (
+    GetAllAnnotationsResult,
+)
+from lightly_studio.resolvers.annotation_resolver.update_bounding_box import BoundingBoxCoordinates
+from lightly_studio.resolvers.annotations.annotations_filter import (
+    AnnotationsFilter,
+)
+from lightly_studio.services import annotations_service
+from lightly_studio.services.annotations_service.update_annotation import (
+    AnnotationUpdate,
+)
+
+annotations_router = APIRouter(prefix="/datasets/{dataset_id}", tags=["annotations"])
+annotations_router.include_router(annotations_module.create_annotation_router)
+
+
+class AnnotationQueryParamsModel(BaseModel):
+    """Model for all annotation query parameters."""
+
+    pagination: PaginatedWithCursor
+    annotation_label_ids: list[UUID] | None = None
+    tag_ids: list[UUID] | None = None
+
+
+def _get_annotation_query_params(
+    pagination: Annotated[PaginatedWithCursor, Depends()],
+    annotation_label_ids: Annotated[list[UUID] | None, Query()] = None,
+    tag_ids: Annotated[list[UUID] | None, Query()] = None,
+) -> AnnotationQueryParamsModel:
+    return AnnotationQueryParamsModel(
+        pagination=pagination,
+        annotation_label_ids=annotation_label_ids,
+        tag_ids=tag_ids,
+    )
+
+
+@annotations_router.get("/annotations/count")
+def count_annotations_by_dataset(  # noqa: PLR0913 // FIXME: refactor to use proper pydantic
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    session: SessionDep,
+    filtered_labels: Annotated[list[str] | None, Query()] = None,
+    min_width: Annotated[int | None, Query(ge=0)] = None,
+    max_width: Annotated[int | None, Query(ge=0)] = None,
+    min_height: Annotated[int | None, Query(ge=0)] = None,
+    max_height: Annotated[int | None, Query(ge=0)] = None,
+    tag_ids: list[UUID] | None = None,
+) -> list[dict[str, str | int]]:
+    """Get annotation counts for a specific dataset.
+
+    Returns a list of dictionaries with label name and count.
+    """
+    counts = annotation_resolver.count_annotations_by_dataset(
+        session=session,
+        dataset_id=dataset.dataset_id,
+        filtered_labels=filtered_labels,
+        min_width=min_width,
+        max_width=max_width,
+        min_height=min_height,
+        max_height=max_height,
+        tag_ids=tag_ids,
+    )
+
+    return [
+        {
+            "label_name": label_name,
+            "current_count": current_count,
+            "total_count": total_count,
+        }
+        for label_name, current_count, total_count in counts
+    ]
+
+
+@annotations_router.get(
+    "/annotations",
+    response_model=AnnotationViewsWithCount,
+)
+def read_annotations(
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],
+    session: SessionDep,
+    pagination: Annotated[PaginatedWithCursor, Depends()],
+    annotation_label_ids: Annotated[list[UUID] | None, Query()] = None,
+    tag_ids: Annotated[list[UUID] | None, Query()] = None,
+) -> GetAllAnnotationsResult:
+    """Retrieve a list of annotations from the database."""
+    return annotation_resolver.get_all(
+        session=session,
+        pagination=Paginated(
+            offset=pagination.offset,
+            limit=pagination.limit,
+        ),
+        filters=AnnotationsFilter(
+            dataset_ids=[dataset_id],
+            annotation_label_ids=annotation_label_ids,
+            annotation_tag_ids=tag_ids,
+        ),
+    )
+
+
+@annotations_router.get(
+    "/annotations/payload",
+)
+def read_annotations_with_payload(
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],
+    session: SessionDep,
+    params: Annotated[AnnotationQueryParamsModel, Depends(_get_annotation_query_params)],
+) -> AnnotationWithPayloadAndCountView:
+    """Retrieve a list of annotations along with the parent sample data from the database."""
+    return annotation_resolver.get_all_with_payload(
+        session=session,
+        pagination=Paginated(
+            offset=params.pagination.offset,
+            limit=params.pagination.limit,
+        ),
+        filters=AnnotationsFilter(
+            dataset_ids=[dataset_id],
+            annotation_label_ids=params.annotation_label_ids,
+            annotation_tag_ids=params.tag_ids,
+        ),
+        dataset_id=dataset_id,
+    )
+
+
+@annotations_router.post(
+    "/annotations/{annotation_id}/tag/{tag_id}",
+    status_code=HTTP_STATUS_CREATED,
+)
+def add_tag_to_annotation(
+    session: SessionDep,
+    annotation_id: UUID,
+    tag_id: UUID,
+) -> bool:
+    """Add annotation to a tag."""
+    annotation = annotation_resolver.get_by_id(session=session, annotation_id=annotation_id)
+    if not annotation:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Annotation {annotation_id} not found",
+        )
+
+    if not tag_resolver.add_tag_to_annotation(
+        session=session, tag_id=tag_id, annotation=annotation
+    ):
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail=f"Tag {tag_id} not found")
+
+    return True
+
+
+class AnnotationUpdateInput(BaseModel):
+    """API input model for updating an annotation."""
+
+    annotation_id: UUID
+    dataset_id: UUID
+    label_name: str | None = None
+    bounding_box: BoundingBoxCoordinates | None = None
+
+
+@annotations_router.put("/annotations/{annotation_id}")
+def update_annotation(
+    session: SessionDep,
+    dataset_id: Annotated[
+        UUID,
+        Path(title="Dataset Id"),
+    ],
+    annotation_id: Annotated[
+        UUID,
+        Path(title="Annotation ID", description="ID of the annotation to update"),
+    ],
+    annotation_update_input: Annotated[AnnotationUpdateInput, Body()],
+) -> AnnotationBaseTable:
+    """Update an existing annotation in the database."""
+    return annotations_service.update_annotation(
+        session=session,
+        annotation_update=AnnotationUpdate(
+            annotation_id=annotation_id,
+            dataset_id=dataset_id,
+            label_name=annotation_update_input.label_name,
+            bounding_box=annotation_update_input.bounding_box,
+        ),
+    )
+
+
+@annotations_router.put(
+    "/annotations",
+)
+def update_annotations(
+    session: SessionDep,
+    dataset_id: Annotated[
+        UUID,
+        Path(title="Dataset Id"),
+    ],
+    annotation_update_inputs: Annotated[list[AnnotationUpdateInput], Body()],
+) -> list[AnnotationBaseTable]:
+    """Update multiple annotations in the database."""
+    return annotations_service.update_annotations(
+        session=session,
+        annotation_updates=[
+            AnnotationUpdate(
+                annotation_id=annotation_update_input.annotation_id,
+                dataset_id=dataset_id,
+                label_name=annotation_update_input.label_name,
+                bounding_box=annotation_update_input.bounding_box,
+            )
+            for annotation_update_input in annotation_update_inputs
+        ],
+    )
+
+
+@annotations_router.get("/annotations/{annotation_id}", response_model=AnnotationView)
+def get_annotation(
+    session: SessionDep,
+    dataset_id: Annotated[  # noqa: ARG001
+        UUID,
+        Path(title="Dataset Id", description="The ID of the dataset"),
+    ],  # We need dataset_id because otherwise the path would not match
+    annotation_id: Annotated[UUID, Path(title="Annotation ID")],
+) -> AnnotationBaseTable:
+    """Retrieve an existing annotation from the database."""
+    return annotations_service.get_annotation_by_id(session=session, annotation_id=annotation_id)
+
+
+@annotations_router.delete("/annotations/{annotation_id}/tag/{tag_id}")
+def remove_tag_from_annotation(
+    session: SessionDep,
+    tag_id: UUID,
+    annotation_id: UUID,
+) -> bool:
+    """Remove annotation from a tag."""
+    annotation = annotation_resolver.get_by_id(session=session, annotation_id=annotation_id)
+    if not annotation:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Annotation {annotation_id} not found",
+        )
+
+    if not tag_resolver.remove_tag_from_annotation(
+        session=session, tag_id=tag_id, annotation=annotation
+    ):
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail=f"Tag {tag_id} not found")
+
+    return True
+
+
+@annotations_router.delete("/annotations/{annotation_id}")
+def delete_annotation(
+    session: SessionDep,
+    # We need dataset_id because generator doesn't include it
+    # actuall path for this route is /datasets/{dataset_id}/annotations/{annotation_id}
+    dataset_id: Annotated[  # noqa: ARG001
+        UUID,
+        Path(title="Dataset Id", description="The ID of the dataset"),
+    ],
+    annotation_id: Annotated[
+        UUID, Path(title="Annotation ID", description="ID of the annotation to delete")
+    ],
+) -> dict[str, str]:
+    """Delete an annotation from the database."""
+    try:
+        annotations_service.delete_annotation(session=session, annotation_id=annotation_id)
+        return {"status": "deleted"}
+    except ValueError as e:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail="Annotation not found",
+        ) from e
+
+
+@annotations_router.get("/annotations/payload/{sample_id}")
+def get_annotation_with_payload(
+    session: SessionDep,
+    sample_id: Annotated[UUID, Path(title="Annotation ID")],
+) -> AnnotationDetailsWithPayloadView | None:
+    """Retrieve an existing annotation with payload from the database."""
+    return annotation_resolver.get_by_id_with_payload(session=session, sample_id=sample_id)

lightly_studio/api/routes/api/annotation_label.py

@@ -0,0 +1,87 @@
+"""This module contains the API routes for managing annotation labels."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException
+
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_CREATED,
+    HTTP_STATUS_NOT_FOUND,
+)
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.annotation_label import (
+    AnnotationLabelCreate,
+    AnnotationLabelTable,
+)
+from lightly_studio.resolvers import annotation_label_resolver
+
+annotations_label_router = APIRouter()
+
+
+@annotations_label_router.post(
+    "/annotation_labels",
+    status_code=HTTP_STATUS_CREATED,
+)
+def create_annotation_label(
+    input_label: AnnotationLabelCreate,
+    session: SessionDep,
+) -> AnnotationLabelTable:
+    """Create a new annotation label in the database."""
+    return annotation_label_resolver.create(session=session, label=input_label)
+
+
+@annotations_label_router.get("/annotation_labels")
+def read_annotation_labels(
+    session: SessionDep,
+) -> list[AnnotationLabelTable]:
+    """Retrieve a list of annotation labels from the database."""
+    return annotation_label_resolver.get_all(session=session)
+
+
+@annotations_label_router.get("/annotation_labels/{label_id}")
+def read_annotation_label(
+    label_id: UUID,
+    session: SessionDep,
+) -> AnnotationLabelTable:
+    """Retrieve a single annotation label from the database."""
+    label = annotation_label_resolver.get_by_id(session=session, label_id=label_id)
+    if not label:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail="Annotation label not found",
+        )
+    return label
+
+
+@annotations_label_router.put("/annotation_labels/{label_id}")
+def update_annotation_label(
+    label_id: UUID,
+    label_input: AnnotationLabelCreate,
+    session: SessionDep,
+) -> AnnotationLabelTable:
+    """Update an existing annotation label in the database."""
+    label = annotation_label_resolver.update(
+        session=session, label_id=label_id, label_data=label_input
+    )
+    if not label:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail="Annotation label not found",
+        )
+    return label
+
+
+@annotations_label_router.delete("/annotation_labels/{label_id}")
+def delete_annotation_label(
+    label_id: UUID,
+    session: SessionDep,
+) -> dict[str, str]:
+    """Delete an annotation label from the database."""
+    if not annotation_label_resolver.delete(session=session, label_id=label_id):
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail="Annotation label not found",
+        )
+    return {"status": "deleted"}

lightly_studio/api/routes/api/annotations/__init__.py

@@ -0,0 +1,7 @@
+from .create_annotation import (
+    create_annotation_router,
+)
+
+__all__ = [
+    "create_annotation_router",
+]