media-optimization-engine 1.4.0__py3-none-any.whl

media_engine/processors/panorama/cube_tiles.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from PIL import Image
+from django.core.files.base import ContentFile
+from django.core.files.storage import default_storage
+
+from ...image_ops import encode_with_budget
+from ...models import PanoramaTile
+from .cubemap import equirectangular_to_cubemap
+
+# Marzipano's CubeGeometry canonical face keys.
+FACE_NAME_TO_KEY = {
+    'front': 'f',
+    'back': 'b',
+    'left': 'l',
+    'right': 'r',
+    'top': 'u',
+    'bottom': 'd',
+}
+
+
+@dataclass(frozen=True)
+class CubeLevelPlan:
+    level: int
+    size: int
+    tile_size: int
+
+    @property
+    def cols(self) -> int:
+        return math.ceil(self.size / self.tile_size)
+
+    @property
+    def rows(self) -> int:
+        return math.ceil(self.size / self.tile_size)
+
+
+def _largest_power_of_two_lte(value: int, *, minimum: int = 512, maximum: int = 4096) -> int:
+    value = min(max(int(value), minimum), maximum)
+    power = 1
+    while power * 2 <= value:
+        power *= 2
+    return max(power, minimum)
+
+
+def cube_level_sizes(original_width: int, *, min_size: int = 512, max_size: int = 4096) -> list[int]:
+    # A common equirectangular panorama has width ~= 4 * cubemap face width.
+    estimated = max(min_size, int(original_width / 4))
+    top = _largest_power_of_two_lte(estimated, minimum=min_size, maximum=max_size)
+    sizes: list[int] = []
+    current = min_size
+    while current <= top:
+        sizes.append(current)
+        current *= 2
+    return sizes or [min_size]
+
+
+def generate_cube_level(
+    asset,
+    source_image: Image.Image,
+    *,
+    profile: str,
+    version: int,
+    plan: CubeLevelPlan,
+    fmt: str = 'webp',
+    quality: int = 72,
+    force: bool = False,
+) -> int:
+    faces = equirectangular_to_cubemap(source_image, plan.size)
+    generated = 0
+    for face_name, face_image in faces.items():
+        face = FACE_NAME_TO_KEY[face_name]
+        for row in range(plan.rows):
+            for col in range(plan.cols):
+                left = col * plan.tile_size
+                top = row * plan.tile_size
+                right = min(left + plan.tile_size, plan.size)
+                bottom = min(top + plan.tile_size, plan.size)
+                tile = face_image.crop((left, top, right, bottom))
+                obj, _ = PanoramaTile.objects.get_or_create(
+                    asset=asset,
+                    profile=profile,
+                    processor_version=version,
+                    level=plan.level,
+                    face=face,
+                    col=col,
+                    row=row,
+                    format=fmt,
+                    defaults={
+                        'width': tile.width,
+                        'height': tile.height,
+                        'level_width': plan.size,
+                        'level_height': plan.size,
+                    },
+                )
+                if obj.status == PanoramaTile.Status.READY and not force:
+                    continue
+                encoded = encode_with_budget(tile, fmt, quality, target_bytes=None)
+                path = (
+                    f'media_engine/panoramas/{asset.original_sha256[:2]}/'
+                    f'{asset.original_sha256}/v{version}/{profile}/'
+                    f'l{plan.level}/{face}/{col}_{row}.{fmt}'
+                )
+                if default_storage.exists(path):
+                    default_storage.delete(path)
+                stored = default_storage.save(path, ContentFile(encoded.content))
+                obj.file = stored
+                obj.width = tile.width
+                obj.height = tile.height
+                obj.level_width = plan.size
+                obj.level_height = plan.size
+                obj.file_size = len(encoded.content)
+                obj.quality = encoded.quality
+                obj.status = PanoramaTile.Status.READY
+                obj.last_error = ''
+                obj.save()
+                generated += 1
+    return generated

media_engine/processors/panorama/cubemap.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import math
+import numpy as np
+from PIL import Image
+
+
+_FACE_VECTORS = {
+    'front': lambda a, b: (a, b, np.ones_like(a)),
+    'back': lambda a, b: (-a, b, -np.ones_like(a)),
+    'left': lambda a, b: (-np.ones_like(a), b, a),
+    'right': lambda a, b: (np.ones_like(a), b, -a),
+    'top': lambda a, b: (a, np.ones_like(a), -b),
+    'bottom': lambda a, b: (a, -np.ones_like(a), b),
+}
+
+
+def _sample_equirectangular(array: np.ndarray, x: np.ndarray, y: np.ndarray, z: np.ndarray) -> np.ndarray:
+    norm = np.sqrt(x * x + y * y + z * z)
+    x, y, z = x / norm, y / norm, z / norm
+    lon = np.arctan2(x, z)
+    lat = np.arcsin(np.clip(y, -1.0, 1.0))
+    h, w = array.shape[:2]
+    px = ((lon / (2.0 * math.pi)) + 0.5) * (w - 1)
+    py = (0.5 - lat / math.pi) * (h - 1)
+    xi = np.mod(np.rint(px).astype(np.int64), w)
+    yi = np.clip(np.rint(py).astype(np.int64), 0, h - 1)
+    return array[yi, xi]
+
+
+def equirectangular_to_cubemap(image: Image.Image, face_size: int) -> dict[str, Image.Image]:
+    src = np.asarray(image.convert('RGB'))
+    axis = np.linspace(-1.0, 1.0, face_size, dtype=np.float32)
+    a, b = np.meshgrid(axis, -axis)
+    result = {}
+    for name, vector_fn in _FACE_VECTORS.items():
+        x, y, z = vector_fn(a, b)
+        sampled = _sample_equirectangular(src, x, y, z)
+        result[name] = Image.fromarray(sampled.astype(np.uint8), mode='RGB')
+    return result

media_engine/processors/panorama/detect.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PanoramaDetection:
+    is_panorama: bool
+    projection: str
+    confidence: str
+    reason: str
+
+
+def detect_equirectangular(width: int, height: int, metadata: dict | None = None) -> PanoramaDetection:
+    metadata = metadata or {}
+    projection_type = str(metadata.get('ProjectionType') or metadata.get('GPano:ProjectionType') or '').lower()
+    if projection_type == 'equirectangular':
+        return PanoramaDetection(True, 'equirectangular', 'high', 'GPano/XMP projection metadata')
+    if height > 0:
+        ratio = width / height
+        if width >= 2048 and 1.98 <= ratio <= 2.02:
+            return PanoramaDetection(True, 'equirectangular', 'medium', '2:1 dimensions typical of equirectangular panoramas')
+    return PanoramaDetection(False, '', 'low', 'No reliable panorama signal')

media_engine/processors/panorama/equirectangular.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from django.conf import settings
+from django.core.files.base import ContentFile
+from django.core.files.storage import default_storage
+from django.utils import timezone
+
+from ...image_ops import normalized_image, encode_with_budget
+from ...models import MediaAsset, PanoramaTile
+from ..base import ProcessorResult
+from .tiles import pyramid_widths, build_plan, generate_level
+from .cube_tiles import cube_level_sizes, CubeLevelPlan, generate_cube_level
+
+
+class Panorama360Processor:
+    name = 'panorama_360'
+
+    def supports(self, asset, profile_name: str) -> bool:
+        return getattr(asset, 'media_kind', '') == 'panorama' or profile_name.startswith('panorama.')
+
+    def _write_preview(self, asset, image, *, version: int, profile_name: str):
+        preview_width = min(1024, asset.width)
+        preview_height = max(1, preview_width // 2)
+        preview = image.resize((preview_width, preview_height))
+        encoded_preview = encode_with_budget(preview, 'webp', 58, target_bytes=140000)
+        preview_path = (
+            f'media_engine/panoramas/{asset.original_sha256[:2]}/'
+            f'{asset.original_sha256}/v{version}/{profile_name}/preview.webp'
+        )
+        if default_storage.exists(preview_path):
+            default_storage.delete(preview_path)
+        asset.panorama_preview = default_storage.save(preview_path, ContentFile(encoded_preview.content))
+
+    def _process_equirect_tiles(self, asset, image, *, version: int, profile_name: str, force: bool):
+        tile_size = getattr(settings, 'MEDIA_ENGINE_PANORAMA_TILE_SIZE', 512)
+        min_width = getattr(settings, 'MEDIA_ENGINE_PANORAMA_MIN_LEVEL_WIDTH', 1024)
+        formats = tuple(getattr(settings, 'MEDIA_ENGINE_PANORAMA_FORMATS', ('avif', 'webp')))
+        quality_map = getattr(settings, 'MEDIA_ENGINE_PANORAMA_QUALITY', {'avif': 52, 'webp': 72})
+        widths = pyramid_widths(asset.width, min_width=min_width)
+        for level, width in enumerate(widths):
+            plan = build_plan(width, tile_size, level)
+            for fmt in formats:
+                generate_level(
+                    asset,
+                    image,
+                    profile=profile_name,
+                    version=version,
+                    plan=plan,
+                    fmt=fmt,
+                    quality=quality_map.get(fmt, 70),
+                    force=force,
+                )
+                PanoramaTile.objects.filter(
+                    asset=asset,
+                    profile=profile_name,
+                    processor_version=version,
+                    level=level,
+                    face='',
+                ).update(level_width=plan.width, level_height=plan.height)
+        return {'layout': 'equirectangular-grid', 'levels': len(widths), 'formats': list(formats)}
+
+    def _process_marzipano_cube(self, asset, image, *, version: int, profile_name: str, force: bool):
+        tile_size = getattr(settings, 'MEDIA_ENGINE_PANORAMA_TILE_SIZE', 512)
+        min_size = getattr(settings, 'MEDIA_ENGINE_PANORAMA_CUBE_MIN_SIZE', 512)
+        max_size = getattr(settings, 'MEDIA_ENGINE_PANORAMA_CUBE_MAX_SIZE', 4096)
+        fmt = getattr(settings, 'MEDIA_ENGINE_PANORAMA_CUBE_FORMAT', 'webp').lower()
+        quality = int(getattr(settings, 'MEDIA_ENGINE_PANORAMA_CUBE_QUALITY', 72))
+        sizes = cube_level_sizes(asset.width, min_size=min_size, max_size=max_size)
+        for level, size in enumerate(sizes):
+            generate_cube_level(
+                asset,
+                image,
+                profile=profile_name,
+                version=version,
+                plan=CubeLevelPlan(level=level, size=size, tile_size=tile_size),
+                fmt=fmt,
+                quality=quality,
+                force=force,
+            )
+        return {
+            'layout': 'cube-multires',
+            'levels': len(sizes),
+            'face_sizes': sizes,
+            'format': fmt,
+            'tile_size': tile_size,
+        }
+
+    def process(self, asset, profile_name: str, force: bool = False) -> ProcessorResult:
+        version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+        asset.status = MediaAsset.Status.PROCESSING
+        asset.last_error = ''
+        asset.save(update_fields=['status', 'last_error', 'updated_at'])
+        try:
+            with default_storage.open(asset.original_file.name, 'rb') as source:
+                image = normalized_image(source).convert('RGB')
+            self._write_preview(asset, image, version=version, profile_name=profile_name)
+
+            PanoramaTile.objects.filter(
+                asset=asset,
+                profile=profile_name,
+                processor_version=version,
+            ).exclude(status=PanoramaTile.Status.READY).delete()
+
+            if profile_name in {'panorama.marzipano', 'panorama.cube'}:
+                pipeline = self._process_marzipano_cube(
+                    asset, image, version=version, profile_name=profile_name, force=force
+                )
+            else:
+                pipeline = self._process_equirect_tiles(
+                    asset, image, version=version, profile_name=profile_name, force=force
+                )
+
+            metadata = dict(asset.metadata_json or {})
+            metadata['panorama_pipeline'] = pipeline
+            if getattr(settings, 'MEDIA_ENGINE_PANORAMA_GENERATE_CUBEMAP', False) and profile_name not in {'panorama.marzipano', 'panorama.cube'}:
+                from .cubemap import equirectangular_to_cubemap
+                face_size = min(
+                    getattr(settings, 'MEDIA_ENGINE_PANORAMA_CUBEMAP_FACE_SIZE', 2048),
+                    max(256, asset.height // 2),
+                )
+                faces = equirectangular_to_cubemap(image, face_size)
+                face_urls = {}
+                for face_name, face_image in faces.items():
+                    encoded_face = encode_with_budget(face_image, 'webp', 76, target_bytes=None)
+                    face_path = (
+                        f'media_engine/panoramas/{asset.original_sha256[:2]}/'
+                        f'{asset.original_sha256}/v{version}/{profile_name}/cube/{face_name}.webp'
+                    )
+                    if default_storage.exists(face_path):
+                        default_storage.delete(face_path)
+                    stored_face = default_storage.save(face_path, ContentFile(encoded_face.content))
+                    face_urls[face_name] = default_storage.url(stored_face)
+                metadata['cubemap'] = {'face_size': face_size, 'format': 'webp', 'faces': face_urls}
+
+            asset.metadata_json = metadata
+            asset.media_kind = 'panorama'
+            asset.projection = asset.projection or 'equirectangular'
+            asset.processor = self.name
+            asset.processor_version = version
+            asset.status = MediaAsset.Status.READY
+            asset.processed_at = timezone.now()
+            asset.last_error = ''
+            asset.save()
+        except Exception as exc:
+            asset.status = MediaAsset.Status.FAILED
+            asset.last_error = str(exc)
+            asset.save(update_fields=['status', 'last_error', 'updated_at'])
+            raise
+        return ProcessorResult(str(asset.pk), self.name, asset.status)

media_engine/processors/panorama/manifest.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from django.conf import settings
+
+
+def panorama_manifest(asset, profile: str = 'panorama.multires') -> dict:
+    qs = asset.panorama_tiles.filter(profile=profile, status='READY').order_by('level', 'face', 'row', 'col')
+    is_cube = qs.exclude(face='').exists()
+
+    if is_cube:
+        groups = defaultdict(lambda: {
+            'formats': defaultdict(list),
+            'size': 0,
+            'cols': 0,
+            'rows': 0,
+            'faces': set(),
+        })
+        for tile in qs:
+            level = groups[tile.level]
+            level['size'] = max(level['size'], tile.level_width, tile.level_height)
+            level['cols'] = max(level['cols'], tile.col + 1)
+            level['rows'] = max(level['rows'], tile.row + 1)
+            level['faces'].add(tile.face)
+            level['formats'][tile.format].append({
+                'face': tile.face,
+                'x': tile.col,
+                'y': tile.row,
+                'width': tile.width,
+                'height': tile.height,
+                'url': tile.file.url,
+                'bytes': tile.file_size,
+            })
+        levels = []
+        for level_id in sorted(groups):
+            item = groups[level_id]
+            levels.append({
+                'level': level_id,
+                'size': item['size'],
+                'width': item['size'],
+                'height': item['size'],
+                'cols': item['cols'],
+                'rows': item['rows'],
+                'tile_size': getattr(settings, 'MEDIA_ENGINE_PANORAMA_TILE_SIZE', 512),
+                'faces': sorted(item['faces']),
+                'formats': dict(item['formats']),
+            })
+        return {
+            'asset_id': str(asset.pk),
+            'media_kind': 'panorama',
+            'projection': asset.projection or 'equirectangular',
+            'layout': 'cube-multires',
+            'width': asset.width,
+            'height': asset.height,
+            'profile': profile,
+            'levels': levels,
+            'preview': asset.panorama_preview.url if asset.panorama_preview else '',
+            'dominant_color': asset.dominant_color,
+            'blurhash': asset.blurhash,
+            'processor_version': asset.processor_version,
+            'cubemap': (asset.metadata_json or {}).get('cubemap'),
+        }
+
+    groups = defaultdict(lambda: {'formats': defaultdict(list), 'width': 0, 'height': 0, 'cols': 0, 'rows': 0})
+    for tile in qs:
+        level = groups[tile.level]
+        level['width'] = max(level['width'], tile.level_width)
+        level['height'] = max(level['height'], tile.level_height)
+        level['cols'] = max(level['cols'], tile.col + 1)
+        level['rows'] = max(level['rows'], tile.row + 1)
+        level['formats'][tile.format].append({
+            'x': tile.col,
+            'y': tile.row,
+            'width': tile.width,
+            'height': tile.height,
+            'url': tile.file.url,
+            'bytes': tile.file_size,
+        })
+    levels = []
+    for level_id in sorted(groups):
+        item = groups[level_id]
+        levels.append({
+            'level': level_id,
+            'width': item['width'],
+            'height': item['height'],
+            'cols': item['cols'],
+            'rows': item['rows'],
+            'tile_size': getattr(settings, 'MEDIA_ENGINE_PANORAMA_TILE_SIZE', 512),
+            'formats': dict(item['formats']),
+        })
+    return {
+        'asset_id': str(asset.pk),
+        'media_kind': 'panorama',
+        'projection': asset.projection or 'equirectangular',
+        'layout': 'equirectangular-grid',
+        'width': asset.width,
+        'height': asset.height,
+        'profile': profile,
+        'levels': levels,
+        'preview': asset.panorama_preview.url if asset.panorama_preview else '',
+        'dominant_color': asset.dominant_color,
+        'blurhash': asset.blurhash,
+        'processor_version': asset.processor_version,
+        'cubemap': (asset.metadata_json or {}).get('cubemap'),
+    }

media_engine/processors/panorama/tiles.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import io
+import math
+from dataclasses import dataclass
+
+from PIL import Image
+from django.core.files.base import ContentFile
+from django.core.files.storage import default_storage
+
+from ...image_ops import encode_with_budget
+from ...models import PanoramaTile
+
+
+@dataclass(frozen=True)
+class TilePlan:
+    level: int
+    width: int
+    height: int
+    cols: int
+    rows: int
+    tile_size: int
+
+
+def pyramid_widths(original_width: int, min_width: int = 1024) -> list[int]:
+    values = []
+    width = max(1, original_width)
+    while width > min_width:
+        values.append(width)
+        width = width // 2
+    values.append(min(width, min_width) if original_width >= min_width else original_width)
+    return sorted(set(v for v in values if v > 0))
+
+
+def build_plan(width: int, tile_size: int, level: int) -> TilePlan:
+    height = max(1, width // 2)
+    return TilePlan(
+        level=level,
+        width=width,
+        height=height,
+        cols=math.ceil(width / tile_size),
+        rows=math.ceil(height / tile_size),
+        tile_size=tile_size,
+    )
+
+
+def generate_level(asset, image: Image.Image, *, profile: str, version: int, plan: TilePlan, fmt: str, quality: int, force: bool = False):
+    work = image.resize((plan.width, plan.height), Image.Resampling.LANCZOS)
+    generated = 0
+    for row in range(plan.rows):
+        for col in range(plan.cols):
+            left = col * plan.tile_size
+            top = row * plan.tile_size
+            right = min(left + plan.tile_size, plan.width)
+            bottom = min(top + plan.tile_size, plan.height)
+            tile = work.crop((left, top, right, bottom))
+            obj, _ = PanoramaTile.objects.get_or_create(
+                asset=asset,
+                profile=profile,
+                processor_version=version,
+                level=plan.level,
+                face='',
+                col=col,
+                row=row,
+                format=fmt,
+                defaults={'width': tile.width, 'height': tile.height},
+            )
+            if obj.status == PanoramaTile.Status.READY and not force:
+                continue
+            encoded = encode_with_budget(tile, fmt, quality, target_bytes=None)
+            path = (
+                f'media_engine/panoramas/{asset.original_sha256[:2]}/'
+                f'{asset.original_sha256}/v{version}/{profile}/'
+                f'l{plan.level}/{col}_{row}.{fmt}'
+            )
+            if default_storage.exists(path):
+                default_storage.delete(path)
+            stored = default_storage.save(path, ContentFile(encoded.content))
+            obj.file = stored
+            obj.width = tile.width
+            obj.height = tile.height
+            obj.file_size = len(encoded.content)
+            obj.quality = encoded.quality
+            obj.status = PanoramaTile.Status.READY
+            obj.last_error = ''
+            obj.save()
+            generated += 1
+    return generated

media_engine/processors/registry.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .image.standard import StandardImageProcessor
+from .panorama.equirectangular import Panorama360Processor
+
+_PROCESSORS = [Panorama360Processor(), StandardImageProcessor()]
+
+
+def get_processor(asset, profile_name: str):
+    for processor in _PROCESSORS:
+        if processor.supports(asset, profile_name):
+            return processor
+    raise RuntimeError(f'No media processor supports asset={asset.pk} profile={profile_name}')
+
+
+def registered_processors():
+    return tuple(p.name for p in _PROCESSORS)

media_engine/profiles.py

@@ -0,0 +1,77 @@
+from django.conf import settings
+
+DEFAULT_PROFILES = {
+    'default': {
+        'widths': [320, 480, 640, 960, 1280, 1600],
+        'formats': ['avif', 'webp'],
+        'fallback_format': 'jpeg',
+        'fit': 'contain',
+        'quality': {'avif': 52, 'webp': 72, 'jpeg': 80},
+        'target_bytes': {},
+    },
+    'avatar': {
+        'widths': [96, 192, 384],
+        'formats': ['avif', 'webp'],
+        'fallback_format': 'jpeg',
+        'fit': 'cover',
+        'aspect_ratio': [1, 1],
+        'quality': {'avif': 48, 'webp': 68, 'jpeg': 78},
+        'target_bytes': {96: 25000, 192: 40000, 384: 70000},
+    },
+    'card': {
+        'widths': [320, 480, 640, 768],
+        'formats': ['avif', 'webp'],
+        'fallback_format': 'jpeg',
+        'fit': 'cover',
+        'aspect_ratio': [4, 3],
+        'quality': {'avif': 50, 'webp': 70, 'jpeg': 80},
+        'target_bytes': {320: 45000, 480: 70000, 640: 95000, 768: 120000},
+    },
+    'hero': {
+        'widths': [640, 960, 1280, 1600, 1920],
+        'formats': ['avif', 'webp'],
+        'fallback_format': 'jpeg',
+        'fit': 'cover',
+        'aspect_ratio': [16, 9],
+        'quality': {'avif': 56, 'webp': 76, 'jpeg': 84},
+        'target_bytes': {640: 120000, 960: 170000, 1280: 220000, 1600: 300000, 1920: 360000},
+    },
+    'panorama.preview': {
+        'widths': [1024],
+        'formats': ['webp'],
+        'fallback_format': 'jpeg',
+        'fit': 'contain',
+        'quality': {'webp': 58, 'jpeg': 72},
+        'target_bytes': {1024: 140000},
+    },
+    'panorama.multires': {
+        'widths': [],
+        'formats': ['avif', 'webp'],
+        'fallback_format': 'webp',
+        'fit': 'contain',
+        'quality': {'avif': 52, 'webp': 72},
+        'target_bytes': {},
+        'tile_size': 512,
+        'projection': 'equirectangular',
+    },
+}
+
+
+def get_profile(name):
+    profiles = DEFAULT_PROFILES.copy()
+    profiles.update(getattr(settings, 'MEDIA_ENGINE_PROFILES', {}) or {})
+    if name not in profiles:
+        raise KeyError(f'Unknown media profile: {name}')
+    return profiles[name]
+
+
+def requested_widths(profile, original_width):
+    return [w for w in profile.get('widths', []) if w <= original_width] or [min(original_width, max(profile.get('widths', [original_width])))]
+
+
+def all_formats(profile):
+    formats = list(profile.get('formats', []))
+    fallback = profile.get('fallback_format')
+    if fallback and fallback not in formats:
+        formats.append(fallback)
+    return formats

media_engine/queueing.py

@@ -0,0 +1,34 @@
+from django.conf import settings
+
+
+def resolved_task_mode():
+    """Return the effective execution mode without requiring Docker/Redis locally."""
+    configured = str(getattr(settings, 'MEDIA_ENGINE_TASK_MODE', 'auto') or 'auto').lower()
+    if configured in {'eager', 'inline', 'sync', 'synchronous'}:
+        return 'eager'
+    if configured in {'celery', 'async', 'asynchronous'}:
+        return 'celery'
+    if getattr(settings, 'CELERY_TASK_ALWAYS_EAGER', False):
+        return 'eager'
+    return 'eager' if bool(getattr(settings, 'DEBUG', False)) else 'celery'
+
+
+def queue_for_profile(profile, backfill=False):
+    if backfill:
+        return 'image_backfill'
+    if profile == 'hero' or profile.startswith('panorama.'):
+        return 'image_critical'
+    return 'image_normal'
+
+
+def enqueue_asset(asset_id, profile='default', force=False, backfill=False):
+    if resolved_task_mode() == 'eager':
+        from .models import MediaAsset
+        from .services import generate_all_variants
+        asset = MediaAsset.objects.get(pk=asset_id)
+        return generate_all_variants(asset, profile_name=profile, force=force)
+    from .tasks import generate_asset_variants
+    return generate_asset_variants.apply_async(
+        args=[str(asset_id), profile, force],
+        queue=queue_for_profile(profile, backfill=backfill),
+    )