USD Toolset
usdedit
usdedit is a simple script that converts any single USD-readable
file into its (temp) .usda text equivalent and brings the
result up in your editor of choice, which is taken from the EDITOR
environment variable. Upon quitting the editor, any changes to the temp file
will be converted back to the original file’s format (assuming the
FileFormatPlugin for the format allows writing), and the original
file’s contents will be replaced with the edited contents.
usage: usdedit [-h] [-n] [-f] [-p PREFIX] usdFileName
Convert a usd-readable file to the .usda text format in a temporary location
and invoke an editor on it. After saving and quitting the editor, the edited
file will be converted back to the original format and OVERWRITE the original
file, unless you supply the "-n" (--noeffect) flag, in which case no changes
will be saved back to the original file. The editor to use will be looked up
as follows: - USD_EDITOR environment variable - EDITOR environment variable -
emacs in PATH - vim in PATH - notepad in PATH
positional arguments:
usdFileName The usd file to edit.
optional arguments:
-h, --help show this help message and exit
-n, --noeffect Do not edit the file. Create the temporary file in a
default location guided by the TMPDIR, TEMP, and TMP
environment variables.
-f, --forcewrite Override file permissions to allow writing.
-p PREFIX, --prefix PREFIX
Provide a prefix for the temporary file name.
Notes:
usdedit foo.abc works as an alembic editor (in USD schema) for all elements of the alembic file that our translator currently handles. As we do not yet cover all aspects of the alembic schema, however, please be careful and do not usdedit an alembic file being used as a source file, since the roundtripping is lossy!
Running usdedit on a very large file with lots of dense, numeric data may take a long time, create a really large text file in your temp area (wherever python’s tempfile package decides to put it), and may push the boundaries of your editor’s scalability.
usdcat
Write usd file(s) either as text to stdout or to a specified output file.
Usage: usdcat [OPTIONS] inputFiles...
Positionals:
inputFiles ... A list of input files
Options:
-h,--help Print this help message and exit
-o,--out file Write a single input file to this output file instead of stdout.
--usdFormat usda|usdc Use this underlying file format for output files
with the extension 'usd'. For example, passing
'-o output.usd --usdformat usda' will create
output.usd as a text file. The USD_DEFAULT_FILE_FORMAT
environment variable is another way to achieve this.
-l,--loadOnly Attempt to load the specified input files and report 'OK'
or 'ERR' for each one. After all files are processed, this
script will exit with a non-zero exit code if any files
failed to load.
-f,--flatten Compose stages with the input files as root layers
and write their flattened content.
--flattenLayerStack Flatten the layer stack with the given root layer, and
write out the results. Unlike --flatten, this does not flatten
composition arcs (such as references).
--skipSourceFileComment If --flatten is specified, skip adding a comment regarding the
source of the flattened layer in the documentation field of the
output layer.
--mask PRIMPATH[,PRIMPATH...]
Limit stage population to these prims, their descendants and
ancestors. To specify multiple paths, either use commas with no
spaces, or quote the argument and separate paths by commas
and/or spaces. Requires --flatten.
--layerMetadata Load only layer metadata in the USD file.
This option cannot be combined with either --flatten or
--flattenLayerStack.
Notes:
The multi-file input to usdcat does not perform any kind of merge of the content in the separate files (and there is no such utility to do so, yet… parameterizing that problem is an interesting challenge!); it simply dumps the contents of each file, sequentially.
The
--flattenoption uses UsdStage::Export() , which, as one might expect, “bakes in” the effects of all composition operators, simultaneously removing the operators themselves, in the result; this applies both to namespace operators like references, sublayers, and variants, and also to value-resolution operators like layer and reference time offsets. Flattening a stage does preserve USD native instancing by flattening each prototype into the generated layer and adding references on each instance to its corresponding prototype. Thus, the exported data may appear structurally different than in the participating source files, but should evaluate/compute identically to that of the source files.
usddiff
usddiff runs a diff program on the result of usdcat ‘ing two named USD-readable files. It is currently quite primitive, with limitations noted below, but even so can be quite useful.
usage: usddiff [-h] [-n] [-f] [-q] files [files ...]
Compares two usd-readable files using a selected diff program. This is chosen
by looking at the $USD_DIFF environment variable. If this is unset, it will
consult the $DIFF environment variable. Lastly, if neither of these is set, it
will try to use the canonical unix program, diff. This will relay the exit
code of the selected diff program.When comparing two usdz files, each file
contained in the package will be examined individually. The $USD_IMAGE_DIFF
environment variable specifies a specific diff program for comparing image
files. The $USD_IMAGE_DIFF_FORMATS environment variable specifies supported
image formats using a "," separated list of file extensions.
positional arguments:
files The files to compare. These must be of the form DIR DIR,
FILE... DIR, DIR FILE... or FILE FILE.
optional arguments:
-h, --help show this help message and exit
-n, --noeffect Do not edit either file.
-f, --flatten Fully compose both layers as Usd Stages and flatten into
single layers.
-q, --brief Do not return full results of diffs. Passes --brief to the
diff command.
Notes:
usddiff does not do any fuzzy numerical comparison. The slightest precision difference will cause a diff.
usdview
usdview is the most fully-featured USD tool, combining interactive gl preview, scenegraph navigation and introspection, a (growing) set of diagnostic and debugging facilities, and an interactive python interpreter.
usage: usdview [-h]
[--renderer {Storm,Embree,RenderMan RIS,RenderMan XPU,GL}]
[--select PRIMPATH]
[--camera CAMERA]
[--mask PRIMPATH[,PRIMPATH...]]
[--clearsettings] [--config {}]
[--defaultsettings]
[--norender] [--noplugins]
[--unloaded] [--bboxStandin]
[--timing] [--allow-async]
[--traceToFile TRACETOFILE]
[--traceFormat {chrome,trace}]
[--tracePython]
[--memstats {none,stage,stageAndImaging}]
[--dumpFirstImage DUMPFIRSTIMAGE]
[--numThreads NUMTHREADS]
[--ff FIRSTFRAME]
[--lf LASTFRAME]
[--cf CURRENTFRAME]
[--complexity {low,medium,high,veryhigh}]
[--quitAfterStartup]
[--sessionLayer SESSIONLAYER]
[--mute MUTELAYERSRE]
[--detachLayers]
[--detachLayersInclude PATTERN[,PATTERN...]]
[--detachLayersExclude PATTERN[,PATTERN,...]]
usdFile
View a usd file
positional arguments:
usdFile The file to view
optional arguments:
-h, --help show this help message and exit
--renderer {Storm,Embree,RenderMan RIS,RenderMan XPU,GL}, -r {Storm,Embree,RenderMan RIS,RenderMan XPU,GL}
Which render backend to use (named as it appears in
the menu). 'GL' and 'Storm' currentlyalias to the same
renderer, Storm.
--select PRIMPATH A prim path to initially select and frame
--camera CAMERA, -cam CAMERA
Which camera to set the view to on open - may be given
as either just the camera's prim name (ie, just the
last element in the prim path), or as a full prim
path. Note that if only the prim name is used, and
more than one camera exists with the name, which is
used will be effectively random (default=None)
--mask PRIMPATH[,PRIMPATH...]
Limit stage population to these prims, their
descendants and ancestors. To specify multiple paths,
either use commas with no spaces or quote the argument
and separate paths by commas and/or spaces.
--clearsettings Restores usdview settings to default
--config {} Load usdview with the state settings found in the
specified config. If not provided will use the
previously saved application state and automatically
persist state on close
--defaultsettings Launch usdview with default settings
--norender Display only hierarchy browser
--noplugins Do not load plugins
--unloaded Do not load payloads
--bboxStandin Display unloaded prims with bounding boxes
--timing Echo timing stats to console. NOTE: timings will be
unreliable when the --memstats option is also in use
--allow-async Enable asynchronous hydra scene processing
--traceToFile TRACETOFILE
Start tracing at application startup and write
--traceFormat specified format output to the specified
trace file when the application quits
--traceFormat {chrome,trace}
Output format for trace file specified by
--traceToFile. 'chrome' files can be read in chrome,
'trace' files are simple text reports.
(default=chrome)
--tracePython Enable python trace collection, requires --traceToFile
to be set.
--memstats {none,stage,stageAndImaging}
Use the Pxr MallocTags memory accounting system to
profile USD, saving results to a tmp file, with a
summary to the console. Will have no effect if
MallocTags are not supported in the USD installation.
--dumpFirstImage DUMPFIRSTIMAGE
Dumps the first image to file (as png)
--numThreads NUMTHREADS
Number of threads used for processing(0 is max,
negative numbers imply max - N)
--ff FIRSTFRAME Set the first frame of the viewer
--lf LASTFRAME Set the last frame of the viewer
--cf CURRENTFRAME Set the current frame of the viewer
--complexity {low,medium,high,veryhigh}, -c {low,medium,high,veryhigh}
Set the initial mesh refinement complexity (low).
--quitAfterStartup quit immediately after start up
--sessionLayer SESSIONLAYER
If specified, the stage will be opened with the
'sessionLayer' in place of the default anonymous
layer. As this changes the session layer from
anonymous to persistent, be aware that layers saved
from Export Overrides will include the opinions in the
persistent session layer.
--mute MUTELAYERSRE Layer identifiers searched against this regular
expression will be muted on the stage prior to, and
after loading. Multiple expressions can be supplied
using the | regex separator operator. Alternatively
the argument may be used multiple times.
Detached Layers:
Specify layers to be detached from their serialized data source when
loaded. This may increase time to load and memory usage but will avoid
issues like open file handles preventing other processes from safely
overwriting a loaded layer.
--detachLayers Detach all layers
--detachLayersInclude PATTERN[,PATTERN...]
Detach layers with identifiers containing any of the
given patterns.
--detachLayersExclude PATTERN[,PATTERN,...]
Exclude layers with identifiers containing any of the
given patterns from the set of detached layers
specified by the --detachLayers or
--detachLayerIncludes arguments.
Further Notes on Command Line Options
--renderer: Can be used to select any of the render delegates whose plugins have been installed. The default Hydra renderer is Storm.
--select primPath: loads and images the entire stage, but selects primPath in the prim browser, and positions the free camera as if one had hit the f (“frame selection”) hotkey.
--mask primPath [primPath ...]: opens the stage in masked mode, restricted to these paths for viewing only a subset of the prims on a stage.
--norender: if one does not require a rendered visualization of the stage, needing only to access navigation and inspection of the data, this option can substantially reduce the startup time and file I/O. Expect some errors in the terminal if you should happen to select some of the menu/shortcut options, as we have yet to do a cleanup pass for this mode. Errors should be harmless, however.
--unloaded: Populates the stage without including any payloads. For a scene constructed of references to models built with payloads, this can create a summary Model Hierarchy view of the scene in a small fraction of the time it would take to compose and present all the prims in the scene. You can then load or unload subtrees of the prim hierarchy using either the “Edit > Load” menu, or the RMB context menu in the browser.
--numThreads: this will determine how many threads the Hydra renderer, boundingBox computer, and other multi-threaded computations will be able to use.
--complexity: Hydra uses OpenSubdiv to refine Mesh gprims whose subdivisionScheme is anything other than polygonal. A complexity of low indicates no subdivision, for maximum performance and lowest fidelity.
usdrecord
usdrecord is a command-line utility for generating images (or sequences of images) of a USD stage. Images output by this tool are generated by Hydra and are equivalent to those displayed in the viewer in usdview .
usage: usdrecord [-h] [--mask PRIMPATH[,PRIMPATH...]]
[--purposes PURPOSE[,PURPOSE...]]
[--sessionLayer SESSIONLAYER] [--disableGpu]
[--disableDrawMode] [--disableCameraLight]
[--resolverContext {root,inherit}] [--camera CAMERA]
[--defaultTime | --frames FRAMESPEC[,FRAMESPEC...]]
[--complexity {low,medium,high,veryhigh}]
[--colorCorrectionMode {disabled,sRGB,openColorIO}]
[--renderer {Storm,Embree,RenderMan RIS,RenderMan XPU,GL}]
[--imageWidth IMAGEWIDTH] [--enableDomeLightVisibility]
[--renderPassPrimPath RPPRIMPATH]
[--renderSettingsPrimPath RSPRIMPATH]
[--traceToFile TRACETOFILE] [--traceFormat {chrome,trace}]
[--memstats]
usdFilePath outputImagePath
Generates images from a USD file
positional arguments:
usdFilePath USD file to record
outputImagePath Output image path. For frame ranges, the path must
contain exactly one frame number placeholder of the
form "###" or "###.###". Note that the number of hash
marks is variable in each group.
optional arguments:
-h, --help show this help message and exit
--mask PRIMPATH[,PRIMPATH...]
Limit stage population to these prims, their
descendants and ancestors. To specify multiple paths,
either use commas with no spaces or quote the argument
and separate paths by commas and/or spaces.
--purposes PURPOSE[,PURPOSE...]
Specify which UsdGeomImageable purposes should be
included in the renders. The "default" purpose is
automatically included, so you need specify only the
*additional* purposes. If you want more than one extra
purpose, either use commas with no spaces or quote the
argument and separate purposes by commas and/or
spaces.
--sessionLayer SESSIONLAYER
If specified, the stage will be opened with the
'sessionLayer' in place of the default anonymous
layer.
--disableGpu Indicates if the GPU should not be used for rendering.
If set this not only restricts renderers to those
which only run on the CPU, but additionally it will
prevent any tasks that require the GPU from being
invoked.
--disableDrawMode Disables support for USD draw modes. If set,
UsdGeomModelAPI's draw modes will be ignored, and no
geometry will be replaced with a draw mode standin.
Everything will render as if applyDrawMode = false.
--disableCameraLight Indicates if the default camera lights should not be
used for rendering.
--resolverContext {root,inherit}
Indicates which resolver context to use. Choosing
"root" will create a resolver based on the rootLayer.
Choosing "inherit" will inherit the incoming resolver
from the environment.
--camera CAMERA, -cam CAMERA
Which camera to use - may be given as either just the
camera's prim name (i.e. just the last element in the
prim path), or as a full prim path. Note that if only
the prim name is used and more than one camera exists
with that name, which one is used will effectively be
random (default=None)
--defaultTime, -d explicitly operate at the Default time code (the
default behavior is to operate at the startTimeCode
authored on the UsdStage which defaults to 0.0)
--frames FRAMESPEC[,FRAMESPEC...], -f FRAMESPEC[,FRAMESPEC...]
specify FrameSpec(s) of the time codes to operate on -
A FrameSpec consists of up to three floating point
values for the start time code, end time code, and
stride of a time code range. A single time code can be
specified, or a start and end time code can be
specified separated by a colon (:). When a start and
end time code are specified, the stride may optionally
be specified as well, separating it from the start and
end time codes with (x). Multiple FrameSpecs can be
combined as a comma-separated list. The following are
examples of valid FrameSpecs: 123 - 101:105 - 105:101
- 101:109x2 - 101:110x2 - 101:104x0.5
--complexity {low,medium,high,veryhigh}, -c {low,medium,high,veryhigh}
level of refinement to use (default=low)
--colorCorrectionMode {disabled,sRGB,openColorIO}, -color {disabled,sRGB,openColorIO}
the color correction mode to use (default=sRGB)
--renderer {Storm,Embree,RenderMan RIS,RenderMan XPU,GL}, -r {Storm,Embree,RenderMan RIS,RenderMan XPU,GL}
Hydra renderer plugin to use when generating images.
"GL" and "Storm" currently alias to the same renderer,
Storm.
--imageWidth IMAGEWIDTH, -w IMAGEWIDTH
Width of the output image. The height will be computed
from this value and the camera's aspect ratio
(default=960). Note that this only affects the
command-line output image; it does not affect any
render products in scene description.
--enableDomeLightVisibility
Show the dome light background in the rendered output.
If this option is not included and there is a dome
light in the stage, the IBL from it will be used for
lighting but not drawn into the background.
--renderPassPrimPath RPPRIMPATH, -rp RPPRIMPATH
Specify the RenderPass prim to use. This overrides any
renderSettingsPrimPath specified in stage metadata.
--renderSettingsPrimPath RSPRIMPATH, -rs RSPRIMPATH
Specify the RenderSettings prim to use. This overrides
any renderSettingsPrimPath specified in stage
metadata.
--traceToFile TRACETOFILE
Start tracing at application startup and write
--traceFormat specified format output to the specified
trace file when the application quits
--traceFormat {chrome,trace}
Output format for trace file specified by
--traceToFile. 'chrome' files can be read in chrome,
'trace' files are simple text reports.
(default=chrome)
--memstats Use the Pxr MallocTags memory accounting system to
profile USD, saving results to a tmp file, with a
summary to the console. Will have no effect if
MallocTags are not supported in the USD installation.
Further Notes on Command Line Options
--camera: When a camera name or prim path is given, images of the scene will be generated as viewed from that camera. Otherwise, a default camera framing all of the geometry on the stage (similar to the free camera in usdview ) will be used.
usdresolve
Command-line ArResolver resolution of asset paths.
usage: usdresolve [-h]
[--createContextForAsset CREATECONTEXTFORASSET | --createContextFromString CREATECONTEXTFROMSTRING]
[--anchorPath ANCHORPATH]
inputPath
Resolves an asset path using a fully configured USD Asset Resolver.
positional arguments:
inputPath An asset path to be resolved by the USD Asset
Resolver.
optional arguments:
-h, --help show this help message and exit
--createContextForAsset CREATECONTEXTFORASSET
Run CreateDefaultContextForAsset with the given asset
path to create the context used for resolution.
--createContextFromString CREATECONTEXTFROMSTRING
Run CreateContextFromString with the given string to
create the context used for resolution. This accepts
strings like [<URI Scheme>:]<Configuration String> and
may be specified multiple times. ex: usdresolve
--createContextFromString 'config_primary'
--createContextFromString 'my_uri_scheme:config_uri'
--anchorPath ANCHORPATH
Run CreateIdentifier with the input path and this
anchor asset path and resolve the result. ex:
usdresolve --anchorPath /asset/asset.usd sublayer.usd
usdtree
Prints to terminal a unixtree-like summary of a USD layer or composition.
usdtree : Writes the tree structure of a USD file. The default is to
inspect a single USD file. Use the --flatten argument to see the
flattened (or composed) Stage tree. Special metadata 'kind' and
'active' are always shown if authored unless --simple is provided.
Usage: usdtree [OPTIONS] inputPath
Positionals:
inputPath TEXT REQUIRED The input file to process
Options:
-h,--help Print this help message and exit
--unloaded Do not load payloads.
-a,--attributes Display authored attributes.
-m,--metadata Display authored metadata (active and kind are part of the label and not shown as individual items
-s,--simple Only display prim names: no specifier, kind or active state.
-f,--flatten Compose the stage with the input file as the root layer and write the flattened content.
--flattenLayerStack Flatten the layer stack with the given root layer. Unlike --flatten, this does not flatten composition arcs (such as references).
--mask PRIMPATH[,PRIMPATH...]
Limit stage population to these prims, their descendants and ancestors. To specify multiple paths, either use commas with no spaces, or quote the argument and separate paths by commas and/or spaces. Requires --flatten.
usdzip
Utility for creating USDZ packages from USD compositions and the assets (images and others in future) they reference.
usage: usdzip [-h] [-r] [-a ASSET] [--arkitAsset ARKITASSET] [-c]
[-l [LISTTARGET]] [-d [DUMPTARGET]] [-v]
[usdzFile] [inputFiles ...]
Utility for creating a .usdz file containing USD assets and for inspecting
existing .usdz files.
positional arguments:
usdzFile Name of the .usdz file to create or to inspect the
contents of.
inputFiles Files to include in the .usdz file.
optional arguments:
-h, --help show this help message and exit
-r, --recurse If specified, files in sub-directories are recursively
added to the package.
-a ASSET, --asset ASSET
Resolvable asset path pointing to the root layer of
the asset to be isolated and copied into the package.
--arkitAsset ARKITASSET
Similar to the --asset option, the --arkitAsset option
packages all of the dependencies of the named scene
file. Assets targeted at the initial usdz
implementation in ARKit operate under greater
constraints than usdz files for more general 'in
house' uses, and this option attempts to ensure that
these constraints are honored; this may involve more
transformations to the data, which may cause loss of
features such as VariantSets.
-c, --checkCompliance
Perform compliance checking of the input files. If the
input asset or "root" layer fails any of the
compliance checks, the package is not created and the
program fails.
-l [LISTTARGET], --list [LISTTARGET]
List contents of the specified usdz file. If a file-
path argument is provided, the list is output to a
file at the given path. If no argument is provided or
if '-' is specified as the argument, the list is
output to stdout.
-d [DUMPTARGET], --dump [DUMPTARGET]
Dump contents of the specified usdz file. If a file-
path argument is provided, the contents are output to
a file at the given path. If no argument is provided
or if '-' is specified as the argument, the contents
are output to stdout.
-v, --verbose Enable verbose mode, which causes messages regarding
files being added to the package to be output to
stdout.
usdchecker
usdchecker attempts to validate a USD or usdz file using a series of rules and metrics that will evolve over time. This tool currently provides the best assurance that an asset will be properly interchangeable and renderable by Hydra.
Utility for checking the compliance of a given USD stage or a USDZ package.
Only the first sample of any relevant time-sampled attribute is checked,
currently. General USD checks are always performed, and more restrictive checks
targeted at distributable consumer content are also applied when the "--arkit"
option is specified. In order to use the old compliance checker (deprecated)
provide the '--useOldComplianceCheckerInterface' option.
Usage: usdchecker [OPTIONS] [inputFile]
Positionals:
inputFile FILE Name of the input file to inspect.
Options:
-h,--help Print this help message and exit
-s,--skipVariants If specified, only the prims that are present in the default (i.e.
selected) variants are checked. When this option is not specified,
prims in all possible combinations of variant selections are
checked.
-p,--rootPackageOnly Check only the specified package. Nested packages, dependencies and
their contents are not validated.
-o,--out FILE The file to which all the failed checks are output. If unspecified,
the failed checks are output to stdout; if "stderr", terminal
coloring will be suppressed.
--noAssetChecks If specified, do NOT perform extra checks to help ensure the stage
or package can be easily and safely referenced into aggregate stages.
--arkit Check if the given USD stage is compatible with RealityKit's
implementation of USDZ as of 2023. These assets operate under
greater constraints that usdz files for more general in-house uses,
and this option attempts to ensure that these constraints are met.
-d,--dumpRules Dump the enumerated set of rules
being checked for the given set of options.
-v,--verbose Enable verbose output mode.
-t,--strict Return failure code even if only warnings are issued, for stricter
compliance.
--useOldComplianceCheckerInterface
Use the old and now deprecated Compliance Checker interface.
--variantSets TEXT ... List of variantSets to validate. All variants for the given
variantSets are validated. This can also be used with --variants to
validate the given variants in combination with variants from the
explicitly specified variantSets. This option is only valid when
using the new validation framework.
--variants TEXT ... List of ',' separated variantSet:variant pairs to validate. Each set
of variants in the list are validated separately. Example:
--variants foo:bar,baz:qux will validate foo:bar and baz:qux
together but --variants foo:bar --variants baz:qux will validate
foo:bar and baz:qux separately. This can also be used with
--variantSets to validate the given variants in combination with
varuants from the explicitly specified variantSets. This option is
only valid when using the new validation framework.
--disableVariantValidationLimit
Disable the limit set to restrict the number of variants validation
calls. This is useful when the number of variants is large and we
want to validate all possible combinations of variants. Default is
to limit the number of validation calls to 1000. This option is only
valid when using the new validation framework.
usdfixbrokenpixarschemas
usdfixbrokenpixarschemas attempts to fix usd(a|c|z) layers for any updates introduced by newer Pixar schema revisions. Note that this does not provide a fixing mechanism for all validation tests listed in usdchecker.
usage: usdfixbrokenpixarschemas [-h] [--backup BACKUPFILE] [-v] [inputFile]
Fixes usd / usdz layer by applying appropriate fixes defined in the
UsdUtils.FixBrokenPixarSchemas. If the given usd file has any fixes to be
saved, a backup is created for that file. If a usdz package is provided, it is
extracted recursively at a temp location, and fixes are applied on each layer
individually, which are then packaged into a new usdz package, while creating
a backup of the original.
positional arguments:
inputFile Name of the input file to inspect and fix.
optional arguments:
-h, --help show this help message and exit
--backup BACKUPFILE optional backup file path, if none provided creates a
<inputFile>.bck.<usda|usdc|usdz> at the inputFile
location
-v, --verbose Enable verbose mode.
usdstitch
usdstitch aggregates any number of usd files into a single file. This process is different from flattening a stage . The key differences are:
The result of usdstitch will contain the ordered union of Composition Arcs present on prims in the input sequence of files, whereas usdcat --flatten removes (by evaluating or flattening the composed opinions) composition arcs.
usdstitch merges the timeSamples from the input sequence of files, whereas flattening preserves the TimeSamples of only the strongest layer that contains TimeSamples, which is consistent with how Value Resolution interprets layered TimeSamples on a stage.
The goal and purpose of usdstitch is to create a time-wise merge
of all of its input files, as if each file represents a timeslice of a
complete scene, and we wish to merge all the scenes together. This is neither
equivalent to stage flattening, as just described, nor will it produce an
equivalent result to flattening a LayerStack, which is the
process of combining all the (nested) SubLayers of a root
layer into a single layer, preserving all composition arcs (other than
subLayers) and guaranteeing the same evaluation behavior, thus (purely)
optimizing N layers into one. One can flatten a LayerStack using usdcat
with its --flattenLayerStack option.
usage: usdstitch [-h] [-o OUT]
usdFiles [usdFiles ...]
Stitch multiple usd file(s) together into one. Opinion strength is determined
by the order in which the file is given, with the first file getting the
highest strength. The exception to this general behavior is in time samples,
which are merged together as a union across the input layers. It is consistent
in that, if two time sample keys conflict, the strong layer takes precedence.
positional arguments:
usdFiles
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT specify a file to write out to
usdstitchclips
usdstitchclips is a tool that produces an aggregate representation of a common prim (and all its descendant prims) shared across a set of USD files using the Value Clips feature. This utility will provide a Value Clip representation of the input files, which are presumed to form a sequential animation, determined by the startTimeCode and endTimeCode of each layer in the sequence. It produces two files, as described in the usage output below:
result.topology.usd - this file will contain the unioned prim and property topology and metadata of all the input files - that is, all prims and properties that appear in any of the input USD files.
result.usd - this file will minimally contain the prim hierarchy described by the
--clipPathcommand argument, to host the Value Clip metadata at CLIPPATH . This means that in the resulting composition, all prims at or below CLIPPATH in namespace will receive values from the input clip layers. result.usd will also contain a reference, on its root prim (the root path component of CLIPPATH ) to the same-named prim in result.topology.usd
result.usd is suitable for sublayering into a Layer Stack whose animation (at CLIPPATH ) is intended to be supplied by the input files.
Note that the animation content of the stitched result is completely dependent on the layout of timeSamples in the input USD files. So, in particular:
If the input files contain only default values , there will be no animation, as Value Clips only look for timeSample values.
When the
--templateMetadataargument has not been specified, then the startTimeCode and endTimeCode metadata of each clip layer will be used to determine the time-range over which that clip will be active, and all timeSamples within that range within the clip layer will be consumed.When the
--templateMetadataargument has been specified, then the range over which each clip will be active is determined by the required--templatePathargument, and the two optional arguments--strideand--activeOffset:
--templatePath: A regex-esque template string representing the form of our asset paths’ names. This can be of two forms: ‘path/basename.###.usd’ and ‘path/basename.###.###.usd’ . These represent integer stage times and sub-integer stage times respectively. In both cases the number of hashes in each section is variable, and indicates to USD how much padding to apply when looking for asset paths. Note that USD is strict about the format of this string: there must be exactly one or two groups of hashes, and if there are two, they must be adjacent, separated by a dot.
--stride: An optional (double precision float) number indicating the stride at which USD will increment when looking for files to resolve. For example, given a start time of 12, an end time of 25, a template string of ‘path/basename.#.usd’, and a stride of 6, USD will look to resolve the following paths: ‘path/basename.12.usd’, ‘path/basename.18.usd’ and ‘path/basename.24.usd’. If no stride is specified, USD will use the value 1.0.
--activeOffset: An optional (double precision float) number indicating the offset USD will use when calculating the clipActive value that determines the time-range over which each clip is active.Given a start time of 101, an endTime of 103, a stride of 1, and an offset of 0.5, USD will generate the following:
clipTimes = [(100.5,100.5), (101,101), (102,102), (103,103), (103.5,103.5)]
clipActive = [(101.5, 0), (102.5, 1), (103.5, 2)]
In other words, an offset allows us to slide the window into each clip in which USD will look for timeSamples to map into the stage’s time, rather than simply using the window implied by each clip’s filename. Note that the ACTIVEOFFSET cannot exceed the absolute value of STRIDE.
usage: usdstitchclips [-h] [-o OUT] [-c CLIPPATH] [-s STARTTIMECODE]
[-r STRIDE] [-e ENDTIMECODE] [-t] [-p TEMPLATEPATH]
[--clipSet CLIPSET] [--activeOffset ACTIVEOFFSET]
[--interpolateMissingClipValues] [-n]
usdFiles [usdFiles ...]
Stitch multiple usd file(s) together into one using value clips.
An example command is:
usdstitchclips --out result.usd --clipPath /World/fx/Particles_Splash clip1.usd clip2.usd
This will produce two files, a result.topology.usd and a result.usd.
positional arguments:
usdFiles
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT specify the filename for the top-level result file,
which also serves as base-name for the topology and
manifest files.
-c CLIPPATH, --clipPath CLIPPATH
specify a prim path at which to begin stitching clip
data.
-s STARTTIMECODE, --startTimeCode STARTTIMECODE
specify the time at which the clips will become active
-r STRIDE, --stride STRIDE
specify a stride for the numeric component of
filenames for template metadata
-e ENDTIMECODE, --endTimeCode ENDTIMECODE
specify the time at which the clips will cease being
active
-t, --templateMetadata
author template clip metadata in the root layer.
-p TEMPLATEPATH, --templatePath TEMPLATEPATH
specify a template asset path to author
--clipSet CLIPSET specify a named clipSet in which to author clip
metadata, so that multiple sets of clips can be
applied on the same prim.
--activeOffset ACTIVEOFFSET
specify an offset for template-based clips, offsetting
the frame number of each clip file.
--interpolateMissingClipValues
specify whether values for clips without authored
samples are interpolated from surrounding clips if no
default value is authored in any clip.
-n, --noComment do not write a comment specifying how the usd file was
generated
usddumpcrate
usddumpcrate provides information on usd files encoded using USD’s Crate File Format. This can be useful for very low-level debugging.
usage: usddumpcrate [-h] [-s] inputFiles [inputFiles ...]
Write information about a usd crate (usdc) file to stdout
positional arguments:
inputFiles
optional arguments:
-h, --help show this help message and exit
-s, --summary report only a short summary
sdfdump
Provides information on Sdf Layers, which are the containers for USD data.
Filter and display raw layer data
Usage: sdfdump [OPTIONS] inputFiles...
Positionals:
inputFiles ... The input files to dump.
Options:
-h,--help Print this help message and exit
-s,--summary Report a high-level summary.
--validate Check validity by trying to read all data values.
-p,--path regex Report only paths matching this regex.
-f,--field regex Report only fields matching this regex.
-t,--time n or ff..lf Report only these times (n) or time ranges (ff..lf) for 'timeSamples' fields
--timeTolerance tol Report times that are close to those requested within this relative tolerance. Default: 0.000125
--sortBy path|field Group output by either path or field. Default: path
--noValues Do not report field values.
--fullArrays Report full array contents rather than number of elements
sdffilter
Provides information in a variety of formats (including usda-like) about Sdf Layers or specified (filtered) parts of a layer. Uses range from finding full information about specific properties, to creating “suitable for web/index display” versions of USD files that elide large array data.
Provides information in a variety of formats (including usda-like) about
Sdf Layers or specified (filtered) parts of a layer.
Usage: sdffilter [OPTIONS] inputFiles...
Positionals:
inputFiles ... The input files to process
Options:
-h,--help Print this help message and exit
-p,--path regex Report only paths matching this regex.
-f,--field regex Report only fields matching this regex.
-t,--time n or ff..lf Report only these times (n) or time ranges (ff..lf) for
'timeSamples' fields
--timeTolerance tol Report times that are close to those requested within this relative tolerance. Default: 0.000125
--arraySizeLimit INT Truncate arrays with more than this many elements. If -1, do not
truncate arrays. Default: 0 for 'outline' output, 8 for
'pseudoLayer' output, and -1 for 'layer' output.
--timeSamplesSizeLimit INT Truncate timeSamples with more than this many values. If -1, do not
truncate timeSamples. Default: 0 for 'outline' output, 8 for
'pseudoLayer' output, and -1 for 'layer' output. Truncation
performed after initial filtering by --time arguments.
-o,--out TEXT Direct output to this file. Use the 'outputFormat' for finer
control over the underlying format for output formats that are
not uniquely determined by file extension.
--outputType validity|summary|outline|pseudoLayer|layer
Specify output format; 'summary' reports overall statistics,
'outline' is a flat text report of paths and fields,
'pseudoLayer' is similar to the usda file format but with truncated
array values and timeSamples for human readability, and 'layer' is
true layer output, with the format controlled by the 'out'
and 'outputFormat' arguments. Default: outline
--outputFormat TEXT Supply this as the 'format' entry of SdfFileFormatArguments for
'layer' output to a file. Requires both 'layer' output and a
specified output file.
--sortBy path|field Group 'outline' output by either path or field. Ignored for other
output types. Default: path
--noValues Do not report field values.
usdmeasureperformance
Helper script to measure usdview asset performance. Recommended usage
is usdmeasureperformance <asset.usd> -i 10 --agg min -o <metrics.yaml>.
If there exists a file ending in overrides.usda in the same
directory as the given asset file, the file will be supplied as
--sessionLayer to usdview and testusdview invocations.
This allows provision of specific variant selections, for example. The first
file found by os.listdir will be used. Ensure there is only one file ending in
overrides.usda in the asset directory to remove ambiguity.
usage: usdmeasureperformance [-h] [-c [CUSTOM_METRICS ...]] -o OUTPUT
[-i ITERATIONS]
[-a {min,mean,max} [{min,mean,max} ...]]
[-t TRACEDIR]
asset
Measure and export USD functional performance
positional arguments:
asset Asset file path.
optional arguments:
-h, --help show this help message and exit
-c [CUSTOM_METRICS ...], --custom-metrics [CUSTOM_METRICS ...]
Additional custom metrics to run `testusdview` timing
on. If not set, a default set of metrics is run. This
should be a whitespace-separated list of
<script>:'<metric name>,<metric name>' e.g.
stageTraversalMetric.py:'traverse stage'. Note the
<script> path is relative to the directory from which
usdmeasureperformance.py is invoked.
-o OUTPUT, --output OUTPUT
Required output file path for metrics data. Must be
.yaml
-i ITERATIONS, --iterations ITERATIONS
Number of iterations to run. Performance metrics are
reported as an average across all iterations. Requires
-o to be set. By default, 3 iterations are set.
-a {min,mean,max} [{min,mean,max} ...], --aggregation {min,mean,max} [{min,mean,max} ...]
When multiple iterations are set, report an aggregated
statistic instead of every value. Requires -o to be
set. When one aggregation is requested, the output
yaml format will be a key value dictionary with
<metric_name>_<aggregation> to aggregated time value.
If multiple aggregations are requested, the output
yaml format will be <metric_name>: {<agg1>: <value1>,
<agg2>:...}.When no aggregation is set, the output
format will be <metric_name>: [<val1>, <val2>, ...] or
one measured value for each iteration.
-t TRACEDIR, --tracedir TRACEDIR
Outputs a trace file for each run of usdview in the
given directory if provided and if 'aggregation'
includes min or max. A trace file for the iteration of
testusdview or usdview from which the aggregated value
of each metric was observed will be output in the form
<metric name>_<aggregation>.trace
usdGenSchema
USD provides a code generator script usdGenSchema for creating new schema classes. The script is driven by a USD layer (typically named schema.usda) and generates the necessary C++ classes and supporting Python code for all the schema classes defined in it.
Run usdGenSchema to generate code in the current directory for the schema
classes defined in schema.usda. usdGenSchema will update
any pre-existing files in the current directory if it detects any differences
with the code it generates. Make sure these files are editable before running
usdGenSchema.
If you used usdInitSchema to create your schema module, schema CMakeLists.txt and module.cpp files will be kept up to date as you add new schema classes and run usdGenSchema, except for any added tests, which must be manually added to CMakeLists.txt. If you created CMakeLists.txt or module.cpp by hand and/or did not originally use usdInitSchema, usdGenSchema will not update these files, and you will need to manually update these files when you add new schema classes.
For more details on developing schemas, see Creating New Schema Classes with usdGenSchema.
usage: usdGenSchema [-h] [-v] [-q] [-n NAMESPACE [NAMESPACE ...]]
[-t TEMPLATEPATH] [-hts HEADERTERMINATORSTRING]
[schemaPath] [codeGenPath]
Generate C++ schema class code from a USD file.
positional arguments:
schemaPath The source USD file where schema classes are defined.
[Default: ./schema.usda]
codeGenPath The target directory where the code should be
generated. [Default: .]
optional arguments:
-h, --help show this help message and exit
-v, --validate Verify that the source files are unchanged.
-q, --quiet Do not output text during execution.
-n NAMESPACE [NAMESPACE ...], --namespace NAMESPACE [NAMESPACE ...]
Wrap code in this specified namespace. Multiple
arguments will be interpreted as a nested namespace.
The leftmost argument will be treated as the outermost
namespace, with the rightmost argument as the
innermost.
-t TEMPLATEPATH, --templates TEMPLATEPATH
Directory containing schema class templates. [Default:
first directory that exists from this list:
<usd install dir>/bin/codegenTemplates:<usd install dir>
/lib/usd/usd/resources/codegenTemplates]
-hts HEADERTERMINATORSTRING, --headerTerminatorString HEADERTERMINATORSTRING
The string used to terminate generated C++ header
files, after the custom code section. [Default:
#endif]
usdgenschemafromsdr
Use usdgenschemafromsdr to generate schema.usda, generatedSchema.usda, and plugInfo.json files for sdrNodes (shaders, etc.) provided in a JSON config file (by default schemaConfig.json).
usdgenschemafromsdr generates codeless schemas by default, but the option to generate schema API code can be enabled in the JSON config file.
usage: usdgenschemafromsdr [-h] [--noreadme] [-v]
[schemaConfig] [schemaGenerationPath]
This script generates dynamic schema.usda, generatedSchema.usda and
plugInfo.json. The schema.usda is generated by parsing appropriate sdrNodes
provided in a config file. Along with providing sdrNodes types and
identifier, the config file also provides a list of subLayers which the auto
populated schema.usda should sublayer. Code generation can also be
optionally enabled via the json config, note that code generation is
disabled by default.
The script takes 3 arguments:
- a json config, providing sdrNodes via sourceType, sdrNodeIdentifiers
or explicit list of absolute asset file paths (sourceAssetNodes) and
a list of sublayers. The asset file paths might also contain
environment variables, so users must set these prior to running the
script.
- a destination directory. Note that a schema.usda with appropriate
GLOBAL prim providing a libraryName in its customData, must be
present at this location. This is also the location where
generatedSchema.usda, plugInfo.json will get exported.
In the case code generation is explicitly enabled in the config,
libraryPath must also be provided along with libraryName in the
customData, else usdGenSchema will fail.
- an optional noreadme to ignore generating a README.md providing brief
explaination of the contents of the directory.
This script will run usdGenSchema on the auto populated schema.usda.
If regenerating schemas, it's recommended to set the
USD_DISABLE_AUTO_APPLY_API_SCHEMAS environment variable to true in
order to prevent any previously generated auto-apply API schemas
from being applied to the specified schema bases which can result
in extra properties being pruned.
The schema.usda populated specifications from the provided sdrNodes using
UsdUtils.UpdateSchemaWithSdrNode and skipCodeGeneration metadata will be
set to true, unless explicitly marked False in the config for this
schema.usda.
UsdUtils.UpdateSchemaWithSdrNode is responsible for:
Updates the given schemaLayer with primSpec and propertySpecs from sdrNode
metadata.
A renderContext can be provided which is used in determining the
shaderId namespace, which follows the pattern:
"<renderContext>:<SdrShaderNodeContext>:shaderId". Note that we are using a
node's context (SDR_NODE_CONTEXT_TOKENS) here to construct the shaderId
namespace, so shader parsers should make sure to use appropriate
SDR_NODE_CONTEXT_TOKENS in the node definitions.
overrideIdentifier parameter is the identifier which should be used when
the identifier of the node being processed differs from the one Sdr will
discover at runtime, such as when this function is def a node constructed
from an explicit asset path. This should only be used when clients know the
identifier being passed is the true identifier which sdr Runtime will
provide when querying using GetShaderNodeByIdentifierAndType, etc.
It consumes the following attributes (that manifest as Sdr
metadata) in addition to many of the standard Sdr metadata
specified and parsed (via its parser plugin).
Node Level Metadata:
- "schemaName": Name of the new schema populated from the given sdrNode
(Required)
- "schemaKind": Specifies the UsdSchemaKind for the schema being
populated from the sdrNode. (Note that this does not support
multiple apply schema kinds).
- "schemaBase": Base schema from which the new schema should inherit
from. Note this defaults to "APISchemaBase" for an API schema or
"Typed" for a concrete scheme.
- "apiSchemasForAttrPruning": A list of core API schemas which will be
composed together and any shared shader property from this prim
definition is pruned from the resultant schema.
- "typedSchemaForAttrPruning": A core typed schema which will be
composed together with the apiSchemasForAttrPruning and any shared
shader property from this prim definition is pruned from the
resultant schema. If no typedSchemaForAttrPruning is provided then
only the apiSchemasForAttrPruning are composed to create a prim
definition. This will only be used when creating an APISchema.
- "apiSchemaAutoApplyTo": The schemas to which the sdrNode populated
API schema will autoApply to.
- "apiSchemaCanOnlyApplyTo": If specified, the API schema generated
from the sdrNode can only be validly applied to this set of schemas.
- "providesUsdShadeConnectableAPIBehavior": Used to enable a
connectability behavior for an API schema.
- "isUsdShadeContainer": Only used when
providesUsdShadeConnectableAPIBehavior is set to true. Marks the
connectable prim as a UsdShade container type.
- "requiresUsdShadeEncapsulation": Only used when
providesUsdShadeConnectableAPIBehavior is set to true. Configures the
UsdShade encapsulation rules governing its connectableBehavior.
- "tfTypeNameSuffix": Class name which will get registered with TfType
system. This gets appended to the domain name to register with TfType.
- "schemaPropertyNSPrefixOverride": Node level metadata which can drive
all node's properties namespace prefix. This can be useful for
non connectable nodes which should not get UsdShade inputs and outputs
namespace prefix.
Property Level Metadata:
- "usdVariability": Property level metadata which specifies a specific
sdrNodeProperty should have its USD variability set to Uniform or
Varying
- "usdSuppressProperty": A property level metadata which determines if
the property should be suppressed from translation from args to
property spec.
- "propertyNSPrefixOverride": Provides a way to override a property's
namespace from the default (inputs:/outputs:) or from a node's
schemaPropertyNSPrefixOverride metadata.
Sdr Property Metadata to SdfPropertySpec Translations
- A "null" value for Widget SdrShaderProperty metadata translates to
'hidden' in the SdfPropertySpec's uiHints metadata dictionary.
- SdrShaderProperty's Help metadata (Label metadata if Help metadata not
provided) translates to the SdfPropertySpec's userDocBrief and userDoc
custom metadata strings.
- SdrShaderProperty's Page metadata translates to 'displayGroup'
in the SdfPropertySpec's uiHints metadata dictionary.
- SdrShaderProperty's Label metadata translates to 'displayName'
in the SdfPropertySpec's uiHints metadata dictionary.
- SdrShaderProperty's Options translates to either 'allowedTokens'
(when either labels or values are provided) or 'valueLabels' (when
both labels and values are provided) in the SdfPropertySpec's uiHints
metadata dictionary. For backwards compatibility, set
USD_POPULATE_LEGACY_ALLOWED_TOKENS to write allowedTokens in addition
to valueLabels for string- and token-valued attributes that provide
both labels and values.
- SdrShaderProperty's Default value translates to the SdfPropertySpec's
Default value.
- Connectable input properties translates to InterfaceOnly
SdfPropertySpec's CONNECTABILITY.
positional arguments:
schemaConfig
A json config providing sdrNodes via sourceType, sdrNodeIdentifiers
or explicit list of absolute asset file paths (sourceAssetNodes).
Note that for nodes specified under sourceAssetNodes we will use
the basename stripped of extension as the shaderId for nodes we
create. If node paths specified in sourceAssetNodes contain any
environment variables, user is required to set these prior to
running the script.
And also optionally providing a list of sublayers which the
schema.usda will sublayer. Code generation can also be optionally
enabled via the json config, note that code generation is disabled
by default. [Default: ./schemaConfig.json]').
Example json config file:
{
"sdrNodes":
{
"renderContext": "myRenderContext",
"sourceType": [
"sdrIdentifier1",
"sdrIdentifier2",
"sdrIdentifier3"
],
"sourceAssetNodes": [
"/absolutepath/to/sdrNodeIdentifyingAsset1.extension,
"/absolutepath/to/sdrNodeIdentifyingAsset1.extension,
],
},
"sublayers": [
"usd/schema.usda",
"usdGeom/schema.usda",
"usdLux/schema.usda"
],
"skipCodeGeneration": True
}
schemaGenerationPath
The target directory where the code should be generated. The script
assumes a basic schema.usda is defined at this location with a
GLOBAL prim configured with appropriate libraryName.
[Default: .]
optional arguments:
-h, --help show this help message and exit
--noreadme
When specified a README.md will not be created in the schemaGenerationPath
explaining the source of the contents of this directory.
-v, --validate
This is passed to usdGenSchem to verify that the source files are
unchanged.
usdInitSchema
Use usdInitSchema to set up schema modules for the first time. It generates templates for:
CMakeLists.txt
_init_.py
module.cpp
schema.usda
schemaUserDoc.usda
Example usage for creating a new pxr/usd/testModule schema module:
Run
usdInitSchema testModule pxr/usd/testModule pxr/usdFill in the created schema.usda with schema classes. Update the userDoc/schemaUserDoc.usda with schema class user documentation (see docs/README.md for more information on schema user documentation).
Run usdGenSchema in the new module directory to generate code as-needed for the new schema classes.
In CMakeLists.txt, list dependency libraries under “LIBRARIES”. If there are any non-schema code classes, add them under “CPPFILES”. Schema classes and generated files will be automatically built.
If there are non-schema classes, list them in module.cpp in the format
TF_WRAP(CPP_class_name);If using the OpenUSD build system, add
testModuleto the list of DIRS in the parent directory.
Note: If not using the OpenUSD build system, moduleDeps.cpp might be
needed. If so, run usdInitSchema with the --genModuleDeps flag.
The moduleDeps.cpp file will then need to be kept manually updated
with the module dependencies.
usage: usdInitSchema [-h] [-v] [-q] [--genModuleDeps] [-t TEMPLATEPATH]
codeGenPath libraryPath [pxrPrefix]
Set up build necessities for schema classes. This will generate templates for
the CMakeLists.txt, __init__.py, schema.usda, module.cpp, and a user doc if
they do not already exist.
positional arguments:
codeGenPath The target directory where the code should be
generated. Can be '.' for the current directory.
libraryPath The partial path with which to prefix '#include'
statements of generated files for this module. For
external (non-Pixar) plugins, we recommend setting
libraryPath to ".", so that the headers inside src
directory are included in the generated files.
pxrPrefix Prefix to the path from pxr to this library. For
pxr/usd/usd, the prefix would be pxr/usd. Omit this
argument for non-OpenUSD build systems.
optional arguments:
-h, --help show this help message and exit
-v, --validate Verify that the source files are unchanged.
-q, --quiet Do not output text during execution.
--genModuleDeps Generates a template for the moduleDeps.cpp. This
template will need to be filled in and kept up to date
with library dependencies if you are not using the
OpenUSD build system.
-t TEMPLATEPATH, --templates TEMPLATEPATH
Directory containing schema class templates. [Default:
first directory that exists from this list:
<usd install dir>/bin/codegenTemplates:<usd install dir>
/lib/usd/usd/resources/codegenTemplates]