@deepblend/dsh-blender-provider-local 0.2.20 → 0.3.0

package/python/deepblend_gltf_images.py

@@ -0,0 +1,183 @@
+"""Inspect selected glTF textures without decoding pixels or whole BIN buffers."""
+import base64
+import binascii
+import os
+import posixpath
+import re
+from urllib.parse import unquote
+
+from deepblend_asset_bundle import inside, member_path, read_document, resources
+from deepblend_image_headers import inspect_image_header, MAX_IMAGE_DECODE_BYTES
+from deepblend_util import ActionError
+from deepblend_gltf_roles import texture_uses
+
+
+def invalid(message):
+    raise ValueError(message)
+
+
+def integer(value, minimum=0):
+    if type(value) is not int or value < minimum:
+        invalid('image buffer references require nonnegative integer bounds')
+    return value
+
+
+def indexed(entries, index):
+    index = integer(index)
+    if not isinstance(entries, list) or index >= len(entries) or not isinstance(entries[index], dict):
+        invalid('image reference names a missing glTF resource')
+    return entries[index]
+
+
+class FileSlice:
+    def __init__(self, file, offset, length):
+        self.file, self.remaining = file, length
+        file.seek(offset)
+
+    def read(self, count):
+        if count < 0:
+            invalid('unbounded image buffer read')
+        data = self.file.read(min(count, self.remaining))
+        self.remaining -= len(data)
+        return data
+
+
+class DataSlice:
+    def __init__(self, uri, offset=0, length=None):
+        if not isinstance(uri, str) or not re.fullmatch(r'data:[^,]*;base64,[A-Za-z0-9+/]*={0,2}', uri):
+            invalid('image buffers require valid base64 data URIs')
+        self.uri, self.start = uri, uri.index(',') + 1
+        encoded = len(uri) - self.start
+        if encoded % 4:
+            invalid('image buffers require complete base64 quartets')
+        self.size = encoded // 4 * 3 - (len(uri) - len(uri.rstrip('=')))
+        self.position, self.end = offset, self.size if length is None else offset + length
+        if not 0 <= self.position <= self.end <= self.size:
+            invalid('image view escapes its embedded buffer')
+
+    def read(self, count):
+        if count < 0:
+            invalid('unbounded embedded image read')
+        end = min(self.position + count, self.end)
+        first, last = self.position // 3 * 4, (end + 2) // 3 * 4
+        if end == self.position:
+            return b''
+        # Decode only the quartets needed by this header read, even when a
+        # small image is located near the end of a large embedded buffer.
+        data = base64.b64decode(self.uri[self.start + first:self.start + last], validate=True)
+        offset = self.position % 3
+        data = data[offset:offset + end - self.position]
+        self.position = end
+        return data
+
+
+def relative_resource(root, entrypoint, uri):
+    if not isinstance(uri, str) or not uri or uri.startswith('/') or '\\' in uri or '?' in uri or '#' in uri or re.match(r'^[a-z][a-z0-9+.-]*:', uri, re.I):
+        invalid('image resources require contained relative file URIs')
+    if re.search(r'%(?![a-f0-9]{2})', uri, re.I):
+        invalid('invalid image resource percent encoding')
+    decoded = unquote(uri, errors='strict')
+    path = member_path(posixpath.normpath(posixpath.join(posixpath.dirname(entrypoint), decoded)))
+    return inside(root, path)
+
+
+def image_facts(root, entrypoint, path, document, binary, image):
+    uri = image.get('uri')
+    if uri is not None:
+        if 'bufferView' in image:
+            invalid('an image cannot declare both a URI and a buffer view')
+        if isinstance(uri, str) and uri.startswith('data:'):
+            return inspect_image_header(DataSlice(uri))
+        with open(relative_resource(root, entrypoint, uri), 'rb') as source:
+            return inspect_image_header(source)
+    view = indexed(document.get('bufferViews'), image.get('bufferView'))
+    if not isinstance(image.get('mimeType'), str):
+        invalid('buffer-view images require a media type')
+    if 'byteStride' in view or any(key in (view.get('extensions') or {}) for key in ('EXT_meshopt_compression', 'KHR_meshopt_compression')):
+        invalid('image views require contiguous encoded image bytes')
+    offset, length = integer(view.get('byteOffset', 0)), integer(view.get('byteLength'), 1)
+    buffer_index = integer(view.get('buffer'))
+    buffer = indexed(document.get('buffers'), buffer_index)
+    buffer_length = integer(buffer.get('byteLength'))
+    if offset + length > buffer_length:
+        invalid('image view escapes its declared buffer length')
+    buffer_uri = buffer.get('uri')
+    if isinstance(buffer_uri, str) and buffer_uri.startswith('data:'):
+        data = DataSlice(buffer_uri, offset, length)
+        if data.size < buffer_length:
+            invalid('embedded buffer is shorter than its declared length')
+        return inspect_image_header(data)
+    if buffer_uri is not None:
+        file = relative_resource(root, entrypoint, buffer_uri)
+        with open(file, 'rb') as source:
+            if os.fstat(source.fileno()).st_size < buffer_length:
+                invalid('image buffer file is shorter than its declared length')
+            return inspect_image_header(FileSlice(source, offset, length))
+    if buffer_index != 0 or binary is None or not 0 <= binary['bytes'] - buffer_length <= 3:
+        invalid('image buffer requires the first GLB buffer and a matching BIN chunk')
+    with open(path, 'rb') as source:
+        return inspect_image_header(FileSlice(source, binary['offset'] + offset, length))
+
+
+def inspect_gltf_images(project_root, asset):
+    """Match the pinned native importer's default core/WebP source choice.
+
+    Count each selected image once per import, including texture declarations
+    which may be unused in the default scene. Repeated import costs are added
+    by the scene budget; external native image reuse can make that estimate
+    conservative. Unselected fallback formats stay available to other readers.
+    """
+    try:
+        bundle = re.fullmatch(r'assets/bundles/([a-f0-9]{64})/(.+)', asset['path'])
+        root = inside(project_root or '.', 'assets/bundles/' + bundle[1]) if bundle else os.path.realpath(project_root or '.')
+        entrypoint = bundle[2] if bundle else asset['path']
+        path = inside(root, entrypoint)
+        document, binary = read_document(path, asset['type'], include_bin_location=True)
+        resources(document, entrypoint, binary['bytes'] if binary is not None else None)
+        textures = document.get('textures', [])
+        if not isinstance(textures, list):
+            invalid('glTF textures must be an array')
+        selected = set()
+        sources = []
+        for texture in textures:
+            if not isinstance(texture, dict):
+                invalid('invalid glTF texture declaration')
+            source = texture.get('source')
+            if source is None:
+                extensions = texture.get('extensions') or {}
+                webp = extensions.get('EXT_texture_webp') if isinstance(extensions, dict) else None
+                source = webp.get('source') if isinstance(webp, dict) else None
+            if source is not None:
+                source = integer(source)
+                selected.add(source)
+            sources.append(source)
+        roles = {source: set() for source in selected}
+        baked = set()
+        for texture_index, role in texture_uses(document):
+            indexed(textures, texture_index)
+            source = sources[texture_index]
+            if source is None:
+                continue
+            if role == 'baked':
+                baked.add(source)
+            else:
+                roles[source].add(role)
+        facts = []
+        total, allocations = 0, 0
+        for index in sorted(selected):
+            image = indexed(document.get('images'), index)
+            value = image_facts(root, entrypoint, path, document, binary, image)
+            if value['format'] not in ('png', 'jpeg', 'webp'):
+                invalid('glTF textures require PNG, JPEG or static WebP bytes')
+            declared = image.get('mimeType')
+            if declared is not None and declared != {'png': 'image/png', 'jpeg': 'image/jpeg', 'webp': 'image/webp'}[value['format']]:
+                invalid('image media type disagrees with its inspected bytes')
+            count = max(1, len(roles[index] & {'color', 'data'})) + int(index in baked)
+            total += value['decodedBytes'] * count
+            allocations += count
+            if total > MAX_IMAGE_DECODE_BYTES:
+                invalid('imported images exceed the 1 GiB decoded pixel budget')
+            facts.append({'imageIndex': index, 'allocations': count, 'roles': sorted(roles[index]), **value})
+        return {'images': len(facts), 'allocations': allocations, 'decodedBytes': total, 'facts': facts}
+    except (OSError, ValueError, UnicodeError, binascii.Error) as error:
+        raise ActionError('ASSET_CONTENT_MISMATCH', 'cannot inspect imported image before decoding: %s' % error)

package/python/deepblend_gltf_import.py

@@ -0,0 +1,95 @@
+"""Preserve native glTF color/data image uses without changing importer files."""
+import bpy
+from deepblend_image_roles import SOURCE_SPACE
+
+
+class ImageRoles:
+    is_critical = True
+
+    def __init__(self):
+        self.images = {}
+        self.rgb_roles = {}
+
+    def gather_import_gltf_before_hook(self, gltf):
+        from types import SimpleNamespace
+        from io_scene_gltf2.blender.imp.texture import get_source
+        from deepblend_gltf_roles import texture_uses
+        document = {'materials': [material.to_dict() for material in (gltf.data.materials or [])]}
+        for index, role in texture_uses(document):
+            if role not in ('color', 'data'):
+                continue
+            source = get_source(SimpleNamespace(gltf=gltf), gltf.data.textures[index])
+            if source is not None:
+                self.rgb_roles.setdefault(source, set()).add(role)
+
+    def gather_import_texture_before_hook(self, texture, mh, tex_info, location,
+                                         label, color_socket, alpha_socket, is_data, gltf):
+        from io_scene_gltf2.blender.imp.image import BlenderImage
+        from io_scene_gltf2.blender.imp.texture import get_source
+        source = get_source(mh, texture)
+        if source is None:
+            return
+        BlenderImage.create(gltf, source)
+        declaration = gltf.data.images[source]
+        if not declaration.blender_image_name:
+            return
+        image = bpy.data.images[declaration.blender_image_name]
+        # The native hook supplies semantic use, independent of node labels or
+        # later graph rewrites. Alpha alone has the same values in either space.
+        role = 'alpha' if color_socket is None and alpha_socket is not None else 'data' if is_data else 'color'
+        if role == 'alpha' and source in self.rgb_roles:
+            # If alpha is imported first, use a declared RGB interpretation.
+            # Otherwise a later RGB use would create an unnecessary copy which
+            # the alpha-only budget correctly does not include.
+            roles = self.rgb_roles[source]
+            role = next(iter(roles)) if len(roles) == 1 else 'data' if image.colorspace_settings.name == 'Non-Color' else 'color'
+        key = (source, role)
+        if key not in self.images:
+            if role != 'alpha':
+                native_space = image.get(SOURCE_SPACE, image.colorspace_settings.name)
+                space = 'Non-Color' if role == 'data' else 'sRGB'
+                if image.colorspace_settings.name != space:
+                    # External files may reuse an image from another material,
+                    # image index or imported instance. Protect its existing users.
+                    if image.users:
+                        image = image.copy()
+                    image[SOURCE_SPACE] = native_space
+                    image.colorspace_settings.name = space
+            self.images[key] = image
+        declaration.blender_image_name = self.images[key].name
+
+    def gather_import_texture_after_hook(self, texture, tree, mh, tex_info, location,
+                                        label, color_socket, alpha_socket, is_data, gltf):
+        from io_scene_gltf2.blender.imp.texture import get_source
+        source = get_source(mh, texture)
+        if source is None:
+            return
+        # Restore a color interpretation for native specular/glossiness baking,
+        # which reads the image cache directly outside the texture-node hook.
+        for role in ('color', 'data', 'alpha'):
+            if (source, role) in self.images:
+                gltf.data.images[source].blender_image_name = self.images[source, role].name
+                return
+
+
+def import_gltf(path):
+    """Run the registered operator with one critical extension for this call.
+
+    The pinned operator exposes user hooks through its importer constructor.
+    Attach ours in memory for the synchronous call and restore that constructor
+    on success and failure. Keep native settings, geometry, samplers, UVs and
+    material conversion; no addon file or user preference is changed.
+    """
+    from io_scene_gltf2.io.imp.gltf2_io_gltf import glTFImporter
+    original = glTFImporter.__init__
+
+    def initialize(self, filename, settings):
+        options = dict(settings)
+        options['import_user_extensions'] = [*settings['import_user_extensions'], ImageRoles()]
+        original(self, filename, options)
+
+    glTFImporter.__init__ = initialize
+    try:
+        return bpy.ops.import_scene.gltf(filepath=path)
+    finally:
+        glTFImporter.__init__ = original

package/python/deepblend_gltf_roles.py

@@ -0,0 +1,56 @@
+"""Declared image uses supported by the pinned native glTF material importer."""
+
+CORE = {
+    'baseColorTexture': 'color', 'metallicRoughnessTexture': 'data',
+}
+MATERIAL = {
+    'emissiveTexture': 'color', 'normalTexture': 'data', 'occlusionTexture': 'data',
+}
+EXTENSIONS = {
+    'KHR_materials_pbrSpecularGlossiness': {
+        'diffuseTexture': 'color', 'specularGlossinessTexture': 'color',
+    },
+    'KHR_materials_clearcoat': {
+        'clearcoatTexture': 'data', 'clearcoatRoughnessTexture': 'data',
+        'clearcoatNormalTexture': 'data',
+    },
+    'KHR_materials_transmission': {'transmissionTexture': 'data'},
+    'KHR_materials_volume': {'thicknessTexture': 'data'},
+    'KHR_materials_specular': {'specularColorTexture': 'color', 'specularTexture': 'alpha'},
+    'KHR_materials_sheen': {'sheenColorTexture': 'color', 'sheenRoughnessTexture': 'alpha'},
+    'KHR_materials_iridescence': {'iridescenceTexture': 'data', 'iridescenceThicknessTexture': 'data'},
+    'KHR_materials_anisotropy': {'anisotropyTexture': 'data'},
+}
+
+
+def texture_uses(document):
+    """Yield texture indices and roles, including native baked roughness copies.
+
+    Alpha is linear in either image color space and needs no independent RGB
+    interpretation. Count declared uses conservatively, even unused materials.
+    Unknown material extensions remain subject to native support checks.
+    """
+    materials = document.get('materials', [])
+    if not isinstance(materials, list):
+        raise ValueError('glTF materials must be an array')
+    for material in materials:
+        if not isinstance(material, dict):
+            raise ValueError('invalid glTF material declaration')
+        groups = [(material, MATERIAL), (material.get('pbrMetallicRoughness') or {}, CORE)]
+        extensions = material.get('extensions') or {}
+        if not isinstance(extensions, dict):
+            raise ValueError('invalid glTF material extensions')
+        groups.extend((extensions.get(name) or {}, fields) for name, fields in EXTENSIONS.items())
+        for group, fields in groups:
+            if not isinstance(group, dict):
+                raise ValueError('invalid glTF material texture group')
+            for field, role in fields.items():
+                info = group.get(field)
+                if info is not None:
+                    if not isinstance(info, dict):
+                        raise ValueError('invalid glTF material texture reference')
+                    yield info.get('index'), role
+        specular = extensions.get('KHR_materials_pbrSpecularGlossiness') or {}
+        info = specular.get('specularGlossinessTexture')
+        if info is not None and specular.get('glossinessFactor', 1) != 0:
+            yield info.get('index'), 'baked'

package/python/deepblend_image_headers.py

@@ -0,0 +1,294 @@
+"""Bounded image metadata inspection before Blender allocates decoded pixels.
+
+This is a resource gate, not a replacement for the native decoder. Dimensions
+come from actual PNG/JPEG/Radiance/OpenEXR headers, never a filename or asset
+declaration. Pixel payloads are not read here.
+"""
+import io
+import re
+import struct
+import zlib
+
+from deepblend_util import ActionError
+
+MAX_IMAGE_SIDE = 8192
+MAX_IMAGE_HEADER_BYTES = 1024 * 1024
+MAX_IMAGE_DECODE_BYTES = 1024 * 1024 * 1024
+MAX_IMAGE_PARTS = 256
+MAX_IMAGE_CHANNELS = 64
+
+
+class HeaderReader:
+    def __init__(self, source, limit=MAX_IMAGE_HEADER_BYTES):
+        self.source = source
+        self.limit = limit
+        self.consumed = 0
+
+    def read(self, count):
+        if count < 0 or self.consumed + count > self.limit:
+            raise ValueError('image header exceeds the 1 MiB metadata budget')
+        data = self.source.read(count)
+        self.consumed += len(data)
+        if len(data) != count:
+            raise ValueError('truncated image header')
+        return data
+
+    def string(self, maximum=255):
+        result = bytearray()
+        for _ in range(maximum + 1):
+            byte = self.read(1)
+            if byte == b'\0':
+                return bytes(result)
+            result.extend(byte)
+        raise ValueError('image header name exceeds its format limit')
+
+    def line(self):
+        result = bytearray()
+        while True:
+            byte = self.read(1)
+            if byte == b'\n':
+                return bytes(result).rstrip(b'\r')
+            result.extend(byte)
+
+
+def dimensions(width, height, channels=4, tile_mode=0):
+    if not (1 <= width <= MAX_IMAGE_SIDE and 1 <= height <= MAX_IMAGE_SIDE):
+        raise ValueError('image dimensions must be between 1 and 8192 pixels')
+    # Float RGBA is a conservative common Blender buffer, including PNG/JPEG.
+    # EXR can allocate additional channels and complete mip/ripmap pyramids.
+    pixels = width * height
+    level = tile_mode & 0xf
+    rounding = 1 if tile_mode & 0x10 else 0
+    if level == 1:
+        w, h = width, height
+        while w > 1 or h > 1:
+            w, h = max(1, (w + rounding) // 2), max(1, (h + rounding) // 2)
+            pixels += w * h
+    elif level == 2:
+        def total_axis(size):
+            total = size
+            while size > 1:
+                size = max(1, (size + rounding) // 2)
+                total += size
+            return total
+        pixels = total_axis(width) * total_axis(height)
+    decoded = pixels * max(4, channels) * 4
+    if decoded > MAX_IMAGE_DECODE_BYTES:
+        raise ValueError('image exceeds the 1 GiB decoded pixel budget')
+    return {'width': width, 'height': height, 'channels': channels,
+            'decodedBytes': decoded}
+
+
+def png_header(reader):
+    data = reader.read(25)
+    if data[:8] != b'\x00\x00\x00\rIHDR':
+        raise ValueError('PNG requires a first 13-byte IHDR')
+    header = data[8:21]
+    if zlib.crc32(b'IHDR' + header) & 0xffffffff != struct.unpack('>I', data[21:])[0]:
+        raise ValueError('PNG IHDR checksum does not match')
+    width, height, depth, color, compression, filtering, interlace = struct.unpack('>IIBBBBB', header)
+    depths = {0: (1, 2, 4, 8, 16), 2: (8, 16), 3: (1, 2, 4, 8), 4: (8, 16), 6: (8, 16)}
+    if depth not in depths.get(color, ()) or compression or filtering or interlace not in (0, 1):
+        raise ValueError('invalid PNG header encoding')
+    return [dimensions(width, height)]
+
+
+def jpeg_header(reader):
+    frames = {0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf}
+    for _ in range(4096):
+        if reader.read(1) != b'\xff':
+            raise ValueError('invalid JPEG marker')
+        marker = reader.read(1)[0]
+        while marker == 0xff:
+            marker = reader.read(1)[0]
+        if marker in (0x00, 0xd8, 0xd9, 0xda):
+            raise ValueError('JPEG has no bounded frame dimensions before pixel data')
+        if marker == 0x01 or 0xd0 <= marker <= 0xd7:
+            continue
+        size = struct.unpack('>H', reader.read(2))[0]
+        if size < 2:
+            raise ValueError('invalid JPEG segment length')
+        data = reader.read(size - 2)
+        if marker in frames:
+            if len(data) < 6:
+                raise ValueError('truncated JPEG frame')
+            height, width = struct.unpack('>HH', data[1:5])
+            channels = data[5]
+            if not 1 <= channels <= 4 or size != 8 + 3 * channels:
+                raise ValueError('invalid JPEG frame component count')
+            return [dimensions(width, height, channels)]
+    raise ValueError('JPEG exceeds the marker count budget')
+
+
+def hdr_header(reader, prefix):
+    first = prefix + reader.line()
+    if first not in (b'#?RADIANCE', b'#?RGBE'):
+        raise ValueError('invalid Radiance image signature')
+    found = False
+    for _ in range(4096):
+        line = reader.line()
+        if not line:
+            break
+        if line.startswith(b'FORMAT='):
+            if found or line not in (b'FORMAT=32-bit_rle_rgbe', b'FORMAT=32-bit_rle_xyze'):
+                raise ValueError('invalid Radiance image encoding')
+            found = True
+    else:
+        raise ValueError('Radiance exceeds the header line budget')
+    resolution = re.fullmatch(rb'([+-])([XY])\s+(\d+)\s+([+-])([XY])\s+(\d+)', reader.line())
+    if not found or not resolution or resolution[2] == resolution[5]:
+        raise ValueError('Radiance requires two distinct resolution axes')
+    axes = {resolution[2]: int(resolution[3]), resolution[5]: int(resolution[6])}
+    return [dimensions(axes[b'X'], axes[b'Y'])]
+
+
+def webp_header(reader):
+    size, magic = struct.unpack('<I4s', reader.read(8))
+    if magic != b'WEBP' or size < 12:
+        raise ValueError('invalid WebP RIFF container')
+    remaining = size - 4
+    for _ in range(4096):
+        if remaining < 8:
+            raise ValueError('WebP has no bounded image header')
+        kind, length = struct.unpack('<4sI', reader.read(8))
+        padded = length + length % 2
+        remaining -= 8
+        if padded > remaining:
+            raise ValueError('WebP chunk escapes its RIFF container')
+        if kind == b'VP8X':
+            if length != 10:
+                raise ValueError('invalid WebP extended image header')
+            data = reader.read(10)
+            if data[0] & 0xc3 or data[1:4] != b'\0\0\0':
+                raise ValueError('animated or reserved WebP features are not static textures')
+            return [dimensions(1 + int.from_bytes(data[4:7], 'little'),
+                               1 + int.from_bytes(data[7:10], 'little'))]
+        if kind == b'VP8L':
+            if length < 5:
+                raise ValueError('truncated WebP lossless header')
+            data = reader.read(5)
+            bits = int.from_bytes(data[1:], 'little')
+            if data[0] != 0x2f or bits >> 29:
+                raise ValueError('invalid WebP lossless signature or version')
+            return [dimensions(1 + (bits & 0x3fff), 1 + ((bits >> 14) & 0x3fff))]
+        if kind == b'VP8 ':
+            if length < 10:
+                raise ValueError('truncated WebP lossy header')
+            data = reader.read(10)
+            frame = int.from_bytes(data[:3], 'little')
+            if frame & 1 or (frame >> 1) & 7 > 3 or not frame & 0x10 or data[3:6] != b'\x9d\x01\x2a':
+                raise ValueError('WebP requires a visible VP8 key frame')
+            width, height = struct.unpack('<HH', data[6:10])
+            return [dimensions(width & 0x3fff, height & 0x3fff)]
+        reader.read(padded)
+        remaining -= padded
+    raise ValueError('WebP exceeds the chunk count budget')
+
+
+def exr_header(reader):
+    version = struct.unpack('<I', reader.read(4))[0]
+    if version & 0xff not in (1, 2) or version & ~0x1eFF:
+        raise ValueError('unsupported OpenEXR version flags')
+    if version & 0x800:
+        raise ValueError('deep OpenEXR sample allocation cannot be bounded from dimensions')
+    maximum = 255 if version & 0x400 else 31
+    multipart = bool(version & 0x1000)
+    parts = []
+    while True:
+        attributes = {}
+        for _ in range(4096):
+            name = reader.string(maximum)
+            if not name:
+                break
+            kind = reader.string(maximum)
+            if not kind or name in attributes:
+                raise ValueError('empty or duplicate OpenEXR attribute')
+            size = struct.unpack('<i', reader.read(4))[0]
+            attributes[name] = (kind, reader.read(size))
+        else:
+            raise ValueError('OpenEXR exceeds the attribute count budget')
+        if not attributes:
+            if not multipart or not parts:
+                raise ValueError('OpenEXR has no image header')
+            return parts
+        if len(parts) >= MAX_IMAGE_PARTS:
+            raise ValueError('OpenEXR exceeds the 256-part budget')
+        for kind, value in attributes.values():
+            if kind == b'preview':
+                if len(value) < 8:
+                    raise ValueError('truncated OpenEXR preview header')
+                preview_width, preview_height = struct.unpack('<II', value[:8])
+                dimensions(preview_width, preview_height)
+                if len(value) != 8 + preview_width * preview_height * 4:
+                    raise ValueError('OpenEXR preview size disagrees with its payload')
+        window = attributes.get(b'dataWindow')
+        channels = attributes.get(b'channels')
+        if not window or window[0] != b'box2i' or len(window[1]) != 16 or not channels or channels[0] != b'chlist':
+            raise ValueError('OpenEXR requires dataWindow and channel metadata')
+        xmin, ymin, xmax, ymax = struct.unpack('<iiii', window[1])
+        channel_reader = HeaderReader(io.BytesIO(channels[1]))
+        names = set()
+        while True:
+            name = channel_reader.string(maximum)
+            if not name:
+                break
+            pixel_type, linear, reserved, xs, ys = struct.unpack('<iB3sii', channel_reader.read(16))
+            if name in names or len(names) >= MAX_IMAGE_CHANNELS or pixel_type not in (0, 1, 2) or linear not in (0, 1) or reserved != b'\0\0\0' or xs < 1 or ys < 1:
+                raise ValueError('invalid or excessive OpenEXR channels')
+            names.add(name)
+        if not names or channel_reader.consumed != len(channels[1]):
+            raise ValueError('invalid OpenEXR channel list')
+        kind = attributes.get(b'type')
+        if kind and (kind[0] != b'string' or kind[1] not in (b'scanlineimage', b'tiledimage')):
+            raise ValueError('unsupported OpenEXR part type')
+        tile_mode = 0
+        tiles = attributes.get(b'tiles')
+        if tiles:
+            if tiles[0] != b'tiledesc' or len(tiles[1]) != 9:
+                raise ValueError('invalid OpenEXR tile descriptor')
+            tile_width, tile_height, tile_mode = struct.unpack('<IIB', tiles[1])
+            if not tile_width or not tile_height or tile_mode not in (0, 1, 2, 16, 17, 18):
+                raise ValueError('invalid OpenEXR tile descriptor')
+        part = dimensions(xmax - xmin + 1, ymax - ymin + 1, len(names), tile_mode)
+        display = attributes.get(b'displayWindow')
+        if display:
+            if display[0] != b'box2i' or len(display[1]) != 16:
+                raise ValueError('invalid OpenEXR display window')
+            dxmin, dymin, dxmax, dymax = struct.unpack('<iiii', display[1])
+            display_facts = dimensions(dxmax - dxmin + 1, dymax - dymin + 1, len(names), tile_mode)
+            part['decodedBytes'] = max(part['decodedBytes'], display_facts['decodedBytes'])
+        parts.append(part)
+        if sum(p['decodedBytes'] for p in parts) > MAX_IMAGE_DECODE_BYTES:
+            raise ValueError('OpenEXR parts exceed the 1 GiB decoded pixel budget')
+        if not multipart:
+            return parts
+
+
+def inspect_image_header(source):
+    """Read a seek-free bounded header from an already open binary stream."""
+    reader = HeaderReader(source)
+    prefix = reader.read(2)
+    if prefix == b'\xff\xd8':
+        format_name, parts = 'jpeg', jpeg_header(reader)
+    elif prefix == b'#?':
+        format_name, parts = 'hdr', hdr_header(reader, prefix)
+    else:
+        magic = prefix + reader.read(2)
+        if magic == b'\x89PNG' and reader.read(4) == b'\r\n\x1a\n':
+            format_name, parts = 'png', png_header(reader)
+        elif magic == b'v/1\x01':
+            format_name, parts = 'exr', exr_header(reader)
+        elif magic == b'RIFF':
+            format_name, parts = 'webp', webp_header(reader)
+        else:
+            raise ValueError('unsupported image header signature')
+    return {'format': format_name, 'parts': parts, 'headerBytes': reader.consumed,
+            'decodedBytes': sum(p['decodedBytes'] for p in parts)}
+
+
+def check_image_header(path):
+    try:
+        with open(path, 'rb') as source:
+            return inspect_image_header(source)
+    except (OSError, ValueError, struct.error) as error:
+        raise ActionError('ASSET_CONTENT_MISMATCH', 'cannot inspect image asset before decoding: %s' % error)

package/python/deepblend_image_roles.py

@@ -0,0 +1,2 @@
+"""Native file interpretation retained when a binding uses image RGB as data."""
+SOURCE_SPACE = 'deepblend_image_source_colorspace'