feat: Map screenshots / images

- rename an endpoint
- fix the model for screenshot uploads.

TODO:

- [] map serializer return link for most recent image and all images
- [] map serializer return mapfile links

Author: alexlambson

kirovy/migrations/0015_remove_cncmapimagefile_version_and_more.py

@@ -0,0 +1,39 @@
+# Generated by Django 4.2.23 on 2025-08-24 20:27
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("kirovy", "0014_cncmapimagefile"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="cncmapimagefile",
+            name="version",
+        ),
+        migrations.AddField(
+            model_name="cncmapimagefile",
+            name="image_order",
+            field=models.IntegerField(default=0),
+        ),
+        migrations.AddField(
+            model_name="cncmapimagefile",
+            name="is_extracted",
+            field=models.BooleanField(default=False),
+        ),
+        migrations.AddIndex(
+            model_name="cncfileextension",
+            index=models.Index(fields=["extension_type"], name="kirovy_cncf_extensi_5e0362_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="cncmapfile",
+            index=models.Index(fields=["cnc_map"], name="kirovy_cncm_cnc_map_a1e8af_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="cncmapimagefile",
+            index=models.Index(fields=["cnc_map"], name="kirovy_cncm_cnc_map_078511_idx"),
+        ),
+    ]

kirovy/models/cnc_game.py

@@ -56,6 +56,9 @@ class ExtensionTypes(models.TextChoices):
         blank=False,
     )
 
+    class Meta:
+        indexes = [models.Index(fields=["extension_type"])]
+
     def save(self, *args, **kwargs):
         self.extension = self.extension.lower()  # Force lowercase
         is_valid_extension(self.extension)  # force validator on save instead from a view.

kirovy/models/cnc_map.py

@@ -146,15 +146,15 @@ def generate_versioned_name_for_file(self) -> str:
         """
         return f"{self.cnc_game.slug}_{self.id.hex}_v{self.next_version_number():02}"
 
-    def get_map_directory_path(self) -> pathlib.Path:
+    def get_map_directory_path(self, upload_type: str = settings.CNC_MAP_DIRECTORY) -> pathlib.Path:
         """Returns the path to the directory where all files related to the map will be store.
 
         :return:
             Directory path to put maps and image previews in.
         """
         return pathlib.Path(
             self.cnc_game.slug,
-            settings.CNC_MAP_DIRECTORY,
+            upload_type,
             self.id.hex,
         )
 
@@ -199,6 +199,7 @@ class Meta:
         constraints = [
             models.UniqueConstraint(fields=["cnc_map_id", "version"], name="unique_map_version"),
         ]
+        indexes = [models.Index(fields=["cnc_map"])]
 
     def save(self, *args, **kwargs):
         if not self.version:
@@ -226,7 +227,7 @@ def generate_upload_to(instance: "CncMapFile", filename: str) -> pathlib.Path:
         final_file_name = f"{instance.name}{filename.suffix}"
 
         # e.g. "yr/maps/CNC_NET_MAP_ID_HEX/ra2_CNC_NET_MAP_ID_HEX_v1.map
-        return pathlib.Path(instance.cnc_map.get_map_directory_path(), final_file_name)
+        return pathlib.Path(instance.cnc_map.get_map_directory_path(instance.UPLOAD_TYPE), final_file_name)
 
 
 class CncMapImageFile(file_base.CncNetFileBaseModel):
@@ -241,19 +242,37 @@ class CncMapImageFile(file_base.CncNetFileBaseModel):
 
     width = models.IntegerField()
     height = models.IntegerField()
-    version = models.IntegerField(editable=False)
 
     cnc_map = models.ForeignKey(CncMap, on_delete=models.CASCADE, null=False)
 
     ALLOWED_EXTENSION_TYPES = {game_models.CncFileExtension.ExtensionTypes.IMAGE.value}
 
-    UPLOAD_TYPE = settings.CNC_MAP_DIRECTORY
+    UPLOAD_TYPE = settings.CNC_MAP_IMAGE_DIRECTORY
+
+    is_extracted = models.BooleanField(null=False, blank=False, default=False)
+    """attr: If true, then this image was extracted from the uploaded map file, usually generated by FinalAlert.
+
+    This will always be false for games released after Yuri's Revenge because Generals and beyond do not pack the
+    preview image into the map files.
+    """
+
+    image_order = models.IntegerField(null=False, default=0)
+    """attr: The order in which images will be returned to the UI.
+
+    ``0`` will be the "primary" image that we use in the thumbnails for the search screen.
+    If there are ``order`` collisions, then we fallback to the creation date.
+    """
+
+    class Meta:
+        indexes = [models.Index(fields=["cnc_map"])]
 
     def save(self, *args, **kwargs):
+        self.name = self.cnc_map.map_name
+        self.cnc_game = self.cnc_map.cnc_game
         super().save(*args, **kwargs)
 
     @staticmethod
-    def generate_upload_to(instance: "CncMapFile", filename: str) -> pathlib.Path:
+    def generate_upload_to(instance: "CncMapImageFile", filename: str) -> pathlib.Path:
         """Generate the path to upload map files to.
 
         Gets called by :func:`kirovy.models.file_base._generate_upload_to` when ``CncMapImageFile.save`` is called.
@@ -269,7 +288,7 @@ def generate_upload_to(instance: "CncMapFile", filename: str) -> pathlib.Path:
             Path to upload map to relative to :attr:`~kirovy.settings.base.MEDIA_ROOT`.
         """
         filename = pathlib.Path(filename)
-        final_file_name = f"{instance.name}{filename.suffix}"
+        final_file_name = f"{instance.created.isoformat('-')}_{instance.id.hex}{filename.suffix}"
 
-        # e.g. "yr/maps/CNC_NET_MAP_ID_HEX/screenshot_of_map.jpg
-        return pathlib.Path(instance.cnc_map.get_map_directory_path(), final_file_name)
+        # e.g. "yr/map_images/CNC_NET_MAP_ID_HEX/2020-01-01_somelongid.jpg
+        return pathlib.Path(instance.cnc_map.get_map_directory_path(instance.UPLOAD_TYPE), final_file_name)

kirovy/settings/_base.py

@@ -92,6 +92,7 @@
     ],
     "EXCEPTION_HANDLER": "kirovy.exception_handler.kirovy_exception_handler",
     "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+    "DEFAULT_RENDERER_CLASSES": ("rest_framework.renderers.JSONRenderer",),
 }
 """
 attr: Define the default authentication backend for endpoints.
@@ -179,6 +180,14 @@
 CNC_MAP_DIRECTORY = "maps"
 """attr: The directory, beneath the game slug, where map files will be stored."""
 
+CNC_MAP_IMAGE_DIRECTORY = "map_images"
+"""att: The directory, beneath the game slug, where map images will be stored.
+
+.. note::
+
+    Example: ``/data/cncnet_silo/yr/map_images/
+"""
+
 
 ### --------------- SERVING FILES ---------------
 ### This section of settings has to do with serving files

kirovy/urls.py

@@ -107,7 +107,7 @@ def _get_url_patterns() -> list[_DjangoPath]:
     path("client/upload/", map_upload_views.CncnetClientMapUploadView.as_view()),
     path("<uuid:pk>/", cnc_map_views.MapRetrieveUpdateView.as_view()),
     path("delete/<uuid:pk>/", cnc_map_views.MapDeleteView.as_view()),
-    path("search/", cnc_map_views.MapListCreateView.as_view()),
+    path("search/", cnc_map_views.MapListView.as_view()),
     # path("img/<uuid:map_id>/"),
     # path("img/<uuid:map_id>/", ...),
     # path("search/")

kirovy/views/cnc_map_views.py

@@ -11,7 +11,7 @@
 from rest_framework.renderers import TemplateHTMLRenderer
 from rest_framework.views import APIView
 
-from kirovy import permissions
+from kirovy import permissions, typing as t
 from kirovy.models import (
     MapCategory,
     CncGame,
@@ -119,7 +119,7 @@ def filter_include_map_edits(self, queryset: QuerySet[CncMap], name: str, value:
     #     return queryset | CncMap.objects.filter(cnc_game__parent_game__in=)
 
 
-class MapListCreateView(base_views.KirovyListCreateView):
+class MapListView(base_views.KirovyListCreateView):
     """
     The view for maps.
     """
@@ -169,7 +169,7 @@ def get_queryset(self):
     search_param = "search"
     """attr: The query param to use in the URL
 
-     Searches the fields defined in :attr:`~kirovy.views.cnc_map_views.MapListCreateView`
+     Searches the fields defined in :attr:`~kirovy.views.cnc_map_views.MapListView`
      """
 
     search_fields = [
@@ -199,7 +199,7 @@ def get_queryset(self):
 class MapRetrieveUpdateView(base_views.KirovyRetrieveUpdateView):
     serializer_class = cnc_map_serializers.CncMapBaseSerializer
 
-    def get_queryset(self):
+    def get_queryset(self) -> QuerySet[CncMap]:
         """Get the queryset for map detail views.
 
         Who can view what:
@@ -208,7 +208,7 @@ def get_queryset(self):
             -   Anyone: Can view published, legacy, or temporary (cncnet client uploaded) maps.
                 Banned maps will be excluded.
             -   Registered Users: Can edit their own maps if the map isn't banned.
-                Can view their own maps even if the map banned.
+                Can view their own maps even if the map is banned.
                 The queryset will return a user's banned map, but :class:`kirovy.permissions.CanEdit` will block
                 any modification attempts.
 
@@ -223,7 +223,7 @@ def get_queryset(self):
             return CncMap.objects.filter()
 
         # Anyone can view legacy maps, temporary maps (for the cncnet client,) and published maps that aren't banned.
-        queryset = CncMap.objects.filter(
+        queryset: QuerySet[CncMap] = CncMap.objects.filter(
             Q(Q(is_published=True) | Q(is_legacy=True) | Q(is_temporary=True)) & Q(is_banned=False)
         )
 
@@ -290,7 +290,7 @@ def get(self, request: KirovyRequest) -> KirovyResponse:
         return KirovyResponse()
 
 
-class MapLegacySearchUI(MapListCreateView):
+class MapLegacySearchUI(MapListView):
 
     permission_classes = [AllowAny]
     renderer_classes = [TemplateHTMLRenderer]

requirements-dev.txt

@@ -5,4 +5,5 @@ black==24.*
 pre-commit==3.*
 pytest-django==4.*
 markdown>=3.4.4, <=4.0
-drf-spectacular[sidecar]
+# for docs
+sphinx