reverse3d 0.4.0__py3-none-any.whl

reverse3d/recipes.py

@@ -0,0 +1,394 @@
+"""One-call end-to-end workflows ("recipes").
+
+A recipe chains the individual tools into a complete job and returns a short
+summary. For AI agents this is the main token saver: one tool call and one
+small result instead of five or six round-trips with full intermediate
+reports. The complete details are written to ``<output_dir>/report.json``.
+
+Recipes
+-------
+photos_to_model   photo set   → analysis → photogrammetry → clean/align → measure → render
+plan_to_part      plan/stencil → mask → extrusion → clean → measure → render
+scan_to_cad       mesh/scan   → clean/align → measure → primitives → OpenSCAD + CadQuery → render
+photo_to_relief   one photo   → depth → 2.5D mesh → clean → render
+mesh_report       mesh        → measure → render
+auto              anything    → detects the input and runs the right recipe, retrying
+                                with other parameters when that can help (see autopilot)
+
+Device (CPU/GPU) and speed/quality come from ``Settings.device`` and
+``Settings.profile`` unless explicitly overridden.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, TypeVar
+
+from reverse3d.config import Settings
+from reverse3d.errors import (
+    CaptureQualityError,
+    DependencyMissingError,
+    InputValidationError,
+    ProcessingError,
+)
+from reverse3d.hardware import torch_device, wants_gpu
+from reverse3d.profiles import profile_values
+from reverse3d.reverse_eng.measure import MeshStats
+from reverse3d.security import prepare_output_dir
+
+logger = logging.getLogger(__name__)
+
+RecipeName = Literal[
+    "photos_to_model", "plan_to_part", "scan_to_cad", "photo_to_relief", "mesh_report", "auto"
+]
+RECIPES: tuple[RecipeName, ...] = (
+    "photos_to_model",
+    "plan_to_part",
+    "scan_to_cad",
+    "photo_to_relief",
+    "mesh_report",
+    "auto",
+)
+MaskMethod = Literal["otsu", "adaptive", "canny", "alpha"]
+_T = TypeVar("_T")
+
+
+@dataclass
+class RecipeOptions:
+    """Optional knobs shared by recipes. ``None`` means "use the profile"."""
+
+    thickness: float = 5.0
+    units_per_pixel: float | None = None
+    scale: float = 1.0
+    render: bool = True
+    quality: Literal["low", "medium", "high"] | None = None
+    force_analysis: bool = False
+    overwrite: bool = False
+    #: plan_to_part: how the drawing is separated from the background.
+    mask_method: MaskMethod = "otsu"
+    #: mesh repair strength; "strong" closes much larger holes.
+    repair: Literal["normal", "strong"] = "normal"
+
+
+@dataclass
+class _Run:
+    recipe: str
+    settings: Settings
+    out: Path
+    outputs: dict[str, str] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def step(self, name: str, fn: Callable[[], _T]) -> _T:
+        start = time.perf_counter()
+        try:
+            value = fn()
+        except Exception:
+            self.steps.append(
+                {"step": name, "ok": False, "s": round(time.perf_counter() - start, 2)}
+            )
+            raise
+        self.steps.append({"step": name, "ok": True, "s": round(time.perf_counter() - start, 2)})
+        return value
+
+
+def _summary_dims(stats: MeshStats) -> dict[str, Any]:
+    return {
+        "size_obb": stats.obb_extents,
+        "size_aabb": stats.aabb_extents,
+        "volume": stats.volume,
+        "area": stats.surface_area,
+        "watertight": stats.watertight,
+        "faces": stats.faces,
+    }
+
+
+def _clean(
+    run: _Run,
+    src: Path,
+    dst: Path,
+    *,
+    scale: float,
+    overwrite: bool,
+    fill_holes: bool = True,
+    align: Literal["none", "obb"] = "obb",
+    keep_largest: bool = False,
+    repair: Literal["normal", "strong"] = "normal",
+) -> MeshStats:
+    """Repair + align. ``keep_largest`` only for photogrammetry/relief output,
+    where floating fragments are noise; plans and scans may have several real
+    parts, and tiny debris is already dropped by the area filter."""
+    from reverse3d.reverse_eng.mesh_cleaner import CleanOptions, clean_mesh_file
+
+    report = run.step(
+        "clean",
+        lambda: clean_mesh_file(
+            src,
+            dst,
+            run.settings,
+            CleanOptions(
+                keep_largest_only=keep_largest,
+                fill_holes=fill_holes,
+                align=align,
+                ground=align != "none",
+                scale=scale,
+                max_hole_edges=2000 if repair == "strong" else 200,
+            ),
+            overwrite=overwrite,
+        ),
+    )
+    run.warnings.extend(report.warnings)
+    run.outputs["model"] = str(dst)
+    run.details["clean"] = report.to_dict()
+    return report.after
+
+
+def _render(run: _Run, mesh: Path, overwrite: bool) -> None:
+    from reverse3d.rendering.blender_render import RenderOptions, render_mesh
+
+    prof = profile_values(run.settings)
+    options = RenderOptions(
+        width=prof.render_width,
+        height=prof.render_height,
+        samples=prof.render_samples,
+        device="gpu" if wants_gpu(run.settings) else "cpu",
+    )
+    try:
+        result = run.step(
+            "render",
+            lambda: render_mesh(
+                mesh, run.out / "render.png", run.settings, options, overwrite=overwrite
+            ),
+        )
+    except DependencyMissingError as exc:
+        run.warnings.append(f"Render skipped: {exc.message} {exc.hint or ''}".strip())
+        return
+    run.outputs["render"] = result.files[0]
+    run.details["render"] = result.to_dict()
+
+
+def _measure(run: _Run, mesh: Path) -> MeshStats:
+    from reverse3d.reverse_eng.measure import measure_mesh_file
+
+    stats = run.step("measure", lambda: measure_mesh_file(mesh, run.settings))
+    run.details["measure"] = stats.to_dict()
+    return stats
+
+
+# ─── recipes ──────────────────────────────────────────────────────────────────
+
+
+def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
+    from reverse3d.reconstruction.photogrammetry import PhotogrammetryOptions, run_photogrammetry
+    from reverse3d.vision.feature_matcher import analyze_image_set
+
+    analysis = run.step("analyze", lambda: analyze_image_set(src, run.settings))
+    run.details["analysis"] = analysis.to_dict()
+    if not analysis.suitable_for_photogrammetry:
+        if not opt.force_analysis:
+            raise CaptureQualityError(
+                "The photo set is not suitable for photogrammetry: "
+                + " ".join(analysis.recommendations),
+                hint="Improve the capture, or pass force_analysis=true to try anyway.",
+            )
+        run.warnings.extend(analysis.recommendations)
+
+    quality = opt.quality or profile_values(run.settings).photo_quality
+    photo = run.step(
+        "photogrammetry",
+        lambda: run_photogrammetry(
+            src,
+            run.out / "reconstruction",
+            run.settings,
+            PhotogrammetryOptions(quality=quality, use_gpu=wants_gpu(run.settings)),  # type: ignore[arg-type]
+            overwrite=opt.overwrite,
+        ),
+    )
+    run.warnings.extend(photo.warnings)
+    run.details["photogrammetry"] = photo.to_dict()
+    run.outputs["point_cloud"] = photo.dense_points_path or photo.sparse_points_path
+    if not photo.mesh_path:
+        raise ProcessingError(
+            "Point cloud created but no mesh could be built.",
+            hint='Install the meshing extra: pip install "reverse3d[recon]" (Python ≤ 3.12).',
+        )
+    model = run.out / "model.stl"
+    _clean(
+        run,
+        Path(photo.mesh_path),
+        model,
+        scale=opt.scale,
+        overwrite=opt.overwrite,
+        keep_largest=True,
+        repair=opt.repair,
+    )
+    return _measure(run, model)
+
+
+def _plan_to_part(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
+    from reverse3d.vision.mask_extractor import extract_mask, silhouette_to_mesh
+
+    mask = run.step(
+        "mask",
+        lambda: extract_mask(
+            src,
+            run.out / "mask",
+            run.settings,
+            method=opt.mask_method,
+            units_per_pixel=opt.units_per_pixel,
+            overwrite=opt.overwrite,
+        ),
+    )
+    run.warnings.extend(mask.warnings)
+    run.outputs["contours_svg"] = mask.svg_path
+    if opt.units_per_pixel is None:
+        run.warnings.append("No units_per_pixel given: sizes are in pixels.")
+    raw = run.out / "extruded.stl"
+    run.step(
+        "extrude",
+        lambda: silhouette_to_mesh(
+            mask.contours_path, raw, run.settings, thickness=opt.thickness, overwrite=opt.overwrite
+        ),
+    )
+    model = run.out / "model.stl"
+    _clean(run, raw, model, scale=opt.scale, overwrite=opt.overwrite)
+    return _measure(run, model)
+
+
+def _scan_to_cad(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
+    from reverse3d.reverse_eng.geometry_fit import fit_primitives_file
+    from reverse3d.reverse_eng.parametric import export_parametric
+
+    model = run.out / "model.stl"
+    _clean(run, src, model, scale=opt.scale, overwrite=opt.overwrite, repair=opt.repair)
+    stats = _measure(run, model)
+    samples = profile_values(run.settings).fit_samples
+    fit = run.step("fit", lambda: fit_primitives_file(model, run.settings, sample_count=samples))
+    run.details["primitives"] = fit.to_dict()
+    run.details["primitive_summary"] = [
+        {
+            "kind": p.kind,
+            **{k: v for k, v in p.params.items() if k in ("radius", "height", "normal")},
+        }
+        for p in fit.primitives
+    ]
+    if fit.primitives:
+        run.outputs["cad_openscad"] = str(
+            export_parametric(fit, run.out / "cad.scad", overwrite=opt.overwrite)
+        )
+        run.outputs["cad_cadquery"] = str(
+            export_parametric(fit, run.out / "cad.py", overwrite=opt.overwrite)
+        )
+    else:
+        run.warnings.append("No primitives detected; no CAD code generated.")
+    return stats
+
+
+def _photo_to_relief(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
+    from reverse3d.reconstruction.depth_estimation import estimate_depth
+
+    depth = run.step(
+        "depth",
+        lambda: estimate_depth(
+            src,
+            run.out / "depth",
+            run.settings,
+            device=torch_device(run.settings),
+            stride=profile_values(run.settings).depth_stride,
+            overwrite=opt.overwrite,
+        ),
+    )
+    run.details["depth"] = depth.to_dict()
+    run.warnings.append("Monocular depth is relative: shape is approximate, not metric.")
+    if depth.mesh_path is None:  # pragma: no cover - make_mesh is always on here
+        raise ProcessingError("Depth estimation produced no mesh.")
+    model = run.out / "model.stl"
+    _clean(
+        run,
+        Path(depth.mesh_path),
+        model,
+        scale=opt.scale,
+        overwrite=opt.overwrite,
+        fill_holes=False,
+        align="none",
+        keep_largest=True,
+    )
+    return _measure(run, model)
+
+
+def _mesh_report(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
+    run.outputs["model"] = str(src)
+    return _measure(run, src)
+
+
+_RECIPES: dict[str, Callable[[_Run, Path, RecipeOptions], MeshStats]] = {
+    "photos_to_model": _photos_to_model,
+    "plan_to_part": _plan_to_part,
+    "scan_to_cad": _scan_to_cad,
+    "photo_to_relief": _photo_to_relief,
+    "mesh_report": _mesh_report,
+}
+
+
+def run_recipe(
+    recipe: str,
+    input_path: str | Path,
+    output_dir: str | Path,
+    settings: Settings,
+    options: RecipeOptions | None = None,
+) -> dict[str, Any]:
+    """Run a recipe and return a compact summary (full report in report.json).
+
+    Raises:
+        InputValidationError: unknown recipe or invalid options.
+        Reverse3DError: any step failure (the error names the failing step).
+    """
+    if recipe == "auto":
+        from reverse3d.autopilot import auto_run
+
+        return auto_run(input_path, output_dir, settings, options)
+    if recipe not in _RECIPES:
+        raise InputValidationError(
+            f"Unknown recipe '{recipe}'.", hint=f"Use one of: {', '.join(RECIPES)}"
+        )
+    opt = options or RecipeOptions()
+    if not 0 < opt.thickness <= 1e6:
+        raise InputValidationError("thickness must be in (0, 1e6].")
+    if not 1e-9 < opt.scale < 1e9:
+        raise InputValidationError("scale must be a positive factor.")
+
+    out = prepare_output_dir(output_dir)
+    run = _Run(recipe=recipe, settings=settings, out=out)
+    start = time.perf_counter()
+    stats = _RECIPES[recipe](run, Path(input_path), opt)
+    if opt.render:
+        _render(run, Path(run.outputs["model"]), opt.overwrite)
+
+    summary: dict[str, Any] = {
+        "recipe": recipe,
+        "outputs": run.outputs,
+        "dimensions": _summary_dims(stats),
+        "device": "gpu" if wants_gpu(settings) else "cpu",
+        "profile": settings.profile,
+        "seconds": round(time.perf_counter() - start, 1),
+        "steps": [f"{s['step']}:{s['s']}s" for s in run.steps],
+        "warnings": run.warnings,
+    }
+    if "primitive_summary" in run.details:
+        summary["primitives"] = run.details["primitive_summary"]
+
+    report_path = out / "report.json"
+    if report_path.exists() and not opt.overwrite:
+        report_path = out / f"report_{int(time.time())}.json"
+    report_path.write_text(
+        json.dumps({**summary, "details": run.details}, indent=2, default=str), encoding="utf-8"
+    )
+    summary["outputs"]["report"] = str(report_path)
+    logger.info("Recipe %s finished in %.1fs", recipe, summary["seconds"])
+    return summary

reverse3d/reconstruction/__init__.py

@@ -0,0 +1,22 @@
+"""3D reconstruction: COLMAP photogrammetry, monocular depth and point-cloud meshing.
+
+Heavy optional imports (Open3D, PyTorch) happen inside the functions that need
+them, so importing this package is always cheap.
+"""
+
+from reverse3d.reconstruction.depth_estimation import depth_to_mesh, estimate_depth
+from reverse3d.reconstruction.photogrammetry import (
+    ColmapPipeline,
+    PhotogrammetryOptions,
+    run_photogrammetry,
+)
+from reverse3d.reconstruction.pointcloud import poisson_mesh
+
+__all__ = [
+    "ColmapPipeline",
+    "PhotogrammetryOptions",
+    "depth_to_mesh",
+    "estimate_depth",
+    "poisson_mesh",
+    "run_photogrammetry",
+]

reverse3d/reconstruction/depth_estimation.py

@@ -0,0 +1,263 @@
+"""Monocular depth estimation (feed-forward, single image) and depth → mesh.
+
+Inference uses Hugging Face ``transformers`` (optional ``[depth]`` extra).
+
+Supply-chain controls (OWASP LLM03 / ASI04):
+
+* Only models in :data:`ALLOWED_MODELS` can be loaded — an agent cannot make the
+  toolkit download arbitrary repositories.
+* ``trust_remote_code`` is never enabled, so no repository Python code runs.
+* Weights are loaded with ``use_safetensors=True``: pickle-based ``.bin``
+  checkpoints (arbitrary code execution on load) are refused.
+* Models are loaded from ``~/.reverse3d/models`` (see :mod:`reverse3d.offline`):
+  once downloaded, depth estimation works without internet.
+
+The geometric part (:func:`depth_to_mesh`) is pure NumPy/trimesh and works
+without the extra, e.g. with depth maps from other sources.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+import cv2
+import numpy as np
+import trimesh
+
+from reverse3d.config import Settings
+from reverse3d.errors import DependencyMissingError, InputValidationError
+from reverse3d.imaging import load_image, save_image
+from reverse3d.mesh_io import save_mesh
+from reverse3d.security import prepare_output_dir, prepare_output_file
+
+logger = logging.getLogger(__name__)
+
+DepthMode = Literal["disparity", "depth"]
+
+#: model id → (output semantics, license note). Depth Anything V2 predicts
+#: relative inverse depth (disparity).
+ALLOWED_MODELS: dict[str, tuple[DepthMode, str]] = {
+    "depth-anything/Depth-Anything-V2-Small-hf": ("disparity", "Apache-2.0"),
+    "depth-anything/Depth-Anything-V2-Base-hf": ("disparity", "CC-BY-NC-4.0 (non-commercial)"),
+    "depth-anything/Depth-Anything-V2-Large-hf": ("disparity", "CC-BY-NC-4.0 (non-commercial)"),
+}
+DEFAULT_MODEL = "depth-anything/Depth-Anything-V2-Small-hf"
+
+
+@dataclass
+class DepthResult:
+    """Outputs of :func:`estimate_depth`."""
+
+    depth_png_path: str
+    depth_npy_path: str
+    mesh_path: str | None
+    model: str
+    model_license: str
+    width: int
+    height: int
+    mesh_faces: int | None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def _load_pipeline(model: str, device: str, settings: Settings | None = None) -> Any:
+    try:
+        from transformers import pipeline
+    except ImportError as exc:
+        raise DependencyMissingError(
+            "transformers/torch are required for depth estimation.",
+            hint='pip install "reverse3d[depth]"',
+        ) from exc
+    from reverse3d.offline import force_offline_env, is_offline, resolve_model
+
+    settings = settings or Settings.load()
+    local_path = resolve_model(model, settings)
+    if is_offline(settings):
+        force_offline_env()
+    try:  # keep CLI/agent output clean: no download/loading progress bars
+        from transformers.utils import logging as hf_logging
+
+        hf_logging.disable_progress_bar()
+        hf_logging.set_verbosity_error()
+    except ImportError:  # pragma: no cover - very old transformers
+        pass
+    return pipeline(
+        task="depth-estimation",
+        model=str(local_path),
+        device=device,
+        trust_remote_code=False,
+        model_kwargs={"use_safetensors": True},
+    )
+
+
+def predict_depth(
+    rgb: np.ndarray,
+    model: str = DEFAULT_MODEL,
+    device: str = "cpu",
+    settings: Settings | None = None,
+) -> np.ndarray:
+    """Run the depth model on an RGB uint8 image and return a float32 map of the
+    same height/width (relative units, semantics per :data:`ALLOWED_MODELS`)."""
+    if model not in ALLOWED_MODELS:
+        raise InputValidationError(
+            f"Model '{model}' is not in the allowlist.",
+            hint=f"Allowed: {', '.join(ALLOWED_MODELS)}",
+        )
+    if device not in {"cpu", "cuda", "mps"}:
+        raise InputValidationError("device must be cpu, cuda or mps.")
+    from PIL import Image
+
+    pipe = _load_pipeline(model, device, settings)
+    output = pipe(Image.fromarray(rgb))
+    predicted = output["predicted_depth"]
+    depth = np.asarray(predicted.squeeze().detach().cpu().numpy(), dtype=np.float32)
+    h, w = rgb.shape[:2]
+    if depth.shape != (h, w):
+        depth = cv2.resize(depth, (w, h), interpolation=cv2.INTER_CUBIC)
+    return depth
+
+
+def _normalize(values: np.ndarray) -> np.ndarray:
+    lo, hi = np.percentile(values, [1, 99])
+    if hi - lo < 1e-9:
+        return np.zeros_like(values, dtype=np.float64)
+    return np.clip((values - lo) / (hi - lo), 0.0, 1.0)
+
+
+def depth_to_mesh(
+    depth: np.ndarray,
+    rgb: np.ndarray | None = None,
+    *,
+    mode: DepthMode = "disparity",
+    fov_deg: float = 60.0,
+    near: float = 1.0,
+    far: float = 5.0,
+    stride: int = 2,
+    max_depth_jump: float = 0.08,
+    mask: np.ndarray | None = None,
+) -> trimesh.Trimesh:
+    """Back-project a (relative) depth map into a triangulated height-field mesh.
+
+    Relative predictions are mapped to the metric-like range ``[near, far]``.
+    Triangles spanning a depth discontinuity larger than ``max_depth_jump``
+    (relative to the range) are dropped to avoid "rubber sheet" artifacts
+    between foreground and background. Camera looks down -Z (OpenGL convention).
+
+    Args:
+        depth: HxW array.
+        rgb: optional HxWx3 uint8 colors (RGB order).
+        mask: optional HxW boolean/uint8 array; only masked pixels are meshed.
+    """
+    if depth.ndim != 2:
+        raise InputValidationError("depth must be a 2D array.")
+    if not 10 <= fov_deg <= 170:
+        raise InputValidationError("fov_deg must be in [10, 170].")
+    if not 0 < near < far:
+        raise InputValidationError("Require 0 < near < far.")
+    if not 1 <= stride <= 32:
+        raise InputValidationError("stride must be in [1, 32].")
+
+    d = _normalize(depth[::stride, ::stride].astype(np.float64))
+    if mode == "disparity":
+        # Interpolate in inverse depth: disparity 1 → near, 0 → far.
+        z = 1.0 / (d * (1.0 / near - 1.0 / far) + 1.0 / far)
+    else:
+        z = near + d * (far - near)
+
+    h, w = z.shape
+    full_w = depth.shape[1]
+    f = (full_w / 2.0) / math.tan(math.radians(fov_deg) / 2.0) / stride
+    u, v = np.meshgrid(np.arange(w, dtype=np.float64), np.arange(h, dtype=np.float64))
+    x = (u - w / 2.0) * z / f
+    y = -(v - h / 2.0) * z / f
+    vertices = np.stack([x, y, -z], axis=-1).reshape(-1, 3)
+
+    idx = np.arange(h * w).reshape(h, w)
+    a, b = idx[:-1, :-1].ravel(), idx[:-1, 1:].ravel()
+    c, e = idx[1:, :-1].ravel(), idx[1:, 1:].ravel()
+    faces = np.concatenate([np.stack([a, c, b], 1), np.stack([b, c, e], 1)])
+
+    zf = z.ravel()[faces]
+    keep = (zf.max(axis=1) - zf.min(axis=1)) <= max_depth_jump * (far - near)
+    if mask is not None:
+        m = np.asarray(mask)[::stride, ::stride].astype(bool).ravel()
+        keep &= m[faces].all(axis=1)
+    faces = faces[keep]
+    if len(faces) == 0:
+        raise InputValidationError("No triangles left after filtering; relax max_depth_jump.")
+
+    colors = None
+    if rgb is not None:
+        small = rgb[::stride, ::stride][:h, :w]
+        colors = np.concatenate(
+            [small.reshape(-1, 3), np.full((h * w, 1), 255, dtype=np.uint8)], axis=1
+        )
+    mesh = trimesh.Trimesh(vertices=vertices, faces=faces, vertex_colors=colors, process=False)
+    mesh.remove_unreferenced_vertices()
+    return mesh
+
+
+def estimate_depth(
+    image_path: str | Path,
+    output_dir: str | Path,
+    settings: Settings,
+    *,
+    model: str = DEFAULT_MODEL,
+    device: str = "cpu",
+    make_mesh: bool = True,
+    fov_deg: float = 60.0,
+    stride: int = 2,
+    mask_path: str | Path | None = None,
+    overwrite: bool = False,
+) -> DepthResult:
+    """Estimate depth for one image and optionally build a 2.5D mesh.
+
+    Outputs in ``output_dir``: ``<stem>_depth.png`` (16-bit visualisation),
+    ``<stem>_depth.npy`` (raw float32) and ``<stem>_depth_mesh.ply``.
+    """
+    bgr = load_image(image_path, settings)
+    rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
+    mask = None
+    if mask_path is not None:
+        mask = load_image(mask_path, settings, flags=cv2.IMREAD_GRAYSCALE) > 127
+        if mask.shape != rgb.shape[:2]:
+            raise InputValidationError("Mask size must match the image size.")
+
+    depth = predict_depth(rgb, model=model, device=device, settings=settings)
+    out_dir = prepare_output_dir(output_dir)
+    stem = Path(image_path).stem
+
+    png = save_image(
+        (_normalize(depth) * 65535).astype(np.uint16),
+        out_dir / f"{stem}_depth.png",
+        overwrite=overwrite,
+    )
+    npy = prepare_output_file(
+        out_dir / f"{stem}_depth.npy", allowed_extensions={".npy"}, overwrite=overwrite
+    )
+    np.save(npy, depth.astype(np.float32), allow_pickle=False)
+
+    mesh_path: str | None = None
+    faces: int | None = None
+    if make_mesh:
+        mode, _ = ALLOWED_MODELS[model]
+        mesh = depth_to_mesh(depth, rgb, mode=mode, fov_deg=fov_deg, stride=stride, mask=mask)
+        mesh_path = str(save_mesh(mesh, out_dir / f"{stem}_depth_mesh.ply", overwrite=overwrite))
+        faces = len(mesh.faces)
+
+    h, w = depth.shape
+    return DepthResult(
+        depth_png_path=str(png),
+        depth_npy_path=str(npy),
+        mesh_path=mesh_path,
+        model=model,
+        model_license=ALLOWED_MODELS[model][1],
+        width=w,
+        height=h,
+        mesh_faces=faces,
+    )