omni.asset_validator.core API

class omni.asset_validator.core.ValidationEngine(initRules: bool = True)

An engine for running rule-checkers on a given Omniverse Asset.

Rules are BaseRuleChecker derived classes which perform specific validation checks over various aspects of a USD layer/stage. Rules must be registered with the ValidationRulesRegistry and subsequently enabled on each instance of the ValidationEngine.

Validation can be performed asynchronously (using either validate_async or validate_with_callbacks) or blocking (via validate).

AssetType

A typedef for the assets that ValidationEngine can process. When it is a str, it is expected to be an Omniverse URI that can be accessed via the Omni Client Library. When it is a Usd.Stage, it will be validated directly without ever locating a file on disk/server. Note using a live Stage necessarily bypasses some validations (i.e. file I/O checks).

Type: Union[str,Usd.Stage]

AssetLocatedCallback

A typedef for the notification of asset(s) founds during ValidationEngine, validate_with_callbacks. The parameter is AssetType. It is invoked at the beginning of asset validation.

Type: Callable[[AssetType], None]

AssetValidatedCallback

A typedef for the notification of asset results found during ValidationEngine, validate_with_callbacks. The parameter is Result. It is invoked at the end of asset validation.

Type: Callable[[Results], None]

Example

Construct an engine and validate several assets using the default-enabled rules:

import omni.asset_validator.core

engine = omni.asset_validator.core.ValidationEngine()

# Validate a single Omniverse file
print( engine.validate('omniverse://localhost/NVIDIA/Samples/Astronaut/Astronaut.usd') )

# Validate a local file on disk. Windows paths must be pre-converted to Omniverse compatible paths
import omni.client
( status, localFile ) = omni.client.get_local_file('C:\\Users\\Public\\Documents\\test.usda')
if status == omni.client.Result.OK :
    print( engine.validate(localFile) )

# Search an Omniverse folder and recursively validate all USD files asynchronously
# note a running asyncio EvenLoop is required
task = engine.validate_with_callbacks(
    'omniverse://localhost/NVIDIA/Assets/ArchVis/Industrial/Containers/',
    asset_located_fn = lambda url: print(f'Validating "{url}"'),
    asset_validated_fn = lambda result: print(result),
)
task.add_done_callback(lambda task: print('validate_with_callbacks complete'))

# Perform the same search & validate but await the results
import asyncio
async def test(url):
    results = await engine.validate_async(url)
    for result in results:
        print(result)
asyncio.ensure_future(test('omniverse://localhost/NVIDIA/Assets/ArchVis/Industrial/Containers/'))

# Load a a layer onto a stage and validate it in-memory, including any unsaved edits
from pxr import Usd, Kind
stage = Usd.Stage.Open('omniverse://localhost/NVIDIA/Samples/Astronaut/Astronaut.usd')
prim = stage.DefinePrim(f'{stage.GetDefaultPrim().GetPath()}/MyCube', 'cube')
Usd.ModelAPI(prim).SetKind(Kind.Tokens.component)
print( engine.validate(stage) )

# Validate the current stage in any Kit based app (eg Create, View)
import omni.usd
print( engine.validate( omni.usd.get_context().get_stage() ) )

Parameters: initRules – Flag to default-enable Rules on this engine based on carb settings. Clients may wish to opt-out of this behavior to gain finer control over rule enabling at runtime.

static isAssetSupported(asset: Union[str, pxr.Usd.Stage]) → bool

Determines if the provided asset can be validated by the engine.

Parameters: asset – A single Omniverse Asset pointing to a file URI, folder/container URI, or a live Usd.Stage.
Returns: Whether the provided asset can be validated by the engine.

static describe(asset: Union[str, pxr.Usd.Stage]) → str

Provides a description of an Omniverse Asset.

Parameters: asset – A single Omniverse Asset pointing to a file URI, folder/container URI, or a live Usd.Stage.
Returns: The str description of the asset that was validated.

enableRule(rule: Type[omni.asset_validator.core.complianceChecker.BaseRuleChecker]) → None

Enable a given rule on this engine.

This gives control to client code to enable rules one by one. Rules must be BaseRuleChecker derived classes, and should be registered with the ValidationRulesRegistry before the are enabled on this engine.

Note many rules may have been pre-enabled if the engine was default-constructed with initRules=True.

Parameters: rule – A BaseRuleChecker derived class to be enabled

validate(asset: Union[str, pxr.Usd.Stage]) → omni.asset_validator.core.autofix.Results

Run the enabled rules on the given asset. (Blocking version)

Note Validation of folders/container URIs is not supported in the blocking version. Use validate_async or validate_with_callbacks to recursively validate a folder.

Parameters: asset – A single Omniverse Asset pointing to a file URI or a live Usd.Stage.
Returns: All issues reported by the enabled rules.

async validate_async(asset: Union[str, pxr.Usd.Stage]) → List[omni.asset_validator.core.autofix.Results]

Asynchronously run the enabled rules on the given asset. (Concurrent Version)

If the asset is a folder/container URI it will be recursively searched for individual asset files and each applicable URI will be validated, with all results accumulated and indexed alongside the respective asset.

Note even a single asset will return a List[Results], so it must be indexed via results[0].asset, results[0].failures, etc

Parameters: asset – A single Omniverse Asset. Note this can be a file URI, folder/container URI, or a live Usd.Stage.
Returns: All issues reported by the enabled rules, index aligned with their respective asset.

validate_with_callbacks(asset: Union[str, pxr.Usd.Stage], asset_located_fn: Optional[Callable[[Union[str, pxr.Usd.Stage]], None]] = None, asset_validated_fn: Optional[Callable[[omni.asset_validator.core.autofix.Results], None]] = None) → _asyncio.Task

Asynchronously run the enabled rules on the given asset. (Callbacks Version)

If the asset is validate-able (e.g. a USD layer file), asset_located_fn will be invoked before validation begins. When validation completes, asset_validated_fn will be invoked with the results.

If the asset is a folder/container URI it will be recursively searched for individual asset files and each applicable URL will be validated, with asset_located_fn and asset_validated_fn being invoked once per validate-able asset.

Parameters

asset – A single Omniverse Asset. Note this can be a file URI, folder/container URI, or a live Usd.Stage.
asset_located_fn – A callable to be invoked upon locating an individual asset. If asset is a single validate-able asset (e.g. a USD layer file) asset_located_fn will be called once. If asset is a folder/container URI asset_located_fn will be called once per validate-able asset within the container (e.g. once per USD layer file). Signature must be cb(AssetType) where str is the url of the located asset.
asset_validated_fn – A callable to be invoked when validation of an individual asset has completed. If asset is itself a single validate-able asset (e.g. a USD layer file) asset_validated_fn will be called once. If asset is a folder/container asset_validated_fn will be called once per validate-able asset within the container (e.g. once per USD layer file). Signature must be cb(results).

Returns

A task to control execution.

class omni.asset_validator.core.ValidationRulesRegistry

A registry enabling external clients to add new rules to the engine.

Rules must derive from omni.asset_validator.core.BaseRuleChecker and should re-implement the necessary virtual methods required for their specific check, as well as re-implementing GetDescripton() with an appropriate user-facing message.

Rules are registered to specific categories (str labels) to provide bulk enabling/disabling via carb settings and to make logical grouping in UIs or other documentation easier.

Example

Define a new Rule that requires all prims to be meshes or xforms (e.g. if your app only handles these types) and register it with the validation framework under a custom category:

import omni.asset_validator.core

@omni.asset_validator.core.registerRule("MyOwnRules")
class MyRuleChecker(omni.asset_validator.core.BaseRuleChecker):

    @staticmethod
    def GetDescription():
        return "Check that all prims are meshes for xforms"

    def CheckPrim(self, prim) -> None:
        self._Msg("Checking prim <%s>." % prim.GetPath())
        if prim.GetTypeName() not in ("Mesh", "Xform"):
            self._AddFailedCheck(
                f"Prim <{prim.GetPath()}> has unsupported type '{prim.GetTypeName()}'."
            )

By default all rules that ship with USD itself are registered into “Basic” and “ARKit” categories, though “ARKit” rules have been default disabled via carb settings.

static categories(enabledOnly: bool = False) → Tuple[str, ...]

Query all registered categories

Parameters: enabledOnly – Filter the results to only categories that are enabled (via carb settings)
Returns: A tuple of category strings that can be used in ValidationRulesRegistry.rules()

static rules(category: str, enabledOnly: bool = False) → Tuple[Type[omni.asset_validator.core.complianceChecker.BaseRuleChecker], ...]

Query all registered rules in a given category

Parameters

category – Filter for rules only in a specific category
enabledOnly – Filter the results to only rules that are enabled (via carb settings)

Returns

A tuple of BaseRuleChecker derived classes

static registerRule(rule: Type[omni.asset_validator.core.complianceChecker.BaseRuleChecker], category: str) → None

Register a new Rule to a specific category

Parameters

rule – A BaseRuleChecker derived class that implements a specific check
category – The label with which this rule will be associated

static deregisterRule(rule: Type[omni.asset_validator.core.complianceChecker.BaseRuleChecker]) → None

Remove a specific Rule from the registry

For convenience it is not required to specify the category, the rule will be removed from all categories, and subsequent empty categories will be removed from the registry.

Parameters: rule – A BaseRuleChecker derived class that implements a specific check

static rule(name: str) → Optional[Type[omni.asset_validator.core.complianceChecker.BaseRuleChecker]]

Query a registered rule by class name

Parameters: name – The exact (case sensitive) class name of a previously registered rule
Returns: A BaseRuleChecker derived class or None

static category(rule: Type[omni.asset_validator.core.complianceChecker.BaseRuleChecker]) → str

Query the category of a specific rule

Parameters: rule – A previously registered BaseRuleChecker derived class
Returns: A valid category name or empty string

core.registerRule() → Callable

Decorator. Register a new Rule to a specific category.

Example

Register MyRule into the category “MyCategory” so that becomes part of the default initialized ValidationEngine.

@registerRule("MyCategory")
class MyRule(BaseRuleChecker):
    pass

Parameters: category – The label with which this rule will be associated

class omni.asset_validator.core.BaseRuleChecker(verbose: bool, consumerLevelChecks: bool, assetLevelChecks: bool)

This is Base class for all the rule-checkers.

Parameters

verbose – Controls output (print) verbosity
consumerLevelChecks – Expands checks with coverage relevant to the general public/community (eg limit file types)
assetLevelChecks – Expand checks with asset (top) level coverage

static GetDescription(): Description used to describe the rule.

CheckStage(usdStage): Check the given usdStage.

CheckDiagnostics(diagnostics): Check the diagnostic messages that were generated when opening the USD stage. The diagnostic messages are collected using a UsdUtilsCoalescingDiagnosticDelegate.

CheckUnresolvedPaths(unresolvedPaths): Check or process any unresolved asset paths that were found when analysing the dependencies.

CheckDependencies(usdStage, layerDeps, assetDeps): Check usdStage’s layer and asset dependencies that were gathered using UsdUtils.ComputeAllDependencies().

CheckLayer(layer): Check the given SdfLayer.

CheckZipFile(zipFile, packagePath): Check the zipFile object created by opening the package at path packagePath.

CheckPrim(prim): Check the given prim, which may only exist is a specific combination of variant selections on the UsdStage.

ResetCaches(): Reset any caches the rule owns. Called whenever stage authoring occurs, such as when we iterate through VariantSet combinations.

class omni.asset_validator.core.TextureChecker(verbose, consumerLevelChecks, assetLevelChecks)

A RuleChecker which handles locating texture files automatically.

Derived classes can reimplement TextureChecker._CheckTexture.

CheckStage(usdStage): Check the given usdStage.

_CheckTexture(texAssetPath, inputPath)

Check the texture asset used by the shader input

Parameters

texAssetPath – The AssetPath for the texture file
inputPath – The SdfPath to the shader attribute that uses the texture

CheckPrim(prim): Check the given prim, which may only exist is a specific combination of variant selections on the UsdStage.

class omni.asset_validator.core.IssueSeverity(value): Defines the severity of an issue.

class omni.asset_validator.core.Issue(message: str, severity: omni.asset_validator.core.autofix.IssueSeverity, rule: Optional[omni.asset_validator.core.autofix.RuleType] = None, at=None, suggestion: Optional[omni.asset_validator.core.autofix.Suggestion] = None)

Issues capture information related to Validation Rules:

message

The reason this issue is mentioned.

Type: str

severity

The severity associated with the issue.

Type: IssueSeverity

rule

Optional. The class of rule detecting this issue.

Type: BaseRuleChecker

at

Optional. The Prim/Stage/Layer/SdfLayer/SdfPrim/etc.. where this issue arises.

Type: Identifier

suggestion

Optional. The suggestion to apply in form of a Callable(`stage`, `at`). Suggestion evaluation (i.e. suggestion()) could raise exception, in which case they will be handled by IssueFixer and mark as failed.

Type: Callable

The following exemplifies the expected arguments of an issue:

import omni.asset_validator.core

class MyRule(BaseRuleChecker):
    pass

stage = Usd.Stage.Open('omniverse://localhost/NVIDIA/Samples/Astronaut/Astronaut.usd')
prim = stage.GetPrimAtPath("/");

def my_suggestion(stage: Usd.Stage, at: Usd.Prim):
    pass

issue = omni.asset_validator.core.Issue(
    message="The reason this issue is mentioned",
    severity=IssueSeverity.ERROR,
    rule=MyRule,
    at=stage,
    suggestion=Suggestion(my_suggestion, "A good suggestion"),
)

classmethod from_message(severity: omni.asset_validator.core.autofix.IssueSeverity, message: str) → omni.asset_validator.core.autofix.Issue

Converts legacy messages into issues

Parameters

severity – The severity associated with the issue.
message – The message associated with the issue.

Returns

The resulting Issue.

classmethod from_(severity: omni.asset_validator.core.autofix.IssueSeverity, rule: omni.asset_validator.core.autofix.RuleType, message: str) → omni.asset_validator.core.autofix.Issue

Converts legacy results into issues

Parameters

severity – The severity associated with the issue.
rule – The rule class producing the issue.
message – The message associated with the issue.

Returns

The resulting issue.

class omni.asset_validator.core.Results(asset: str, issues: List[omni.asset_validator.core.autofix.Issue])

A collection of Issues.

Provides convenience mechanisms to filter Issues by IssuePredicates.

property asset: str: The Asset corresponding to these Results.

property errors: List[str]: Deprecated. Use the issues method.

property warnings: List[str]: Deprecated. Use the issues method.

property failures: List[str]: Deprecated. Use the issues method.

issues(predicate: Optional[Callable[[omni.asset_validator.core.autofix.Issue], bool]] = None) → List[omni.asset_validator.core.autofix.Issue]

Filter Issues using an option IssuePredicate.

Parameters: predicate – Optional. A predicate to filter the issues.
Returns: A list of issues matching the predicate or all issues.

remove_issues(predicate: Callable[[omni.asset_validator.core.autofix.Issue], bool]) → None

Remove Issues from the Results.

Convenience to purge issues that can be ignored or have already been processed.

Parameters: predicate – Optional. A predicate to filter issues.

class omni.asset_validator.core.IssuePredicates

Convenient methods to filter issues. Additionally, provides And and Or predicates to chain multiple predicates, see example below.

import omni.asset_validator.core

issues = [
    omni.asset_validator.core.Issue.from_message(
        omni.asset_validator.core.IssueSeverity.ERROR, "This is an error"),
    omni.asset_validator.core.Issue.from_message(
        omni.asset_validator.core.IssueSeverity.WARNING, "Important warning!"),
]
filtered = list(filter(
    omni.asset_validator.core.IssuePredicates.And(
        omni.asset_validator.core.IssuePredicates.IsError(),
        omni.asset_validator.core.IssuePredicates.ContainsMessage("Important"),
    ),
    issues
))

class omni.asset_validator.core.FixStatus(value): Result of fix status.

class omni.asset_validator.core.FixResult(issue: omni.asset_validator.core.autofix.Issue, status: omni.asset_validator.core.autofix.FixStatus, exception: Optional[Exception] = None)

FixResult is a combination of input and output to the IssueFixer.

issue

The issue originating this result. Useful for back tracing.

Type: omni.asset_validator.core.autofix.Issue

status

The status of processing the issue, See FixStatus.

Type: omni.asset_validator.core.autofix.FixStatus

exception

Optional. If the status is a Failure, it will contain the thrown exception.

Type: Optional[Exception]

class omni.asset_validator.core.IssueFixer(asset)

Fixes issues for the given Asset.

asset

An in-memory Usd.Stage, either provided directly or opened from a URI pointing to a Usd layer file.

Type: Usd.Stage

import omni.asset_validator.core

# validate a layer file
engine = omni.asset_validator.core.ValidationEngine()
results = engine.validate('omniverse://localhost/NVIDIA/Samples/Astronaut/Astronaut.usd')
issues = results.issues()

# fix that layer file
fixer = omni.asset_validator.core.IssueFixer('omniverse://localhost/NVIDIA/Samples/Astronaut/Astronaut.usd')
fixer.fix(issues)
fixer.save()

# fix a live stage directly
stage = Usd.Stage.Open('omniverse://localhost/NVIDIA/Samples/Astronaut/Astronaut.usd')
engine = omni.asset_validator.core.ValidationEngine()
results = engine.validate(stage)
issues = results.issues()

# fix that same stage in-memory
fixer = omni.asset_validator.core.IssueFixer(stage)
fixer.fix(issues)
fixer.save()

fix(issues: List[omni.asset_validator.core.autofix.Issue]) → List[omni.asset_validator.core.autofix.FixResult]

Fix the specified issues.

Parameters: issues – The list of issues to fix.
Returns: An array with the resulting status (i.e. FixResult) of each issue.

fix_at(issues: List[omni.asset_validator.core.autofix.Issue], layer: pxr.Sdf.Layer) → List[omni.asset_validator.core.autofix.FixResult]

Fix the specified issues persisting on a provided layer.

Parameters

issues – The list of issues to fix.
layer – Layer where to persist the changes.

Returns

An array with the resulting status (i.e. FixResult) of each issue.

property fixed_layers: List[pxr.Sdf.Layer]

The layers affected by fix or fix_at methods.

Type: Returns

save() → None: Save the Asset to disk. :raises IOError: If writing permissions are not granted.

class omni.asset_validator.core.Suggestion(callable: Callable[[pxr.Usd.Stage, Union[pxr.Usd.Stage, pxr.Usd.Prim, pxr.Usd.Attribute]], None], message: str): A suggestion is a combination of a callable and a message describing the suggestion.