ovphysx-output-read

name	ovphysx-output-read
description	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.
compatibility	Requires ovphysx >=0.5.2 and an attached ovstage Stage; supports the Python wheel and C SDK.
metadata	{"author":"NVIDIA Omniverse Physics Team","version":"0.1.0","tags":"ovphysx, ovstage, physics-output, query-read"}

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

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.