media-optimization-engine 1.4.0__tar.gz

media_optimization_engine-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Achille Kabasele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

media_optimization_engine-1.4.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: media-optimization-engine
+Version: 1.4.0
+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>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kabasele754/media-optimization-engine
+Project-URL: Repository, https://github.com/Kabasele754/media-optimization-engine
+Project-URL: Issues, https://github.com/Kabasele754/media-optimization-engine/issues
+Project-URL: Documentation, https://github.com/Kabasele754/media-optimization-engine/tree/master/docs
+Keywords: django,media,image-optimization,avif,webp,panorama,360,marzipano,cdn,cloudflare-r2
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<6.1,>=4.2.30
+Requires-Dist: djangorestframework<4,>=3.14
+Requires-Dist: Pillow<13,>=10.3
+Requires-Dist: pillow-avif-plugin<2,>=1.5
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: blurhash<2,>=1.1
+Provides-Extra: celery
+Requires-Dist: celery<6,>=5.4; extra == "celery"
+Requires-Dist: redis<7,>=5; extra == "celery"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
+Provides-Extra: s3
+Requires-Dist: boto3<2,>=1.35; extra == "s3"
+Requires-Dist: django-storages[s3]<2,>=1.14; extra == "s3"
+Provides-Extra: r2
+Requires-Dist: boto3<2,>=1.35; extra == "r2"
+Requires-Dist: django-storages[s3]<2,>=1.14; extra == "r2"
+Provides-Extra: observability
+Requires-Dist: prometheus-client<1,>=0.21; extra == "observability"
+Provides-Extra: all
+Requires-Dist: celery<6,>=5.4; extra == "all"
+Requires-Dist: redis<7,>=5; extra == "all"
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "all"
+Requires-Dist: boto3<2,>=1.35; extra == "all"
+Requires-Dist: django-storages[s3]<2,>=1.14; extra == "all"
+Requires-Dist: prometheus-client<1,>=0.21; extra == "all"
+Dynamic: license-file
+
+# Media Optimization Engineer 1.4
+
+Media Optimization Engineer (MOE) is a reusable Django/Python package for image optimization, responsive delivery, and 360-degree media processing.
+
+The public package is intentionally application-agnostic. It does not depend on any consuming project's themes, tenants, brands, business models, or private infrastructure.
+
+## Core capabilities
+
+### Standard images
+
+- automatic ImageField / FileField integration;
+- immutable originals;
+- AVIF, WebP and JPEG derivatives;
+- responsive width sets;
+- semantic profiles such as avatar, card, hero, and default;
+- focal-point aware crops;
+- dominant color, BlurHash and lightweight placeholders;
+- SHA-256 deduplication;
+- local, S3-compatible and Cloudflare R2 storage;
+- Redis/Celery processing when enabled;
+- CDN-ready derivative URLs;
+- Django template tags for responsive rendering.
+
+### 360 panoramas
+
+- equirectangular panorama support;
+- progressive preview;
+- multiresolution pyramids;
+- tiled AVIF/WebP delivery;
+- generic manifests;
+- Pannellum, Marzipano and Three.js adapters;
+- optional cubemap generation.
+
+## Install
+
+~~~bash
+pip install media-optimization-engine
+~~~
+
+Optional infrastructure extras:
+
+~~~bash
+pip install "media-optimization-engine[all]"
+~~~
+
+## Django setup
+
+~~~python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "rest_framework",
+    "media_engine",
+]
+
+MEDIA_ENGINE_TASK_MODE = "auto"
+
+MEDIA_ENGINE_AUTO_FIELDS = {
+    "articles.Article": {
+        "cover_image": {
+            "profile": "hero",
+            "role": "hero",
+        },
+    },
+    "accounts.Profile": {
+        "photo": {
+            "profile": "avatar",
+            "role": "content",
+        },
+    },
+    "organizations.Organization": {
+        "logo": {
+            "profile": "default",
+            "role": "content",
+        },
+    },
+}
+~~~
+
+~~~python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("api/v1/", include("media_engine.urls")),
+]
+~~~
+
+Then:
+
+~~~bash
+python manage.py migrate
+python manage.py media_engine_doctor
+~~~
+
+## Django template rendering
+
+For normal model fields, use the high-level media_image tag:
+
+~~~django
+{% load responsive_media %}
+
+{% media_image article "cover_image"
+    alt=article.title
+    css_class="article-hero"
+    sizes="(max-width: 768px) 100vw, 1200px"
+%}
+~~~
+
+MOE resolves the field's MediaBinding, generates a responsive picture with available AVIF/WebP sources, preserves the image's CSS classes, and falls back to the original field URL only when no processed binding is available.
+
+### Logo or footer image
+
+~~~django
+{% load responsive_media %}
+
+{% media_image organization "logo"
+    alt=organization.name
+    css_class="site-logo"
+    sizes="240px"
+%}
+~~~
+
+### Card grid
+
+~~~django
+{% load responsive_media %}
+
+{% for article in articles %}
+  <article class="article-card">
+    {% media_image article "cover_image"
+        alt=article.title
+        css_class="article-card__image"
+        sizes="(max-width: 640px) 92vw, (max-width: 1100px) 45vw, 360px"
+    %}
+    <h2>{{ article.title }}</h2>
+  </article>
+{% endfor %}
+~~~
+
+### Direct binding rendering
+
+Advanced integrations can render a known asset directly:
+
+~~~django
+{% load responsive_media %}
+
+{% responsive_image binding.asset
+    profile=binding.profile
+    role=binding.role
+    alt=object.title
+    css_class="media-object"
+    picture_class="media-object-picture"
+    sizes="100vw"
+%}
+~~~
+
+### One optimized URL
+
+For Open Graph metadata, CSS backgrounds, emails, or APIs where picture is not possible:
+
+~~~django
+{% load responsive_media %}
+
+{% media_url organization "logo" preferred_width=512 preferred_format="webp" as optimized_logo %}
+
+<meta property="og:image" content="{{ optimized_logo }}">
+~~~
+
+For normal page images, prefer media_image over media_url; the browser can make a better final choice from srcset and sizes.
+
+## Responsive selection
+
+MOE provides width descriptors and sizes. The browser chooses the final resource using layout width, viewport, DPR, supported formats, and its own network heuristics.
+
+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.
+
+## Backfill
+
+Historical media can be ingested with maintenance commands:
+
+~~~bash
+python manage.py backfill_registered_media
+python manage.py audit_media_engine --fail-on-incomplete
+~~~
+
+New uploads registered in MEDIA_ENGINE_AUTO_FIELDS are handled automatically.
+
+## Runtime independence
+
+Embedded Django mode and standalone-node mode are autonomous. Optional control-plane synchronization must never be required for upload, processing, rendering, or derivative delivery.
+
+## License
+
+MIT License. Copyright (c) 2026 Achille Kabasele.

media_optimization_engine-1.4.0/README.md

@@ -0,0 +1,197 @@
+# Media Optimization Engineer 1.4
+
+Media Optimization Engineer (MOE) is a reusable Django/Python package for image optimization, responsive delivery, and 360-degree media processing.
+
+The public package is intentionally application-agnostic. It does not depend on any consuming project's themes, tenants, brands, business models, or private infrastructure.
+
+## Core capabilities
+
+### Standard images
+
+- automatic ImageField / FileField integration;
+- immutable originals;
+- AVIF, WebP and JPEG derivatives;
+- responsive width sets;
+- semantic profiles such as avatar, card, hero, and default;
+- focal-point aware crops;
+- dominant color, BlurHash and lightweight placeholders;
+- SHA-256 deduplication;
+- local, S3-compatible and Cloudflare R2 storage;
+- Redis/Celery processing when enabled;
+- CDN-ready derivative URLs;
+- Django template tags for responsive rendering.
+
+### 360 panoramas
+
+- equirectangular panorama support;
+- progressive preview;
+- multiresolution pyramids;
+- tiled AVIF/WebP delivery;
+- generic manifests;
+- Pannellum, Marzipano and Three.js adapters;
+- optional cubemap generation.
+
+## Install
+
+~~~bash
+pip install media-optimization-engine
+~~~
+
+Optional infrastructure extras:
+
+~~~bash
+pip install "media-optimization-engine[all]"
+~~~
+
+## Django setup
+
+~~~python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "rest_framework",
+    "media_engine",
+]
+
+MEDIA_ENGINE_TASK_MODE = "auto"
+
+MEDIA_ENGINE_AUTO_FIELDS = {
+    "articles.Article": {
+        "cover_image": {
+            "profile": "hero",
+            "role": "hero",
+        },
+    },
+    "accounts.Profile": {
+        "photo": {
+            "profile": "avatar",
+            "role": "content",
+        },
+    },
+    "organizations.Organization": {
+        "logo": {
+            "profile": "default",
+            "role": "content",
+        },
+    },
+}
+~~~
+
+~~~python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("api/v1/", include("media_engine.urls")),
+]
+~~~
+
+Then:
+
+~~~bash
+python manage.py migrate
+python manage.py media_engine_doctor
+~~~
+
+## Django template rendering
+
+For normal model fields, use the high-level media_image tag:
+
+~~~django
+{% load responsive_media %}
+
+{% media_image article "cover_image"
+    alt=article.title
+    css_class="article-hero"
+    sizes="(max-width: 768px) 100vw, 1200px"
+%}
+~~~
+
+MOE resolves the field's MediaBinding, generates a responsive picture with available AVIF/WebP sources, preserves the image's CSS classes, and falls back to the original field URL only when no processed binding is available.
+
+### Logo or footer image
+
+~~~django
+{% load responsive_media %}
+
+{% media_image organization "logo"
+    alt=organization.name
+    css_class="site-logo"
+    sizes="240px"
+%}
+~~~
+
+### Card grid
+
+~~~django
+{% load responsive_media %}
+
+{% for article in articles %}
+  <article class="article-card">
+    {% media_image article "cover_image"
+        alt=article.title
+        css_class="article-card__image"
+        sizes="(max-width: 640px) 92vw, (max-width: 1100px) 45vw, 360px"
+    %}
+    <h2>{{ article.title }}</h2>
+  </article>
+{% endfor %}
+~~~
+
+### Direct binding rendering
+
+Advanced integrations can render a known asset directly:
+
+~~~django
+{% load responsive_media %}
+
+{% responsive_image binding.asset
+    profile=binding.profile
+    role=binding.role
+    alt=object.title
+    css_class="media-object"
+    picture_class="media-object-picture"
+    sizes="100vw"
+%}
+~~~
+
+### One optimized URL
+
+For Open Graph metadata, CSS backgrounds, emails, or APIs where picture is not possible:
+
+~~~django
+{% load responsive_media %}
+
+{% media_url organization "logo" preferred_width=512 preferred_format="webp" as optimized_logo %}
+
+<meta property="og:image" content="{{ optimized_logo }}">
+~~~
+
+For normal page images, prefer media_image over media_url; the browser can make a better final choice from srcset and sizes.
+
+## Responsive selection
+
+MOE provides width descriptors and sizes. The browser chooses the final resource using layout width, viewport, DPR, supported formats, and its own network heuristics.
+
+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.
+
+## Backfill
+
+Historical media can be ingested with maintenance commands:
+
+~~~bash
+python manage.py backfill_registered_media
+python manage.py audit_media_engine --fail-on-incomplete
+~~~
+
+New uploads registered in MEDIA_ENGINE_AUTO_FIELDS are handled automatically.
+
+## Runtime independence
+
+Embedded Django mode and standalone-node mode are autonomous. Optional control-plane synchronization must never be required for upload, processing, rendering, or derivative delivery.
+
+## License
+
+MIT License. Copyright (c) 2026 Achille Kabasele.

media_optimization_engine-1.4.0/media_engine/__init__.py

@@ -0,0 +1,7 @@
+__version__ = '1.4.0rc3'
+
+def register_model_image(*args, **kwargs):
+    from .registry import register_model_image as _register
+    return _register(*args, **kwargs)
+
+default_app_config = 'media_engine.apps.MediaEngineConfig'

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

@@ -0,0 +1,10 @@
+# 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/adapters/flutter/models.dart

@@ -0,0 +1,88 @@
+class PanoramaTile {
+  final int level;
+  final int x;
+  final int y;
+  final int width;
+  final int height;
+  final String url;
+
+  const PanoramaTile({
+    required this.level,
+    required this.x,
+    required this.y,
+    required this.width,
+    required this.height,
+    required this.url,
+  });
+
+  factory PanoramaTile.fromJson(int level, Map<String, dynamic> json) => PanoramaTile(
+        level: level,
+        x: json['x'] as int,
+        y: json['y'] as int,
+        width: json['width'] as int,
+        height: json['height'] as int,
+        url: json['url'] as String,
+      );
+}
+
+class PanoramaLevel {
+  final int level;
+  final int width;
+  final int height;
+  final int cols;
+  final int rows;
+  final int tileSize;
+  final Map<String, List<PanoramaTile>> formats;
+
+  const PanoramaLevel({
+    required this.level,
+    required this.width,
+    required this.height,
+    required this.cols,
+    required this.rows,
+    required this.tileSize,
+    required this.formats,
+  });
+
+  factory PanoramaLevel.fromJson(Map<String, dynamic> json) {
+    final level = json['level'] as int;
+    final rawFormats = Map<String, dynamic>.from(json['formats'] as Map);
+    return PanoramaLevel(
+      level: level,
+      width: json['width'] as int,
+      height: json['height'] as int,
+      cols: json['cols'] as int,
+      rows: json['rows'] as int,
+      tileSize: json['tile_size'] as int,
+      formats: rawFormats.map((key, value) => MapEntry(
+            key,
+            (value as List)
+                .map((e) => PanoramaTile.fromJson(level, Map<String, dynamic>.from(e as Map)))
+                .toList(),
+          )),
+    );
+  }
+}
+
+class PanoramaManifest {
+  final String assetId;
+  final String projection;
+  final String preview;
+  final List<PanoramaLevel> levels;
+
+  const PanoramaManifest({
+    required this.assetId,
+    required this.projection,
+    required this.preview,
+    required this.levels,
+  });
+
+  factory PanoramaManifest.fromJson(Map<String, dynamic> json) => PanoramaManifest(
+        assetId: json['asset_id'] as String,
+        projection: json['projection'] as String? ?? 'equirectangular',
+        preview: json['preview'] as String? ?? '',
+        levels: (json['levels'] as List? ?? const [])
+            .map((e) => PanoramaLevel.fromJson(Map<String, dynamic>.from(e as Map)))
+            .toList(),
+      );
+}

media_optimization_engine-1.4.0/media_engine/adapters/marzipano/__init__.py

@@ -0,0 +1,2 @@
+from .manifest import to_marzipano
+__all__ = ['to_marzipano']

media_optimization_engine-1.4.0/media_engine/adapters/marzipano/manifest.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+
+def to_marzipano(manifest: dict) -> dict:
+    """Return a browser-friendly Marzipano description.
+
+    For ``panorama.marzipano`` the engine emits a true multires CubeGeometry
+    pyramid. Tiles stay explicit so this works with local storage, S3 and R2
+    without assuming a specific URL layout.
+    """
+    layout = manifest.get('layout', '')
+    if layout != 'cube-multires':
+        # Graceful preview fallback for a generic equirectangular pipeline.
+        return {
+            'type': 'equirectangular',
+            'preview': manifest.get('preview', ''),
+            'projection': manifest.get('projection', 'equirectangular'),
+            'levels': manifest.get('levels', []),
+        }
+
+    levels = []
+    tiles = []
+    preferred_format = 'webp'
+    for item in manifest.get('levels', []):
+        formats = item.get('formats', {})
+        selected = formats.get('webp') or formats.get('avif') or next(iter(formats.values()), [])
+        if not selected:
+            continue
+        if formats.get('webp') is None and formats.get('avif'):
+            preferred_format = 'avif'
+        levels.append({
+            'level': item['level'],
+            'size': item.get('size') or item.get('width'),
+            'tileSize': item.get('tile_size', 512),
+            'fallbackOnly': bool(item.get('fallback_only', False)),
+        })
+        for tile in selected:
+            tiles.append({
+                'z': item['level'],
+                'face': tile.get('face', ''),
+                'x': tile['x'],
+                'y': tile['y'],
+                'url': tile['url'],
+            })
+
+    return {
+        'type': 'cube-multires',
+        'preview': manifest.get('preview', ''),
+        'projection': manifest.get('projection', 'equirectangular'),
+        'format': preferred_format,
+        'geometry': {'type': 'cube', 'levels': levels},
+        'tiles': tiles,
+    }

media_optimization_engine-1.4.0/media_engine/adapters/pannellum/__init__.py

@@ -0,0 +1,2 @@
+from .manifest import to_pannellum
+__all__ = ['to_pannellum']

media_optimization_engine-1.4.0/media_engine/adapters/pannellum/manifest.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+def to_pannellum(manifest: dict) -> dict:
+    levels = manifest.get('levels', [])
+    if not levels:
+        return {'type': 'equirectangular', 'panorama': manifest.get('preview', '')}
+    max_level = max(level['level'] for level in levels)
+    tile_size = levels[0].get('tile_size', 512)
+    base = {
+        'type': 'multires',
+        'multiRes': {
+            'basePath': '',
+            'path': '{z}/{x}_{y}.webp',
+            'fallbackPath': '{z}/{x}_{y}.webp',
+            'extension': 'webp',
+            'tileResolution': tile_size,
+            'maxLevel': max_level,
+            'cubeResolution': levels[-1].get('width', 0),
+        },
+        'preview': manifest.get('preview', ''),
+    }
+    return base

media_optimization_engine-1.4.0/media_engine/adapters/threejs/__init__.py

@@ -0,0 +1,2 @@
+from .manifest import to_threejs
+__all__ = ['to_threejs']

media_optimization_engine-1.4.0/media_engine/adapters/threejs/manifest.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+def to_threejs(manifest: dict) -> dict:
+    return {
+        'type': 'equirectangular-multires',
+        'preview': manifest.get('preview', ''),
+        'levels': manifest.get('levels', []),
+        'projection': manifest.get('projection', 'equirectangular'),
+    }