Skip to content

Production interior authoring and interactive Three.js delivery plugin for img2.

24.5 KB
Raw Blame
#!/usr/bin/env python3
"""Audit declared material wiring and factors, never visual realism or texture pixels."""
import os, sys
sys.dont_write_bytecode = True
root = os.environ.get("IMG2_HOME")
if root: sys.path.insert(0, os.path.join(root, "harness"))
else:
    try: import _img2_local; sys.path.insert(0, _img2_local.CORE)
    except ImportError: sys.exit("img2: core not linked - run `img2 sync`")
from img2_core import require_core_api
require_core_api(1)

import base64
import binascii
import struct

from audit_support import (AuditFailure, JSON_LIMIT, Parser, check_pin, confined_file,
                           decode_json, emit, factor, fields, file_hash, input_path,
                           integer, load_receipt, object_value, persist, pin,
                           read_json, text, workspace_path)

GATE = "interior-materials"
RECEIPT = "material-audit.json"
STATE_KEY = "materialAudit"
LIMITATIONS = [
    "Only explicitly declared policy expectations are checked; omitted expectations are not certified.",
    "Texture pixels and image decoding are not evaluated. A scalar roughness factor is multiplied by the texture's green channel and does not prove effective roughness.",
    "Color-space interpretation, texel density, UV orientation, visible textile identity, lighting, and frontal/grazing appearance require separate consumer and visual review.",
    "This is a bounded material-wiring audit, not a Khronos validator, scene-visibility proof, native reopen, or runtime-render test.",
]


def array(doc, key):
    value = doc.get(key, [])
    if not isinstance(value, list):
        raise ValueError(f"glTF {key} must be an array")
    return value


def indexed(values, index, label):
    integer(index, label)
    if index >= len(values):
        raise ValueError(f"{label} index {index} out of range")
    return object_value(values[index], label)


def validate_policy(value):
    fields(value, ["schemaVersion", "materials"], [], "policy")
    if type(value["schemaVersion"]) is not int or value["schemaVersion"] != 1:
        raise ValueError("policy schemaVersion must be 1")
    rows = value["materials"]
    if not isinstance(rows, list) or not rows:
        raise ValueError("policy materials must be a nonempty array")
    names = set()
    booleans = {"requireBaseColorTexture", "requireNormalTexture", "requireRoughnessTexture"}
    numbers = {"minRoughnessFactor", "maxMetallicFactor", "maxSheenColorFactor"}
    for row in rows:
        fields(row, ["name"], booleans | numbers | {"texCoord"}, "material policy")
        name = text(row["name"], "material name")
        if name in names:
            raise ValueError(f"duplicate material policy target: {name}")
        names.add(name)
        for key in booleans & row.keys():
            if type(row[key]) is not bool:
                raise ValueError(f"{key} must be boolean")
        for key in numbers & row.keys():
            factor(row[key], key)
        if "texCoord" in row:
            integer(row["texCoord"], "texCoord")
    return rows


class GLB:
    """Read only bounded JSON and chunk headers; binary ranges are checked by offsets."""
    def __init__(self, path):
        self.path = path
        self.resources = {}
        self.bin_length = None
        size = path.stat().st_size
        with path.open("rb") as handle:
            header = handle.read(12)
            if len(header) != 12:
                raise ValueError("truncated GLB header")
            magic, version, declared = struct.unpack("<4sII", header)
            if magic != b"glTF" or version != 2 or declared != size or size % 4:
                raise ValueError("invalid GLB magic, version, alignment, or total byte length")
            offset, chunk_number, document = 12, 0, None
            while offset < size:
                raw = handle.read(8)
                if len(raw) != 8:
                    raise ValueError("truncated GLB chunk header")
                length, kind = struct.unpack("<II", raw)
                if length % 4 or offset + 8 + length > size:
                    raise ValueError("invalid or truncated GLB chunk length")
                if chunk_number == 0 and kind != 0x4E4F534A:
                    raise ValueError("first GLB chunk must be JSON")
                if kind == 0x4E4F534A:
                    if document is not None or chunk_number != 0 or not 0 < length <= JSON_LIMIT:
                        raise ValueError("duplicate, misplaced, empty, or oversized GLB JSON chunk")
                    document = decode_json(handle.read(length).decode("utf-8"), "GLB JSON")
                elif kind == 0x004E4942:
                    if self.bin_length is not None or chunk_number != 1:
                        raise ValueError("duplicate or misplaced GLB BIN chunk")
                    self.bin_length = length
                    handle.seek(length, 1)
                else:
                    # glTF permits unknown trailing chunks; their bounds still matter.
                    handle.seek(length, 1)
                offset += 8 + length
                chunk_number += 1
        self.doc = object_value(document, "glTF document")
        asset = object_value(self.doc.get("asset"), "glTF asset")
        if asset.get("version") != "2.0" or asset.get("minVersion", "2.0") != "2.0":
            raise ValueError("only glTF 2.0 is supported")
        for key in ("extensionsUsed", "extensionsRequired"):
            extensions = array(self.doc, key)
            for extension in extensions:
                text(extension, key)
            if len(set(extensions)) != len(extensions):
                raise ValueError(f"duplicate {key} entry")
        if not set(self.doc.get("extensionsRequired", [])).issubset(self.doc.get("extensionsUsed", [])):
            raise ValueError("extensionsRequired must be included in extensionsUsed")
        self.buffers = array(self.doc, "buffers")
        self.views = array(self.doc, "bufferViews")
        self.accessors = array(self.doc, "accessors")
        self.images = array(self.doc, "images")
        self.textures = array(self.doc, "textures")
        self.materials = array(self.doc, "materials")
        self.meshes = array(self.doc, "meshes")
        for index, buffer in enumerate(self.buffers):
            object_value(buffer, "buffer")
            length = integer(buffer.get("byteLength"), "buffer.byteLength", 1)
            if "uri" in buffer:
                resource = self.resource(buffer["uri"], "buffer")
                if resource["byteLength"] < length:
                    raise ValueError(f"buffer {index} exceeds resource bytes")
            elif index != 0 or self.bin_length is None or not length <= self.bin_length <= length + 3:
                raise ValueError(f"buffer {index} has no valid GLB BIN storage")
        if self.bin_length is not None and (not self.buffers or "uri" in self.buffers[0]):
            raise ValueError("GLB BIN chunk has no corresponding buffer 0")
        for index in range(len(self.views)):
            self.view(index)
        # Unselected resources are still part of this delivered GLB's trust boundary.
        for index in range(len(self.images)):
            self.image(index)
        for index in range(len(self.textures)):
            self.texture({"index": index})

    def resource(self, uri, label):
        text(uri, f"{label} URI")
        if uri.startswith("data:"):
            header, separator, encoded = uri.partition(",")
            if not separator or not header.endswith(";base64"):
                raise ValueError("only base64 glTF data URIs are supported")
            media = header[5:-7]
            allowed = ({"application/octet-stream", "application/gltf-buffer"} if label == "buffer"
                       else {"image/png", "image/jpeg", "image/webp", "image/ktx2"})
            if media not in allowed:
                raise ValueError(f"unsupported {label} data URI media type: {media}")
            try:
                data = base64.b64decode(encoded, validate=True)
            except (binascii.Error, ValueError) as exc:
                raise ValueError("invalid base64 resource") from exc
            if not data:
                raise ValueError("empty data URI resource")
            return {"storage": "data-uri", "byteLength": len(data), "mimeType": media}
        path = confined_file(self.path.parent, uri, uri=True)
        digest = file_hash(path)
        item = {"path": str(path), "sha256": digest}
        if str(path) in self.resources and self.resources[str(path)] != item:
            raise AuditFailure(f"resource changed during audit: {path}")
        self.resources[str(path)] = item
        return {"storage": "external", "path": str(path), "sha256": digest,
                "byteLength": path.stat().st_size}

    def view(self, index):
        view = indexed(self.views, index, "bufferView")
        buffer = indexed(self.buffers, view.get("buffer"), "bufferView.buffer")
        offset = integer(view.get("byteOffset", 0), "bufferView.byteOffset")
        length = integer(view.get("byteLength"), "bufferView.byteLength", 1)
        if offset + length > buffer["byteLength"]:
            raise ValueError("bufferView exceeds buffer bytes")
        if "byteStride" in view:
            stride = integer(view["byteStride"], "bufferView.byteStride", 4)
            if stride > 252 or stride % 4:
                raise ValueError("invalid bufferView byteStride")
        if "EXT_meshopt_compression" in object_value(view.get("extensions", {}), "bufferView extensions"):
            raise ValueError("compressed bufferViews require separate decoded accessor inspection")
        return view

    def accessor(self, index, semantic):
        accessor = indexed(self.accessors, index, semantic)
        expected = "VEC2" if semantic.startswith("TEXCOORD_") else "VEC3"
        if accessor.get("type") != expected:
            raise ValueError(f"{semantic} accessor must be {expected}")
        component = accessor.get("componentType")
        sizes = {5120: 1, 5121: 1, 5122: 2, 5123: 2, 5126: 4}
        if type(component) is not int or component not in sizes:
            raise ValueError(f"invalid {semantic} componentType")
        normalized = accessor.get("normalized", False)
        if type(normalized) is not bool:
            raise ValueError("accessor.normalized must be boolean")
        quantized = "KHR_mesh_quantization" in self.doc.get("extensionsUsed", [])
        if semantic.startswith("TEXCOORD_"):
            allowed = component == 5126 and not normalized or component in (5121, 5123) and normalized
            if not allowed and not (quantized and component != 5126):
                raise ValueError("UV accessor needs floats or normalized unsigned integers (or declared quantization)")
        elif component != 5126 and not quantized:
            raise ValueError("POSITION accessor requires floats or declared quantization")
        count = integer(accessor.get("count"), "accessor.count", 1)
        width = sizes[component] * (2 if expected == "VEC2" else 3)
        offset = integer(accessor.get("byteOffset", 0), "accessor.byteOffset")
        if offset % sizes[component]:
            raise ValueError("misaligned accessor byteOffset")
        if "bufferView" in accessor:
            view = self.view(accessor["bufferView"])
            stride = view.get("byteStride", width)
            if stride < width or stride % sizes[component] or (view.get("byteOffset", 0) + offset) % sizes[component]:
                raise ValueError("invalid accessor stride or alignment")
            if offset + (count - 1) * stride + width > view["byteLength"]:
                raise ValueError(f"{semantic} accessor exceeds bufferView bytes")
        elif offset:
            raise ValueError("accessor without bufferView cannot have byteOffset")
        if "sparse" in accessor:
            sparse = object_value(accessor["sparse"], "sparse accessor")
            sparse_count = integer(sparse.get("count"), "sparse.count", 1)
            if sparse_count > count:
                raise ValueError("sparse accessor count exceeds accessor count")
            for key in ("indices", "values"):
                item = object_value(sparse.get(key), f"sparse.{key}")
                view = self.view(item.get("bufferView"))
                item_width = width
                if key == "indices":
                    if type(item.get("componentType")) is not int or item["componentType"] not in (5121, 5123, 5125):
                        raise ValueError("invalid sparse index componentType")
                    item_width = {5121: 1, 5123: 2, 5125: 4}[item["componentType"]]
                start = integer(item.get("byteOffset", 0), "sparse.byteOffset")
                if "byteStride" in view or start + sparse_count * item_width > view["byteLength"]:
                    raise ValueError("invalid sparse accessor byte range")
        return {"accessor": index, "count": count, "type": expected,
                "componentType": component, "normalized": normalized}

    def image(self, index):
        image = indexed(self.images, index, "texture image")
        if ("uri" in image) == ("bufferView" in image):
            raise ValueError("image must have exactly one of uri or bufferView")
        if "uri" in image:
            return dict(self.resource(image["uri"], "image"), image=index)
        mime = image.get("mimeType")
        if mime not in ("image/png", "image/jpeg", "image/webp", "image/ktx2"):
            raise ValueError("embedded image needs a supported mimeType")
        view = self.view(image["bufferView"])
        if "byteStride" in view:
            raise ValueError("image bufferView cannot be strided")
        return {"image": index, "storage": "bufferView", "bufferView": image["bufferView"],
                "byteLength": view["byteLength"], "mimeType": mime}

    def texture(self, info):
        object_value(info, "textureInfo")
        texture = indexed(self.textures, info.get("index"), "textureInfo.index")
        coord = integer(info.get("texCoord", 0), "textureInfo.texCoord")
        extensions = object_value(info.get("extensions", {}), "textureInfo.extensions")
        if "KHR_texture_transform" in extensions:
            transform = object_value(extensions["KHR_texture_transform"], "texture transform")
            coord = integer(transform.get("texCoord", coord), "texture transform texCoord")
            for key, length in (("offset", 2), ("scale", 2)):
                if key in transform:
                    vector(transform[key], length, f"texture transform {key}", bounded=False)
            if "rotation" in transform and type(transform["rotation"]) not in (int, float):
                raise ValueError("texture transform rotation must be numeric")
        images = []
        if "source" in texture:
            images.append(self.image(texture["source"]))
        tex_extensions = object_value(texture.get("extensions", {}), "texture.extensions")
        for name in ("KHR_texture_basisu", "EXT_texture_webp", "MSFT_texture_dds"):
            if name in tex_extensions:
                if name == "MSFT_texture_dds":
                    raise ValueError("DDS texture source inspection is unsupported")
                ext = object_value(tex_extensions[name], name)
                images.append(dict(self.image(ext.get("source")), extension=name))
        if not images:
            raise ValueError("bound texture has no supported image source")
        if "sampler" in texture:
            indexed(array(self.doc, "samplers"), texture["sampler"], "texture.sampler")
        return {"texture": info["index"], "texCoord": coord, "images": images}


def vector(value, length, label, bounded=True):
    if not isinstance(value, list) or len(value) != length:
        raise ValueError(f"{label} must have {length} components")
    for item in value:
        if bounded:
            factor(item, label)
        elif type(item) not in (int, float):
            raise ValueError(f"{label} components must be numeric")
    return value


def material_maps(material):
    pbr = object_value(material.get("pbrMetallicRoughness", {}), "pbrMetallicRoughness")
    maps = {key: pbr[key] for key in ("baseColorTexture", "metallicRoughnessTexture") if key in pbr}
    maps.update({key: material[key] for key in ("normalTexture", "occlusionTexture", "emissiveTexture") if key in material})
    # Inspect extension textureInfo objects as well, rather than silently ignoring sheen maps.
    for name, extension in object_value(material.get("extensions", {}), "material extensions").items():
        object_value(extension, name)
        for key, info in extension.items():
            if key.endswith("Texture"):
                maps[f"{name}.{key}"] = info
    return pbr, maps


def evaluate(glb_path, policy_path):
    inputs = {"glb": pin(glb_path), "policy": pin(policy_path)}
    policy = validate_policy(read_json(policy_path))
    glb = GLB(glb_path)
    reasons, results = [], []
    names = {}
    for index, material in enumerate(glb.materials):
        object_value(material, "material")
        if "name" in material:
            name = material["name"]
            if not isinstance(name, str):
                raise ValueError("glTF material name must be a string")
            names.setdefault(name, []).append(index)
    primitives = {}
    for mesh_index, mesh in enumerate(glb.meshes):
        object_value(mesh, "mesh")
        rows = mesh.get("primitives")
        if not isinstance(rows, list) or not rows:
            raise ValueError("mesh.primitives must be a nonempty array")
        for primitive_index, primitive in enumerate(rows):
            object_value(primitive, "primitive")
            if "material" in primitive:
                index = primitive["material"]
                indexed(glb.materials, index, "primitive.material")
                primitives.setdefault(index, []).append((mesh_index, primitive_index, primitive))
    for rule in policy:
        name = rule["name"]
        matches = names.get(name, [])
        if len(matches) != 1:
            reasons.append(f"{name}: expected exactly one material target; found {len(matches)}")
            continue
        index = matches[0]
        material = glb.materials[index]
        pbr, maps = material_maps(material)
        roughness = factor(pbr.get("roughnessFactor", 1), "roughnessFactor")
        metallic = factor(pbr.get("metallicFactor", 1), "metallicFactor")
        base_color = vector(pbr.get("baseColorFactor", [1, 1, 1, 1]), 4, "baseColorFactor")
        sheen = object_value(material.get("extensions", {}).get("KHR_materials_sheen", {}), "sheen")
        sheen_color = vector(sheen.get("sheenColorFactor", [0, 0, 0]), 3, "sheenColorFactor")
        sheen_roughness = factor(sheen.get("sheenRoughnessFactor", 0), "sheenRoughnessFactor")
        bound = {key: glb.texture(info) for key, info in maps.items()}
        if "normalTexture" in maps:
            scale = maps["normalTexture"].get("scale", 1)
            if type(scale) not in (int, float):
                raise ValueError("normalTexture.scale must be a finite number")
            bound["normalTexture"]["scale"] = scale
        if "occlusionTexture" in maps:
            bound["occlusionTexture"]["strength"] = factor(maps["occlusionTexture"].get("strength", 1), "occlusion strength")
        for requirement, map_key in (("requireBaseColorTexture", "baseColorTexture"),
                                     ("requireNormalTexture", "normalTexture"),
                                     ("requireRoughnessTexture", "metallicRoughnessTexture")):
            if rule.get(requirement) is True and map_key not in bound:
                reasons.append(f"{name}: required {map_key} is not bound")
        if "minRoughnessFactor" in rule and roughness < rule["minRoughnessFactor"]:
            reasons.append(f"{name}: roughnessFactor {roughness} is below declared minimum")
        if "maxMetallicFactor" in rule and metallic > rule["maxMetallicFactor"]:
            reasons.append(f"{name}: metallicFactor {metallic} exceeds declared maximum")
        if "maxSheenColorFactor" in rule and max(sheen_color) > rule["maxSheenColorFactor"]:
            reasons.append(f"{name}: sheenColorFactor {sheen_color} exceeds declared maximum")
        uses = primitives.get(index, [])
        if not uses:
            reasons.append(f"{name}: selected material is not bound to any mesh primitive")
        primitive_results = []
        for mesh_index, primitive_index, primitive in uses:
            if "KHR_draco_mesh_compression" in object_value(primitive.get("extensions", {}), "primitive extensions"):
                raise ValueError("Draco primitive inspection requires decoded geometry")
            attributes = object_value(primitive.get("attributes"), "primitive attributes")
            position = glb.accessor(attributes.get("POSITION"), "POSITION")
            needed = {item["texCoord"] for item in bound.values()}
            if "texCoord" in rule:
                needed.add(rule["texCoord"])
                for key, item in bound.items():
                    if item["texCoord"] != rule["texCoord"]:
                        reasons.append(f"{name}: {key} uses TEXCOORD_{item['texCoord']}, policy requires TEXCOORD_{rule['texCoord']}")
            uvs = {}
            for coord in sorted(needed):
                semantic = f"TEXCOORD_{coord}"
                if semantic not in attributes:
                    reasons.append(f"{name}: mesh {mesh_index} primitive {primitive_index} lacks {semantic}")
                    continue
                uv = glb.accessor(attributes[semantic], semantic)
                if uv["count"] != position["count"]:
                    raise ValueError(f"{name}: {semantic} count does not match POSITION")
                uvs[semantic] = uv
            primitive_results.append({"mesh": mesh_index, "primitive": primitive_index, "uvAttributes": uvs})
        results.append({"name": name, "material": index, "expectations": rule,
                        "factors": {"roughnessFactor": roughness, "metallicFactor": metallic,
                                    "baseColorFactor": base_color, "sheenColorFactor": sheen_color,
                                    "sheenRoughnessFactor": sheen_roughness},
                        "textures": bound, "primitives": primitive_results})
    for label, value in inputs.items():
        check_pin(value, label)
    for resource in glb.resources.values():
        check_pin(resource, "external resource")
    return {"schemaVersion": 1, "audit": GATE, "passed": not reasons, "reasons": reasons,
            "inputs": inputs, "resources": sorted(glb.resources.values(), key=lambda item: item["path"]),
            "materials": results, "texturePixelsEvaluated": False, "limitations": LIMITATIONS}


def gate(workspace):
    receipt = load_receipt(workspace, RECEIPT, STATE_KEY)
    if receipt.get("audit") != GATE:
        raise ValueError("wrong audit receipt kind")
    inputs = fields(receipt.get("inputs"), ["glb", "policy"], [], "receipt.inputs")
    glb = check_pin(inputs["glb"], "GLB")
    policy = check_pin(inputs["policy"], "policy")
    resources = receipt.get("resources")
    if not isinstance(resources, list):
        raise ValueError("receipt resources must be an array")
    for resource in resources:
        check_pin(resource, "external resource")
    current = evaluate(glb, policy)
    if current["resources"] != resources:
        raise AuditFailure("external resource bindings changed since audit")
    if not receipt["passed"]:
        current["passed"] = False
        current["reasons"].append("stored material audit was negative; run the normal audit after repair")
    return current


def main(argv=None):
    argv = sys.argv[1:] if argv is None else argv
    gate_mode = "--gate" in argv
    try:
        parser = Parser(description=__doc__)
        parser.add_argument("--workspace", required=True)
        parser.add_argument("--glb")
        parser.add_argument("--policy")
        parser.add_argument("--gate", action="store_true")
        args = parser.parse_args(argv)
        workspace = workspace_path(args.workspace)
        if args.gate:
            if args.glb or args.policy:
                raise ValueError("--gate reads pinned inputs; do not supply --glb or --policy")
            report = gate(workspace)
        else:
            if not args.glb or not args.policy:
                raise ValueError("normal audit requires --glb and --policy")
            report = evaluate(input_path(args.glb), input_path(args.policy))
            persist(workspace, RECEIPT, STATE_KEY, report)
        return emit(GATE, "pass" if report["passed"] else "fail", report["reasons"], report, gate_mode=gate_mode)
    except AuditFailure as exc:
        return emit(GATE, "fail", [str(exc)], {}, gate_mode=gate_mode)
    except (ValueError, OSError, RuntimeError, RecursionError) as exc:
        return emit(GATE, "error", [str(exc)], {}, gate_mode=gate_mode)


if __name__ == "__main__":
    sys.exit(main())