Basic Datatypes for Scene Description Provided by Sdf

Attribute value types

USD supports a variety of data types for attribute values. These types are encoded in an SdfValueTypeName object that corresponds to an underlying C++ type and is what a user would receive from a call to UsdAttribute::GetTypeName. Methods for looking up these objects are provided by SdfSchema and they're enumerated in the object SdfValueTypeNames

See also

For example, to create a custom, Matrix4d-valued attribute on prim foo:

if (UsdAttribute mat = foo.CreateAttribute(TfToken("myMatrix"), SdfValueTypeNames->Matrix4d)){
mat.Set(GfMatrix4d(1)); // Assign identity matrix
} else {
// error creating the attribute

In python:

mat = foo.CreateAttribute("myMatrix", Sdf.ValueTypeNames.Matrix4d)
if mat:
mat.Set(Gf.Matrix4d(1)) # Assign identity matrix
# error creating the attribute

Basic data types

This table lists the fundamental data types supported by USD.

Value type token C++ type Description
bool bool
uchar uint8_t 8 bit unsigned integer
int int32_t 32 bit signed integer
uint uint32_t 32 bit unsigned integer
int64 int64_t 64 bit signed integer
uint64 uint64_t 64 bit unsigned integer
half GfHalf 16 bit floating point
float float 32 bit floating point
double double 64 bit floating point
timecode SdfTimeCode double representing a resolvable time
string std::string stl string
token TfToken interned string with fast comparison and hashing
asset SdfAssetPath represents a resolvable path to another asset
opaque SdfOpaqueValue represents a value that can't be serialized
matrix2d GfMatrix2d 2x2 matrix of doubles
matrix3d GfMatrix3d 3x3 matrix of doubles
matrix4d GfMatrix4d 4x4 matrix of doubles
quatd GfQuatd double-precision quaternion
quatf GfQuatf single-precision quaternion
quath GfQuath half-precision quaternion
double2 GfVec2d vector of 2 doubles
float2 GfVec2f vector of 2 floats
half2 GfVec2h vector of 2 half's
int2 GfVec2i vector of 2 ints
double3 GfVec3d vector of 3 doubles
float3 GfVec3f vector of 3 floats
half3 GfVec3h vector of 3 half's
int3 GfVec3i vector of 3 ints
double4 GfVec4d vector of 4 doubles
float4 GfVec4f vector of 4 floats
half4 GfVec4h vector of 4 half's
int4 GfVec4i vector of 4 ints


Value types may also be specified by one of a set of special type names. These names correspond to the basic data types listed above but provide extra semantics about how the data should be interpreted. For instance, a value of type "frame4d" is a GfMatrix4d, but represents a coordinate frame.

These type names are grouped by a "role" name, such that all types with the same role have the same semantics. All of these "semantic types" are also provided in SdfValueTypeNames

Value type token Underlying type Role name Role Meaning
point3d Vec3d Point transform as a position
point3f Vec3f Point transform as a position
point3h Vec3h Point transform as a position
normal3d Vec3d Normal transform as a normal
normal3f Vec3f Normal transform as a normal
normal3h Vec3h Normal transform as a normal
vector3d Vec3d Vector transform as a direction
vector3f Vec3f Vector transform as a direction
vector3h Vec3h Vector transform as a direction
color3d Vec3d Color energy-linear RGB
color3f Vec3f Color energy-linear RGB
color3h Vec3h Color energy-linear RGB
color4d Vec4d Color energy-linear RGBA, not pre-alpha multiplied
color4f Vec4f Color energy-linear RGBA, not pre-alpha multiplied
color4h Vec4h Color energy-linear RGBA, not pre-alpha multiplied
frame4d Matrix4d Frame defines a coordinate frame
texCoord2h Vec2h TextureCoordinate 2D uv texture coordinate
texCoord2d Vec2d TextureCoordinate 2D uv texture coordinate
texCoord2f Vec2f TextureCoordinate 2D uv texture coordinate
texCoord3h Vec3h TextureCoordinate 3D uvw texture coordinate
texCoord3d Vec3d TextureCoordinate 3D uvw texture coordinate
texCoord3f Vec3f TextureCoordinate 3D uvw texture coordinate
group SdfOpaqueValue Group used as a grouping mechanism for sibling attributes

The following exist for historical/internal reasons, but we expect to eliminate them prior to open-sourcing.

Value type token Underlying type Role name
Transform Matrix4d Transform
PointIndex int PointIndex
EdgeIndex Vec2i EdgeIndex
FaceIndex int FaceIndex

Array data types

USD also supports arrays of the above data types. The value type name for these arrays is simply the name of the underlying value type and "[]", e.g. "bool[]", "float[]", etc., and are also provided by SdfValueTypeNames with a "Array" suffix on the basic datatype (e.g. SdfValueTypeNames->FloatArray provides "float[]"). The corresponding C++ type is VtArray, e.g. VtArray<bool>, VtArray<float>, etc.

Dictionary-valued Metadata

Metadata in USD (See General Metadata in USD) can take on several other datatypes.

Most of these are highly-specialized, pertaining to composition, like SdfListOp<SdfReference>, but we also provide one very versatile datatype dictionary that can only be assumed by metadata, such as customData. A dictionary's entries are keyed by string, and can take on any other scene description value type, including dictionary, allowing for nested dictionaries.

Dictionaries have special value-resolution semantics, in that each field resolves independently of all others, allowing dictionaries to be sparsely described and overridden in many layers. This behavior, which we have found highly desirable, also makes dictionaries more expensive to fully compose than all other value types (except those that are list-edited). It is for this reason that we disallow dictionary as a value type for attributes: it would eliminate the extremely important performance characteristic of attribute value resolution that "strongest opinion wins".

You can use the builtin customData for your truly ad-hoc user-data needs, but you can also add new dictionary-valued metadata by defining it in a module plugInfo.json file - see Plugin Metadata for details on how to do so.