media-optimization-engine 1.4.0__tar.gz → 1.4.2__tar.gz

{media_optimization_engine-1.4.0/media_optimization_engine.egg-info → media_optimization_engine-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: media-optimization-engine
-Version: 1.4.0
+Version: 1.4.2
 Summary: Media Optimization Engineer for Django/Python: automatic model-field optimization, responsive picture/srcset rendering, AVIF/WebP derivatives, 360 media, autonomous nodes, and CDN-ready storage.
 Author-email: Achille Kabasele <pepexykabasele@gmail.com>
 Maintainer-email: Achille Kabasele <pepexykabasele@gmail.com>
@@ -233,6 +233,38 @@ JavaScript is not required for normal responsive images.
 
 Runtime measurement is appropriate only for highly dynamic components whose rendered width cannot be described reliably with sizes, such as resizable editors, canvas-like builders, or asynchronously mounted panels.
 
+## Docker image
+
+The standalone service is also published as a multi-architecture GHCR image:
+
+~~~bash
+docker pull ghcr.io/kabasele754/media-optimization-engine:1.4.1
+~~~
+
+For Compose deployment, see `docs/DOCKER.md` and `docker-compose.ghcr.yml`.
+
+## Flutter / native clients
+
+MOE also ships reference Dart adapters for native applications.
+
+Standard Flutter clients should fetch the image manifest, measure the rendered widget width, multiply it by device pixel ratio, and select the first derivative at or above that physical width.
+
+~~~dart
+final variant = manifest.select(
+  logicalWidth: constraints.maxWidth,
+  devicePixelRatio: MediaQuery.devicePixelRatioOf(context),
+  preferredFormat: 'webp',
+);
+~~~
+
+Reference adapters are packaged under:
+
+~~~text
+media_engine/adapters/flutter/
+~~~
+
+This keeps optimization and derivative generation on the Django/Python backend while allowing Flutter to select and cache the most appropriate immutable URL. Panorama manifests use the same principle at tile/level granularity.
+
 ## Backfill
 
 Historical media can be ingested with maintenance commands:

{media_optimization_engine-1.4.0 → media_optimization_engine-1.4.2}/README.md

@@ -177,6 +177,38 @@ JavaScript is not required for normal responsive images.
 
 Runtime measurement is appropriate only for highly dynamic components whose rendered width cannot be described reliably with sizes, such as resizable editors, canvas-like builders, or asynchronously mounted panels.
 
+## Docker image
+
+The standalone service is also published as a multi-architecture GHCR image:
+
+~~~bash
+docker pull ghcr.io/kabasele754/media-optimization-engine:1.4.1
+~~~
+
+For Compose deployment, see `docs/DOCKER.md` and `docker-compose.ghcr.yml`.
+
+## Flutter / native clients
+
+MOE also ships reference Dart adapters for native applications.
+
+Standard Flutter clients should fetch the image manifest, measure the rendered widget width, multiply it by device pixel ratio, and select the first derivative at or above that physical width.
+
+~~~dart
+final variant = manifest.select(
+  logicalWidth: constraints.maxWidth,
+  devicePixelRatio: MediaQuery.devicePixelRatioOf(context),
+  preferredFormat: 'webp',
+);
+~~~
+
+Reference adapters are packaged under:
+
+~~~text
+media_engine/adapters/flutter/
+~~~
+
+This keeps optimization and derivative generation on the Django/Python backend while allowing Flutter to select and cache the most appropriate immutable URL. Panorama manifests use the same principle at tile/level granularity.
+
 ## Backfill
 
 Historical media can be ingested with maintenance commands:

media_optimization_engine-1.4.2/media_engine/adapters/flutter/README.md

@@ -0,0 +1,63 @@
+# Flutter adapter
+
+Media Optimization Engineer can be consumed by Flutter through the same immutable manifest API used by other native clients.
+
+The Python package ships Dart reference models under this directory. They are framework-neutral examples that consuming Flutter applications can copy or wrap in their own networking/cache layer.
+
+## Standard images
+
+\`standard_images.dart\` parses a standard MOE manifest and selects a derivative from:
+
+~~~text
+target physical width = rendered logical width × devicePixelRatio
+~~~
+
+Recommended policy:
+
+1. fetch the asset manifest once;
+2. cache the manifest in memory;
+3. measure the actual widget width with \`LayoutBuilder\`;
+4. multiply by \`MediaQuery.devicePixelRatioOf(context)\`;
+5. select the first WebP derivative at or above that physical width;
+6. if none is large enough, use the largest available derivative;
+7. cache the selected immutable URL with the application's normal image cache;
+8. fall back to the manifest fallback/original URL if needed.
+
+Example:
+
+~~~dart
+final targetLogicalWidth = constraints.maxWidth;
+final dpr = MediaQuery.devicePixelRatioOf(context);
+
+final variant = manifest.select(
+  logicalWidth: targetLogicalWidth,
+  devicePixelRatio: dpr,
+  preferredFormat: 'webp',
+);
+~~~
+
+WebP is a conservative default for broad Android/iOS compatibility. Applications may prefer AVIF on platforms where their Flutter image stack reliably supports it.
+
+## Panorama 360
+
+\`models.dart\` parses the generic panorama manifest.
+
+Recommended panorama policy:
+
+- show \`preview\` immediately;
+- select a level from viewport width × DPR;
+- request only tiles intersecting the current field of view;
+- keep adjacent tiles warm for smooth panning;
+- use AVIF where supported, otherwise WebP.
+
+## API
+
+A standard image manifest is available from the REST viewset:
+
+~~~text
+GET /api/v1/images/<asset-id>/manifest/?profile=<profile>
+~~~
+
+When MOE is mounted under another prefix in a Django project, keep the same route relative to that prefix.
+
+The native client should never upload or process an image merely to render it. Processing stays server-side; Flutter only chooses among READY immutable derivatives.

media_optimization_engine-1.4.2/media_engine/adapters/flutter/standard_images.dart

@@ -0,0 +1,106 @@
+class MediaVariant {
+  final int width;
+  final int height;
+  final String url;
+  final int bytes;
+  final int quality;
+
+  const MediaVariant({
+    required this.width,
+    required this.height,
+    required this.url,
+    this.bytes = 0,
+    this.quality = 0,
+  });
+
+  factory MediaVariant.fromJson(Map<String, dynamic> json) => MediaVariant(
+        width: (json['width'] as num?)?.toInt() ?? 0,
+        height: (json['height'] as num?)?.toInt() ?? 0,
+        url: (json['url'] ?? '').toString(),
+        bytes: (json['bytes'] as num?)?.toInt() ?? 0,
+        quality: (json['quality'] as num?)?.toInt() ?? 0,
+      );
+}
+
+class MediaManifest {
+  final String id;
+  final String status;
+  final int width;
+  final int height;
+  final String profile;
+  final String dominantColor;
+  final String blurhash;
+  final String placeholderDataUrl;
+  final String originalUrl;
+  final MediaVariant? fallback;
+  final Map<String, List<MediaVariant>> variants;
+
+  const MediaManifest({
+    required this.id,
+    required this.status,
+    required this.width,
+    required this.height,
+    required this.profile,
+    required this.variants,
+    this.dominantColor = '',
+    this.blurhash = '',
+    this.placeholderDataUrl = '',
+    this.originalUrl = '',
+    this.fallback,
+  });
+
+  factory MediaManifest.fromJson(Map<String, dynamic> json) {
+    final rawVariants =
+        Map<String, dynamic>.from(json['variants'] as Map? ?? const {});
+    final parsed = <String, List<MediaVariant>>{};
+    for (final entry in rawVariants.entries) {
+      final items = (entry.value as List? ?? const [])
+          .whereType<Map>()
+          .map((item) => MediaVariant.fromJson(
+                Map<String, dynamic>.from(item),
+              ))
+          .toList()
+        ..sort((a, b) => a.width.compareTo(b.width));
+      parsed[entry.key] = items;
+    }
+
+    return MediaManifest(
+      id: (json['id'] ?? '').toString(),
+      status: (json['status'] ?? '').toString(),
+      width: (json['width'] as num?)?.toInt() ?? 0,
+      height: (json['height'] as num?)?.toInt() ?? 0,
+      profile: (json['profile'] ?? '').toString(),
+      dominantColor: (json['dominant_color'] ?? '').toString(),
+      blurhash: (json['blurhash'] ?? '').toString(),
+      placeholderDataUrl: (json['placeholder_data_url'] ?? '').toString(),
+      originalUrl: (json['original_url'] ?? '').toString(),
+      fallback: json['fallback'] is Map
+          ? MediaVariant.fromJson(
+              Map<String, dynamic>.from(json['fallback'] as Map),
+            )
+          : null,
+      variants: parsed,
+    );
+  }
+
+  MediaVariant? select({
+    required double logicalWidth,
+    required double devicePixelRatio,
+    String preferredFormat = 'webp',
+  }) {
+    final target = (logicalWidth * devicePixelRatio).ceil().clamp(1, 10000);
+    final order = <String>[preferredFormat, 'webp', 'avif'];
+
+    for (final format in order.toSet()) {
+      final candidates = variants[format];
+      if (candidates == null || candidates.isEmpty) continue;
+
+      for (final candidate in candidates) {
+        if (candidate.width >= target) return candidate;
+      }
+      return candidates.last;
+    }
+
+    return fallback;
+  }
+}

media_optimization_engine-1.4.2/media_engine/management/commands/backfill_registered_media.py

@@ -0,0 +1,72 @@
+from django.core.exceptions import ValidationError
+from django.core.management.base import BaseCommand
+from media_engine.integration import ingest_model_field
+from media_engine.registry import entries
+
+
+class Command(BaseCommand):
+    help = 'Ingest image fields declared through register_model_image().'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--limit', type=int)
+        parser.add_argument(
+            '--fail-fast',
+            action='store_true',
+            help='Stop immediately on the first invalid/unreadable image.',
+        )
+
+    def handle(self, *args, **options):
+        processed = 0
+        skipped = 0
+        failed = 0
+        failures = []
+
+        for entry in entries():
+            qs = entry.model._default_manager.all()
+            if options['limit']:
+                qs = qs[:options['limit']]
+
+            for obj in qs.iterator():
+                try:
+                    asset = ingest_model_field(
+                        obj,
+                        field_name=entry.field_name,
+                        profile=entry.profile,
+                        role=entry.role,
+                    )
+                    if asset is None:
+                        skipped += 1
+                    else:
+                        processed += 1
+                except ValidationError as exc:
+                    failed += 1
+                    message = (
+                        f'{entry.model._meta.label}.{entry.field_name} '
+                        f'pk={obj.pk}: {exc}'
+                    )
+                    failures.append(message)
+                    self.stderr.write(self.style.WARNING(f'SKIP {message}'))
+                    if options['fail_fast']:
+                        raise
+                except (FileNotFoundError, OSError, ValueError) as exc:
+                    failed += 1
+                    message = (
+                        f'{entry.model._meta.label}.{entry.field_name} '
+                        f'pk={obj.pk}: {exc}'
+                    )
+                    failures.append(message)
+                    self.stderr.write(self.style.WARNING(f'SKIP {message}'))
+                    if options['fail_fast']:
+                        raise
+
+        summary = (
+            f'Processed {processed} registered model images; '
+            f'skipped {skipped}; failures {failed}.'
+        )
+        if failed:
+            self.stdout.write(self.style.WARNING(summary))
+            self.stdout.write('Last failures:')
+            for message in failures[-20:]:
+                self.stdout.write(f'  - {message}')
+        else:
+            self.stdout.write(self.style.SUCCESS(summary))

{media_optimization_engine-1.4.0 → media_optimization_engine-1.4.2}/media_engine/storage_paths.py

@@ -2,7 +2,7 @@ from pathlib import Path
 
 
 def safe_extension(fmt):
-    return {'JPEG': 'jpg', 'JPG': 'jpg', 'PNG': 'png', 'WEBP': 'webp', 'AVIF': 'avif'}.get(fmt.upper(), fmt.lower())
+    return {'JPEG': 'jpg', 'JPG': 'jpg', 'MPO': 'jpg', 'PNG': 'png', 'WEBP': 'webp', 'AVIF': 'avif'}.get(fmt.upper(), fmt.lower())
 
 
 def original_storage_name(sha256_hex, extension):

media_optimization_engine-1.4.2/media_engine/tests/test_backfill_registered_media.py

@@ -0,0 +1,51 @@
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from django.core.exceptions import ValidationError
+from django.core.management import call_command
+from django.test import SimpleTestCase
+
+
+class _Manager:
+    def __init__(self, objects):
+        self._objects = list(objects)
+
+    def all(self):
+        return self
+
+    def __iter__(self):
+        return iter(self._objects)
+
+    def __getitem__(self, item):
+        if isinstance(item, slice):
+            return _Manager(self._objects[item])
+        return self._objects[item]
+
+    def iterator(self):
+        return iter(self._objects)
+
+
+class BackfillRegisteredMediaTests(SimpleTestCase):
+    @patch("media_engine.management.commands.backfill_registered_media.entries")
+    @patch("media_engine.management.commands.backfill_registered_media.ingest_model_field")
+    def test_invalid_image_does_not_abort_backfill(self, ingest, entries):
+        model = SimpleNamespace(
+            _default_manager=_Manager([
+                SimpleNamespace(pk=1),
+                SimpleNamespace(pk=2),
+            ]),
+            _meta=SimpleNamespace(label="demo.Photo"),
+        )
+        entries.return_value = [
+            SimpleNamespace(
+                model=model,
+                field_name="image",
+                profile="default",
+                role="content",
+            )
+        ]
+        ingest.side_effect = [ValidationError("Unsupported image format"), object()]
+
+        call_command("backfill_registered_media")
+
+        self.assertEqual(ingest.call_count, 2)

media_optimization_engine-1.4.2/media_engine/tests/test_validators.py

@@ -0,0 +1,30 @@
+from io import BytesIO
+from unittest.mock import MagicMock, patch
+
+from django.core.files.uploadedfile import SimpleUploadedFile
+from django.test import SimpleTestCase
+
+from media_engine.validators import inspect_upload
+
+
+class MpoValidationTests(SimpleTestCase):
+    @patch("media_engine.validators.Image.open")
+    def test_mpo_is_normalized_as_jpeg(self, image_open):
+        image = MagicMock()
+        image.format = "MPO"
+        image.size = (1200, 800)
+        image.verify.return_value = None
+        image_open.return_value = image
+
+        upload = SimpleUploadedFile(
+            "portrait.jpg",
+            b"fake-mpo-container",
+            content_type="image/jpeg",
+        )
+
+        raw, fmt, mime, width, height = inspect_upload(upload)
+
+        self.assertEqual(raw, b"fake-mpo-container")
+        self.assertEqual(fmt, "JPEG")
+        self.assertEqual(mime, "image/jpeg")
+        self.assertEqual((width, height), (1200, 800))

{media_optimization_engine-1.4.0 → media_optimization_engine-1.4.2}/media_engine/validators.py

@@ -7,9 +7,10 @@ try:
 except Exception:
     pillow_avif = None
 
-ALLOWED_FORMATS = {'JPEG', 'PNG', 'WEBP', 'AVIF'}
+ALLOWED_FORMATS = {'JPEG', 'PNG', 'WEBP', 'AVIF', 'MPO'}
 MIME_BY_FORMAT = {
     'JPEG': 'image/jpeg',
+    'MPO': 'image/jpeg',
     'PNG': 'image/png',
     'WEBP': 'image/webp',
     'AVIF': 'image/avif',
@@ -31,6 +32,11 @@ def inspect_upload(uploaded_file):
         fmt = (image.format or '').upper()
         if fmt not in ALLOWED_FORMATS:
             raise ValidationError(f'Unsupported image format: {fmt or "unknown"}')
+        # Pillow reports some JPEG containers as MPO. For optimization purposes,
+        # the primary frame is a normal JPEG-compatible raster and can safely
+        # enter the standard image pipeline.
+        if fmt == 'MPO':
+            fmt = 'JPEG'
         width, height = image.size
         max_pixels = getattr(settings, 'MEDIA_ENGINE_MAX_PIXELS', 50_000_000)
         if width * height > max_pixels:

{media_optimization_engine-1.4.0 → media_optimization_engine-1.4.2/media_optimization_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: media-optimization-engine
-Version: 1.4.0
+Version: 1.4.2
 Summary: Media Optimization Engineer for Django/Python: automatic model-field optimization, responsive picture/srcset rendering, AVIF/WebP derivatives, 360 media, autonomous nodes, and CDN-ready storage.
 Author-email: Achille Kabasele <pepexykabasele@gmail.com>
 Maintainer-email: Achille Kabasele <pepexykabasele@gmail.com>
@@ -233,6 +233,38 @@ JavaScript is not required for normal responsive images.
 
 Runtime measurement is appropriate only for highly dynamic components whose rendered width cannot be described reliably with sizes, such as resizable editors, canvas-like builders, or asynchronously mounted panels.
 
+## Docker image
+
+The standalone service is also published as a multi-architecture GHCR image:
+
+~~~bash
+docker pull ghcr.io/kabasele754/media-optimization-engine:1.4.1
+~~~
+
+For Compose deployment, see `docs/DOCKER.md` and `docker-compose.ghcr.yml`.
+
+## Flutter / native clients
+
+MOE also ships reference Dart adapters for native applications.
+
+Standard Flutter clients should fetch the image manifest, measure the rendered widget width, multiply it by device pixel ratio, and select the first derivative at or above that physical width.
+
+~~~dart
+final variant = manifest.select(
+  logicalWidth: constraints.maxWidth,
+  devicePixelRatio: MediaQuery.devicePixelRatioOf(context),
+  preferredFormat: 'webp',
+);
+~~~
+
+Reference adapters are packaged under:
+
+~~~text
+media_engine/adapters/flutter/
+~~~
+
+This keeps optimization and derivative generation on the Django/Python backend while allowing Flutter to select and cache the most appropriate immutable URL. Panorama manifests use the same principle at tile/level granularity.
+
 ## Backfill
 
 Historical media can be ingested with maintenance commands:

{media_optimization_engine-1.4.0 → media_optimization_engine-1.4.2}/media_optimization_engine.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ media_engine/adapters/__init__.py
 media_engine/adapters/flutter/README.md
 media_engine/adapters/flutter/__init__.py
 media_engine/adapters/flutter/models.dart
+media_engine/adapters/flutter/standard_images.dart
 media_engine/adapters/marzipano/__init__.py
 media_engine/adapters/marzipano/manifest.py
 media_engine/adapters/pannellum/__init__.py
@@ -74,12 +75,14 @@ media_engine/static/media_engine/media-cache-sw.js
 media_engine/templatetags/__init__.py
 media_engine/templatetags/responsive_media.py
 media_engine/tests/__init__.py
+media_engine/tests/test_backfill_registered_media.py
 media_engine/tests/test_distributed_node.py
 media_engine/tests/test_image_ops.py
 media_engine/tests/test_panorama.py
 media_engine/tests/test_paths.py
 media_engine/tests/test_profiles.py
 media_engine/tests/test_responsive_media.py
+media_engine/tests/test_validators.py
 media_optimization_engine.egg-info/PKG-INFO
 media_optimization_engine.egg-info/SOURCES.txt
 media_optimization_engine.egg-info/dependency_links.txt

{media_optimization_engine-1.4.0 → media_optimization_engine-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "media-optimization-engine"
-version = "1.4.0"
+version = "1.4.2"
 description = "Media Optimization Engineer for Django/Python: automatic model-field optimization, responsive picture/srcset rendering, AVIF/WebP derivatives, 360 media, autonomous nodes, and CDN-ready storage."
 requires-python = ">=3.11"
 authors = [{ name = "Achille Kabasele", email = "pepexykabasele@gmail.com" }]

media_optimization_engine-1.4.0/media_engine/adapters/flutter/README.md

@@ -1,10 +0,0 @@
-# Flutter panorama adapter
-
-`models.dart` parses the generic MOE panorama manifest. A Flutter viewer can select the lowest level that satisfies current viewport width and devicePixelRatio, then request only visible tiles.
-
-Recommended policy:
-- show `preview` immediately;
-- select a level from viewport width x DPR;
-- request only tiles intersecting the current field of view;
-- keep adjacent tiles warm for smooth panning;
-- use AVIF where the Flutter image stack supports it, otherwise WebP.

media_optimization_engine-1.4.0/media_engine/management/commands/backfill_registered_media.py

@@ -1,21 +0,0 @@
-from django.core.management.base import BaseCommand
-from media_engine.integration import ingest_model_field
-from media_engine.registry import entries
-
-
-class Command(BaseCommand):
-    help = 'Ingest image fields declared through register_model_image().' 
-
-    def add_arguments(self, parser):
-        parser.add_argument('--limit', type=int)
-
-    def handle(self, *args, **options):
-        processed = 0
-        for entry in entries():
-            qs = entry.model._default_manager.all()
-            if options['limit']:
-                qs = qs[:options['limit']]
-            for obj in qs.iterator():
-                ingest_model_field(obj, field_name=entry.field_name, profile=entry.profile, role=entry.role)
-                processed += 1
-        self.stdout.write(self.style.SUCCESS(f'Processed {processed} registered model images.'))