Read ovphysx Simulation Output
Use the output-read API when results must retain ovstage prim identity, emitted
attribute tokens, and fixed/array column layout. TensorBindingsAPI is the route
for caller-owned bulk buffers; raycast, sweep, and overlap are geometry queries.
Workflow
Select the language branch and read its bundled reference:
- Python: Python output reads
- C: C query/read lifecycle
Read only the selected language reference. Select the simulated object type,
semantic attributes, ALL or ACTIVE scope, and destination. When selecting
ACTIVE or caching layout state, also read
Scope and layout constraints; support is
type-dependent and the current layout metadata is not an invalidation signal.
Complete when: the language, type, attributes, scope, and destination are
explicit.
Keep an ovstage Stage attached and alive. When attachment and process
lifecycle are not already established, invoke the basic-workflow skill by
name.
Complete when: the attached Stage owns the shared path dictionary for the
whole read.
Complete the simulation work whose output will be read. Use step_sync() /
ovphysx_step_sync(), or wait for the asynchronous step before opening the
read.
Complete when: the intended step has completed.
Open and drain the read exactly as the selected language reference describes.
A zero-object match is successful and yields no groups.
Complete when: every returned group is consumed and normal exhaustion is
distinguished from failure.
Consume each group according to its destination.
- For local Python inspection, retain the copied NumPy values.
- For native C inspection, copy values that must outlive the native group.
- For ovstage write-back, first read
Closed-loop ovstage write-back, then complete
the write while the group's identity and borrowed data remain valid.
Complete when: retained values are caller-owned, or the ovstage write has
completed before releasing its source group.
Release resources and validate the selected branch. Python uses the
ReadResult context manager. C releases every fetched group, then the read
and query handles on success and error paths. Exercise an integration test
that checks values and, for write-back, ordinal separation.
Complete when: no read resources remain live, supported ACTIVE reads are
reopened per frame, structural changes trigger fresh query and downstream
layout setup, and the test observes the expected output.
Shared Contracts
- Query by simulated type, not USD schema or prim-path pattern.
- Request semantic names such as
position, orientation,
linearVelocity, angularVelocity, jointPosition, jointVelocity,
points, or velocities.
- Treat a query as a lazy selector. A read observes the most recently completed
step, not a snapshot captured when the query was opened.
- Before using
ACTIVE or caching prim order and shapes, apply the bundled
scope and layout constraints. Do not assume
every object type filters ACTIVE, discovery counts always match an ACTIVE
read, or layout_generation changes after structural edits.
Installed API Sources
For the caller's installed ovphysx version, prefer:
- C SDK headers:
include/ovphysx/ovphysx.h and
include/ovphysx/ovphysx_types.h
- Python docstrings:
ovphysx.api.PhysX, ReadResult, and ReadGroup
The public release documentation starts at
https://nvidia-omniverse.github.io/PhysX/ovphysx/latest/index.html.
1---2name: ovphysx-output-read3description: Read ovphysx simulation output with the ovstage-native output-read API when results must retain ovstage identity or write back without rebuilding paths or repacking tensors. Covers Python `PhysX.read()` / `PhysX.read_tokens()`, C `ovphysx_query()` / `ovphysx_read()`, emitted attribute tokens, borrowed groups, and closed-loop physics-to-ovstage write-back.4---56# Read ovphysx Simulation Output78Use the output-read API when results must retain ovstage prim identity, emitted9attribute tokens, and fixed/array column layout. TensorBindingsAPI is the route10for caller-owned bulk buffers; raycast, sweep, and overlap are geometry queries.1112## Workflow13141. Select the language branch and read its bundled reference:1516 - Python: [Python output reads](references/python.md)17 - C: [C query/read lifecycle](references/c.md)1819 Read only the selected language reference. Select the simulated object type,20 semantic attributes, `ALL` or `ACTIVE` scope, and destination. When selecting21 `ACTIVE` or caching layout state, also read22 [Scope and layout constraints](references/scope_and_layout.md); support is23 type-dependent and the current layout metadata is not an invalidation signal.2425 **Complete when:** the language, type, attributes, scope, and destination are26 explicit.27282. Keep an ovstage Stage attached and alive. When attachment and process29 lifecycle are not already established, invoke the `basic-workflow` skill by30 name.3132 **Complete when:** the attached Stage owns the shared path dictionary for the33 whole read.34353. Complete the simulation work whose output will be read. Use `step_sync()` /36 `ovphysx_step_sync()`, or wait for the asynchronous step before opening the37 read.3839 **Complete when:** the intended step has completed.40414. Open and drain the read exactly as the selected language reference describes.42 A zero-object match is successful and yields no groups.4344 **Complete when:** every returned group is consumed and normal exhaustion is45 distinguished from failure.46475. Consume each group according to its destination.4849 - For local Python inspection, retain the copied NumPy values.50 - For native C inspection, copy values that must outlive the native group.51 - For ovstage write-back, first read52 [Closed-loop ovstage write-back](references/closed_loop.md), then complete53 the write while the group's identity and borrowed data remain valid.5455 **Complete when:** retained values are caller-owned, or the ovstage write has56 completed before releasing its source group.57586. Release resources and validate the selected branch. Python uses the59 `ReadResult` context manager. C releases every fetched group, then the read60 and query handles on success and error paths. Exercise an integration test61 that checks values and, for write-back, ordinal separation.6263 **Complete when:** no read resources remain live, supported `ACTIVE` reads are64 reopened per frame, structural changes trigger fresh query and downstream65 layout setup, and the test observes the expected output.6667## Shared Contracts6869- Query by simulated type, not USD schema or prim-path pattern.70- Request semantic names such as `position`, `orientation`,71 `linearVelocity`, `angularVelocity`, `jointPosition`, `jointVelocity`,72 `points`, or `velocities`.73- Treat a query as a lazy selector. A read observes the most recently completed74 step, not a snapshot captured when the query was opened.75- Before using `ACTIVE` or caching prim order and shapes, apply the bundled76 [scope and layout constraints](references/scope_and_layout.md). Do not assume77 every object type filters `ACTIVE`, discovery counts always match an `ACTIVE`78 read, or `layout_generation` changes after structural edits.7980## Installed API Sources8182For the caller's installed ovphysx version, prefer:8384- C SDK headers: `include/ovphysx/ovphysx.h` and85 `include/ovphysx/ovphysx_types.h`86- Python docstrings: `ovphysx.api.PhysX`, `ReadResult`, and `ReadGroup`8788The public release documentation starts at89<https://nvidia-omniverse.github.io/PhysX/ovphysx/latest/index.html>.
NVIDIA-Omniverse