Feature: Unified Image Storage using InvenTreeImage Model

.gitignore

@@ -117,5 +117,17 @@ api.yaml
 src/backend/InvenTree/web/static
 InvenTree/web/static
 
+
+media/*
+backup/*
+static/*
+
+schema.yml
+.yarn/*
+
+package-lock.json
+yarn.lock
+install-state.gz
+.yarnrc.yml
 # performance test results
 .codspeed/

src/backend/InvenTree/InvenTree/api_version.py

@@ -1,11 +1,16 @@
 """InvenTree API version information."""
 
 # InvenTree API version
-INVENTREE_API_VERSION = 453
+INVENTREE_API_VERSION = 454
 """Increment this API version number whenever there is a significant change to the API that any clients need to know about."""
 
 INVENTREE_API_TEXT = """
 
+v454 -> 2026-02-13 : https://github.com/inventree/InvenTree/pull/...
+    - Expose InvenTreeImage model to api/image API endpoints
+    - Adds 'image_url' and 'thumbnail_url' fields to relevant API serializers
+    - Updates Part and Company API endpoints to use new image architecture
+
 v453 -> 2026-02-11 : https://github.com/inventree/InvenTree/pull/11244
     - Adds (internal) endpoint to end a observability tooling session
 

src/backend/InvenTree/InvenTree/management/commands/rebuild_thumbnails.py

@@ -11,8 +11,7 @@
 import structlog
 from PIL import UnidentifiedImageError
 
-from company.models import Company
-from part.models import Part
+from common.models import InvenTreeImage
 
 logger = structlog.get_logger('inventree')
 
@@ -52,18 +51,11 @@ def handle(self, *args, **kwargs):
         """Rebuild all thumbnail images."""
         logger.info('Rebuilding Part thumbnails')
 
-        for part in Part.objects.exclude(image=None):
+        for image in InvenTreeImage.objects.exclude(image=None):
             try:
-                self.rebuild_thumbnail(part)
+                self.rebuild_thumbnail(image)
             except (OperationalError, ProgrammingError):
                 logger.exception('ERROR: Database read error.')
                 break
 
         logger.info('Rebuilding Company thumbnails')
-
-        for company in Company.objects.exclude(image=None):
-            try:
-                self.rebuild_thumbnail(company)
-            except (OperationalError, ProgrammingError):
-                logger.exception('ERROR: abase read error.')
-                break

src/backend/InvenTree/InvenTree/models.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable
 from datetime import datetime
 from string import Formatter
-from typing import Any, Optional
+from typing import Optional
 
 from django.contrib.auth import get_user_model
 from django.contrib.contenttypes.fields import GenericRelation
@@ -23,7 +23,6 @@
 from error_report.models import Error
 from mptt.exceptions import InvalidMove
 from mptt.models import MPTTModel, TreeForeignKey
-from stdimage.models import StdImageField
 
 import common.settings
 import InvenTree.exceptions
@@ -1468,52 +1467,157 @@
 
 
 class InvenTreeImageMixin(models.Model):
-    """A mixin class for adding image functionality to a model class.
+    """A mixin to add image  capability to any model.
 
-    The following fields are added to any model which implements this mixin:
-
-    - image : An image field for storing an image
+    Provides a GenericRelation back to InvenTreeImage, plus helpers for primary image logic.
     """
 
     IMAGE_RENAME: Callable | None = None
 
+    # if True, only one image may ever be attached
+    single_image = False
+
+    images = GenericRelation(
+        'common.InvenTreeImage',
+        content_type_field='model_type',
+        object_id_field='object_id',
+        related_query_name='%(app_label)s_%(class)ss',
+    )
+
     class Meta:
-        """Metaclass options for this mixin.
+        """Metaclass options for this mixin."""
 
-        Note: abstract must be true, as this is only a mixin, not a separate table
+        abstract = True
+
+    def save_image(self, file, file_name, primary=False):
+        """Save an image to this instance.
+
+        Args:
+            file: File object or file-like object (e.g., UploadedFile, BytesIO, or file path)
+            file_name: Name for the image file
+            primary: If True, set this image as the primary image (default: False)
+
+        Returns:
+            InvenTreeImage: The created image instance
+
+        Raises:
+            ValueError: If single_image is True and an image already exists
         """
+        from django.core.files import File
 
-        abstract = True
+        from common.models import InvenTreeImage
 
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """Custom init method for InvenTreeImageMixin to ensure IMAGE_RENAME is implemented."""
-        if self.IMAGE_RENAME is None:
-            raise NotImplementedError(
-                'IMAGE_RENAME must be implemented in the model class'
-            )
-        super().__init__(*args, **kwargs)
+        # Check if single_image constraint is violated
+        if self.single_image and self.images.exists():
+            raise ValueError('This object can only have a single image')
+
+        # If setting as primary, unset any existing primary images
+        if primary:
+            self.images.filter(primary=True).update(primary=False)
+
+        # Create the InvenTreeImage instance
+        img = InvenTreeImage(content_object=self, primary=primary)
+
+        # Handle different file input types
+        if isinstance(file, str):
+            # If file is a path string, open it
+            with open(file, 'rb') as f:
+                img.image.save(file_name, File(f), save=True)
+        else:
+            # Assume it's a file-like object (UploadedFile, BytesIO, etc.)
+            img.image.save(file_name, file, save=True)
+
+        return img
+
+    def delete(self, *args, **kwargs):
+        """Ensure related images are deleted first."""
+        # delete all related images
+        self.images.all().delete()
+        return super().delete(*args, **kwargs)
 
     def rename_image(self, filename):
         """Rename the uploaded image file using the IMAGE_RENAME function."""
         return self.IMAGE_RENAME(filename)  # type: ignore
 
-    image = StdImageField(
-        upload_to=rename_image,
-        null=True,
-        blank=True,
-        variations={'thumbnail': (128, 128), 'preview': (256, 256)},
-        delete_orphans=False,
-        verbose_name=_('Image'),
-    )
+    # image = StdImageField(
+    #     upload_to=rename_image,
+    #     null=True,
+    #     blank=True,
+    #     variations={'thumbnail': (128, 128), 'preview': (256, 256)},
+    #     delete_orphans=False,
+    #     verbose_name=_('Image'),
+    # )
+
+    @property
+    def image(self):
+        """Return the primary image, or None."""
+        return self.images.filter(primary=True).first()
+
+    def copy_images_to(self, target_pk):
+        """Copy all images from this instance to another instance of the same model with pk."""
+        from common.models import InvenTreeImage
+
+        ct = ContentType.objects.get_for_model(self, for_concrete_model=False)
+        new_images = []
+        for img in self.images.all():
+            new_img = InvenTreeImage(
+                model_type=ct,
+                object_id=target_pk,
+                primary=img.primary,
+                image=img.image.name,
+            )
+            new_images.append(new_img)
+
+        InvenTreeImage.objects.bulk_create(new_images)
+
+
+# class InvenTreeImageMixin(models.Model):
+#     """A mixin class for adding image functionality to a model class.
+
+#     The following fields are added to any model which implements this mixin:
+
+#     - image : An image field for storing an image
+#     """
+
+#     IMAGE_RENAME: Callable | None = None
+
+#     class Meta:
+#         """Metaclass options for this mixin.
+
+#         Note: abstract must be true, as this is only a mixin, not a separate table
+#         """
+
+#         abstract = True
+
+#     def __init__(self, *args: Any, **kwargs: Any) -> None:
+#         """Custom init method for InvenTreeImageMixin to ensure IMAGE_RENAME is implemented."""
+#         if self.IMAGE_RENAME is None:
+#             raise NotImplementedError(
+#                 'IMAGE_RENAME must be implemented in the model class'
+#             )
+#         super().__init__(*args, **kwargs)
+
+#     def rename_image(self, filename):
+#         """Rename the uploaded image file using the IMAGE_RENAME function."""
+#         return self.IMAGE_RENAME(filename)  # type: ignore
+
+#     image = StdImageField(
+#         upload_to=rename_image,
+#         null=True,
+#         blank=True,
+#         variations={'thumbnail': (128, 128), 'preview': (256, 256)},
+#         delete_orphans=False,
+#         verbose_name=_('Image'),
+#     )
+
+#     def get_image_url(self):
+#         """Return the URL of the image for this object."""
+#         if self.image:
+#             return InvenTree.helpers.getMediaUrl(self.image)
+#         return InvenTree.helpers.getBlankImage()
 
-    def get_image_url(self):
-        """Return the URL of the image for this object."""
-        if self.image:
-            return InvenTree.helpers.getMediaUrl(self.image)
-        return InvenTree.helpers.getBlankImage()
-
-    def get_thumbnail_url(self) -> str:
-        """Return the URL of the image thumbnail for this object."""
-        if self.image:
-            return InvenTree.helpers.getMediaUrl(self.image, 'thumbnail')
-        return InvenTree.helpers.getBlankThumbnail()
+#     def get_thumbnail_url(self) -> str:
+#         """Return the URL of the image thumbnail for this object."""
+#         if self.image:
+#             return InvenTree.helpers.getMediaUrl(self.image, 'thumbnail')
+#         return InvenTree.helpers.getBlankThumbnail()

src/backend/InvenTree/InvenTree/tests.py

@@ -31,7 +31,7 @@
 import InvenTree.helpers_model
 import InvenTree.tasks
 from common.currency import currency_codes
-from common.models import CustomUnit, InvenTreeSetting
+from common.models import CustomUnit, InvenTreeImage, InvenTreeSetting
 from common.settings import get_global_setting
 from InvenTree.helpers_mixin import ClassProviderMixin, ClassValidationMixin
 from InvenTree.sanitizer import sanitize_svg
@@ -706,7 +706,7 @@ def testMediaUrl(self):
             helpers.getMediaUrl('xx/yy.png')  # type: ignore
 
         # Correct usage
-        part = Part().image
+        part = InvenTreeImage().image
         self.assertEqual(
             helpers.getMediaUrl(StdImageFieldFile(part, part, 'xx/yy.png')),  # type: ignore
             '/media/xx/yy.png',

src/backend/InvenTree/build/api.py

@@ -22,6 +22,7 @@
 import stock.serializers
 from build.models import Build, BuildItem, BuildLine
 from build.status_codes import BuildStatus, BuildStatusGroups
+from common.filters import prefetch_related_images
 from data_exporter.mixins import DataExportViewMixin
 from generic.states.api import StatusView
 from InvenTree.api import BulkDeleteMixin, ParameterListMixin, meta_path
@@ -319,6 +320,8 @@ def get_queryset(self):
 
         queryset = build.serializers.BuildSerializer.annotate_queryset(queryset)
 
+        queryset = prefetch_related_images(queryset, reference='part__')
+
         return queryset
 
 

src/backend/InvenTree/build/serializers.py

@@ -28,6 +28,7 @@
 import InvenTree.helpers
 import part.filters
 import part.serializers as part_serializers
+from common.filters import prefetch_related_images
 from common.settings import get_global_setting
 from generic.states.fields import InvenTreeCustomStatusSerializerMixin
 from InvenTree.mixins import DataImportExportSerializerMixin
@@ -1702,6 +1703,13 @@ def annotate_queryset(queryset, build=None):
             )
         )
 
+        queryset = prefetch_related_images(
+            queryset, reference='allocations__stock_item__part__'
+        )
+        queryset = prefetch_related_images(queryset, reference='build__part__')
+        queryset = prefetch_related_images(queryset, reference='bom_item__part__')
+        queryset = prefetch_related_images(queryset, reference='bom_item__sub_part__')
+
         return queryset
 
 

src/backend/InvenTree/common/admin.py

@@ -1,6 +1,7 @@
 """Admin for the common app."""
 
 from django.contrib import admin
+from django.utils.html import format_html
 
 import common.models
 import common.validators
@@ -59,6 +60,48 @@ def formfield_for_dbfield(self, db_field, request, **kwargs):
     search_fields = ('content_type', 'comment')
 
 
+@admin.register(common.models.InvenTreeImage)
+class InvenTreeImageAdmin(admin.ModelAdmin):
+    """Admin interface for InvenTreeImage objects."""
+
+    list_display = (
+        'id',
+        'model_type',
+        'object_id',
+        'primary',
+        'image',
+        'image_thumbnail',
+    )
+    list_filter = ('model_type', 'primary', 'image')
+    search_fields = ('object_id',)
+    readonly_fields = ('image_thumbnail',)
+    fieldsets = (
+        (
+            None,
+            {
+                'fields': (
+                    'model_type',
+                    'object_id',
+                    'primary',
+                    'image',
+                    'image_thumbnail',
+                )
+            },
+        ),
+    )
+
+    def image_thumbnail(self, obj):
+        """Returns a small preview of the uploaded image."""
+        if obj.image and hasattr(obj.image, 'url'):
+            return format_html(
+                '<img src="{}" style="max-height: 100px; max-width: 100px;" />',
+                obj.image.url,
+            )
+        return '-'
+
+    image_thumbnail.short_description = 'Preview'
+
+
 @admin.register(common.models.DataOutput)
 class DataOutputAdmin(admin.ModelAdmin):
     """Admin interface for DataOutput objects."""