Reading Attributes

Reading Attributes

When to Use

Use this skill when the user asks to read an attribute value, fetch mesh data (points, faceVertexCounts, etc.), inspect a render setting, or sample transforms.

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.
• Reusable ovstage query, interned attribute token, expected USD value type, and scalar versus array read mode.
• Target consumer: CPU NumPy, C DLTensor, GPU-aware DLPack consumer, or metadata/schema inspection.
• Whether the caller needs raw storage, shape/dtype discovery, or values copied out for later use.
• 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.
• Use stage-queries first if the user needs to discover prims or attribute schemas before reading values.

Instructions

1. Identify the target language, prim paths or prim-list handle, attribute name, scalar/array mode, memory target, and sync/async requirement.
2. Read the matching source snippet and copy its lifecycle pattern rather than inventing equivalent calls.
3. Validate dtype, shape, semantic, and ownership rules before proposing or editing code.
4. Release each fetched ovstage group and read/query handle according to the referenced examples; preserve C compatibility lifetimes when maintaining C code.
5. When changing code, run the narrow docs test or example 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

• Deprecated ovrtx compatibility reads retain their documented unsupported-type limits for string arrays, asset arrays, and timecode attributes.
• The OVRTX_SEMANTIC_NONE restriction applies only to deprecated ovrtx compatibility reads.
• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

stage.read_attributes reads one or more requested attribute columns through an ovstage query. Fetch each result group, consume its DLPack tensors, then release the group and read handle.

Use ovstage.OrdinalRange.latest(ordinal) to read the latest committed values visible at an ordinal.

For mapping (zero-copy writes into ovstage buffers), see the mapping-attributes skill.

USD Type Lookup

Use this table to answer "how do I read USD type X?" Ovstage uses stage.read_attributes for both scalar and array-valued columns; inspect each group's is_array flag. Deprecated C bindings set binding.binding_desc.attribute_type.is_array = true for array reads. Python exposes shape dimensions; C uses DLDataType::lanes.

Python

Scalar read

Returns a ManagedDLTensor with shape (N,) for N input prims. Convert with np.from_dlpack() for a zero-copy numpy view.

Source: tests/docs/python/test_attribute_read.py snippet doc-read-attribute-scalar

Deprecated compatibility: scalar read into a destination

Pass dest= with a DLPack-compatible tensor (NumPy array, Warp array, etc.). The read writes directly into dest; the returned tensor aliases the same memory. The dest dtype must match how the runtime stores the attribute.

Source: tests/docs/python/test_attribute_read.py snippet doc-read-attribute-dest-tensor

Array read

Fetch the array-valued group, copy or consume its DLPack tensor, and release the group.

Source: tests/docs/python/test_attribute_read.py snippet doc-read-array-attribute

Async read

Wait for the ovstage read handle, fetch groups, then release each group and the read handle.

Source: tests/docs/python/test_attribute_read.py snippet doc-read-attribute-async

Deprecated compatibility: GPU destination (CUDA)

Allocate the destination on the GPU via any DLPack-compatible allocator (e.g. Warp). Pass the CUDA stream handle so the read is stream-ordered with your GPU work.

Source: tests/docs/python/test_attribute_read.py snippet doc-read-attribute-cuda-dest

Authored attribute matrix

Python raw snippets:

The snippets listed in this table live in tests/docs/python/test_all_attributes.py.

These examples use ovstage.PathDictionary to obtain attribute-name tokens, read through a reusable ovstage query, copy each returned tensor, and release its result group.

Local and world-space extents

extent is the authored local-space extent. _worldExtent is populated as the transformed world-space extent.

Source: tests/docs/python/test_all_attributes.py snippet doc-extent-world-extent

C

Scalar read

Source: tests/docs/c/test_attribute_read.cpp snippet doc-read-attribute-scalar-c

Array read

Under ovstage, array-vs-scalar kind is not part of the read call — the read handle returns group.is_array reflecting the column's declared kind. Under the deprecated ovrtx_read_attribute compat shim, set binding.binding_desc.attribute_type.is_array = true explicitly (defaulted to false by ovrtx_make_binding_desc).

Source: tests/docs/c/test_attribute_read.cpp snippet doc-read-array-attribute-c

Supported authored attribute read snippets in C

The snippets below are ovstage-native: ovstage_read_attributes against a DocsQueryAndToken (single-prim query + interned attribute token), one ovstage_fetch_read_next per matched group, ovstage_release_group per group, then ovstage_release_read. Each snippet asserts group.data.tensor_count > 0 before dereferencing group.data.tensors[0].

C raw snippets:

The snippets listed in this table live in tests/docs/c/test_all_attributes.cpp.

C token snippets include path-dictionary resolution because the C API exposes ovstage_get_path_dictionary(). As of ovstage 0.2, reading a scalar asset returns ASSET_PATH_ID token id pairs ({kDLUInt, 64, 2}, is_array=false, one (authored, resolved) pair per prim). Resolve both ids through the path dictionary. A resolved id of 0 is the empty token, which means the path resolved to nothing. On ovstage 0.1.x the same read returned {kDLUInt, 64, 2} pairs with semantic NONE, and on 0.1.0 single-prim reads failed with END_OF_ITERATION. The doc-read-usd-asset-c / doc-write-usd-asset-c snippets are runtime-validated by AllAttributesTest.AssetReadWriteSnippets.

Local and world-space extents in C

Source: tests/docs/c/test_all_attributes.cpp snippet doc-extent-world-extent-c

Key Types / Functions

Ovstage C result layout (ovstage_read_group_t):

• .is_array — array vs scalar kind, matches the write-side declaration.
• .data.tensors / .data.tensor_count — DLTensor array. tensor_count==1 under the packed-uniform layout every snippet uses; always assert tensor_count > 0 before dereferencing tensors[0].
• Each DLTensor in the group: shape=[prim_count] for scalar reads and shape=[element_count] for array reads, with dtype.lanes carrying the tuple width (matrix4d → {kDLFloat, 64, 16}, point3f → {kDLFloat, 32, 3}, etc.).
• .prims.list / .prims.count / .prims.offset / .prims.index_map — enumerate the matched prims via the group's prim list; index_map applies gather/reorder semantics.
• .attribute — the token that identifies which of the caller's requested attributes this group corresponds to. Route multi-attribute reads (e.g. doc-extent-world-extent-c) by comparing to the interned tokens. One token can yield more than one group: when the queried prims use the name for several column types and no ovstage write has given the name an identity, each prim is served with the type of its own column, so the groups differ in dtype and is_array. Read the shape off each group rather than off the first one. Such a name cannot be served to a GPU destination, so a device read returns no group for it and serves the rest of the read normally (ovstage >= 0.2).

Deprecated C compat result layout (ovrtx_read_output_t):

• Scalar reads: buffer_count == 1, single tensor with shape [prim_count].
• Array reads: buffer_count == prim_count, one tensor per prim (variable length).
• When a caller-supplied read_dest tensor was passed in: buffer_count == 0 (data landed in your tensor).

Troubleshooting

• Ovstage reads carry the schema semantic; ovrtx compat reads do not. ovrtx_read_attribute rejects any semantic other than OVRTX_SEMANTIC_NONE. ovstage_read_attributes reads the column at whatever semantic it was created with, so the caller does not pass a semantic on read — the returned DLTensor dtype code/bits/lanes are the authoritative shape.
• Generic authored USD attributes require opt-in population. Root-layer customLayerData.populateAllAuthoredAttributes = true asks the runtime to populate authored attributes beyond the normal schema set. Use it only when needed: populating everything can dramatically increase memory usage on assets with many unused properties. See loading-usd for the layer metadata tradeoff.
• Schema-owned attributes fix the element type. omni:rtx:rtpt:maxBounces is stored as uint32 even if you wrote it as int32. When allocating a dest tensor, match the runtime's dtype (np.uint32) — not what you wrote.
• Release fetched ovstage groups explicitly. Call stage.release_group(group) after consuming or copying each group, and release manually managed read/query handles.
• Ovstage reads carry array-vs-scalar kind in the returned group, not the request. Check group.is_array after ovstage_fetch_read_next — the read call itself takes no is_array parameter. The deprecated ovrtx_read_attribute compat shim still requires binding.binding_desc.attribute_type.is_array = true on the binding (defaulted to false by ovrtx_make_binding_desc).
• Ovstage queries own their prim-list storage; ovrtx compat bindings borrow. ovstage_query_from_path_list retains a reference to the passed ovx_primpath_list_t until ovstage_release_query fires — the caller then calls path_dictionary_release_path_list_reference. The deprecated ovrtx_make_binding_desc stores the ovx_string_t* prim path array you pass without copying; keep it alive until the read has been enqueued, waited, fetched, and released.
• Unsupported authored types are tested as absent. tests/docs/data/all-attributes.usda deliberately authors string[], asset[], custom relationships, timecode, and timecode[]; the all-attributes tests assert they are not populated by the current runtime.

Deprecated Standalone APIs

The renderer attribute-read APIs in this skill are deprecated in 0.4 and retained for compatibility. New code should read through an ovstage query, consume fetched groups, and release each group and read handle according to ovstage ownership rules.

See docs/core/ovstage_integration.rst, skills/update-0_3-0_4-c/SKILL.md and skills/update-0_3-0_4-python/SKILL.md.

Related skills

• stage-queries — discover prims and their attribute schemas before reading.
• writing-attributes — write values that can then be read back.
• mapping-attributes — zero-copy mapping (no fetch step).
• async-operations — polling, timeouts, the two-phase Operation/PendingFetch lifecycle.

References

• Use the > **Source:** directives in this skill to locate tested snippets before reusing API patterns.
• Keep related skills, docs, and snippets synchronized when changing the workflow.