/reading-attributes

# 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: reading-attributes
description: >
  Reading scalar or array attributes from prims into CPU or GPU tensors. Use when user
  asks to read an attribute value, fetch mesh data (points, faceVertexCounts, etc.),
  inspect a render setting, or sample transforms.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - attributes
  - reading
tools:
  - Read
  - Grep

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.
• Deprecated ovrtx compatibility reads reject write-only conversion semantics; a stored matrix role can still be returned as `OVRTX_SEMANTIC_MATRIX`.
• 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 a snapshot at a sealed ordinal. It returns `OUT_OF_RANGE` if a queried path of a requested attribute changed after that ordinal; use `(1 << 64) - 1` as the ordinal to read current values instead.

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. Read results in both languages use scalar lanes and trailing component dimensions; C binding types still use `DLDataType::lanes` to describe storage width.

| USD type(s) | Python read result | C binding dtype | Notes | |---|---|---|---| | `bool` / `bool[]` | `(N,)` or `(M,)`, `np.bool_` | `{kDLBool, 8, 1}` | | | `uchar` / `uchar[]` | `np.uint8` | `{kDLUInt, 8, 1}` | | | `int`, `int2`, `int3`, `int4` and arrays | `np.int32`, trailing shape `()`, `(2,)`, `(3,)`, `(4,)` | `{kDLInt, 32, lanes}` | | | `uint` / `uint[]` | `np.uint32` | `{kDLUInt, 32, 1}` | | | `int64` / `int64[]` | `np.int64` | `{kDLInt, 64, 1}` | | | `uint64` / `uint64[]` | `np.uint64` | `{kDLUInt, 64, 1}` | | | `half`, `half2`, `half3`, `half4` and arrays | `np.float16`, trailing shape by component count | `{kDLFloat, 16, lanes}` | | | `float`, `float2`, `float3`, `float4` and arrays | `np.float32`, trailing shape by component count | `{kDLFloat, 32, lanes}` | Authored scalar USD `float3` currently populates as zero; prefer role-bearing `point3f`, `normal3f`, `vector3f`, or `color3f` for values read from USD. | | `double`, `double2`, `double3`, `double4` and arrays | `np.float64`, trailing shape by component count | `{kDLFloat, 64, lanes}` | | | `point3*`, `normal3*`, `vector3*`, `color3*`, `color4*`, `texCoord2f` and arrays | numeric dtype by suffix (`h/f/d`), trailing role dimensions | same numeric dtype/lanes as storage | Roles are not surfaced as tensor metadata; they still matter for USD population and schema intent. | | `quat*` and arrays | numeric dtype by suffix, shape `(N, 4)` or `(M, 4)` | `{kDLFloat, bits, 4}` | Runtime component order is `(i, j, k, real)`, while USDA authoring order is `(real, i, j, k)`. | | `matrix2d`, `matrix3d`, `matrix4d`, `frame4d` and arrays | `np.float64`, matrix roles use square trailing dimensions; untyped tuples use flat component di