This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
stitchClips.h File Reference

Collection of utilities for sequencing multiple layers each holding sequential time-varying data into USD Value Clips. More...

+ Include dependency graph for stitchClips.h:

Go to the source code of this file.

Functions

 SDF_DECLARE_HANDLES (SdfLayer)
 
USDUTILS_API bool UsdUtilsStitchClips (const SdfLayerHandle &resultLayer, const std::vector< std::string > &clipLayerFiles, const SdfPath &clipPath, const double startTimeCode=std::numeric_limits< double >::max(), const double endTimeCode=std::numeric_limits< double >::max(), const bool interpolateMissingClipValues=false, const TfToken &clipSet=UsdClipsAPISetNames->default_)
 A function that creates layers that use USD Value Clips to effectively merge the time samples in the given clipLayers under clipPath without copying the samples into a separate layer.
 
USDUTILS_API bool UsdUtilsStitchClipsTopology (const SdfLayerHandle &topologyLayer, const std::vector< std::string > &clipLayerFiles)
 A function which aggregates the topology of a set of clipLayerFiles for use in USD's Value Clips system.
 
USDUTILS_API bool UsdUtilsStitchClipsManifest (const SdfLayerHandle &manifestLayer, const SdfLayerHandle &topologyLayer, const std::vector< std::string > &clipLayerFiles, const SdfPath &clipPath)
 A function which creates a clip manifest from the set of clipLayerFiles for use in USD's Value Clips system.
 
USDUTILS_API bool UsdUtilsStitchClipsTemplate (const SdfLayerHandle &resultLayer, const SdfLayerHandle &topologyLayer, const SdfLayerHandle &manifestLayer, const SdfPath &clipPath, const std::string &templatePath, const double startTime, const double endTime, const double stride, const double activeOffset=std::numeric_limits< double >::max(), const bool interpolateMissingClipValues=false, const TfToken &clipSet=UsdClipsAPISetNames->default_)
 A function which authors clip template metadata on a particular prim in a result layer, as well as adding the topologyLayer to the list of subLayers on the resultLayer.
 
USDUTILS_API std::string UsdUtilsGenerateClipTopologyName (const std::string &rootLayerName)
 Generates a topology file name based on an input file name.
 
USDUTILS_API std::string UsdUtilsGenerateClipManifestName (const std::string &rootLayerName)
 Generates a manifest file name based on an input file name.
 

Detailed Description

Collection of utilities for sequencing multiple layers each holding sequential time-varying data into USD Value Clips.

Definition in file stitchClips.h.

Function Documentation

◆ UsdUtilsGenerateClipManifestName()

USDUTILS_API std::string UsdUtilsGenerateClipManifestName ( const std::string &  rootLayerName)

Generates a manifest file name based on an input file name.

For example, if given 'foo.usd', it generates 'foo.manifest.usd'

Note: this will not strip preceding paths off of a file name so /bar/baz/foo.usd will produce /bar/baz/foo.manifest.usd

rootLayerName The filepath used as a basis for generating our manifest layer name.

◆ UsdUtilsGenerateClipTopologyName()

USDUTILS_API std::string UsdUtilsGenerateClipTopologyName ( const std::string &  rootLayerName)

Generates a topology file name based on an input file name.

For example, if given 'foo.usd', it generates 'foo.topology.usd'

Note: this will not strip preceding paths off of a file name so /bar/baz/foo.usd will produce /bar/baz/foo.topology.usd

rootLayerName The filepath used as a basis for generating our topology layer name.

◆ UsdUtilsStitchClips()

USDUTILS_API bool UsdUtilsStitchClips ( const SdfLayerHandle &  resultLayer,
const std::vector< std::string > &  clipLayerFiles,
const SdfPath clipPath,
const double  startTimeCode = std::numeric_limits< double >::max(),
const double  endTimeCode = std::numeric_limits< double >::max(),
const bool  interpolateMissingClipValues = false,
const TfToken clipSet = UsdClipsAPISetNames->default_ 
)

A function that creates layers that use USD Value Clips to effectively merge the time samples in the given clipLayers under clipPath without copying the samples into a separate layer.

resultLayer The layer to which clip metadata and frame data will be written. The layer representing the static scene topology will be authored as a sublayer on this layer as well; it will be authored as the first sublayer in the list(strongest).

clipLayerFiles The files containing the time varying data.

clipPath The path at which we will put the clip metadata.

startTimeCode The first time coordinate for the rootLayer to point to. If none is provided, it will be the lowest startTimeCode available from the clipLayers.

endTimeCode The last time coordinate for the rootLayer to point to. If none is provided, it will be the highest endTimeCode authored from the clipLayers.

interpolateMissingClipValues Whether values for clips without samples are interpolated from surrounding clips. See UsdClipsAPI::GetInterpolateMissingClipValues for more details.

clipSet The name of the clipSet in which the aforementioned metadata will be authored.

Note
If this parameter is omitted, the default clipSet name will be authored.

Details on how this is accomplished can be found below:

Pre-existing opinions will be wiped away upon success. Upon failure, the original topology and manifest layers, if pre-existing, will be preserved. These layers will be named/looked up via the following scheme:

topologyLayerName = <resultIdWithoutExt>.topology.<resultExt>
manifestLayerName = <resultIdWithoutExt>.manifest.<resultExt>

For example: if the resultLayerFile's name is foo.usd the expected topology layer will be foo.topology.usd and the expected manifest layer will be foo.manifest.usd.

The topology layer contains the aggregated topology of the set of clipLayers. This process will merge prims and properties, save for time varying properties, those will be accessed from the original clip files.

The aggregation of topology works by merging a clipLayer at a time with the topologyLayer. If a prim already exists in the topologyLayer, its attributes will be merged.

For example, if we have a layer, clipA with attributes /World/fx/foo.bar and a second layer with /World/fx/foo.baz. Our aggregate topology layer will contain both /World/fx/foo.bar, /World/fx/foo.baz.

The manifest layer contains declarations for all attributes that exist under clipPath and descendants in the clip layers with authored time samples. Any default values authored into the topology layer for these time sampled attributes will also be authored into the manifest.

The resultLayer will contain clip metadata at the specified clipPath. The resultLayer will also have timeCode range data, such as start and end timeCodes written to it, with the starting position being provided by startTimeCode and the ending provided by endTimeCode.

Note: an invalid clip path(because the prim doesn't exist in the aggregate topologyLayer) will result in a TF_CODING_ERROR.

◆ UsdUtilsStitchClipsManifest()

USDUTILS_API bool UsdUtilsStitchClipsManifest ( const SdfLayerHandle &  manifestLayer,
const SdfLayerHandle &  topologyLayer,
const std::vector< std::string > &  clipLayerFiles,
const SdfPath clipPath 
)

A function which creates a clip manifest from the set of clipLayerFiles for use in USD's Value Clips system.

This manifest will contain declarations for attributes with authored time samples in the clip layers. If a time sampled attribute has a default value authored in the given topologyLayer, that value will also be authored as its default in the manifest.

manifestLayer The layer where manifest data will be inserted.

topologyLayer The topology layer for clipLayerFiles.

clipLayerFiles The files containing the time varying data.

clipPrimPath The manifest will contain attributes from this prim and its descendants in clipLayerFiles.

◆ UsdUtilsStitchClipsTemplate()

USDUTILS_API bool UsdUtilsStitchClipsTemplate ( const SdfLayerHandle &  resultLayer,
const SdfLayerHandle &  topologyLayer,
const SdfLayerHandle &  manifestLayer,
const SdfPath clipPath,
const std::string &  templatePath,
const double  startTime,
const double  endTime,
const double  stride,
const double  activeOffset = std::numeric_limits< double >::max(),
const bool  interpolateMissingClipValues = false,
const TfToken clipSet = UsdClipsAPISetNames->default_ 
)

A function which authors clip template metadata on a particular prim in a result layer, as well as adding the topologyLayer to the list of subLayers on the resultLayer.

It will clear the resultLayer and create a prim at clipPath. Specifically, this will author clipPrimPath, clipTemplateAssetPath, clipTemplateStride, clipTemplateStartTime,
clipTemplateEndTime, and clipManifestAssetPath.

resultLayer The layer in which we will author the metadata.

topologyLayer The layer containing the aggregate topology of the clipLayers which the metadata refers to.

manifestLayer The layer containing manifest for the attributes in the clipLayers.

clipPath The path at which to author the metadata in resultLayer

templatePath The template string to be authored at the clipTemplateAssetPath metadata key.

startTime The start time to be authored at the clipTemplateStartTime metadata key.

endTime The end time to be authored at the clipTemplateEndTime metadata key.

stride The stride to be authored at the clipTemplateStride metadata key.

activeOffset The offset to be authored at the clipTemplateActiveOffset metadata key.

Note
If this parameter is omitted, no value will be authored as the metadata is optional.

interpolateMissingClipValues Whether values for clips without samples are interpolated from surrounding clips. See UsdClipsAPI::GetInterpolateMissingClipValues for more details.

clipSet The name of the clipSet in which the aforementioned metadata will be authored.

Note
If this parameter is omitted, the default clipSet name("default") will be authored.

For further information on these metadatum, see Advanced Scenegraph Scalability Features

◆ UsdUtilsStitchClipsTopology()

USDUTILS_API bool UsdUtilsStitchClipsTopology ( const SdfLayerHandle &  topologyLayer,
const std::vector< std::string > &  clipLayerFiles 
)

A function which aggregates the topology of a set of clipLayerFiles for use in USD's Value Clips system.

This aggregated scene topology will only include non-time-varying data, as it is for use in conjunction with the value clip metadata in a manifest layer.

topologyLayer The layer in which topology of the clipLayerFiles will be aggregated and inserted.

clipLayerFiles The files containing the time varying data.