USDCHECKER() USDCHECKER()

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

usdchecker [options] [inputFile]

usdchecker is a utility that verifies a file is a compliant USD file.

Only the first sample of any relevant time-sampled attribute is checked.

General USD checks are always performed. More restrictive checks targeted at distributable consumer content are also applied when the --arkit option is specified to ensure the stage is compatible with RealityKit's implementation of USDZ as of 2023.

inputFile
Name of the input USD file to inspect. This is a required argument unless --dumpRules is specified.

-h, --help
Prints out a help message and exits.

-o, --out [output]
The file to which all the failed checks are output. If unspecified, the failed checks are output to stdout. If stderr is provided, terminal coloring will be suppressed.

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

--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 than usdz files for more general in-house uses, and this option attempts to ensure that these constraints are met.

-d, --dumpRules
Prints 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.

--variants
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 variants from the explicitly specified variantSets. This option is only valid when using the new validation framework.

--variantSets
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.

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

--version
Display program version information and exits.

Some options have specific requirements or cannot be used together:

--rootPackageOnly and --skipVariants cannot be used together.

Either an input file or the --dumpRules option must be specified.

The --variants, --variantSets, and --disableVariantValidationLimit options are only valid when using the new validation framework (which is the default).

The following validation tests are available. Some may only run when the --arkit option is provided, and some may enable extra rigidity based on other contexts.

The list of validation tests and their behaviour may change in future versions of this tool.

usdGeomValidators:StageMetadataChecker
All stages must declare their 'upAxis' and 'metersPerUnit'.

usdGeomValidators:SubsetFamilies
Validates all of the geom subset families authored beneath an Imageable prim.

usdGeomValidators:SubsetParentIsImageable
Validates that GeomSubset prims are direct descendants of an Imageable prim.

usdShadeValidators:EncapsulationRulesValidator
Connectable prims (e.g. Shader, Material, etc) can only be nested inside other Container-like Connectable prims. Container-like prims include Material, NodeGraph, Light, LightFilter. Shader is not a Container-like prim.

usdShadeValidators:MaterialBindingApiAppliedValidator
Verify a prim has the MaterialBindingAPI applied if it has a material binding relationship.

usdShadeValidators:MaterialBindingCollectionValidator
Verify that a collection defining a material binding is well-formed

usdShadeValidators:MaterialBindingRelationships
All properties named 'material:binding' or in that namespace should be relationships.

usdShadeValidators:NormalMapTextureValidator
UsdUVTexture nodes that feed the _inputs:normals_ of a UsdPreviewSurface must ensure that the data is encoded and scaled properly. Specifically, since normals are expected to be in the range [(-1,-1,-1), (1,1,1)], the Texture node must transform 8-bit textures from their [0..1] range by setting its _inputs:scale_ to (2, 2, 2, 1) and _inputs:bias_ to (-1, -1, -1, 0). Normal map data is commonly expected to be linearly encoded. However, many image-writing tools automatically set the profile of three-channel, 8-bit images to SRGB. To prevent an unwanted transformation, the UsdUVTexture's _inputs:sourceColorSpace_ must be set to raw.

usdShadeValidators:ShaderSdrCompliance
Shader prim's input types must be conforming to their appropriate sdf types in the respective sdr shader.

usdShadeValidators:SubsetMaterialBindFamilyName
Geom subsets with authored material bindings should have the 'materialBind' family name.

usdShadeValidators:SubsetsMaterialBindFamily
Geom subsets of the 'materialBind' family should have a restricted family type.

usdSkelValidators:SkelBindingApiAppliedValidator
Verify a prim has the SkelBindingAPI applied if it has a UsdSkelBinding property.

usdSkelValidators:SkelBindingApiValidator
Verify that a prim with SkelBindingAPI applied, is either of SkelRoot type or parented by a SkelRoot prim.

usdUtilsValidators:FileExtensionValidator
Only valid core layer extensions (.usd, .usda, .usdc, .usdz), valid core texture extensions (.exr, .jpg, .jpeg, .png) and embedded audio files (.M4A, .MP3, .WAV) are allowed in a package.

usdUtilsValidators:MissingReferenceValidator
The composed USD stage should not contain any unresolvable asset dependencies (in every possible variation of the asset), when using the default asset resolver.

usdUtilsValidators:PackageEncapsulationValidator
If the root layer is a package, then its recommended for the composed stage to not contain references to files outside the package. The package should be self-contained, warn if not.

usdUtilsValidators:UsdzPackageValidator
Files within all usdz packages within a stage should not be compressed or encrypted, and should be aligned to 64 bytes.

usdValidation:CompositionErrorTest
Validator aims at providing all composition errors, which were generated while composing the stage.

usdValidation:StageMetadataChecker
Stages that can be consumed as referenceable assets must have a valid 'defaultPrim' specified.

usdchecker exits with the following status codes:

0
Success. All validation checks passed, or only info messages were generated.

1
Failure. One or more validation errors were found, the stage failed to open, or invalid command-line arguments were provided. When --strict is specified, this code is also returned if any warnings are issued.

A file that passes the usdchecker may still have issues that the checker is not aware of.

usdchecker --arkit input.usdz
Checks the input USDZ for commonly known issues.

usdchecker --dumpRules --arkit
Display all validation rules that would be applied with the --arkit option.

usdchecker --strict --out report.txt input.usd
Check input.usd with strict validation (warnings cause failure) and write results to report.txt.

usdchecker --variants variantSet1:variant1,variantSet2:variant2 input.usd
Validate specific variant combinations in the input USD file.

usdchecker --skipVariants --verbose input.usdz
Check only the default variant selections with verbose output.