Metadata-Version: 2.4
Name: simready-thumbnail
Version: 2026.8.0
Summary: SimReady USD thumbnail generation library
Author: NVIDIA Corporation
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.nvidia.com
Keywords: nvidia,simready,thumbnail,capture
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: usd-core>=22.11
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: ovrtx<0.5,>=0.4
Requires-Dist: ovstage<0.2,>=0.1.1
Dynamic: license-file

# simready.thumbnail

Standalone library for SimReady USD thumbnails. Default backend is OVRTX (GPU).
Kit is available with `--backend kit`.

## Quick start

```bash
pip install simready-thumbnail
simready-thumbnail "path/to/asset.usd"
simready-thumbnail "path/to/asset.usd" --background all
simready-thumbnail "path/to/asset.usd" --fill 80
simready-thumbnail "path/to/asset.usd" --layout manifest
simready-thumbnail "path/to/asset.usd" --backend kit --kit-exe /path/to/kit.exe
```

<!-- AUTOREMOVE: BEGIN -->
> `simready-thumbnail` is published to the internal artifactory only, so append
> `--extra-index-url https://urm.nvidia.com/artifactory/api/pypi/ct-omniverse-pypi-local/simple/`.
<!-- AUTOREMOVE: END -->

Default layout is `nucleus`. Use `--layout manifest` for Explorer names.
`--background` defaults to dark; `all` writes dark, light, and transparent.
`--fill` is 1–90 (default 90).

Output (next to the USD):

- `nucleus`: `.thumbs/256x256/{usd_filename}.png` (dark);
  `{usd_filename}_{light|transparent}.png` beside it
- `manifest`: `.thumbs/{stem}_thumbnail.png` (dark);
  `{stem}_thumbnail_{light|transparent}.png` for the other backgrounds

Existing thumbnails are skipped (CLI exits 0). Delete `.thumbs` to recapture.

`--kit-exe` must be `kit.exe`, not `workspace.bat` / `workspace.sh`.

Asset lights are ignored; lighting always comes from the setup layer.

Optional `--usd-setup PATH` replaces the packaged lighting/camera layer
(`defaultPrim` must be `ThumbnailSetup`). Copy the whole `data/` directory if
you customize it; the dark dome references `thumbnail_env_gradient.png`.

## Dependencies and licenses

The wheel declares the following external dependencies. Version constraints do
not specify exact installed versions.

| Dependency | Requirement | License |
|------------|-------------|---------|
| usd-core | `>=22.11` | Version-specific modified Apache terms; `LicenseRef-TOST-1.0` |
| numpy | Unpinned | BSD-3-Clause, plus bundled-component licenses |
| pillow | Unpinned | MIT-CMU, plus bundled-component licenses |
| ovrtx | `>=0.4,<0.5` | NVIDIA proprietary; NVIDIA Software License Agreement for 0.4.1.364340 |
| ovstage | `>=0.1.1,<0.2` | NVIDIA proprietary; NVIDIA Software License Agreement for 0.1.1.355824 |

These packages are installed separately and are not bundled in the thumbnail
wheel. Their licenses remain separate from thumbnail's Apache-2.0 license.
The license versions listed above identify inspected reference artifacts;
check the notices and applicable terms of the artifacts installed in your
environment.

USD and NumPy are imported in-process for stage preparation and calculations.
The OVRTX and Kit backends launch worker subprocesses. The OVRTX worker imports
Pillow, NumPy, ovrtx and ovstage; the Kit worker imports Pillow, NumPy and the
Kit-provided modules. USD runtimes provided by OVRTX or Kit are separate from
the `usd-core` package.

`simready.logging` is optional: the CLI and OVRTX worker fall back to standard
Python logging when it is unavailable. It is not included in the thumbnail
wheel.

The optional Kit backend requires an external Kit installation and the
`omni.simready.viewport_capture` extension. These are not included in the
thumbnail wheel. The extension requires `omni.usd`, `omni.kit.viewport.window`,
`omni.kit.viewport.utility`, `omni.hydra.rtx` and `omni.kit.commands`.

OVRTX is available from NVIDIA PyPI. Its first run can take minutes while
shaders compile; later runs reuse `ovrtx/bin/cache`.

## Contributing

This project is currently not accepting contributions.

## License

SimReady Thumbnail is distributed under Apache-2.0. The packaged
`thumbnail_env_gradient.png` is NVIDIA-authored and covered by the same license.
Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

External dependency packages retain their own licenses and notices.

## Common issues

| Issue | Fix |
|------|-----|
| `simready-thumbnail` not found | Activate the venv; reinstall the wheel |
| Exit `-2` | Missing `kit.exe` |
| Exit `-7` | OVRTX harness path is not a file |
| `No command provided. Usage: workspace <command>` | Pass `kit.exe`, not the launcher |
| Missing `ovrtx` / `ovstage` / `pxr` | Reinstall the wheel (NVIDIA PyPI if needed) |
| Asset looks unlit | Asset lights are off; use the packaged setup or `--usd-setup` |
