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: SdfSchema

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
else:
   # 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

Note that opaque-valued attributes cannot be authored, and are used for cases where the value can't be represented in USD, such as shader outputs.

Roles

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 matrix4d, but represents a coordinate frame.

These type names are grouped, in several instances, 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. To get the "semantic type" role name from the type token, use SdfGetRoleNameForValueTypeName().

The following table lists the type tokens for these roles, the corresponding base type token, which can be matched to the C++ type in the table above, and the role name and meaning.

Value type token	Base type	Role name	Role Meaning
point3d	double3	Point	transform as a position
point3f	float3	Point	transform as a position
point3h	half3	Point	transform as a position
normal3d	double	Normal	transform as a normal
normal3f	float3	Normal	transform as a normal
normal3h	half3	Normal	transform as a normal
vector3d	double3	Vector	transform as a direction
vector3f	float3	Vector	transform as a direction
vector3h	half3	Vector	transform as a direction
color3d	double3	Color	energy-linear RGB
color3f	float3	Color	energy-linear RGB
color3h	half3	Color	energy-linear RGB
color4d	double4	Color	energy-linear RGBA, not pre-alpha multiplied
color4f	float4	Color	energy-linear RGBA, not pre-alpha multiplied
color4h	half4	Color	energy-linear RGBA, not pre-alpha multiplied
frame4d	matrix4d	Frame	defines a coordinate frame
texCoord2d	double2	TextureCoordinate	2D uv texture coordinate
texCoord2f	float2	TextureCoordinate	2D uv texture coordinate
texCoord2h	half2	TextureCoordinate	2D uv texture coordinate
texCoord3d	double3	TextureCoordinate	3D uvw texture coordinate
texCoord3f	float3	TextureCoordinate	3D uvw texture coordinate
texCoord3h	half3	TextureCoordinate	3D uvw texture coordinate
group	opaque	Group	used as a grouping mechanism for namespaced properties

A Group attribute is an opaque attribute used to represent a group of other properties. It behaves like a connectable/targetable property namespace.

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.