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 foo.abcworks 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.
- 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 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.
- It does not do any fuzzy numerical comparison. The slightest precision difference will cause a diff.
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.
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 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 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.
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.
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.usdwill also contain a reference, on its root prim (the root path component of clipPath) to the same-named prim in
usddumpcrate provides information on usd files encoded using USD's Crate File Format.
Provides information on Sdf Layers which underpin USD.