meshprobe 0.2.0__py3-none-any.whl

meshprobe/__init__.py

@@ -0,0 +1,8 @@
+"""Read-only 3D model inspection primitives."""
+
+from meshprobe.controller import BlenderController
+from meshprobe.models import SceneManifest
+from meshprobe.session import InspectionSession
+
+__all__ = ["BlenderController", "InspectionSession", "SceneManifest"]
+__version__ = "0.2.0"

meshprobe/artifacts.py

@@ -0,0 +1,333 @@
+"""Deterministic, atomic storage for derived MeshProbe artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import cast
+
+from meshprobe.sources import sha256_file
+
+type JsonScalar = str | int | float | bool | None
+type JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]
+
+_MANIFEST_NAME = "manifest.json"
+_PAYLOAD_DIRECTORY = "payload"
+_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class ArtifactOutput:
+    """One immutable file in a cache entry."""
+
+    relative_path: str
+    sha256: str
+    bytes: int
+
+
+@dataclass(frozen=True)
+class ArtifactCacheEntry:
+    """A validated, completely published cache entry."""
+
+    key: str
+    source_sha256: str
+    importer_version: str
+    normalization_parameters: dict[str, JsonValue]
+    output_sha256: str
+    outputs: tuple[ArtifactOutput, ...]
+    path: Path
+
+    def output_path(self, relative_path: str) -> Path:
+        """Return a declared output path and reject undeclared names."""
+
+        declared = {output.relative_path for output in self.outputs}
+        normalized = _normalized_relative_path(relative_path)
+        if normalized not in declared:
+            raise KeyError(f"cache entry has no output named {normalized!r}")
+        return self.path / _PAYLOAD_DIRECTORY / Path(*PurePosixPath(normalized).parts)
+
+
+class ArtifactCache:
+    """Content-addressed cache whose incomplete writes are never visible."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root.expanduser().resolve()
+        self._entries = self.root / "entries"
+        self._staging = self.root / ".staging"
+        self._entries.mkdir(parents=True, exist_ok=True)
+        self._staging.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def key_for(
+        source_sha256: str,
+        importer_version: str,
+        normalization_parameters: Mapping[str, JsonValue],
+    ) -> str:
+        """Derive an entry key from every input that can change normalization."""
+
+        normalized = _normalized_parameters(normalization_parameters)
+        _validate_sha256(source_sha256, "source_sha256")
+        _validate_importer_version(importer_version)
+        material = {
+            "schema_version": _SCHEMA_VERSION,
+            "source_sha256": source_sha256,
+            "importer_version": importer_version,
+            "normalization_parameters": normalized,
+        }
+        return hashlib.sha256(_canonical_json(material)).hexdigest()
+
+    def lookup(
+        self,
+        source_sha256: str,
+        importer_version: str,
+        normalization_parameters: Mapping[str, JsonValue],
+    ) -> ArtifactCacheEntry | None:
+        """Return a verified entry or ``None``; staging data is never consulted."""
+
+        key = self.key_for(source_sha256, importer_version, normalization_parameters)
+        entry_path = self._entry_path(key)
+        if not entry_path.exists():
+            return None
+        entry = self._validate_entry(entry_path)
+        if entry.key != key:
+            raise ValueError(f"cache manifest key mismatch at {entry_path}")
+        return entry
+
+    def publish(
+        self,
+        source_sha256: str,
+        importer_version: str,
+        normalization_parameters: Mapping[str, JsonValue],
+        write_outputs: Callable[[Path], None],
+    ) -> ArtifactCacheEntry:
+        """Create and atomically publish one cache entry.
+
+        ``write_outputs`` receives an empty payload directory on the cache volume.
+        It may create files and directories but not symbolic links. If another
+        process publishes the same key first, its validated entry wins.
+        """
+
+        parameters = _normalized_parameters(normalization_parameters)
+        key = self.key_for(source_sha256, importer_version, parameters)
+        existing = self.lookup(source_sha256, importer_version, parameters)
+        if existing is not None:
+            return existing
+
+        staging_path = self._staging / f"{key}-{uuid.uuid4().hex}"
+        payload_path = staging_path / _PAYLOAD_DIRECTORY
+        payload_path.mkdir(parents=True)
+        try:
+            write_outputs(payload_path)
+            outputs = _inventory_payload(payload_path)
+            if not outputs:
+                raise ValueError("cache publication produced no output files")
+            output_sha256 = _outputs_digest(outputs)
+            manifest = {
+                "schema_version": _SCHEMA_VERSION,
+                "key": key,
+                "source_sha256": source_sha256,
+                "importer_version": importer_version,
+                "normalization_parameters": parameters,
+                "output_sha256": output_sha256,
+                "outputs": [
+                    {
+                        "relative_path": output.relative_path,
+                        "sha256": output.sha256,
+                        "bytes": output.bytes,
+                    }
+                    for output in outputs
+                ],
+            }
+            (staging_path / _MANIFEST_NAME).write_bytes(_canonical_json(manifest) + b"\n")
+            self._validate_entry(staging_path)
+
+            destination = self._entry_path(key)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                os.replace(staging_path, destination)
+            except OSError as error:
+                if not destination.exists():
+                    raise
+                winner = self._validate_entry(destination)
+                if winner.key != key:
+                    raise ValueError(
+                        f"concurrent cache publication produced wrong key {winner.key}"
+                    ) from error
+            return self._validate_entry(destination)
+        finally:
+            shutil.rmtree(staging_path, ignore_errors=True)
+
+    def evict(self, key: str) -> bool:
+        """Remove one complete entry and return whether it existed."""
+
+        _validate_sha256(key, "cache key")
+        entry_path = self._entry_path(key)
+        if not entry_path.exists():
+            return False
+        shutil.rmtree(entry_path)
+        return True
+
+    def cleanup_staging(self) -> int:
+        """Remove abandoned unpublished directories and return their count."""
+
+        removed = 0
+        for candidate in self._staging.iterdir():
+            if candidate.is_dir() and not candidate.is_symlink():
+                shutil.rmtree(candidate)
+            else:
+                candidate.unlink()
+            removed += 1
+        return removed
+
+    def _entry_path(self, key: str) -> Path:
+        _validate_sha256(key, "cache key")
+        return self._entries / key[:2] / key
+
+    def _validate_entry(self, entry_path: Path) -> ArtifactCacheEntry:
+        manifest_path = entry_path / _MANIFEST_NAME
+        payload_path = entry_path / _PAYLOAD_DIRECTORY
+        try:
+            raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ValueError(f"invalid cache manifest at {manifest_path}: {error}") from error
+        if not isinstance(raw, dict):
+            raise ValueError(f"cache manifest must be an object at {manifest_path}")
+        if raw.get("schema_version") != _SCHEMA_VERSION:
+            raise ValueError(f"unsupported cache manifest schema at {manifest_path}")
+
+        key = _required_string(raw, "key")
+        source_sha256 = _required_string(raw, "source_sha256")
+        importer_version = _required_string(raw, "importer_version")
+        output_sha256 = _required_string(raw, "output_sha256")
+        _validate_sha256(key, "cache manifest key")
+        _validate_sha256(source_sha256, "cache manifest source_sha256")
+        _validate_sha256(output_sha256, "cache manifest output_sha256")
+        _validate_importer_version(importer_version)
+
+        parameters_raw = raw.get("normalization_parameters")
+        if not isinstance(parameters_raw, dict):
+            raise ValueError("cache manifest normalization_parameters must be an object")
+        parameters = _normalized_parameters(cast(dict[str, JsonValue], parameters_raw))
+
+        outputs_raw = raw.get("outputs")
+        if not isinstance(outputs_raw, list) or not outputs_raw:
+            raise ValueError("cache manifest outputs must be a non-empty array")
+        outputs: list[ArtifactOutput] = []
+        for item in outputs_raw:
+            if not isinstance(item, dict):
+                raise ValueError("cache manifest output must be an object")
+            relative_path = _normalized_relative_path(_required_string(item, "relative_path"))
+            sha256 = _required_string(item, "sha256")
+            size = item.get("bytes")
+            _validate_sha256(sha256, "cache output sha256")
+            if not isinstance(size, int) or isinstance(size, bool) or size < 0:
+                raise ValueError("cache output bytes must be a non-negative integer")
+            outputs.append(ArtifactOutput(relative_path, sha256, size))
+        if len({output.relative_path for output in outputs}) != len(outputs):
+            raise ValueError("cache manifest output paths must be unique")
+        declared = tuple(sorted(outputs, key=lambda output: output.relative_path))
+        actual = _inventory_payload(payload_path)
+        if actual != declared:
+            raise ValueError(f"cache payload does not match manifest at {entry_path}")
+        if _outputs_digest(declared) != output_sha256:
+            raise ValueError(f"cache output digest mismatch at {entry_path}")
+        expected_key = self.key_for(source_sha256, importer_version, parameters)
+        if expected_key != key:
+            raise ValueError(f"cache input digest mismatch at {entry_path}")
+
+        return ArtifactCacheEntry(
+            key=key,
+            source_sha256=source_sha256,
+            importer_version=importer_version,
+            normalization_parameters=parameters,
+            output_sha256=output_sha256,
+            outputs=declared,
+            path=entry_path,
+        )
+
+
+def _inventory_payload(payload_path: Path) -> tuple[ArtifactOutput, ...]:
+    if not payload_path.is_dir() or payload_path.is_symlink():
+        raise ValueError("cache payload must be a real directory")
+    outputs: list[ArtifactOutput] = []
+    for path in sorted(payload_path.rglob("*")):
+        if path.is_symlink():
+            raise ValueError(f"cache payload cannot contain symbolic links: {path}")
+        if path.is_dir():
+            continue
+        if not path.is_file():
+            raise ValueError(f"cache payload contains unsupported entry: {path}")
+        relative_path = path.relative_to(payload_path).as_posix()
+        outputs.append(
+            ArtifactOutput(
+                relative_path=_normalized_relative_path(relative_path),
+                sha256=sha256_file(path),
+                bytes=path.stat().st_size,
+            )
+        )
+    return tuple(outputs)
+
+
+def _outputs_digest(outputs: tuple[ArtifactOutput, ...]) -> str:
+    records = [
+        {
+            "relative_path": output.relative_path,
+            "sha256": output.sha256,
+            "bytes": output.bytes,
+        }
+        for output in outputs
+    ]
+    return hashlib.sha256(_canonical_json(records)).hexdigest()
+
+
+def _normalized_parameters(parameters: Mapping[str, JsonValue]) -> dict[str, JsonValue]:
+    if any(not isinstance(key, str) for key in parameters):
+        raise ValueError("normalization parameter keys must be strings")
+    try:
+        encoded = _canonical_json(dict(parameters))
+        normalized = json.loads(encoded)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"normalization parameters must be finite JSON values: {error}") from error
+    if not isinstance(normalized, dict):
+        raise ValueError("normalization parameters must be an object")
+    return cast(dict[str, JsonValue], normalized)
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def _normalized_relative_path(relative_path: str) -> str:
+    path = PurePosixPath(relative_path.replace("\\", "/"))
+    if path.is_absolute() or not path.parts or any(part in {"", ".", ".."} for part in path.parts):
+        raise ValueError(f"cache output path must be a normalized relative path: {relative_path!r}")
+    return path.as_posix()
+
+
+def _required_string(value: Mapping[str, object], key: str) -> str:
+    item = value.get(key)
+    if not isinstance(item, str) or not item:
+        raise ValueError(f"cache manifest {key} must be a non-empty string")
+    return item
+
+
+def _validate_sha256(value: str, label: str) -> None:
+    if len(value) != 64 or any(character not in "0123456789abcdef" for character in value):
+        raise ValueError(f"{label} must be a lowercase SHA-256 digest")
+
+
+def _validate_importer_version(importer_version: str) -> None:
+    if not importer_version or len(importer_version) > 256:
+        raise ValueError("importer_version must contain between 1 and 256 characters")

meshprobe/blender/__init__.py

@@ -0,0 +1 @@
+"""Blender-side worker implementation."""

meshprobe/blender/curated_builder.py

@@ -0,0 +1,172 @@
+"""Factory-clean Blender batch builder for curated evaluation assemblies."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import bpy  # type: ignore[import-not-found]
+from mathutils import Vector  # type: ignore[import-not-found]
+
+
+def arguments() -> tuple[Path, Path]:
+    args = sys.argv[sys.argv.index("--") + 1 :]
+    if len(args) != 2:
+        raise ValueError("curated builder expects jobs.json and checkpoint.json")
+    return Path(args[0]).resolve(strict=True), Path(args[1]).resolve()
+
+
+def clear_scene() -> None:
+    bpy.ops.object.select_all(action="SELECT")
+    bpy.ops.object.delete(use_global=False)
+    for collection in list(bpy.data.collections):
+        if collection.users == 0:
+            bpy.data.collections.remove(collection)
+
+
+def imported_objects(path: Path) -> list[bpy.types.Object]:
+    before = set(bpy.data.objects)
+    result = bpy.ops.import_scene.gltf(filepath=str(path))
+    if "FINISHED" not in result:
+        raise RuntimeError(f"curated source import failed: {path}")
+    return [obj for obj in bpy.data.objects if obj not in before]
+
+
+def parent_preserving_world(obj: bpy.types.Object, parent: bpy.types.Object) -> None:
+    matrix = obj.matrix_world.copy()
+    obj.parent = parent
+    obj.matrix_world = matrix
+
+
+def mesh_span(objects: list[bpy.types.Object]) -> float:
+    points = [
+        obj.matrix_world @ Vector(corner)
+        for obj in objects
+        if obj.type == "MESH"
+        for corner in obj.bound_box
+    ]
+    if not points:
+        raise ValueError("curated source contains no mesh objects")
+    minimum = Vector(min(point[axis] for point in points) for axis in range(3))
+    maximum = Vector(max(point[axis] for point in points) for axis in range(3))
+    return float(max((maximum - minimum).length, 1e-6))
+
+
+def add_camera_and_light(variant: str) -> None:
+    camera_data = bpy.data.cameras.new("inspection_camera")
+    camera = bpy.data.objects.new("inspection_camera", camera_data)
+    bpy.context.scene.collection.objects.link(camera)
+    camera.location = (5.5, -8.0, 4.5)
+    camera.rotation_euler = (math.radians(67), 0, math.radians(34))
+    camera_data.lens = 24 if variant == "start_state" else 50
+    bpy.context.scene.camera = camera
+    light_data = bpy.data.lights.new("inspection_key", "AREA")
+    light_data.energy = 1_000 if variant == "start_state" else 700
+    light_data.shape = "DISK"
+    light_data.size = 5
+    light = bpy.data.objects.new("inspection_key", light_data)
+    bpy.context.scene.collection.objects.link(light)
+    light.location = (-4, -5, 6) if variant == "start_state" else (4, -5, 6)
+
+
+def build(job: dict[str, Any]) -> dict[str, object]:
+    clear_scene()
+    variant = str(job["variant"])
+    assembly_root = bpy.data.objects.new("assembly", None)
+    bpy.context.scene.collection.objects.link(assembly_root)
+    placements = list(job["placements"])
+    if variant == "reorder_hierarchy":
+        placements.reverse()
+    roles: dict[str, list[str]] = {}
+    for placement_index, placement in enumerate(placements):
+        role = str(placement["role"])
+        group = bpy.data.objects.new(f"group_{placement_index + 1:02d}", None)
+        bpy.context.scene.collection.objects.link(group)
+        group.parent = assembly_root
+        objects = imported_objects(Path(str(placement["path"])).resolve(strict=True))
+        top_level = [obj for obj in objects if obj.parent not in objects]
+        for obj in top_level:
+            parent_preserving_world(obj, group)
+        scale = 1 / mesh_span(objects)
+        group.scale = (scale, scale, scale)
+        group.location = tuple(float(value) / 1_000 for value in placement["position_mm"])
+        role_names: list[str] = []
+        meshes = sorted((obj for obj in objects if obj.type == "MESH"), key=lambda obj: obj.name)
+        for mesh_index, obj in enumerate(meshes, start=1):
+            suffix = f"part_{mesh_index:02d}" if variant == "rename" else obj.name
+            obj.name = f"{role}__{suffix}"
+            role_names.append(obj.name)
+        roles[role] = role_names
+
+    if variant == "rigid_transform":
+        assembly_root.location = (1.7, -0.8, 0.6)
+        assembly_root.rotation_euler[2] = math.radians(37)
+    if variant == "rescale":
+        assembly_root.scale = (0.1, 0.1, 0.1)
+    if variant == "mirror":
+        assembly_root.scale.x = -1
+    if variant == "material":
+        material = bpy.data.materials.new("curated_diagnostic_blue")
+        material.diffuse_color = (0.08, 0.25, 0.7, 1)
+        for obj in bpy.context.scene.objects:
+            if obj.type == "MESH":
+                obj.data.materials.clear()
+                obj.data.materials.append(material)
+    if variant == "extra_occluder":
+        bpy.ops.mesh.primitive_cube_add(location=(0.2, -0.55, 0.25), scale=(0.45, 0.12, 0.45))
+        occluder = bpy.context.active_object
+        occluder.name = "distractor__irrelevant_panel"
+        occluder.parent = assembly_root
+        roles["distractor"] = [occluder.name]
+    add_camera_and_light(variant)
+    output = Path(str(job["output"])).resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    result = bpy.ops.export_scene.gltf(
+        filepath=str(output),
+        export_format="GLB",
+        export_cameras=True,
+        export_lights=True,
+    )
+    if "FINISHED" not in result or not output.is_file():
+        raise RuntimeError(f"curated assembly export failed: {output}")
+    return {"roles": roles, "variant": variant, "model_file": output.name}
+
+
+def atomic_json(path: Path, payload: object) -> None:
+    pending = path.with_name(f".{path.name}.pending")
+    pending.write_text(json.dumps(payload, sort_keys=True, separators=(",", ":")) + "\n")
+    os.replace(pending, path)
+
+
+def main() -> None:
+    jobs_path, checkpoint_path = arguments()
+    payload = json.loads(jobs_path.read_text(encoding="utf-8"))
+    build_id = str(payload["build_id"])
+    jobs = list(payload["jobs"])
+    checkpoint: dict[str, Any] = {"build_id": build_id, "completed": []}
+    if checkpoint_path.is_file():
+        candidate = json.loads(checkpoint_path.read_text(encoding="utf-8"))
+        if candidate.get("build_id") == build_id:
+            checkpoint = candidate
+    completed = set(checkpoint.get("completed", []))
+    for job in jobs:
+        key = str(job["key"])
+        output = Path(str(job["output"]))
+        metadata = Path(str(job["metadata"]))
+        if key in completed and output.is_file() and metadata.is_file():
+            continue
+        result = build(job)
+        atomic_json(metadata, result)
+        completed.add(key)
+        atomic_json(
+            checkpoint_path,
+            {"build_id": build_id, "completed": sorted(completed)},
+        )
+
+
+if __name__ == "__main__":
+    main()