USD Toolset

USD Toolset


USD Toolset

usdedit

usdedit is a simple script that converts any single usd-readable file into its (temp) .usda ascii 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.

> usdedit -h

usage: usdedit [-h] [-n] [-f] usdFileName

Convert a usd-readable file to the usd ascii 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 queried
from the EDITOR environment variable.

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.
  -f, --forcewrite     Override file permissions to allow writing.


 

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 ascii 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

> usdcat -h
usage: usdcat [-h] [-o file] [--usdFormat usda|usdb|usdc] [-f]
              [--mask PRIMPATH[,PRIMPATH...]]
              inputFiles [inputFiles ...]

Write usd file(s) either as text to stdout or to a specified output file.

positional arguments:
  inputFiles


optional arguments:
  -h, --help            show this help message and exit
  -o file, --out file   Write a single input file to this output file instead
                        of stdout.
  --usdFormat usda|usdb|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.
  -f, --flatten         Compose stages with the input files as root layers and
                        write their flattened content.
  --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.

Notes:

  • The mulit-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 --flatten option 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 master into the generated layer and adding references on each instance to its corresponding master.  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.

> usddiff -h
usage: usddiff [-h] [-n] [-f] 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.

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.

Notes:

  • It 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.

> usdview -h
usage: ./bin/usdview [-h] [--renderer {opt,simple}] [--select PRIMPATH]
                     [--camera CAMERA] [--mask PRIMPATH[,PRIMPATH...]]
                     [--clearsettings] [--norender] [--unloaded] [--timing]
                     [--memstats {none,stage,stageAndImaging}]
                     [--numThreads NUMTHREADS] [--ff FIRSTFRAME]
                     [--lf LASTFRAME] [--complexity COMPLEXITY]
                     [--quitAfterStartup]
                     usdFile

View a usd file

positional arguments:
  usdFile               The file to view

optional arguments:
  -h, --help            show this help message and exit
  --renderer {opt,simple}
                        Which renderer to use
  --select PRIMPATH     A prim path to initially select and frame
  --camera 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
  --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
  --norender            Display only hierarchy browser
  --unloaded            Do not load payloads
  --timing              echo timing stats to console. NOTE: timings will be
                        unreliable when the --mallocTagStats option is also in
                        use
  --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.
  --numThreads NUMTHREADS
                        Number of threads used for processing(0 is max,
                        negative numbers imply max - N)
  --ff FIRSTFRAME
  --lf LASTFRAME
  --complexity COMPLEXITY
                        A float complexity value in the closed range [1,2]
  --quitAfterStartup    quit immediately after start up

Further Notes on Command Line Options

  • --renderer : The default, "opt" renderer is the HD (hydra) high-performance renderer developed for the USD project. The "simple" gl renderer is single-threaded, uses simple VBO's to draw unrefined (only) geometry, and is largely used for debugging the "opt" renderer, or for when the underlying graphics hardware does not support the features required by the "opt" renderer. "Simple" also:
    • currently does not support intrinsics like Spheres, Capsules, Cylinders, and Cubes
    • uses only the main thread
    • does not support renderer plugins
  • --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  ("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 absolutely need the gl visualization of the stage, just access to navigating and introspecting 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 1.0 indicates no subdivision, for maximum performance and lowest fidelity.


usdzip

Utility for creating usdz packages from USD compositions and the assets (images and others in future) they reference.

> usdzip -h
usage: usdzip [-h] [-r] [-a ASSET] [--arkitAsset ARKITASSET] [-c]
              [-l [LISTTARGET]] [-d [DUMPTARGET]] [-v]
              [usdzFile] [inputFiles [inputFiles ...]]

Utility for creating a .usdz file containging 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.

> usdchecker -h
usage: usdchecker [-h] [-s] [-p] [-o [OUTFILE]] [--arkit] [-d] [-v] inputFile

Utility for checking the compliance of a given USD stage or a USDZ package.

positional arguments:
  inputFile             Name of the input file to inspect.

optional arguments:
  -h, --help            show 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 specifiedpackage. Nested packages,
                        dependencies and their contents are not validated.
  -o [OUTFILE], --out [OUTFILE]
                        The file to which all the failed checks are output. If
                        unspecified, the failed checks are output to stdout.
  --arkit               Check if the given USD stage is compatible with
                        ARKit's initial implementation of usdz. 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.
  -v, --verbose         Enable verbose output 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 flattening removes (by baking in ("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 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.  USD does not yet have a tool for this operation.

> usdstitch -h
usage: [-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 which produces an aggregate representation of a common prim 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.
  • result.usd - this file will minimally contain the prim hierarchy described by the --clipPath command 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 form 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.

 

> usdstitchclips -h
usage: usdstitchclips [-h] [-o OUT] [-c CLIPPATH]
                      [-s STARTTIMECODE]
                      [-r STRIDE] [-e ENDTIMECODE]
                      [-t] [-p TEMPLATEPATH] [-n]
                      usdFiles [usdFiles ...]
Stitch multiple usd file(s) together into one using value clips. An example
call 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 a file to write out to
  -c CLIPPATH, --clipPath CLIPPATH
                        specify a prim path to stitch clip data at.
  -s STARTTIMECODE, --startTimeCode STARTTIMECODE
                        specify a start time
  -r STRIDE, --stride STRIDE
                        specify a stride for template metadata
  -e ENDTIMECODE, --endTimeCode ENDTIMECODE
                        specify an end time
  -t, --templateMetadata
                        author template clip metadata in the root layer.
  -p TEMPLATEPATH, --templatePath TEMPLATEPATH
                        specify a template asset path to author
  -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.

> usddumpcrate -h
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 underpin USD.

> sdfdump -h
Usage: sdfdump [options] <input file>
Options:
  -h [ --help ]                   Show help message.
  -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 or time ranges for 
                                  'timeSamples' fields.
  --timeTolerance tol (=0.000125) Report times that are close to those 
                                  requested within this relative tolerance.
  --sortBy path|field (=path)     Group output by either path or field.
  --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.

> sdffilter -h
Usage: sdffilter [options] <input files>
Options:
  -h [ --help ]                         Show help message.
  -p [ --path ] regex                   Report only paths matching this regex. 
                                        For 'layer' and 'pseudoLayer' output 
                                        types, include all descendants of 
                                        matching paths.
  -f [ --field ] regex                  Report only fields matching this regex.
  -t [ --time ] n or ff..lf             Report only these times or time ranges 
                                        for 'timeSamples' fields.
  --timeTolerance tol (=0.000125)       Report times that are close to those 
                                        requested within this relative 
                                        tolerance.
  --arraySizeLimit N                    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 N              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 ] outputFile               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 (=outline)
                                        Specify output format; 'summary' 
                                        reports overall statistics, 'outline' 
                                        is a flat text report of paths and 
                                        fields, 'pseudoLayer' is similar to the
                                        sdf file format but with truncated 
                                        array values and timeSamples for human 
                                        readability, and 'layer' is true layer 
                                        output, with the format controlled by 
                                        the 'outputFile' and 'outputFormat' 
                                        arguments.
  --outputFormat format                 Supply this as the 'format' entry of 
                                        SdfFileFormatArguments for 'layer' 
                                        output to a file.  Requires both 
                                        'layer' output and a specified 
                                        'outputFile'.
  --sortBy path|field (=path)           Group 'outline' output by either path 
                                        or field.  Ignored for other output 
                                        types.
  --noValues                            Do not report field values for 
                                        'outline' output.  Ignored for other 
                                        output types.





Graphics Home