OpenUSD

Attribute Value Types in OpenUSD

A reference for all the built in attribute types.

Ryan Stelzleni

— 3 min read
Share
Attribute Value Types in OpenUSD

OpenUSD Prims have Attributes and Primvars (a type of attribute), which contain values for that prim. These values can be things like points for a Mesh, or a texture path for a Shader. The types for that data are specified by the schema. For instance, Mesh points are stored as a point3f[].

You can also store any arbitrary data you need in an Attribute. Recently I needed to figure out what types are available for Attributes. Like, what is everything they could represent?

The answer is not super simple, and not the easiest thing to find in the USD source, so I thought I'd write this up in case it helps someone, or most likely, me in the future. Hello future me and future readers. Be careful on those hoverboards. 🛹

Attribute Type Names

There are 3 different ways that attribute types are named in USD source code and USD files. They all refer to the same underlying data. The types of names are:

  • C++/Python Source Code Type - For example, GfVec2f/Gf.Vec2ffor a 2 value floating point pair
  • Value Type Name - Found in SdfValueTypeNames/Sdf.ValueTypeNames, could be Float2 or TexCoord2f
  • usda text name - This is what you'll see in usda files, could be float2 or texCoord2f

Semantic Type Names

You'll notice that in Value Type Names we can refer to a 2 value float pair as a float2 or a texCoord2f. This is so we can provide a hint to readers as to the intended use for this 2 value float pair. I'll add Semantic Types sections to these tables to show all the possibilities for these.

Arrays

Most types can have an array form. In usda text this will add a [] to the type name, like float2[] or texCoord2f[]. The Value Type Name and source code names will have Array appended, like GfVec2fArray and Sdf.ValueTypeNames.TexCoord2fArray.

USD Attribute Types — Reference Table

Scalars

usda Sdf.ValueTypeNames C++ type notes
bool Bool bool
uchar UChar uint8_t Unsigned 8-bit. Useful for raw byte data
int Int int32_t
uint UInt uint32_t
int64 Int64 int64_t
uint64 UInt64 uint64_t
half Half GfHalf 16-bit float (IEEE 754)
float Float float 32-bit float
double Double double 64-bit float
timecode TimeCode SdfTimeCode A time value, rescaled across layer offsets
string String std::string Arbitrary UTF-8 string
token Token TfToken Interned string. Prefer over string for enumerated values
asset Asset SdfAssetPath A file path. USD resolves this through the asset resolver

Vectors — Generic (no semantic meaning)

usda Sdf.ValueTypeNames C++ type memory layout notes
float2 Float2 GfVec2f 2× float32
float3 Float3 GfVec3f 3× float32
float4 Float4 GfVec4f 4× float32
double2 Double2 GfVec2d 2× float64
double3 Double3 GfVec3d 3× float64
double4 Double4 GfVec4d 4× float64
half2 Half2 GfVec2h 2× float16
half3 Half3 GfVec3h 3× float16
half4 Half4 GfVec4h 4× float16
int2 Int2 GfVec2i 2× int32
int3 Int3 GfVec3i 3× int32
int4 Int4 GfVec4i 4× int32

Notable gap: No unsigned int vector types (GfVec2ui does not exist).

Matrices

usda Sdf.ValueTypeNames C++ type memory layout notes
matrix2d Matrix2d GfMatrix2d 4× float64, row-major
matrix3d Matrix3d GfMatrix3d 9× float64, row-major
matrix4d Matrix4d GfMatrix4d 16× float64, row-major The standard xform matrix in USD
frame4d Frame4d GfMatrix4d 16× float64, row-major Alias for matrix4d; semantic hint for coordinate frames

Note: All matrix types are double-precision only. There are no float32 matrix types.

Quaternions

usda Sdf ValueTypeName C++ type memory layout notes
quatd Quatd GfQuatd 4× float64
quatf Quatf GfQuatf 4× float32
quath Quath GfQuath 4× float16

Semantic Types — Colors

usda Sdf.ValueTypeNames C++ type equivalent generic notes
color3f Color3f GfVec3f float3 RGB, 32-bit. Most common for shader inputs
color3d Color3d GfVec3d double3
color3h Color3h GfVec3h half3 Common in EXR / HDR workflows
color4f Color4f GfVec4f float4 RGBA
color4d Color4d GfVec4d double4
color4h Color4h GfVec4h half4

Semantic Types — Geometry

usda Sdf.ValueTypeNames C++ type equivalent generic transforms as
point3f Point3f GfVec3f float3 position (w=1)
point3d Point3d GfVec3d double3 position (w=1)
point3h Point3h GfVec3h half3 position (w=1)
normal3f Normal3f GfVec3f float3
normal3d Normal3d GfVec3d double3
normal3h Normal3h GfVec3h half3
vector3f Vector3f GfVec3f float3 direction (w=0)
vector3d Vector3d GfVec3d double3 direction (w=0)
vector3h Vector3h GfVec3h half3 direction (w=0)

Note: No 2-component semantic vector types. For 2D directions, use float2 / Float2.

Semantic Types — Texture Coordinates

usda Sdf.ValueTypeNames C++ type equivalent generic notes
texCoord2f TexCoord2f GfVec2f float2 The standard UV primvar type
texCoord2d TexCoord2d GfVec2d double2
texCoord2h TexCoord2h GfVec2h half2
texCoord3f TexCoord3f GfVec3f float3 UVW / projected coords
texCoord3d TexCoord3d GfVec3d double3
texCoord3h TexCoord3h GfVec3h half3

Special / Uncommon Types

usda Sdf.ValueTypeNames C++ type notes
pathExpression PathExpression SdfPathExpression Pattern matching for prim paths. Used in USD collections
opaque Opaque SdfOpaqueValue A type with no value representation. Can't be serialized.
group Group SdfOpaqueValue A type of opaque value

How to enumerate this yourself

for x in dir(Sdf.ValueTypeNames):
    if not x.startswith('_') and x not in ('Find',):
        print(x, ":", getattr(Sdf.ValueTypeNames, x))

Note: Find appears in dir() output but is a method, not a type entry — filter it out.

What's not here

  • SdfPath does not appear in Sdf.ValueTypeNames. Relationships handle storing prim paths, not Attributes. Relationships can update the SdfPath value when stages are composing, since composition can change the path to the prim the SdfPath refers to.
  • Plugin-defined types can extend this list. These tables only have the built in types.

Read more