nvidia-omniverse/physx/ovphysx-output-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. The session write API (ovphysx_write / PhysX.write) is the route for pushing caller-owned bulk buffers in -- see the ovphysx-session-write skill (the deprecated tensor-binding API also covered this); raycast, sweep, and overlap are geometry queries.

The prim list and attribute token a result carries are interned handles, not paths or names. Resolve them through the attached Stage's dictionary: ovstage.PathDictionary(stage) or result.dictionary in Python — get_path_strings(group.prim_list) for the prim paths and token_to_string(group.attribute) for the emitted attribute name (C: ovstage_get_path_dictionary(stage) with path_dictionary_get_paths_from_path_list / path_dictionary_get_strings_from_tokens). See references/python.md or references/c_api.md for the selected language.

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.

1. Keep an ovstage Stage attached and alive. When attachment and process

lifecycle are not already established, invoke the ovphysx-basic-workflow skill by name.

Complete when: the attached Stage owns the shared path dictionary for the whole read.

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

1. Open and drain the read exactly as the selected language reference describes.

A zero-object match is successful and yields no groups. Request the optional read result (C ovphysx_read_result_t*, Python metadata=True) when the caller must tell an empty match from an unsupported or not-yet-ready attribute.

Complete when: every returned group is consumed and normal exhaustion is distinguished from failure.

1. Consume each group according to its destination.

• In Python, every non-empty numeric column is a borrowed warp.array on its

native CPU or CUDA device. Use it directly in Warp; call .numpy().copy() when a caller-owned host copy is actually needed. Building a CUDA group's arrays orders its producer event onto the Warp stream current at that point (inside read_sync(), or at the first wait() / result of a fetch_next() operation), so no manual wait or import-time negotiation is needed.

• For native C inspection, copy values that must outlive the read session.
• 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 data is a caller-owned copy, or the Warp arrays of a result not closed, or the ovstage write completed before releasing its source read session.

1. Release resources and validate the selected branch. Python closes the

ReadResult and any explicit Query with their context managers and collects the submitted releases with wait_all(); a closed result's arrays are invalid (a read_sync() result waits for the releases it submits on exit). 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: every retained array is a deliberate copy, or belongs to a result not closed and is dropped before PhysX.destroy(), 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

• Native query/read/write, fetch, commit and release operations return task

receipts. Check admission, wait for that receipt, then consume outputs. Fetch exhaustion is a successful wait with a null group. Copy task diagnostics before destroying wait-result storage. Python's default session calls return an Operation; wait() collects it and raises TaskError on failure, and read_sync() / read_tokens_sync() wait internally.

• Query by simulated type, not USD schema. To narrow a type to specific prims,

add a prim-set selection (C ovphysx_query_selection, Python prim_paths= / pattern=); it always covers the whole selected set, so it takes no scope.

• Request semantic names such as position, orientation,

linearVelocity, angularVelocity, linearAcceleration, angularAcceleration, jointPosition, jointVelocity, points, or velocities. Body properties (mass, inertia, centerOfMassPosition, disableGravity, ...) are also readable, but are always host-resident and the two flags are uint8 -- check dtype and device per tensor rather than assuming device-resident f32. Per-shape properties (contactOffset, staticFriction, ...) are padded to the widest selected object in the read; pair them with shapeCount to find where each row's real values stop.

• Rigid bodies and articulation links also serve read-only worldScale: the

signed world scale stored when the body was created (PhysX simulates no scale). It shares the pose's residency, so position, orientation and worldScale compose the world matrix on the same device. It has no point-instancer array form.

• Read isSleeping with ALL scope to inspect current rigid-body sleep state, including

sleepers. It is a read-only host uint8 scalar: 1 asleep, 0 awake. Articulation links report their owning articulation's state; no point-instancer array form exists. CPU and GPU-with-readback scenes report PhysX state, including kinematics and disabled bodies. Sleeping-disabled scenes, including DirectGPU, report 0 for emitted rows; DirectGPU still omits pre-step partitions and disabled rows. Use disableSimulation separately for participation. ACTIVE membership, zero velocity and the last wake command do not determine sleep state. Re-read for fresh values; copied arrays are snapshots.

• Deformable bodies serve points and velocities as device columns on a

DirectGPU scene, plus restPoints and the int32 simElementIndices (collisionElementIndices too, on the volume type only). The topology three are authored arrays with no device copy, so they arrive host-resident in the same read as the device points -- branch on device per tensor.

• Particle sets serve points (or positions) and velocities as device

columns, one array group per attribute carrying one tensor per set -- so walk tensor_count and pair each tensor with the prim at the same index, rather than assuming a group covers one set. points is prim-local and velocities is world, the same split deformables have. A read before the first step returns the authored positions. The type needs a CUDA context and emits nothing without one.

• Deformable materials are their own type, SimObjectType.DEFORMABLE_MATERIAL,

keyed by the bound Material prim: deformableDynamicFriction, deformableYoungsModulus, deformablePoissonsRatio, deformableElasticityDamping, and on surface materials only deformableBendingStiffness, deformableThickness and deformableBendingDamping. Those last three OMIT volume materials rather than reporting 0.0, so pair values with prims through the group's own prim list -- its row count can be smaller than the query's.

• Character controllers use SimObjectType.CHARACTER_CONTROLLER, keyed by the

capsule prim carrying PhysxCharacterControllerAPI. The type has no readable columns. Read the controller prim as RIGID_BODY position and orientation: the backing actor's global position and the controller prim's world orientation, with the capsule-axis correction applied. The pose updates on the step after move.

• SDF collision shapes use SimObjectType.SDF_SHAPE and have no readable

columns. Evaluate them with physx.evaluate_sdf_shapes(points, out, pattern=...): points [N, Q, 3] in mesh-local space, out [N, Q, 4] (gradient, then distance), float32 on the CUDA device, DirectGPU only. Row i is the i-th matched shape in pattern order.

• Deformable skin meshes are their own read-only type,

SimObjectType.DEFORMABLE_SKIN_MESH, keyed by the skinned render Mesh prim under a deformable body (volume or surface): one array group, one points tensor per skin mesh prim, skin-mesh-local and device-resident, ordered after the step's skinning through the group's completion event. points is the only attribute -- skinning produces no velocities -- and the skin prims exist in an ovstage instance only when the rendering domain was populated. To move a skin mesh, write the owning body's sim-mesh points; the skin follows.

• In ovphysx 0.6.0 and later, whole articulations use

SimObjectType.ARTICULATION and report the articulation-root API prim. They serve root pose/velocity as rootPosition, rootOrientation, rootLinearVelocity and rootAngularVelocity -- qualified because the row is keyed by the API prim, which may be an ancestor Xform rather than the root link -- plus centerOfMassWorld, centerOfMassLocal, and the padded per-shape set. rootPosition and world COM stay in scene world regardless of TensorBindings subspace roots; local COM uses the physical root link's center-of-mass (mass) frame. Root/COM columns follow the simulation device; shape columns remain on CPU.

• Articulation joints also serve the per-step control values

(jointPositionTarget, jointVelocityTarget, jointActuationForce, jointProjectedForce) and the authored DOF properties (jointStiffness, jointDamping, jointLimit, jointMaxVelocity, jointMaxForce, jointArmature, jointStaticFriction, jointDynamicFriction, jointViscousFriction, jointSpeedEffortGradient, jointMaxActuatorVelocity, jointVelocityDependentResistance, jointDriveType). The properties behave like body properties -- always host-resident, so one GPU read mixes devices -- and jointDriveType is uint8 (0 none, 1 force, 2 acceleration). jointLimit is one column of two lanes, (lower, upper), authored-order regardless of the joint's body order; an unset bound reads back as FLT_MAX rather than a converted number. Articulation links additionally serve linkIncomingJointForce, six lanes of force xyz then torque xyz.

• On an angular axis, the unit follows the QUANTITY, not just the axis:

coordinates and rates are degrees, gains and per-rate coefficients are per degree, and efforts, inertia and the drive type are unconverted. Do not apply a blanket radian conversion to a joint column.

• Whole articulations also serve jacobian, massMatrix, coriolisForce,

gravityForce and centroidalMomentum. Unlike every other column, each row's dimensions are tensor axes and dtype.lanes is 1: jacobian [N, R, C], massMatrix [N, M, M], the two force columns [N, M], centroidalMomentum [N, 6, numDofs + 7] with the bias in its last column. These groups cover topology-based subsets of a type's rows: the dimensions depend on each articulation's topology, so rows are split into cohorts of structurally identical articulations and each cohort is its own