Thumbnails API for SourceImages

ami/main/admin.py

@@ -27,6 +27,7 @@
     Site,
     SourceImage,
     SourceImageCollection,
+    SourceImageThumbnail,
     Tag,
     TaxaList,
     Taxon,
@@ -293,6 +294,17 @@ def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
         )
 
 
+@admin.register(SourceImageThumbnail)
+class SourceImageThumbnailAdmin(AdminBase):
+    """Admin panel for ``SourceImageThumbnail`` model."""
+
+    list_display = ("source_image", "path", "label", "width", "height", "size")
+    list_filter = ("source_image__deployment__project", "source_image__deployment__data_source", "label")
+
+    def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
+        return super().get_queryset(request).select_related("source_image", "source_image__deployment")
+
+
 class ClassificationInline(admin.TabularInline):
     model = Classification
     extra = 0

ami/main/api/serializers.py

@@ -1,5 +1,6 @@
 import datetime
 
+from django.conf import settings
 from django.db.models import QuerySet
 from guardian.shortcuts import get_perms
 from rest_framework import serializers
@@ -1097,6 +1098,18 @@ class SourceImageListSerializer(DefaultSerializer):
     event = EventNestedSerializer(read_only=True)
     project = serializers.PrimaryKeyRelatedField(queryset=Project.objects.all(), required=False)
     # file = serializers.ImageField(allow_empty_file=False, use_url=True)
+    thumbnails = serializers.SerializerMethodField()
+
+    def get_thumbnails(self, obj: SourceImage) -> dict | None:
+        return {
+            label: reverse_with_params(
+                "sourceimagethumbnail-detail",
+                args=(obj.pk,),
+                request=self.context.get("request"),
+                params={"label": label},
+            )
+            for label in settings.THUMBNAILS["SIZES"]
+        }
 
     class Meta:
         model = SourceImage
@@ -1107,7 +1120,6 @@ class Meta:
             "event",
             "url",
             "path",
-            # "thumbnail",
             "timestamp",
             "width",
             "height",
@@ -1118,6 +1130,7 @@ class Meta:
             "taxa_count",
             "detections",
             "project",
+            "thumbnails",
         ]
 
 

ami/main/api/views.py

@@ -2,14 +2,16 @@
 import logging
 from statistics import mode
 
+from django.conf import settings
 from django.contrib.postgres.search import TrigramSimilarity
 from django.core import exceptions
+from django.core.files.storage import default_storage
 from django.db import models
 from django.db.models import Prefetch, Q
 from django.db.models.functions import Coalesce
 from django.db.models.query import QuerySet
 from django.forms import BooleanField, CharField, IntegerField
-from django.shortcuts import get_object_or_404
+from django.shortcuts import get_object_or_404, redirect
 from django.utils import timezone
 from django_filters.rest_framework import DjangoFilterBackend
 from drf_spectacular.types import OpenApiTypes
@@ -709,6 +711,35 @@ def unstar(self, _request, pk=None) -> Response:
             raise api_exceptions.ValidationError(detail="Source image must be associated with a project")
 
 
+class SourceImageThumbnailViewSet(DefaultReadOnlyViewSet, ProjectMixin):
+    """
+    Endpoint for capture thumbnails
+    """
+
+    queryset = SourceImage.objects.all()
+
+    permission_classes = [ObjectPermission]
+
+    def list(self, request):
+        raise api_exceptions.NotFound(detail=f"No collection of thumbnails")
+
+    def retrieve(self, request, pk=None):
+        _sizes = settings.THUMBNAILS["SIZES"]
+
+        label = self.request.query_params.get("label", next(iter(_sizes)))
+        size = _sizes.get(label, None)
+        if size is None:
+            raise api_exceptions.ValidationError(
+                detail=f"Invalid thumbnail size label provided: {label} not in {', '.join(_sizes.keys())}"
+            )
+        obj: SourceImage = self.get_object()
+        try:
+            thumb = obj.find_or_generate_thumbnail_for_label(label)
+        except exceptions.ObjectDoesNotExist as e:
+            raise api_exceptions.NotFound(detail=f"{e}")
+        return redirect(default_storage.url(thumb.path))
+
+
 class SourceImageCollectionViewSet(DefaultViewSet, ProjectMixin):
     """
     Endpoint for viewing capture sets or samples of captures.

ami/main/migrations/0085_sourceimagethumbnail.py

@@ -0,0 +1,49 @@
+# Generated by Django 4.2.10 on 2026-05-13 10:17
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("main", "0084_revoke_delete_job_from_roles"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="SourceImageThumbnail",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("path", models.CharField(blank=True, max_length=255)),
+                ("label", models.CharField(max_length=255)),
+                ("width", models.IntegerField(blank=True, null=True)),
+                ("height", models.IntegerField(blank=True, null=True)),
+                ("size", models.BigIntegerField(blank=True, null=True)),
+                ("last_modified", models.DateTimeField(blank=True, null=True, auto_now_add=True)),
+                (
+                    "source_image",
+                    models.ForeignKey(
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="thumbnails",
+                        to="main.sourceimage",
+                    ),
+                ),
+            ],
+            options={
+                "abstract": False,
+            },
+        ),
+        migrations.AddIndex(
+            model_name="sourceimagethumbnail",
+            index=models.Index(fields=["source_image", "label"], name="main_source_source__b0d4cd_idx"),
+        ),
+        migrations.AddConstraint(
+            model_name="sourceimagethumbnail",
+            constraint=models.UniqueConstraint(
+                fields=("source_image", "label"), name="unique_source_image_thumbnail_label"
+            ),
+        ),        
+    ]

ami/main/models.py

@@ -15,7 +15,7 @@
 from django.conf import settings
 from django.contrib.auth.models import AbstractUser, AnonymousUser
 from django.contrib.postgres.fields import ArrayField
-from django.core.exceptions import ValidationError
+from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.core.files.storage import default_storage
 from django.db import IntegrityError, models, transaction
 from django.db.models import Exists, OuterRef, Q
@@ -44,6 +44,7 @@
 from ami.users.models import User
 from ami.utils.media import calculate_file_checksum, extract_timestamp
 from ami.utils.requests import get_apply_default_filters_flag, get_default_classification_threshold
+from ami.utils.s3 import botocore, read_image
 from ami.utils.schemas import OrderedEnum
 
 if typing.TYPE_CHECKING:
@@ -2206,6 +2207,63 @@ def get_custom_user_permissions(self, user) -> list[str]:
             custom_perms.add(Project.Permissions.RUN_SINGLE_IMAGE_JOB)
         return list(custom_perms)
 
+    def find_or_generate_thumbnail_for_label(self, label):
+        try:
+            thumb = self.thumbnails.get(label=label)
+        except SourceImageThumbnail.DoesNotExist:
+            thumb = None
+        size = settings.THUMBNAILS["SIZES"].get(label)
+        prefix = settings.THUMBNAILS["STORAGE_PREFIX"]
+
+        if (
+            not thumb
+            or thumb.width != size["width"]
+            or thumb.last_modified < self.last_modified
+            or not default_storage.exists(thumb.path)
+        ):
+            if self.path and self.deployment and self.deployment.data_source:
+                config = self.deployment.data_source.config
+                # Get the file
+                try:
+                    img = read_image(config=config, key=self.path)
+                except botocore.exceptions.ClientError as e:
+                    logger.error(f"Could not read image for {self.path}: {e}")
+                    raise ObjectDoesNotExist(f"SourceImage with id {self.pk} media not found") from e
+            elif self.path:
+                img = PIL.Image.open(default_storage.open(self.path))
+            else:
+                raise ObjectDoesNotExist(f"SourceImage with id {self.pk} media config not found")
+            # Make the thumbnail
+            orig_width, orig_height = img.size
+            width = size["width"]
+            height = size.get("height", None)
+            if not height:
+                height = int(orig_height * (width / float(orig_width)))
+            new_size = (width, height)
+            img.thumbnail(new_size)
+
+            buffer = BytesIO()
+            img.save(buffer, format="JPEG")
+            contents = buffer.getvalue()
+            file_size = len(contents)
+
+            # Remove prior thumbnails for this size
+            for t in self.thumbnails.filter(label=label):
+                default_storage.delete(t.path)
+                t.delete()
+
+            # Write to storage
+            buffer.seek(0)
+            thumbnail_key = f"{prefix}capture_{self.pk}/{label}.jpg"
+            thumbnail_path = default_storage.save(thumbnail_key, buffer)
+
+            # Save to DB
+            width, height = img.size
+            thumb = self.thumbnails.create(
+                path=thumbnail_path, label=label, width=width, height=height, size=file_size
+            )
+        return thumb
+
     class Meta:
         ordering = ("deployment", "event", "timestamp")
 
@@ -2392,6 +2450,31 @@ def sample_captures_by_nth(
         yield from qs[::nth]
 
 
+@final
+class SourceImageThumbnail(BaseModel):
+    """A thumbnail cache of a SourceImage"""
+
+    path = models.CharField(max_length=255, blank=True)
+    label = models.CharField(max_length=255)
+    width = models.IntegerField(null=True, blank=True)
+    height = models.IntegerField(null=True, blank=True)
+    size = models.BigIntegerField(null=True, blank=True)
+    last_modified = models.DateTimeField(null=True, blank=True, auto_now_add=True)
+
+    source_image = models.ForeignKey(SourceImage, on_delete=models.SET_NULL, null=True, related_name="thumbnails")
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["source_image", "label"],
+                name="unique_source_image_thumbnail_label",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["source_image", "label"]),
+        ]
+
+
 # @final
 # class IdentificationHistory(BaseModel):
 #     """A history of identifications for an occurrence."""