lightly-studio 0.4.6__py3-none-any.whl

lightly_studio/api/routes/api/export.py

@@ -0,0 +1,114 @@
+"""API routes for exporting dataset annotation tasks."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from pathlib import Path as PathlibPath
+from tempfile import TemporaryDirectory
+
+from fastapi import APIRouter, Depends, Path
+from fastapi.responses import StreamingResponse
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api import dataset as dataset_api
+from lightly_studio.core.dataset_query.dataset_query import DatasetQuery
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.export import export_dataset
+from lightly_studio.models.dataset import DatasetTable
+
+export_router = APIRouter(prefix="/datasets/{dataset_id}", tags=["export"])
+
+
+@export_router.get("/export/annotations")
+def export_dataset_annotations(
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(dataset_api.get_and_validate_dataset_id),
+    ],
+    session: SessionDep,
+) -> StreamingResponse:
+    """Export dataset annotations for an object detection task in COCO format."""
+    # Query to export - all samples in the dataset.
+    dataset_query = DatasetQuery(dataset=dataset, session=session)
+
+    # Create the export in a temporary directory. We cannot use a context manager
+    # because the directory should be deleted only after the file has finished streaming.
+    temp_dir = TemporaryDirectory()
+    output_path = PathlibPath(temp_dir.name) / "coco_export.json"
+
+    try:
+        export_dataset.to_coco_object_detections(
+            session=session,
+            samples=dataset_query,
+            output_json=output_path,
+        )
+    except Exception:
+        temp_dir.cleanup()
+        # Reraise.
+        raise
+
+    return StreamingResponse(
+        content=_stream_export_file(
+            temp_dir=temp_dir,
+            file_path=output_path,
+        ),
+        media_type="application/json",
+        headers={
+            "Access-Control-Expose-Headers": "Content-Disposition",
+            "Content-Disposition": f"attachment; filename={output_path.name}",
+        },
+    )
+
+
+@export_router.get("/export/captions")
+def export_dataset_captions(
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(dataset_api.get_and_validate_dataset_id),
+    ],
+    session: SessionDep,
+) -> StreamingResponse:
+    """Export dataset captions in COCO format."""
+    # Query to export - all samples in the dataset.
+    dataset_query = DatasetQuery(dataset=dataset, session=session)
+
+    # Create the export in a temporary directory. We cannot use a context manager
+    # because the directory should be deleted only after the file has finished streaming.
+    temp_dir = TemporaryDirectory()
+    output_path = PathlibPath(temp_dir.name) / "coco_captions_export.json"
+
+    try:
+        export_dataset.to_coco_captions(
+            samples=dataset_query,
+            output_json=output_path,
+        )
+    except Exception:
+        temp_dir.cleanup()
+        # Reraise.
+        raise
+
+    return StreamingResponse(
+        content=_stream_export_file(
+            temp_dir=temp_dir,
+            file_path=output_path,
+        ),
+        media_type="application/json",
+        headers={
+            "Access-Control-Expose-Headers": "Content-Disposition",
+            "Content-Disposition": f"attachment; filename={output_path.name}",
+        },
+    )
+
+
+def _stream_export_file(
+    temp_dir: TemporaryDirectory[str],
+    file_path: PathlibPath,
+) -> Generator[bytes, None, None]:
+    """Stream the export file and clean up the temporary directory afterwards."""
+    try:
+        with file_path.open("rb") as file:
+            yield from file
+    finally:
+        temp_dir.cleanup()

lightly_studio/api/routes/api/features.py

@@ -0,0 +1,17 @@
+"""This module contains the API routes for active features."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from lightly_studio.api.features import lightly_studio_active_features
+
+__all__ = ["features_router", "lightly_studio_active_features"]
+
+features_router = APIRouter()
+
+
+@features_router.get("/features")
+def get_features() -> list[str]:
+    """Get the list of active features in the LightlyStudio app."""
+    return lightly_studio_active_features

lightly_studio/api/routes/api/frame.py

@@ -0,0 +1,241 @@
+"""API routes for dataset frames."""
+
+from __future__ import annotations
+
+from typing import List
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Path
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+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, AnnotationView
+from lightly_studio.models.annotation.instance_segmentation import (
+    InstanceSegmentationAnnotationView,
+)
+from lightly_studio.models.annotation.object_detection import ObjectDetectionAnnotationView
+from lightly_studio.models.annotation.semantic_segmentation import (
+    SemanticSegmentationAnnotationView,
+)
+from lightly_studio.models.sample import SampleTable, SampleView
+from lightly_studio.models.video import (
+    FrameView,
+    VideoFrameFieldsBoundsView,
+    VideoFrameTable,
+    VideoFrameView,
+    VideoFrameViewsWithCount,
+    VideoTable,
+    VideoView,
+)
+from lightly_studio.resolvers import video_frame_resolver
+from lightly_studio.resolvers.video_frame_resolver.video_frame_annotations_counter_filter import (
+    VideoFrameAnnotationsCounterFilter,
+)
+from lightly_studio.resolvers.video_frame_resolver.video_frame_filter import (
+    VideoFrameFilter,
+)
+from lightly_studio.resolvers.video_resolver.count_video_frame_annotations_by_video_dataset import (
+    CountAnnotationsView,
+)
+
+frame_router = APIRouter(prefix="/datasets/{video_frame_dataset_id}/frame", tags=["frame"])
+
+
+class ReadVideoFramesRequest(BaseModel):
+    """Request body for reading videos."""
+
+    filter: VideoFrameFilter | None = Field(None, description="Filter parameters for video frames")
+
+
+class ReadCountVideoFramesAnnotationsRequest(BaseModel):
+    """Request body for reading video frames annotations counter."""
+
+    filter: VideoFrameAnnotationsCounterFilter | None = Field(
+        None, description="Filter parameters for video frames annotations counter"
+    )
+
+
+@frame_router.post("/", response_model=VideoFrameViewsWithCount)
+def get_all_frames(
+    video_frame_dataset_id: Annotated[UUID, Path(title="Video dataset Id")],
+    session: SessionDep,
+    pagination: Annotated[PaginatedWithCursor, Depends()],
+    body: ReadVideoFramesRequest,
+) -> VideoFrameViewsWithCount:
+    """Retrieve a list of all frames for a given dataset ID with pagination.
+
+    Args:
+        session: The database session.
+        video_frame_dataset_id: The ID of the dataset to retrieve frames for.
+        pagination: Pagination parameters including offset and limit.
+        body: The body containing the filters
+    Returns:
+        A list of frames along with the total count.
+    """
+    result = video_frame_resolver.get_all_by_dataset_id(
+        session=session,
+        dataset_id=video_frame_dataset_id,
+        pagination=Paginated(offset=pagination.offset, limit=pagination.limit),
+        video_frame_filter=body.filter,
+    )
+
+    return VideoFrameViewsWithCount(
+        samples=[_build_video_frame_view(vf=frame) for frame in result.samples],
+        total_count=result.total_count,
+        next_cursor=result.next_cursor,
+    )
+
+
+@frame_router.get("/bounds")
+def get_video_frames_fields_bounds(
+    session: SessionDep,
+    video_frame_dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+) -> VideoFrameFieldsBoundsView | None:
+    """Retrieve the video fields bounds for a given dataset ID.
+
+    Args:
+        session: The database session.
+        video_frame_dataset_id: The ID of the dataset to retrieve video frames bounds.
+        body: The body containg the filters.
+
+    Returns:
+        A video frame fields bounds object.
+    """
+    return video_frame_resolver.get_table_fields_bounds(
+        dataset_id=video_frame_dataset_id,
+        session=session,
+    )
+
+
+@frame_router.get("/{sample_id}", response_model=VideoFrameView)
+def get_frame_by_id(
+    session: SessionDep,
+    sample_id: Annotated[UUID, Path(title="Sample Id")],
+) -> VideoFrameView:
+    """Retrieve a frame by its sample ID within a given dataset.
+
+    Args:
+        session: The database session.
+        sample_id: The ID of the sample to retrieve.
+
+    Returns:
+        A frame corresponding to the given sample ID.
+    """
+    result = video_frame_resolver.get_by_id(session=session, sample_id=sample_id)
+
+    return _build_video_frame_view(result)
+
+
+@frame_router.post("/annotations/count", response_model=List[CountAnnotationsView])
+def count_video_frame_annotations(
+    session: SessionDep,
+    video_frame_dataset_id: Annotated[UUID, Path(title="Video dataset Id")],
+    body: ReadCountVideoFramesAnnotationsRequest,
+) -> list[CountAnnotationsView]:
+    """Retrieve a list of annotations along with total count and filtered count.
+
+    Args:
+        session: The database session.
+        video_frame_dataset_id: The ID of the dataset to retrieve videos for.
+        body: The body containing filters.
+
+    Returns:
+        A list of annotations and counters.
+    """
+    return video_frame_resolver.count_video_frames_annotations(
+        session=session,
+        dataset_id=video_frame_dataset_id,
+        filters=body.filter,
+    )
+
+
+# TODO (Leonardo 11/25): These manual conversions are needed because
+# of the circular import between Annotation and Sample.
+def _build_annotation_view(a: AnnotationBaseTable) -> AnnotationView:
+    return AnnotationView(
+        parent_sample_id=a.parent_sample_id,
+        sample_id=a.sample_id,
+        annotation_type=a.annotation_type,
+        confidence=a.confidence,
+        created_at=a.created_at,
+        annotation_label=AnnotationView.AnnotationLabel(
+            annotation_label_name=a.annotation_label.annotation_label_name
+        ),
+        object_detection_details=(
+            ObjectDetectionAnnotationView(
+                x=a.object_detection_details.x,
+                y=a.object_detection_details.y,
+                width=a.object_detection_details.width,
+                height=a.object_detection_details.height,
+            )
+            if a.object_detection_details
+            else None
+        ),
+        instance_segmentation_details=(
+            InstanceSegmentationAnnotationView(
+                width=a.instance_segmentation_details.width,
+                height=a.instance_segmentation_details.height,
+                x=a.instance_segmentation_details.x,
+                y=a.instance_segmentation_details.y,
+            )
+            if a.instance_segmentation_details
+            else None
+        ),
+        semantic_segmentation_details=(
+            SemanticSegmentationAnnotationView(
+                segmentation_mask=a.semantic_segmentation_details.segmentation_mask,
+            )
+            if a.semantic_segmentation_details
+            else None
+        ),
+        tags=[AnnotationView.AnnotationViewTag(tag_id=t.tag_id, name=t.name) for t in a.tags],
+        sample=_build_sample_view(a.sample),
+    )
+
+
+def _build_sample_view(sample: SampleTable) -> SampleView:
+    return SampleView(
+        dataset_id=sample.dataset_id,
+        sample_id=sample.sample_id,
+        created_at=sample.created_at,
+        updated_at=sample.updated_at,
+        tags=sample.tags,
+        metadata_dict=sample.metadata_dict,
+        captions=sample.captions,
+        annotations=[_build_annotation_view(a) for a in sample.annotations],
+    )
+
+
+def _build_video_view(video: VideoTable) -> VideoView:
+    return VideoView(
+        width=video.width,
+        height=video.height,
+        duration_s=video.duration_s,
+        fps=video.fps,
+        file_name=video.file_name,
+        file_path_abs=video.file_path_abs,
+        sample_id=video.sample_id,
+        sample=_build_sample_view(video.sample),
+    )
+
+
+def _build_video_frame_view(vf: VideoFrameTable) -> VideoFrameView:
+    return VideoFrameView(
+        frame_number=vf.frame_number,
+        frame_timestamp_s=vf.frame_timestamp_s,
+        sample_id=vf.sample_id,
+        video=_build_video_view(vf.video),
+        sample=_build_sample_view(vf.sample),
+    )
+
+
+def build_frame_view(vf: VideoFrameTable) -> FrameView:
+    """Create a FrameView."""
+    return FrameView(
+        frame_number=vf.frame_number,
+        frame_timestamp_s=vf.frame_timestamp_s,
+        sample_id=vf.sample_id,
+        sample=_build_sample_view(vf.sample),
+    )

lightly_studio/api/routes/api/image.py

@@ -0,0 +1,155 @@
+"""This module contains the API routes for managing samples."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api.dataset import get_and_validate_dataset_id
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_NOT_FOUND,
+)
+from lightly_studio.api.routes.api.validators import Paginated
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.dataset import DatasetTable
+from lightly_studio.models.image import (
+    ImageView,
+    ImageViewsWithCount,
+)
+from lightly_studio.resolvers import (
+    image_resolver,
+)
+from lightly_studio.resolvers.image_filter import (
+    ImageFilter,
+)
+
+image_router = APIRouter(prefix="/datasets/{dataset_id}", tags=["image"])
+
+
+class ReadImagesRequest(BaseModel):
+    """Request body for reading samples with text embedding."""
+
+    filters: ImageFilter | None = Field(None, description="Filter parameters for samples")
+    text_embedding: list[float] | None = Field(None, description="Text embedding to search for")
+    sample_ids: list[UUID] | None = Field(None, description="The list of requested sample IDs")
+    pagination: Paginated | None = Field(
+        None, description="Pagination parameters for offset and limit"
+    )
+
+
+@image_router.post("/images/list")
+def read_images(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+    body: ReadImagesRequest,
+) -> ImageViewsWithCount:
+    """Retrieve a list of samples from the database with optional filtering.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset to filter samples by.
+        body: Optional request body containing text embedding.
+
+    Returns:
+        A list of filtered samples.
+    """
+    result = image_resolver.get_all_by_dataset_id(
+        session=session,
+        dataset_id=dataset_id,
+        pagination=body.pagination,
+        filters=body.filters,
+        text_embedding=body.text_embedding,
+        sample_ids=body.sample_ids,
+    )
+    # TODO(Michal, 10/2025): Add SampleView to ImageView and then use a response model
+    # instead of manual conversion.
+    return ImageViewsWithCount(
+        samples=[
+            ImageView(
+                file_name=image.file_name,
+                file_path_abs=image.file_path_abs,
+                sample_id=image.sample_id,
+                annotations=image.sample.annotations,
+                captions=image.sample.captions,
+                tags=[
+                    ImageView.ImageViewTag(
+                        tag_id=tag.tag_id,
+                        name=tag.name,
+                        kind=tag.kind,
+                        created_at=tag.created_at,
+                        updated_at=tag.updated_at,
+                    )
+                    for tag in image.sample.tags
+                ],
+                metadata_dict=image.sample.metadata_dict,
+                width=image.width,
+                height=image.height,
+                sample=image.sample,
+            )
+            for image in result.samples
+        ],
+        total_count=result.total_count,
+        next_cursor=result.next_cursor,
+    )
+
+
+@image_router.get("/images/dimensions")
+def get_image_dimensions(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    annotation_label_ids: Annotated[list[UUID] | None, Query()] = None,
+) -> dict[str, int]:
+    """Get min and max dimensions of samples in a dataset."""
+    return image_resolver.get_dimension_bounds(
+        session=session,
+        dataset_id=dataset.dataset_id,
+        annotation_label_ids=annotation_label_ids,
+    )
+
+
+@image_router.get("/images/{sample_id}")
+def read_image(
+    session: SessionDep,
+    sample_id: Annotated[UUID, Path(title="Sample Id")],
+) -> ImageView:
+    """Retrieve a single sample from the database."""
+    image = image_resolver.get_by_id(session=session, sample_id=sample_id)
+    if not image:
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail="Sample not found")
+    # TODO(Michal, 10/2025): Add SampleView to ImageView and then use a response model
+    # instead of manual conversion.
+    return ImageView(
+        file_name=image.file_name,
+        file_path_abs=image.file_path_abs,
+        sample_id=image.sample_id,
+        annotations=image.sample.annotations,
+        captions=image.sample.captions,
+        tags=[
+            ImageView.ImageViewTag(
+                tag_id=tag.tag_id,
+                name=tag.name,
+                kind=tag.kind,
+                created_at=tag.created_at,
+                updated_at=tag.updated_at,
+            )
+            for tag in image.sample.tags
+        ],
+        metadata_dict=image.sample.metadata_dict,
+        width=image.width,
+        height=image.height,
+        sample=image.sample,
+    )
+
+
+class SampleAdjacentsParams(BaseModel):
+    """Parameters for getting adjacent samples."""
+
+    filters: ImageFilter | None = None
+    text_embedding: list[float] | None = None

lightly_studio/api/routes/api/metadata.py

@@ -0,0 +1,161 @@
+"""This module contains the API routes for managing datasets."""
+
+from __future__ import annotations
+
+from typing import List
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api.dataset import get_and_validate_dataset_id
+from lightly_studio.api.routes.api.status import HTTP_STATUS_NOT_FOUND
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.errors import TagNotFoundError
+from lightly_studio.metadata import compute_similarity, compute_typicality
+from lightly_studio.models.dataset import DatasetTable
+from lightly_studio.models.metadata import MetadataInfoView
+from lightly_studio.resolvers import embedding_model_resolver
+from lightly_studio.resolvers.metadata_resolver.sample.get_metadata_info import (
+    get_all_metadata_keys_and_schema,
+)
+
+metadata_router = APIRouter(prefix="/datasets/{dataset_id}", tags=["metadata"])
+
+
+@metadata_router.get("/metadata/info", response_model=List[MetadataInfoView])
+def get_metadata_info(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+) -> list[MetadataInfoView]:
+    """Get all metadata keys and their schema for a dataset.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset.
+
+    Returns:
+        List of metadata info objects with name, type, and optionally min/max values
+        for numerical metadata types.
+    """
+    return get_all_metadata_keys_and_schema(session=session, dataset_id=dataset_id)
+
+
+class ComputeTypicalityRequest(BaseModel):
+    """Request model for computing typicality metadata."""
+
+    embedding_model_name: str | None = Field(
+        default=None,
+        description="Embedding model name (uses default if not specified)",
+    )
+    metadata_name: str = Field(
+        default="typicality",
+        description="Metadata field name (defaults to 'typicality')",
+    )
+
+
+@metadata_router.post(
+    "/metadata/typicality",
+    status_code=204,
+    response_model=None,
+)
+def compute_typicality_metadata(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Depends(get_and_validate_dataset_id),
+    ],
+    request: ComputeTypicalityRequest,
+) -> None:
+    """Compute typicality metadata for a dataset.
+
+    Args:
+        session: The database session.
+        dataset: The dataset to compute typicality for.
+        request: Request parameters including optional embedding model name
+            and metadata field name.
+
+    Returns:
+        None (204 No Content on success).
+    """
+    embedding_model = embedding_model_resolver.get_by_name(
+        session=session,
+        dataset_id=dataset.dataset_id,
+        embedding_model_name=request.embedding_model_name,
+    )
+
+    compute_typicality.compute_typicality_metadata(
+        session=session,
+        dataset_id=dataset.dataset_id,
+        embedding_model_id=embedding_model.embedding_model_id,
+        metadata_name=request.metadata_name,
+    )
+
+
+class ComputeSimilarityRequest(BaseModel):
+    """Request model for computing typicality metadata."""
+
+    embedding_model_name: str | None = Field(
+        default=None,
+        description="Embedding model name (uses default if not specified)",
+    )
+    metadata_name: str | None = Field(
+        default=None,
+        description="Metadata field name (defaults to None)",
+    )
+
+
+@metadata_router.post(
+    "/metadata/similarity/{query_tag_id}",
+    response_model=str,
+)
+def compute_similarity_metadata(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Depends(get_and_validate_dataset_id),
+    ],
+    query_tag_id: Annotated[UUID, Path(title="Query Tag ID")],
+    request: ComputeSimilarityRequest,
+) -> str:
+    """Compute similarity metadata for a dataset.
+
+    Args:
+        session: The database session.
+        dataset: The dataset to compute similarity for.
+        query_tag_id: The ID of the tag to use for the query
+        request: Request parameters including optional embedding model name
+            and metadata field name.
+
+    Returns:
+        Metadata name used for the similarity.
+
+    Raises:
+        HTTPException: 404 if invalid embedding model or query tag is given.
+    """
+    try:
+        embedding_model = embedding_model_resolver.get_by_name(
+            session=session,
+            dataset_id=dataset.dataset_id,
+            embedding_model_name=request.embedding_model_name,
+        )
+    except ValueError as e:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail="Embedding model not found",
+        ) from e
+
+    try:
+        return compute_similarity.compute_similarity_metadata(
+            session=session,
+            key_dataset_id=dataset.dataset_id,
+            query_tag_id=query_tag_id,
+            embedding_model_id=embedding_model.embedding_model_id,
+            metadata_name=request.metadata_name,
+        )
+    except TagNotFoundError as e:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Query tag {query_tag_id} not found",
+        ) from e