simready-thumbnail 2026.8.0__py3-none-any.whl

simready/thumbnail/__init__.py

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SimReady USD thumbnail generation.
+
+``_cli``, ``_ovrtx_worker``, and ``review_stage`` are deliberately not imported
+here: the worker pulls in ovrtx, ovstage, numpy and Pillow, and importing this
+package must stay cheap for callers that only need path resolution or backend
+selection.
+"""
+
+from .backends import (
+    CAPTURE_CMD_REJECTED,
+    CAPTURE_FAILED,
+    CAPTURE_HARNESS_MISSING,
+    CAPTURE_KIT_MISSING,
+    CAPTURE_PATH_FAILED,
+    CAPTURE_SKIPPED,
+    KitSubprocessBackend,
+    OvRtxSubprocessBackend,
+    RenderBackend,
+    ThumbnailBackendKind,
+    ThumbnailBackgroundPreset,
+    build_kit_capture_command,
+    build_ovrtx_capture_command,
+    create_render_backend,
+    default_ovrtx_harness_argv,
+    default_ovrtx_run_command,
+    resolve_kit_executable,
+)
+from .layout import (
+    DEFAULT_THUMBNAIL_FILL_PERCENT,
+    DEFAULT_THUMBNAIL_HEIGHT,
+    DEFAULT_THUMBNAIL_WIDTH,
+    ThumbnailLayout,
+    capture_output_paths,
+    manifest_capture_paths,
+    resolve_output_path,
+    validate_thumbnail_fill_percent,
+)
+from .thumbnail_gen import (
+    OverwritePolicy,
+    ThumbnailGenerator,
+    ThumbnailResult,
+    ThumbnailSpec,
+    ThumbnailStatus,
+    generate_thumbnails_for_asset_paths,
+    run_manifest_capture,
+    run_manifest_capture_all_backgrounds,
+)
+from .usd_setup import (
+    DEFAULT_THUMBNAIL_SETUP_PATH,
+    resolve_thumbnail_setup_path,
+)
+
+# Configure the SimReady log file (raise the "simready" logger to INFO + install
+# the capture-all file sink). Best-effort so a missing/old logging package can't
+# break this import.
+try:
+    import simready.logging
+
+    simready.logging.init_log_file()
+except Exception:
+    pass
+
+__all__ = [
+    "CAPTURE_CMD_REJECTED",
+    "CAPTURE_FAILED",
+    "CAPTURE_HARNESS_MISSING",
+    "CAPTURE_KIT_MISSING",
+    "CAPTURE_PATH_FAILED",
+    "CAPTURE_SKIPPED",
+    "DEFAULT_THUMBNAIL_FILL_PERCENT",
+    "DEFAULT_THUMBNAIL_HEIGHT",
+    "DEFAULT_THUMBNAIL_SETUP_PATH",
+    "DEFAULT_THUMBNAIL_WIDTH",
+    "KitSubprocessBackend",
+    "OvRtxSubprocessBackend",
+    "OverwritePolicy",
+    "RenderBackend",
+    "ThumbnailBackendKind",
+    "ThumbnailBackgroundPreset",
+    "ThumbnailGenerator",
+    "ThumbnailLayout",
+    "ThumbnailResult",
+    "ThumbnailSpec",
+    "ThumbnailStatus",
+    "build_kit_capture_command",
+    "build_ovrtx_capture_command",
+    "capture_output_paths",
+    "create_render_backend",
+    "default_ovrtx_harness_argv",
+    "default_ovrtx_run_command",
+    "generate_thumbnails_for_asset_paths",
+    "manifest_capture_paths",
+    "resolve_kit_executable",
+    "resolve_output_path",
+    "resolve_thumbnail_setup_path",
+    "run_manifest_capture",
+    "run_manifest_capture_all_backgrounds",
+    "validate_thumbnail_fill_percent",
+]

simready/thumbnail/_cli.py

@@ -0,0 +1,223 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""CLI entry point for simready-thumbnail."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import subprocess
+import sys
+from typing import List
+
+from .backends import (
+    CAPTURE_SKIPPED,
+    ThumbnailBackendKind,
+    ThumbnailBackgroundPreset,
+    default_ovrtx_harness_argv,
+    default_ovrtx_run_command,
+)
+from .layout import (
+    CLI_THUMBNAIL_LAYOUTS,
+    DEFAULT_THUMBNAIL_FILL_PERCENT,
+    ThumbnailLayout,
+    validate_thumbnail_fill_percent,
+)
+
+_BACKGROUND_ALL = "all"
+_BACKGROUND_CHOICES = [preset.value for preset in ThumbnailBackgroundPreset] + [_BACKGROUND_ALL]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="simready-thumbnail",
+        description="Generate SimReady USD thumbnail PNGs via a subprocess render backend.",
+    )
+    parser.add_argument(
+        "usd_path",
+        nargs="?",
+        help="Path to a SimReady USD asset",
+    )
+    parser.add_argument(
+        "--backend",
+        choices=[kind.value for kind in ThumbnailBackendKind],
+        default=ThumbnailBackendKind.OVRTX.value,
+        help="Subprocess render backend (default: ovrtx)",
+    )
+    parser.add_argument(
+        "--kit-exe",
+        dest="kit_exe",
+        required=False,
+        help="Path to kit.exe, or to a workspace launcher whose build tree contains it "
+        "(required when --backend=kit)",
+    )
+    parser.add_argument(
+        "--ovrtx-exe",
+        dest="ovrtx_exe",
+        required=False,
+        help="Path to an OVRTX capture harness executable (optional when --backend=ovrtx; "
+        "defaults to the in-tree python -m simready.thumbnail._ovrtx_worker worker)",
+    )
+    parser.add_argument(
+        "--fill",
+        dest="target_fill_percent",
+        type=float,
+        default=DEFAULT_THUMBNAIL_FILL_PERCENT,
+        metavar="PERCENT (1-90)",
+        help=(
+            "Target asset fill on the limiting frame axis, 1-90 (%%) " f"(default: {DEFAULT_THUMBNAIL_FILL_PERCENT})"
+        ),
+    )
+    parser.add_argument(
+        "--usd-setup",
+        dest="usd_setup",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Thumbnail setup USD layer with ThumbnailLighting + optional "
+            "ThumbnailCamera. Must have defaultPrim ThumbnailSetup; "
+            "omit to use the packaged default USDA."
+        ),
+    )
+    parser.add_argument(
+        "--layout",
+        choices=[layout.value for layout in CLI_THUMBNAIL_LAYOUTS],
+        default=ThumbnailLayout.NUCLEUS.value,
+        help=(
+            "Output path convention (default: nucleus). "
+            "nucleus: .thumbs/256x256/{usd_filename}.png (dark) and "
+            "{usd_filename}_{light|transparent}.png for the other backgrounds; "
+            "manifest: .thumbs/{stem}_thumbnail.png (dark) and "
+            "{stem}_thumbnail_{light|transparent}.png for the other backgrounds"
+        ),
+    )
+    parser.add_argument(
+        "--background",
+        choices=_BACKGROUND_CHOICES,
+        default=ThumbnailBackgroundPreset.DARK.value,
+        help=(
+            "Background: dark (#1A1A1A), light (#F0F0F0), transparent RGBA, or all "
+            "(dark+light+transparent; default: dark if omitted)"
+        ),
+    )
+    parser.add_argument(
+        "-V",
+        "--show-version",
+        action="store_true",
+        help="Print version and exit",
+    )
+    return parser
+
+
+def _default_run_command(cmd: List[str]) -> int:
+    completed = subprocess.run(cmd, check=False)
+    return int(completed.returncode)
+
+
+def _init_console_logging() -> None:
+    """Echo SimReady logs to the console, as logs.py prescribes for standalone CLIs.
+
+    ``simready.logging`` is an optional dependency, so when it is missing or too
+    old this degrades to a stdlib stderr handler rather than going silent: the
+    logger is this CLI's only output channel. Console output goes to stderr so
+    stdout stays reserved for machine-readable output such as ``-V``.
+    """
+    try:
+        import simready.logging
+
+        simready.logging.init_console_streaming()
+        return
+    except Exception:
+        pass
+
+    logger = logging.getLogger("simready")
+    logger.setLevel(logging.INFO)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+        logger.addHandler(handler)
+
+
+def main(argv: list[str] | None = None) -> int:
+    _init_console_logging()
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.show_version:
+        try:
+            from importlib.metadata import version
+
+            print(version("simready.thumbnail"))
+        except Exception:
+            print("simready.thumbnail (dev)")
+        return 0
+
+    if not args.usd_path:
+        parser.error("usd_path is required unless --show-version is passed")
+
+    try:
+        target_fill_percent = validate_thumbnail_fill_percent(args.target_fill_percent)
+    except ValueError as exc:
+        parser.error(str(exc))
+
+    backend = ThumbnailBackendKind(args.backend)
+    ovrtx_harness_argv = None
+    harness_exe = ""
+
+    if backend == ThumbnailBackendKind.KIT:
+        if not args.kit_exe:
+            parser.error("--kit-exe is required when --backend=kit")
+        harness_exe = args.kit_exe
+    else:
+        if args.ovrtx_exe:
+            harness_exe = args.ovrtx_exe
+        else:
+            ovrtx_harness_argv = default_ovrtx_harness_argv()
+            harness_exe = ovrtx_harness_argv[0]
+
+    from .thumbnail_gen import run_manifest_capture, run_manifest_capture_all_backgrounds
+
+    run_command = _default_run_command
+    if backend == ThumbnailBackendKind.OVRTX and ovrtx_harness_argv is not None:
+        run_command = default_ovrtx_run_command
+
+    common_kwargs = dict(
+        backend=backend,
+        ovrtx_harness_argv=ovrtx_harness_argv,
+        target_fill_percent=target_fill_percent,
+        usd_setup_path=args.usd_setup,
+        layout=ThumbnailLayout(args.layout),
+        run_command=run_command,
+    )
+
+    if args.background == _BACKGROUND_ALL:
+        return run_manifest_capture_all_backgrounds(
+            harness_exe,
+            args.usd_path,
+            **common_kwargs,
+        )
+
+    rc = run_manifest_capture(
+        harness_exe,
+        args.usd_path,
+        background_preset=ThumbnailBackgroundPreset(args.background),
+        **common_kwargs,
+    )
+    return 0 if rc == CAPTURE_SKIPPED else rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simready/thumbnail/_kit_worker.py

@@ -0,0 +1,168 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Direct Kit thumbnail worker injected with ``--exec``."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import carb
+import carb.settings
+import omni.kit.app
+import omni.usd
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+for _root in (_PACKAGE_DIR.parent, _PACKAGE_DIR.parent.parent):
+    if str(_root) not in sys.path:
+        sys.path.insert(0, str(_root))
+
+
+_SETTLE_FRAMES = 64  # MDL warmup frames; the capture extension caps this at 64
+
+# Kit's pathtracer renders this asset class without its normal-map relief, whatever
+# the sample count, denoiser, mip and upscaler settings; RaytracedLighting keeps it,
+# and is also what the OVRTX worker's renderer runs. Overridable for diagnostics.
+_DEFAULT_RENDER_MODE = "realtime"
+
+
+def _thumbnail_modules():
+    try:
+        from thumbnail.backends import CAPTURE_FAILED, ThumbnailBackgroundPreset, unpack_open_stage_result
+        from thumbnail.review_stage import _prepare_review_stage, _rgba_from_solid_plate
+    except ImportError:
+        from simready.thumbnail.backends import CAPTURE_FAILED, ThumbnailBackgroundPreset, unpack_open_stage_result
+        from simready.thumbnail.review_stage import _prepare_review_stage, _rgba_from_solid_plate
+    return (
+        CAPTURE_FAILED,
+        ThumbnailBackgroundPreset,
+        unpack_open_stage_result,
+        _prepare_review_stage,
+        _rgba_from_solid_plate,
+    )
+
+
+def _apply_render_settings(settings) -> None:
+    """Render config the bare Kit binary does not get from an app .kit file."""
+    settings.set("/rtx/hydra/engine", "rtx")
+    settings.set_bool("/rtx/mdl/materialLoading/enabled", True)
+    settings.set_bool("/app/asyncRendering", False)
+    # A material still compiling at capture time renders as untextured plastic.
+    settings.set_bool("/rtx/materialDb/syncLoads", True)
+
+
+def _setting(name: str, default=None):
+    value = carb.settings.get_settings().get(f"/simready/thumbnail/{name}")
+    return default if value in (None, "") else value
+
+
+async def _capture() -> int:
+    CAPTURE_FAILED, BackgroundPreset, unpack_open_stage_result, prepare_review_stage, rgba_from_solid_plate = (
+        _thumbnail_modules()
+    )
+    asset_raw = str(_setting("assetPath", ""))
+    output_raw = str(_setting("outputPath", ""))
+    asset_path = Path(asset_raw)
+    output_path = Path(output_raw)
+    width = int(_setting("width", 1024))
+    height = int(_setting("height", 1024))
+    target_fill = float(_setting("targetFillPercent", 90))
+    background = BackgroundPreset(str(_setting("background", "dark")))
+    setup_raw = str(_setting("usdSetupPath", ""))
+    setup_path = setup_raw or None
+    render_mode = str(_setting("renderMode", _DEFAULT_RENDER_MODE))
+
+    if not asset_raw or not asset_path.is_file() or not output_raw:
+        carb.log_error(f"Invalid thumbnail paths: asset={asset_path}, output={output_path}")
+        return CAPTURE_FAILED
+
+    prepared = prepare_review_stage(
+        asset_path,
+        width,
+        height,
+        target_fill,
+        background,
+        usd_setup_path=setup_path,
+        include_asset_reference=True,
+        log_prefix="Kit",
+    )
+    if prepared is None:
+        return CAPTURE_FAILED
+    review_layer, camera_path, ground_free, bg_display = prepared
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    stage_path = output_path.with_suffix(".thumbnail_review.usda")
+    stage_path.write_text(review_layer, encoding="utf-8")
+
+    try:
+        context = omni.usd.get_context()
+        ok, open_error = unpack_open_stage_result(await context.open_stage_async(stage_path.as_posix()))
+        if not ok:
+            carb.log_error(f"Could not open thumbnail review stage: {stage_path} ({open_error})")
+            return CAPTURE_FAILED
+
+        import omni.simready.viewport_capture as viewport_capture
+
+        api = viewport_capture.get_viewport_capture_api()
+        _apply_render_settings(carb.settings.get_settings())
+
+        success = await api.capture_thumbnail(
+            output_path=output_path.as_posix(),
+            camera_path=camera_path,
+            render_mode=render_mode,
+            width=width,
+            height=height,
+            settle_frames_override=_SETTLE_FRAMES,
+        )
+        if not success:
+            return CAPTURE_FAILED
+
+        if ground_free:
+            import numpy as np
+            from PIL import Image
+
+            rgb = np.asarray(Image.open(output_path).convert("RGB"))
+            rgba = rgba_from_solid_plate(np, rgb, bg_display)
+            Image.fromarray(rgba, mode="RGBA").save(output_path, format="PNG")
+        return 0
+    except Exception as exc:
+        carb.log_error(f"Direct Kit thumbnail capture failed: {exc}")
+        return CAPTURE_FAILED
+    finally:
+        try:
+            stage_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def main() -> int:
+    app = omni.kit.app.get_app()
+    task = asyncio.ensure_future(_capture())
+    while not task.done():
+        app.update()
+    if task.exception():
+        raise task.exception()
+    return int(task.result())
+
+
+try:
+    _exit_code = main()
+except Exception as _exc:
+    carb.log_error(f"Kit thumbnail worker failed: {_exc}")
+    _exit_code = -5
+
+omni.kit.app.get_app().post_quit(_exit_code)