Prim and Property Names#

Utility functions to generate valid names and display names for UsdPrims, and valid property names on UsdPrims.

OpenUsd has strict requirements on what names are valid for a UsdObject, though the specification is evolving over time.

Additionally the names of sibling Objects must be unique so that the SdfPath that identifies them is unique within the UsdStage.

Most authoring functions in this library require that the names and paths supplied are valid. While it would be possible for each of these functions to create valid values directly, this workflow can lead to undetected name collisions.

The functions below can be used to produce valid UsdObject names for any OpenUSD runtime that we support.

Transcoding#

By default, valid names are produced via a transcoding process that generates names which can be losslessly decoded.

For any legal identifier in a given runtime, this transcoding will produce no changes.
For illegal identifiers, the transcoding will produce a human readable name that meets the requirements of the runtime.

While we do not currently provide decoding functions, the omni_transcoding shared library and associated python module do provide decoding. For the time being, it is recommended to use this library directly to decode any UsdPrim or UsdProperty names that have been serialized.

If you prefer to avoid transcoding entirely, this behaviour can be disabled via our Runtime Settings.

Prim Naming Functions#

To ensure that a UsdPrim is valid use getValidPrimName().

When defining multiple prims below a common parent use getValidChildNames() to ensure that the names are not only valid, but also unique from one another and existing children.

When there is no existing parent, we provide getValidPrimNames().

Property Naming Functions#

To ensure that a UsdProperty name is valid, use getValidPropertyName(). This function differs from Prim Name encoding, as it explicitly handles nested namespaces (e.g. foo:bar:baz) and encodes each portion of the namespace independently.

When defining multiple properties for the same UsdPrim, use getValidPropertyNames() to ensure that the names are not only valid, but also unique from one another.

Prim Display Name#

Unlike names, “Display Names” support all UTF-8 encoding across all runtimes, as they are simply metadata on the Prim, and are not used to uniquely identify it. You can author UTF-8 binary strings and/or characters directly in a .usda file.

Example:

def Cube "cube1" (
    displayName = "\xF0\x9F\x9A\x80"
)

def Cube "cube2" (
    displayName = "🚀"
)

We recommend setting the display name metadata in cases where the native name of an item could not be used for the associated UsdObject. This could be because the name was invalid, or because it needed to be allocated a suffix to become unique. In either case the original value can be stored as the display name.

However, support for storing a display name on a Prim is not consistent across all versions of OpenUsd. To make this more consistent, we provide functions to manipulate the display name metadata in any OpenUSD runtime.

Note

The transcoding process has been proposed for inclusion in a future version of OpenUSD. Once a suitable implementation is available, we will adopt it internally to our name validation functions.

Classes#

usdex::core::ValidChildNameCache: A caching mechanism for valid and unique child prim names.

Functions#

bool usdex::core::blockDisplayName(pxr::UsdPrim prim): Block this prim's display name (metadata)
bool usdex::core::clearDisplayName(pxr::UsdPrim prim): Clears this prim's display name (metadata) in the current EditTarget (only)
std::string usdex::core::computeEffectiveDisplayName(const pxr::UsdPrim &prim): Calculate the effective display name of this prim.
std::string usdex::core::getDisplayName(const pxr::UsdPrim &prim): Return this prim's display name (metadata)
pxr::TfToken usdex::core::getValidChildName(const pxr::UsdPrim &prim, const std::string &name): Take a prim and a preferred name. Return a valid and unique name as the child name of the given prim.
pxr::TfTokenVector usdex::core::getValidChildNames(const pxr::UsdPrim &prim, const std::vector< std::string > &names): Take a prim and a vector of the preferred names. Return a matching vector of valid and unique names as the child names of the given prim.
pxr::TfToken usdex::core::getValidPrimName(const std::string &name): Produce a valid prim name from the input name.
pxr::TfTokenVector usdex::core::getValidPrimNames(const std::vector< std::string > &names, const pxr::TfTokenVector &reservedNames={}): Take a vector of the preferred names and return a matching vector of valid and unique names.
pxr::TfToken usdex::core::getValidPropertyName(const std::string &name): Produce a valid property name using the Bootstring algorithm.
pxr::TfTokenVector usdex::core::getValidPropertyNames(const std::vector< std::string > &names, const pxr::TfTokenVector &reservedNames={}): Take a vector of the preferred names and return a matching vector of valid and unique names.
bool usdex::core::setDisplayName(pxr::UsdPrim prim, const std::string &name): Sets this prim's display name (metadata).

Functions#

bool usdex::core::blockDisplayName(pxr::UsdPrim prim)#

Block this prim’s display name (metadata)

The fallback value will be explicitly authored to cause the value to resolve as if there were no authored value opinions in weaker layers

Parameters:: prim – The prim to block the display name for
Returns:: True on success, otherwise false

bool usdex::core::clearDisplayName(pxr::UsdPrim prim)#

Clears this prim’s display name (metadata) in the current EditTarget (only)

Parameters:: prim – The prim to clear the display name for
Returns:: True on success, otherwise false

std::string usdex::core::computeEffectiveDisplayName( const pxr::UsdPrim &prim, )#

Calculate the effective display name of this prim.

If the display name is un-authored or empty then the prim’s name is returned

Parameters:: prim – The prim to compute the display name for
Returns:: The effective display name

std::string usdex::core::getDisplayName(const pxr::UsdPrim &prim)#

Return this prim’s display name (metadata)

Parameters:: prim – The prim to get the display name from
Returns:: Authored value, or an empty string if no display name has been set

pxr::TfToken usdex::core::getValidChildName( const pxr::UsdPrim &prim, const std::string &name, )#

Take a prim and a preferred name. Return a valid and unique name as the child name of the given prim.

Parameters:

prim – The USD prim where the given prim name should live under.
name – A preferred prim name.

Returns:

A valid and unique name.

pxr::TfTokenVector usdex::core::getValidChildNames( const pxr::UsdPrim &prim, const std::vector<std::string> &names, )#

Take a prim and a vector of the preferred names. Return a matching vector of valid and unique names as the child names of the given prim.

Parameters:

prim – The USD prim where the given prim names should live under.
names – A vector of preferred prim names.

Returns:

A vector of valid and unique names.

pxr::TfToken usdex::core::getValidPrimName(const std::string &name)#

Produce a valid prim name from the input name.

This is a lossless encoding algorithm that supports all UTF-8 code set (even control characters).

Parameters:: name – The input name
Returns:: A string that is considered valid for use as a prim name.

pxr::TfTokenVector usdex::core::getValidPrimNames( const std::vector<std::string> &names, const pxr::TfTokenVector &reservedNames = {}, )#

Take a vector of the preferred names and return a matching vector of valid and unique names.

Parameters:

names – A vector of preferred prim names.
reservedNames – A vector of reserved prim names. Names in the vector will not be included in the returns.

Returns:

A vector of valid and unique names.

pxr::TfToken usdex::core::getValidPropertyName( const std::string &name, )#

Produce a valid property name using the Bootstring algorithm.

Parameters:: name – The input name
Returns:: A string that is considered valid for use as a property name.

pxr::TfTokenVector usdex::core::getValidPropertyNames( const std::vector<std::string> &names, const pxr::TfTokenVector &reservedNames = {}, )#

Take a vector of the preferred names and return a matching vector of valid and unique names.

Parameters:

names – A vector of preferred property names.
reservedNames – A vector of reserved property names. Names in the vector will not be included in the return.

Returns:

A vector of valid and unique names.

bool usdex::core::setDisplayName( pxr::UsdPrim prim, const std::string &name, )#

Sets this prim’s display name (metadata).

DisplayName is meant to be a descriptive label, not necessarily an alternate identifier; therefore there is no restriction on which characters can appear in it

Parameters:

prim – The prim to set the display name for
name – The value to set

Returns:

True on success, otherwise false