blender-cli 0.1.0__py3-none-any.whl

blender_cli/__init__.py

@@ -0,0 +1,151 @@
+"""
+maps-creation SDK — agent-friendly procedural map generation.
+
+Core types and primitives are re-exported here for convenience::
+
+    from blender_cli import Scene, plane, box
+
+For less common utilities, import from submodules directly::
+
+    from blender_cli.utils.placement import perimeter_points
+    from blender_cli.types import AddResult
+"""
+
+# Scene & entity primitives — the most-used API surface.
+# Alignment
+from blender_cli.alignment import (
+    AlignmentPipelineResult,
+    ComposeOptions,
+    ComposeResult,
+    GenerationOptions,
+    GenerationResult,
+    PoseEstimationOptions,
+    PoseEstimationResult,
+    compose_from_directory,
+    estimate_pose_from_directory,
+    generate_alignment_assets,
+    integrate_pose_result,
+    load_pose_result,
+    run_alignment_pipeline,
+)
+
+# Assets
+from blender_cli.assets import Material
+
+# Build
+from blender_cli.build import BuildContext
+
+# Geometry
+from blender_cli.geometry import (
+    WILDCARD,
+    Field2D,
+    Heightfield,
+    Mask,
+    PointSet,
+    Spline,
+    SplineOp,
+)
+
+# Project
+from blender_cli.project import ProjectFile, Session
+
+# Render
+from blender_cli.render import (
+    Camera,
+    CameraKeyframe,
+    CameraPath,
+    RenderContext,
+    focus,
+    still,
+)
+from blender_cli.scene import (
+    Anchor,
+    Entity,
+    Instances,
+    Scene,
+    Selection,
+    SnapSpec,
+    Transform,
+    as_entity,
+    box,
+    cone,
+    cylinder,
+    plane,
+    sphere,
+    torus,
+)
+
+# Blenvy
+from blender_cli.blenvy import apply_bevy_components, to_ron
+from blender_cli.blenvy_registry import BevyRegistry, ComponentInfo
+
+# Snap
+from blender_cli.snap import SnapPolicy
+from blender_cli.snap import snap as snap_points
+
+# Types
+from blender_cli.types import Vec3
+
+__all__ = [
+    "WILDCARD",
+    # alignment
+    "AlignmentPipelineResult",
+    # scene
+    "Anchor",
+    # blenvy registry
+    "BevyRegistry",
+    # build
+    "BuildContext",
+    # render
+    "Camera",
+    "CameraKeyframe",
+    "CameraPath",
+    "ComponentInfo",
+    "ComposeOptions",
+    "ComposeResult",
+    "Entity",
+    # geometry
+    "Field2D",
+    "GenerationOptions",
+    "GenerationResult",
+    "Heightfield",
+    "Instances",
+    "Mask",
+    # assets
+    "Material",
+    "PointSet",
+    "PoseEstimationOptions",
+    "PoseEstimationResult",
+    # project
+    "ProjectFile",
+    "Session",
+    "RenderContext",
+    "Scene",
+    "Selection",
+    # snap
+    "SnapPolicy",
+    "SnapSpec",
+    "Spline",
+    "SplineOp",
+    "Transform",
+    # types
+    "Vec3",
+    "apply_bevy_components",
+    "as_entity",
+    "box",
+    "compose_from_directory",
+    "cone",
+    "cylinder",
+    "estimate_pose_from_directory",
+    "focus",
+    "generate_alignment_assets",
+    "integrate_pose_result",
+    "load_pose_result",
+    "plane",
+    "run_alignment_pipeline",
+    "snap_points",
+    "sphere",
+    "still",
+    "to_ron",
+    "torus",
+]

blender_cli/__init__.pyi

@@ -0,0 +1,55 @@
+from blender_cli.alignment import AlignmentPipelineResult as AlignmentPipelineResult
+from blender_cli.alignment import ComposeOptions as ComposeOptions
+from blender_cli.alignment import ComposeResult as ComposeResult
+from blender_cli.alignment import GenerationOptions as GenerationOptions
+from blender_cli.alignment import GenerationResult as GenerationResult
+from blender_cli.alignment import PoseEstimationOptions as PoseEstimationOptions
+from blender_cli.alignment import PoseEstimationResult as PoseEstimationResult
+from blender_cli.alignment import compose_from_directory as compose_from_directory
+from blender_cli.alignment import (
+    estimate_pose_from_directory as estimate_pose_from_directory,
+)
+from blender_cli.alignment import (
+    generate_alignment_assets as generate_alignment_assets,
+)
+from blender_cli.alignment import integrate_pose_result as integrate_pose_result
+from blender_cli.alignment import load_pose_result as load_pose_result
+from blender_cli.alignment import run_alignment_pipeline as run_alignment_pipeline
+from blender_cli.assets import Material as Material
+from blender_cli.blenvy_registry import BevyRegistry as BevyRegistry
+from blender_cli.blenvy_registry import ComponentInfo as ComponentInfo
+from blender_cli.build import BuildContext as BuildContext
+from blender_cli.geometry import WILDCARD as WILDCARD
+from blender_cli.geometry import Field2D as Field2D
+from blender_cli.geometry import Heightfield as Heightfield
+from blender_cli.geometry import Mask as Mask
+from blender_cli.geometry import PointSet as PointSet
+from blender_cli.geometry import Spline as Spline
+from blender_cli.geometry import SplineOp as SplineOp
+from blender_cli.project import ProjectFile as ProjectFile
+from blender_cli.project import Session as Session
+from blender_cli.render import Camera as Camera
+from blender_cli.render import CameraKeyframe as CameraKeyframe
+from blender_cli.render import CameraPath as CameraPath
+from blender_cli.render import RenderContext as RenderContext
+from blender_cli.render import focus as focus
+from blender_cli.render import still as still
+from blender_cli.scene import Anchor as Anchor
+from blender_cli.scene import Entity as Entity
+from blender_cli.scene import Instances as Instances
+from blender_cli.scene import Scene as Scene
+from blender_cli.scene import Selection as Selection
+from blender_cli.scene import SnapSpec as SnapSpec
+from blender_cli.scene import Transform as Transform
+from blender_cli.scene import as_entity as as_entity
+from blender_cli.scene import box as box
+from blender_cli.scene import cone as cone
+from blender_cli.scene import cylinder as cylinder
+from blender_cli.scene import plane as plane
+from blender_cli.scene import sphere as sphere
+from blender_cli.scene import torus as torus
+from blender_cli.snap import SnapPolicy as SnapPolicy
+from blender_cli.snap import snap as snap_points
+from blender_cli.types import Vec3 as Vec3
+
+__all__: list[str]  # noqa: PYI035

blender_cli/alignment/__init__.py

@@ -0,0 +1,37 @@
+"""Alignment pipeline public API."""
+
+from blender_cli.alignment.generation import generate_alignment_assets
+from blender_cli.alignment.integration import (
+    compose_from_directory,
+    integrate_pose_result,
+    load_pose_result,
+)
+from blender_cli.alignment.pipeline import (
+    estimate_pose_from_directory,
+    run_alignment_pipeline,
+)
+from blender_cli.alignment.types import (
+    AlignmentPipelineResult,
+    ComposeOptions,
+    ComposeResult,
+    GenerationOptions,
+    GenerationResult,
+    PoseEstimationOptions,
+    PoseEstimationResult,
+)
+
+__all__ = [
+    "AlignmentPipelineResult",
+    "ComposeOptions",
+    "ComposeResult",
+    "GenerationOptions",
+    "GenerationResult",
+    "PoseEstimationOptions",
+    "PoseEstimationResult",
+    "compose_from_directory",
+    "estimate_pose_from_directory",
+    "generate_alignment_assets",
+    "integrate_pose_result",
+    "load_pose_result",
+    "run_alignment_pipeline",
+]

blender_cli/alignment/_fal.py

@@ -0,0 +1,74 @@
+"""Shared fal.ai client helpers for alignment workflows."""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import logging
+
+_INSTALL_HINT = "Install it with `uv add fal-client` (or `pip install fal-client`)."
+
+
+def require_fal_client(feature: str = "Alignment fal.ai integration") -> Any:
+    """Import ``fal_client`` with a consistent error message."""
+    try:
+        return importlib.import_module("fal_client")
+    except ImportError as exc:  # pragma: no cover - dependency issue
+        msg = f"{feature} requires fal-client. {_INSTALL_HINT}"
+        raise RuntimeError(msg) from exc
+
+
+def upload_file(path: str | Path) -> str:
+    """Upload a local file to Fal storage and return the remote URL."""
+    client = require_fal_client("Alignment generation")
+    return str(client.upload_file(str(Path(path))))
+
+
+def upload_image(image: Any, *, fmt: str = "png") -> str:
+    """Upload a PIL image to Fal storage and return the remote URL."""
+    client = require_fal_client("Alignment fal.ai image upload")
+    return str(client.upload_image(image, fmt))
+
+
+def subscribe(
+    application: str,
+    *,
+    arguments: dict[str, Any],
+    with_logs: bool = False,
+    logger: logging.Logger | None = None,
+    log_prefix: str = "",
+    client_timeout: float | None = None,
+) -> dict[str, Any]:
+    """Call ``fal_client.subscribe`` with optional queue log forwarding."""
+    client = require_fal_client("Alignment fal.ai inference")
+    subscribe_kwargs: dict[str, Any] = {
+        "arguments": arguments,
+        "with_logs": with_logs,
+    }
+
+    if with_logs and logger is not None:
+        in_progress_type = getattr(client, "InProgress", None)
+
+        def _on_queue_update(update: object) -> None:
+            if in_progress_type is not None and not isinstance(
+                update, in_progress_type
+            ):
+                return
+            entries = getattr(update, "logs", None) or []
+            for entry in entries:
+                if isinstance(entry, dict):
+                    message = entry.get("message")
+                else:
+                    message = getattr(entry, "message", None)
+                if message:
+                    logger.info("%s%s", log_prefix, message)
+
+        subscribe_kwargs["on_queue_update"] = _on_queue_update
+
+    if client_timeout is not None:
+        subscribe_kwargs["client_timeout"] = client_timeout
+
+    return client.subscribe(application, **subscribe_kwargs)

blender_cli/alignment/depth.py

@@ -0,0 +1,250 @@
+"""Marigold depth helpers for silhouette/CMA-ES pose initialization."""
+
+from __future__ import annotations
+
+import io
+import logging
+import urllib.request
+
+import cv2
+import numpy as np
+import numpy.typing as npt
+import pyrender  # pyright: ignore[reportMissingImports]
+import trimesh
+from PIL import Image  # pyright: ignore[reportMissingImports]
+
+from ._fal import require_fal_client
+from ._fal import subscribe as fal_subscribe
+from ._fal import upload_image as fal_upload_image
+from .pose import (  # pyright: ignore[reportPrivateUsage]
+    M_SCENE_TO_GLB,
+    CameraParams,
+    _build_camera_pose_opengl,
+    _camera_intrinsics,
+)
+
+log = logging.getLogger("blender_cli.alignment.depth")
+
+_FAL_MODEL_ID = "fal-ai/imageutils/marigold-depth"
+
+
+class DepthEstimator:
+    """Monocular depth estimation using Marigold via fal.ai."""
+
+    def __init__(
+        self,
+        *,
+        ensemble_size: int = 10,
+        num_inference_steps: int = 10,
+    ) -> None:
+        require_fal_client("Depth initialization")
+        self._ensemble_size = ensemble_size
+        self._num_inference_steps = num_inference_steps
+        log.info(
+            "DepthEstimator ready (Marigold via fal.ai, ensemble=%d, steps=%d)",
+            ensemble_size,
+            num_inference_steps,
+        )
+
+    def estimate(self, image_np: npt.NDArray[np.uint8]) -> npt.NDArray[np.float32]:
+        """
+        Estimate relative depth from an RGB image.
+
+        Returns a depth map (H, W) in [0, 1] float range where
+        higher values = farther from camera.
+
+        """
+        h, w = image_np.shape[:2]
+
+        pil_img = Image.fromarray(image_np)
+        image_url = fal_upload_image(pil_img, fmt="png")
+        log.info("Uploaded query image to fal CDN, calling Marigold...")
+
+        result = fal_subscribe(
+            _FAL_MODEL_ID,
+            arguments={
+                "image_url": image_url,
+                "ensemble_size": self._ensemble_size,
+                "num_inference_steps": self._num_inference_steps,
+            },
+            with_logs=True,
+            logger=log,
+            log_prefix="  fal: ",
+        )
+
+        # Download and decode the depth map PNG, preserving bit depth.
+        # Marigold may return 8-bit or 16-bit PNG.
+        depth_url: str = result["image"]["url"]
+        with urllib.request.urlopen(depth_url) as resp:  # noqa: S310
+            depth_bytes = resp.read()
+        depth_img = Image.open(io.BytesIO(depth_bytes))
+
+        # Convert to float preserving full dynamic range
+        if depth_img.mode == "I;16":
+            depth_np = np.asarray(depth_img, dtype=np.float32) / 65535.0
+        elif depth_img.mode in {"I", "F"}:
+            depth_np = np.asarray(depth_img, dtype=np.float32)
+            dmax = depth_np.max()
+            if dmax > 0:
+                depth_np /= dmax
+        else:
+            # 8-bit (L or RGB)
+            depth_np = np.asarray(depth_img.convert("L"), dtype=np.float32) / 255.0
+
+        # Resize to original resolution
+        resized: npt.NDArray[np.float32] = np.asarray(
+            cv2.resize(depth_np, (w, h), interpolation=cv2.INTER_LINEAR),
+            dtype=np.float32,
+        )
+        log.info(
+            "Marigold depth map received (%dx%d, range=[%.3f, %.3f])",
+            w,
+            h,
+            resized.min(),
+            resized.max(),
+        )
+        return resized
+
+
+def render_scene_depth(
+    scene_mesh: trimesh.Scene | trimesh.Trimesh,
+    cam_config: CameraParams,
+    width: int,
+    height: int,
+) -> npt.NDArray[np.float32]:
+    """Render depth buffer of the scene (without object) using pyrender."""
+    pos_scene = np.array(cam_config["position"], dtype=np.float64)
+    look_scene = np.array(cam_config["look_at"], dtype=np.float64)
+    pos_glb = M_SCENE_TO_GLB[:3, :3] @ pos_scene + M_SCENE_TO_GLB[:3, 3]
+    tgt_glb = M_SCENE_TO_GLB[:3, :3] @ look_scene + M_SCENE_TO_GLB[:3, 3]
+    K = _camera_intrinsics(cam_config, width, height)
+    cam_pose = _build_camera_pose_opengl(pos_glb, tgt_glb)
+
+    pr_scene = pyrender.Scene(ambient_light=[0.3, 0.3, 0.3])
+
+    if isinstance(scene_mesh, trimesh.Scene):
+        for node_name in scene_mesh.graph.nodes_geometry:
+            transform, geom_name = scene_mesh.graph[node_name]
+            geom = scene_mesh.geometry[geom_name]
+            try:
+                pr_scene.add(
+                    pyrender.Mesh.from_trimesh(geom, smooth=False),
+                    pose=transform,
+                )
+            except Exception:  # noqa: BLE001 - pyrender raises generic errors for unsupported geometry
+                log.debug("Skipped scene depth geometry node %s", node_name)
+
+    camera = pyrender.IntrinsicsCamera(
+        fx=float(K[0, 0]),
+        fy=float(K[1, 1]),
+        cx=float(K[0, 2]),
+        cy=float(K[1, 2]),
+        znear=0.05,
+        zfar=50.0,
+    )
+    pr_scene.add(camera, pose=cam_pose)
+
+    r = pyrender.OffscreenRenderer(width, height)
+    result = r.render(pr_scene)
+    assert result is not None
+    _, depth = result
+    r.delete()
+    return depth
+
+
+def align_depth(
+    scene_depth: npt.NDArray[np.float32],
+    mono_depth: npt.NDArray[np.float32],
+    mask: npt.NDArray[np.bool_],
+) -> tuple[npt.NDArray[np.float64], float, float]:
+    """
+    Align monocular (relative) depth to absolute scene depth.
+
+    Fits an affine model ``scene = a * mono + b`` on background pixels
+    (where the rendered scene depth is valid and the object mask is off).
+    Automatically tries both depth and inverse-depth conventions and
+    picks the one with lower residual.
+
+    """
+    valid = (scene_depth > 0.1) & (~mask)
+    if valid.sum() < 100:
+        log.warning("Too few valid background pixels for depth alignment")
+        return mono_depth.astype(np.float64), 1.0, 0.0
+
+    sd = scene_depth[valid].astype(np.float64)
+    md = mono_depth[valid].astype(np.float64)
+
+    # Fit 1: direct linear  scene = a*mono + b
+    A_lin = np.column_stack([md, np.ones_like(md)])
+    res_lin = np.linalg.lstsq(A_lin, sd, rcond=None)
+    a_lin, b_lin = res_lin[0]
+    pred_lin = a_lin * md + b_lin
+    err_lin = float(np.mean((pred_lin - sd) ** 2))
+
+    # Fit 2: inverse  scene = a/mono + b  (handles disparity-like maps)
+    md_inv = 1.0 / (md + 1e-6)
+    A_inv = np.column_stack([md_inv, np.ones_like(md_inv)])
+    res_inv = np.linalg.lstsq(A_inv, sd, rcond=None)
+    a_inv, b_inv = res_inv[0]
+    pred_inv = a_inv * md_inv + b_inv
+    err_inv = float(np.mean((pred_inv - sd) ** 2))
+
+    # Pick the better fit
+    if a_lin > 0 and err_lin <= err_inv:
+        aligned = a_lin * mono_depth.astype(np.float64) + b_lin
+        log.info(
+            "Depth alignment: linear (a=%.4f, b=%.4f, mse=%.6f)", a_lin, b_lin, err_lin
+        )
+        return np.clip(aligned, 0, 50), float(a_lin), float(b_lin)
+
+    aligned = a_inv / (mono_depth.astype(np.float64) + 1e-6) + b_inv
+    log.info(
+        "Depth alignment: inverse (a=%.4f, b=%.4f, mse=%.6f)", a_inv, b_inv, err_inv
+    )
+    return np.clip(aligned, 0, 50), float(a_inv), float(b_inv)
+
+
+def estimate_object_depth(
+    aligned_depth: npt.NDArray[np.float64],
+    mask: npt.NDArray[np.bool_],
+) -> float:
+    """Estimate the depth of the object using the aligned depth map."""
+    object_depths = aligned_depth[mask]
+    if len(object_depths) == 0:
+        return 1.0
+    return float(np.median(object_depths))
+
+
+def depth_to_position(
+    pixel_u: float,
+    pixel_v: float,
+    depth: float,
+    cam_config: CameraParams,
+    width: int,
+    height: int,
+) -> npt.NDArray[np.float64]:
+    """Back-project a pixel at given depth to 3D scene coordinates."""
+    K = _camera_intrinsics(cam_config, width, height)
+    K_inv = np.linalg.inv(K)
+
+    p_h = np.array([pixel_u, pixel_v, 1.0], dtype=np.float64)
+    d_cam = K_inv @ p_h
+    d_cam /= np.linalg.norm(d_cam)
+
+    ray_distance = depth / abs(d_cam[2])
+
+    pos = np.array(cam_config["position"], dtype=np.float64)
+    target = np.array(cam_config["look_at"], dtype=np.float64)
+    fwd = target - pos
+    fwd /= np.linalg.norm(fwd) + 1e-12
+    up_scene = np.array([0.0, 0.0, 1.0])
+    right = np.cross(fwd, up_scene)
+    if np.linalg.norm(right) < 1e-6:
+        up_scene = np.array([0.0, 1.0, 0.0])
+        right = np.cross(fwd, up_scene)
+    right /= np.linalg.norm(right) + 1e-12
+    down = np.cross(fwd, right)
+    down /= np.linalg.norm(down) + 1e-12
+    R_wc = np.column_stack([right, down, fwd])
+
+    return pos + R_wc @ (d_cam * ray_distance)