usdchecker - Utility for checking the compliance of a given USD
stage or a USDZ package.
usdchecker is a utility that verifies a file is a compliant
USD file.
Only the first time sample of any relevant time-sampled attribute
is checked.
General USD checks are always performed. An additional set of
checks may be enabled by specifying --arkit. This enables checks that
try and ensure the file is usable as distributable consumer content.
- -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 surpressed.
- -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.
- --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 support of
USD. 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
- 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 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.
- --variantSets
- 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.
- --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.
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.
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.