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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: media-optimization-engine
-Version: 1.4.0
+Version: 1.4.1
 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,28 @@ 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.
 
+## 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.1}/README.md

@@ -177,6 +177,28 @@ 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.
 
+## 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.1/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.1/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.0 → media_optimization_engine-1.4.1/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.1
 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,28 @@ 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.
 
+## 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.1}/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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "media-optimization-engine"
-version = "1.4.0"
+version = "1.4.1"
 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.