SdfLayer Authoring#

Utility functions to provide consistent authoring of SdfLayers

It is desirable to capture data provenance information into the metadata of SdfLayers, in order to keep track of what tools & versions were used throughout content creation pipelines, and to capture notes from the content author. While OpenUSD does not currently have a formal specification for this authoring metadata, some conventions have emerged throughout the OpenUSD Ecosystem.

The most common convention for tool tracking is to include a “creator” string in the SdfLayer::CustomLayerData. Similarly, notes from the content author should be captured via SdfLayer::SetComment. While these are trivial using SdfLayer public methods, they are also easy to forget, and difficult to discover.

These functions assist authoring applications in setting authoring metadata, so that each application can produce consistant provenance information. The metadata should only add information which can be used to track the data back to its origin. It should not be used to store sensitive information about the content, nor about the end user (i.e. do not use it to store Personal Identifier Information).

Example: 

auto layer = SdfLayer::CreateAnonymous();
static constexpr const char* s_authoringMetadata = "My Content Editor® 2024 SP 2, USD Exporter Plugin v1.1.23.11";
usdex::core::exportLayer(layer, fileName, s_authoringMetadata, userComment);

Note

This metadata is strictly informational, it is not advisable to drive runtime behavior from this metadata. In the future, the “creator” key may change, or a more formal specification for data provenance may emerge.

Functions#

bool usdex::core::exportLayer(pxr::SdfLayerHandle layer, const std::string &identifier, const std::string &authoringMetadata, std::optional< std::string_view > comment=std::nullopt, const pxr::SdfLayer::FileFormatArguments &fileFormatArgs=pxr::SdfLayer::FileFormatArguments())

Export the given SdfLayer to an identifier with an optional comment.

std::string usdex::core::getLayerAuthoringMetadata(const pxr::SdfLayerHandle layer)

Get metadata from the SdfLayer indicating the provenance of the data.

pxr::TfToken usdex::core::getUsdLayerEncoding(const pxr::SdfLayerHandle layer)

Get the USD file format encoding of the given SdfLayer .

bool usdex::core::hasLayerAuthoringMetadata(const pxr::SdfLayerHandle layer)

Check if the SdfLayer has metadata indicating the provenance of the data.

bool usdex::core::saveLayer(pxr::SdfLayerHandle layer, std::optional< std::string_view > authoringMetadata=std::nullopt, std::optional< std::string_view > comment=std::nullopt)

Save the given SdfLayer with an optional comment.

void usdex::core::setLayerAuthoringMetadata(pxr::SdfLayerHandle layer, const std::string &value)

Set metadata on the SdfLayer indicating the provenance of the data.

On this page