/writing-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: writing-attributes
description: >
  Writing scalar and array attribute data to prims. Use when user asks to write an
  attribute, set a property, change a material, set a color, or modify mesh data.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - attributes
  - writing
tools:
  - Read
  - Grep

Writing Attributes

When to Use

Use this skill when the user asks to write an attribute, set a property, change a material, set a color, or modify mesh data.

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.
• Prim paths, attribute name, USD value type, scalar versus array shape, and desired values.
• Data source location, dtype, semantic conversion, ordinal, and write-floor publication.
• Whether the write is one-shot, repeated with a stable target, or needs direct mapped-buffer access.
• 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 `attribute-bindings` for repeated writes to the same prims/attribute, and `mapping-attributes` for zero-copy direct writes.
• Use `binding-materials` when the request is specifically to set `material:binding`.

Instructions

1. Identify the target language, prim paths, attribute name, value kind, data shape, 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. Choose an explicit ordinal satisfying the configured ovstage admission policy and applicable floors. Under the `STRICTLY_INCREASING` policy, rewriting a cell needs a newer ordinal than its retained committed changes even before sealing; disjoint cells may share an ordinal. Wait for the ovstage write to succeed, then advance and wait for the write floor before rendering its ordinal; preserve C compatibility lifetimes when maintaining C code. See the [admission-policy summary](../../docs/core/ovstage_integration.rst#ordinals-and-write-floor-gates). 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 writes retain their documented unsupported-type limits for string arrays, asset arrays, and timecode attributes.
• For ovstage token and path values, intern IDs through `ovstage.PathDictionary` and use the matching `AttributeSemantic`.
• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

Beyond transforms, ovstage can write arbitrary attributes to prims: colors, visibility, mesh geometry, string tokens, and more. The DLTensor dtype must exactly match the USD attribute schema.

There are two categories:

• **Scalar attributes** -- one value per prim (e.g., a color, a transform)
• **Array attributes** -- variable-length per prim (e.g., mesh points, face vertex counts)

Tensor layout

Ovstage Python and the C compatibility API use lane-based DLTensor attribute layouts.

Python ovstage — lane-based attributes

Scalar values can use NumPy arrays directly. For vectors and matrices, wrap NumPy storage with `ovstage.make_dltensor`, set the logical element count in `shape`, and set the component count in `dtype.lanes`:

| USD type | NumPy storage | ovstage DLTensor | |---|---|---| | `int` / `float` scalar for N prims | `(N,)` | `shape=[N]`, lanes 1 | | `float3` / `point3f` scalar for N prims | `(N, 3)` | `shape=[N]`, lanes 3 | | `float4` / `color4f` scalar for N prims | `(N, 4)` | `shape=[N]`, lanes 4 | | 4x4 matrix for N prims | `(N, 4, 4)` | `shape=[N]`, lanes 16 | | `int[]` array with M elements on one prim | `(M,)` | `shape=[M]`, lanes 1 | | `float3[]` / `point3f[]` with M elements on one prim | `(M, 3)` | `shape=[M]`, lanes 3 |

> **Source:** `tests/docs/python/test_attribute_shapes.py` snippets `doc-shape-scalar-int32`, `doc-shape-float3-array`, `doc-shape-mat4-array`.

C — lane-based attributes

The C API accepts `DLDataType::lanes` for multi-component writes; shape-based scalar-lane writes are also accepted. Raw reads return scalar lanes with trailing component dimensions. This table describes canonical write input:

| USD type | C DLTensor shape | C `DLDataType` | |---|---|---| | `int` / `float` scalar for N prims | `[N]` | `{kDLInt/kDLFloat, bits, 1}` | | `float3` / `point3f` scalar for N prims | `[N]` | `{kDLFloat, 32, 3}` | | 4x4 double matrix for N prims | `[N]` | `{kDLFloat, 64, 16}` | | `int[]` array with M elements on one prim | `[M]` | `{kDLInt, 32, 1}` | | `float3[]` / `point3f[]` with M elements on one prim | `[M]` | `{kDLFloat, 32, 3}` |

> **Source:** `tests/docs/c/test_attribute_shapes.cpp` snippets `doc-shape-scalar-int32-c`, `doc-shape-float3-array-c`, `doc-shape-mat4-array-c`.

For a C `point3f[]` attribute with 10 points, write one tensor with `shape