/stepping-and-rendering

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: stepping-and-rendering
description: >
  Running a simulation step to produce rendered frames. Use when user asks to render a
  frame, step the renderer, simulate a sensor, or get an image from ovrtx.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - rendering
  - stepping
tools:
  - Read
  - Grep

Stepping and Rendering

When to Use

Use this skill when the user asks to render a frame, step the renderer, simulate a sensor, or get an image from ovrtx.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, or both.
• Application lifecycle stage: renderer creation, scene loading, stepping, warmup, output readback, or cleanup.
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant `> **Source:**` snippet before writing or explaining API usage.
• For code changes, preserve renderer lifecycle ordering and cleanup semantics for the selected language.

Instructions

1. Identify the requested language and lifecycle stage before choosing an example. 2. Read the referenced snippet that matches the requested stage and language. 3. Preserve the normal ovrtx order: create or initialize the renderer, load or compose USD, step or wait for work, read outputs when needed, then release C resources explicitly. 4. Apply the async, status-query, error-handling, and warmup skills when the workflow crosses those concerns. 5. When changing code, run the narrow example or docs test that owns the snippet whenever practical.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

After loading USD content, you render frames by calling `step()`. Each step advances the simulation by `delta_time` and produces output for the specified render products (cameras/sensors). The result contains a hierarchy of products, frames, and render variables that can be mapped to access pixel data.

Simulation time vs. USD time

ovrtx tracks **two independent clocks** — a frequent point of confusion:

| Clock | Unit | Advanced by | Drives | |-------|------|-------------|--------| | **Simulation time** | seconds | `step(products, delta_time)` (accumulates); `reset(time)` | sensor timing — motion blur, lidar/radar scan, `TimeOffsetNs` | | **USD time** | **timecodes** (converted from seconds via `timeCodesPerSecond`) | `update_from_usd_time(seconds)` (see `loading-usd`) | time-sampled attributes — animated transforms, visibility, ... |

`step()` does **not** advance USD animation, and `update_from_usd_time()` does **not** advance the simulation/sensor clock. To render an animated frame at time *t*: call `update_from_usd_time(t)` first, then `step(...)`. `reset(time)` resets simulation time only (not USD time, and distinct from `reset_stage()`). Remember `update_from_usd_time` takes **seconds**, not timecodes — see `loading-usd` for the `timeCodesPerSecond` conversion.

Step window vs. frame capture time

`reset(time=T)` re-bases the clock so the next `step(dt)` simulates `[T, T + dt]`; it does not emit a frame at `T`.

Python exposes both:

| Field | Where | Meaning after `reset(T)` + `step(dt)` | |-------|-------|----------------------------------------| | `RenderProductSetOutputs.simulation_start_time` | step result | `T` — the step clock base | | `RenderProductSetOutputs.simulation_end_time` | step result | `T + dt` | | `FrameOutput.start_time` / `end_time` | per frame | capture or split interval; an accumulated capture can start before `T` |

A default viewport camera captures instantaneously at the *end* of the step window, so its `FrameOutput.start_time` is `T + dt`, not `T`. That is expected, not a clock bug — assert `products.simulation_start_time` when checking the clock base.

Python

Single frame

> **Source:** `examples/python/minimal/main.py` snippet `step` > > **Source (local-scene example):** `examples/python/projectors/main.py` snippet `projectors-render`

Iterate over results

> **Source:** `examples/python/minimal/main.py` snippet `read-render-output`

Render loop

> **Source:** `tests/docs/python/test_camera_sensors.py` snippet `doc-step-and-map-camera-outputs`

Sensors with different capture rates

> **Source:** `examples/python/multi-rate-sensors/main.py` snippets `doc-multi-rate-step`, `doc-multi-rate-partial-outputs`, and `doc-multi-rate-read-outputs` > > **Source (C):** `tests/docs/c/test_sensor_configuration.cpp` snippets `doc-multi-rate-step-c` and `doc-multi-rate-partial-outputs-c`

Keep all active sensor RenderProducts in every step, including steps with no completed output. Omitting a product discards its accumulated rendering history. Apply `OmniSensorAPI` to scheduled cameras and author `omni:sensor:frameRate` as rational Hz. For compatibility with the pinned ovrtx 0.5 package, set the camera's `omni:sensor:Core:partialOutputs` through ovstage: its camera USD schemas do not declare this attribute, so an