Python API#

omni.asset_validator.core API#

class omni.asset_validator.core.AssetLocatedCallback(*args, **kwargs)#

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

Parameters:: asset (AssetType) – The asset type located.

class omni.asset_validator.core.AssetProgress(asset: str, progress: float)#

Keeps track of the progress for a particular asset.

asset#

The identifier of the asset, i.e. the result of Usd.Describe.

Type:: str

progress#

The percent of progress (between 0 and 1, both inclusive).

Type:: float

class omni.asset_validator.core.AssetProgressCallback(*args, **kwargs)#

A typedef for the notification of asset progress found during ValidationEngine.validate_with_callbacks().

Parameters:: progress (AssetProgress) – The progress for a specific asset.

class omni.asset_validator.core.AssetValidatedCallback(*args, **kwargs)#

A typedef for the notification of asset results found during ValidationEngine.validate_with_callbacks().

Parameters:: results (Results) – The results for a specific asset.

class omni.asset_validator.core.AttributeId( prim_id: PrimId, path: Path, )#

A unique identifier of an attribute, i.e. a combination of prim definition and attribute name.

classmethod from_( attr: Attribute, ) → AttributeId#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

omni.asset_validator.core.AuthoringLayers( at: AtType | list[AtType], ) → list[Layer]#

omni.asset_validator.core.AuthoringLayers( prop: Property | Attribute | Relationship, ) → list[Layer]

omni.asset_validator.core.AuthoringLayers(primvar: Primvar) → list[Layer]

omni.asset_validator.core.AuthoringLayers( at_list: list[AtType], ) → list[Layer]

Parameters:: at (AtType | list[AtType]) – The location to compute the authoring layers.
Returns:: The layers (from stronger to weaker) where the at is authored.

class omni.asset_validator.core.BaseRuleChecker(

verbose: bool = False,

consumerLevelChecks: bool = False,

assetLevelChecks: bool = True,

*args,

parameters: ParameterMapping | None = None,

**kwargs,

)#

This is Base class for all the rule-checkers.

Parameters:

verbose – Deprecated parameter, kept for backward compatibility. Not used in new rules.
consumerLevelChecks – Deprecated parameter, kept for backward compatibility. Not used in new rules.
assetLevelChecks – Deprecated parameter, kept for backward compatibility. Not used in new rules.
parameters – Optional ParameterMapping instance containing rule checker configuration.

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

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

CheckLayer(layer)#: Check the given SdfLayer.

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

CheckStage(usdStage)#: Check the given usdStage.

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

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

classmethod GetDescription()#: Returns the docstring describing the rule.

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

property parameters: ParameterMapping#

Access the ParameterMapping instance containing rule checker configuration.

Returns:: The ParameterMapping instance (never None; defaults to empty ParameterMapping if not provided).

class omni.asset_validator.core.Capability(*args, **kwargs)#

A protocol definition of capability.

id#

A unique identifier of the capability

Type:: str

version#

The version of the capability

Type:: str

path#

The path to the capability

Type:: str

requirements#

The requirements of the capability

Type:: list[omni.asset_validator._impl._requirements.Requirement]

omni.asset_validator.core.CapabilityRegistry()#: A singleton class that keeps capabilities.

class omni.asset_validator.core.FixResult( issue: Issue, status: FixStatus, exception: Exception | None = None, )#

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

issue#

The issue originating this result. Useful for back tracing.

Type:: Issue

status#

The status of processing the issue, See FixStatus.

Type:: FixStatus

exception#

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

Type:: Exception

class omni.asset_validator.core.FixStatus( value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None, )#

Result of fix status.

FAILURE = 2#: A fix was applied, however it resulted into a failure (i.e. Exception). Check stack trace for more information.

INVALID_LOCATION = 5#: A fix could not be performed as the location is no longer valid.

NO_LAYER = 4#: A fix was applied at a specific layer, however the layer is not found in the layer stack.

NO_LOCATION = 0#: A fix could not be performed as there was no location where to apply a suggestion.

NO_SUGGESTION = 1#: A fix could not be performed as there was no suggestion to apply.

SUCCESS = 3#: A fix was successfully applied.

class omni.asset_validator.core.Identifier#

An Identifier is a stateful representation of an Usd object (i.e. Usd.Prim). A identifier can convert back to a live Usd object.

classmethod from_( obj: AtType, ) → Identifier[AtType]#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

get_spec_ids() → list[EditTargetId]#

Returns:: The list of all possible prim specs i.e., path and layer ids associated to this identifier.

restore( stage: Stage, ) → AtType#

Convert this stateful identifier to a live object.

Parameters:: stage (Usd.Stage) – The stage to use to restore the object.
Returns:: An Usd object.

Issues capture information related to Validation Rules:

message#

The reason this issue is mentioned.

Type:: str | None

severity#

The severity associated with the issue.

Type:: IssueSeverity | None

rule#

Optional. The class of rule detecting this issue.

Type:: Type[BaseRuleChecker] | None

at#

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

Type:: Identifier[AtType] | None

suggestion#

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

Type:: Suggestion | None

asset#

Optional. The asset where this Issue happens.

Type:: StageId | None

code#

Optional. The code or identifierof the issue.

Type:: str | None

requirement#

Optional. The requirement that this issue belongs to. When requirement is provided, code and message are ignored.

Type:: Requirement | None

The following exemplifies the expected arguments of an issue:

import omni.asset_validator

class MyRule(BaseRuleChecker):
    pass

stage = Usd.Stage.Open('foo.usd')
prim = stage.GetPrimAtPath("/");

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

issue = omni.asset_validator.Issue(
    identifier=SemanticLabelsRequirements.SL_001.code,
    message=SemanticLabelsRequirements.SL_001.message,
    severity=IssueSeverity.ERROR,
    rule=MyRule,
    at=stage,
    suggestion=Suggestion(my_suggestion, "A good suggestion"),
)

property all_fix_sites: list[EditTargetId]#: Returns: A list of all possible fix sites.

property default_fix_site: EditTargetId | None#: Returns: The default fix site. The default fix site is generally the Node at root layer. Rules can override this behavior by supplying Suggestion.at locations.

classmethod none() → Issue#: Returns: Singleton object representing no Issue.

class omni.asset_validator.core.IssueCSVData( headers: list[str] = <factory>, assets: list[str] = <factory>, rules: list[str] = <factory>, messages: list[str] = <factory>, severities: list[str] = <factory>, suggestions: list[str] = <factory>, ats: list[str] = <factory>, additional_column: dict[str, list[str]] = <factory>, )#

A class for organizing and exporting issue data into a CSV format.

Parameters:

headers (list[str]) – The headers for the CSV columns. By default, it includes “Asset”, “Rule”, “Message”, “Suggestion”, and “Location”.
assets (list[str]) – The list of assets associated with the issues.
rules (list[str]) – The list of rules corresponding to each issue.
messages (list[str]) – Detailed messages for each issue.
suggestions (list[str]) – Suggestions for each issue.
ats (list[str]) – Locations of the issues.
additional_column (dict[str, list[str]]) – Additional custom columns that can be appended dynamically.

append_column( header: str, values: Sequence[str], )#: Appends a custom column to the IssueCSVData instance with the given header and corresponding values.

export_csv( file_url: str | Path, headers: list[str] | None = None, delimiter: str = ',', )#

Exports the issue data to a CSV file at the given file path. This method writes the issue data into a CSV format using the specified file path. The default available headers are: “Asset”, “Rule”, “Severity”, “Message”, “Suggestion”, and “Location”.

Parameters:

file_url – str | pathlib.Path - The file path to write the CSV data to.
headers – list[str] | None - An optional list of headers to include in the CSV.
delimiter – str - The delimiter to use in the CSV.

Example:

result = await engine.validate_async(path)
csvdata = IssueCSVData.from_(result)
csvdata.append_column("idx", [str(idx) for idx in range(40)])
csvdata.export_csv("/path/to/test.csv")

classmethod from_( value: Issue | list[Issue] | IssuesList | Results | ResultsList, )#: Creates an instance of IssueCSVData from given input.

get_csv_as_str( headers: list[str] | None = None, delimiter: str = ',', ) → str#

Returns a string containing the list the data in CSV format. The result can be written to a file using regular file operations, or copied to the clipboard. :param headers: list[str] | None - An optional list of headers to include in the CSV. :param delimiter: str - The delimiter to use in the CSV.

Returns:: A string containing the list the data in CSV format.

class omni.asset_validator.core.IssueFixer( asset: str | ~pxr.Usd.Stage, layers: set[~pxr.Sdf.Layer] = <factory>, lock: ~_thread.allocate_lock = <factory>, )#

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

# validate a layer file
engine = omni.asset_validator.ValidationEngine()
results = engine.validate('foo.usd')
issues = results.issues()

# fix that layer file
fixer = omni.asset_validator.IssueFixer('foo.usd')
fixer.fix(issues)
fixer.save()

# fix a live stage directly
stage = Usd.Stage.Open('foo.usd')
engine = omni.asset_validator.ValidationEngine()
results = engine.validate(stage)
issues = results.issues()

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

apply( issue: Issue, at: Identifier[AtType] | None = None, ) → FixResult#

Fix the specified issues persisting on a specific identifier. If no identifier is given, the default fix site is used.

Parameters:

issue (Issue) – The issue to fix.
at (Identifier[AtType] | None) – Optional. Apply the changes in a different site.

Returns:

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

fix( issues: list[Issue], ) → Sequence[FixResult]#

Fix the specified issues in the default layer of each issue.

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

fix_at( issues: list[Issue], layer: Layer, ) → Sequence[FixResult]#

Fix the specified issues persisting on a provided layer.

Parameters:

issues (List[Issue]) – The list of issues to fix.
layer (Sdf.Layer) – Layer where to persist the changes.

Returns:

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

property fixed_layers: list[Layer]#: Returns: The layers affected by fix or fix_at methods.

save() → None#

Save the Asset to disk.

Raises:: OSError – If writing permissions are not granted.

class omni.asset_validator.core.IssueGroupBy(*args, **kwargs)#

An IssueGroupBy is a callable that returns a list linking an Issue to a specific group.

Parameters:: issues (list[Issue]) – The issues to group.
Returns:: A list of tuples, where the first element is the group name and the second element is the issue.
Return type:: (list[tuple[Any, Issue]])

class omni.asset_validator.core.IssueGroupsBy#

Convenient methods to group issues.

Examples

Group by messages.

import collections
import omni.asset_validator

issues = [
    omni.asset_validator.Issue(
        severity=omni.asset_validator.IssueSeverity.ERROR,
        message="This is an error at Prim1",
        rule=omni.asset_validator.TypeChecker),
    omni.asset_validator.Issue(
        severity=omni.asset_validator.IssueSeverity.ERROR,
        message="This is an error at Prim2",
        rule=omni.asset_validator.TypeChecker),
]
groups = set()
for group, issue in omni.asset_validator.IssueGroupsBy.message()(issues):
    groups.add(group)
print(groups)

Output

{'This is an error at .*'}

Groups by rule.

import collections
import omni.asset_validator

issues = [
    omni.asset_validator.Issue(
        severity=omni.asset_validator.IssueSeverity.ERROR,
        message="This is an error at Prim1",
        rule=omni.asset_validator.TypeChecker),
    omni.asset_validator.Issue(
        severity=omni.asset_validator.IssueSeverity.ERROR,
        message="This is an error at Prim2",
        rule=omni.asset_validator.TypeChecker),
]
groups = set()
for group, issue in omni.asset_validator.IssueGroupsBy.rule()(issues):
    groups.add(group)
print(groups)

Output

{<class 'omni.asset_validator.TypeChecker'>}

Groups by severity.

import collections
import omni.asset_validator

issues = [
    omni.asset_validator.Issue(
        severity=omni.asset_validator.IssueSeverity.ERROR,
        message="This is an error at Prim1",
        rule=omni.asset_validator.TypeChecker),
    omni.asset_validator.Issue(
        severity=omni.asset_validator.IssueSeverity.ERROR,
        message="This is an error at Prim2",
        rule=omni.asset_validator.TypeChecker),
]
groups = set()
for group, issue in omni.asset_validator.IssueGroupsBy.severity()(issues):
    groups.add(group)
print(groups)

{<IssueSeverity.ERROR: 0>}

classmethod asset() → IssueGroupBy#: Returns a list of tuples with the issue asset and the issue.

classmethod code() → IssueGroupBy#: Returns a list of tuples with the issue code and the issue.

classmethod message() → IssueGroupBy#: Returns a list of tuples with the issue message and the issue.

classmethod requirement() → IssueGroupBy#: Returns a list of tuples with the issue requirement code and the issue.

classmethod rule() → IssueGroupBy#: Returns a list of tuples with the issue rule and the issue.

classmethod rule_name() → IssueGroupBy#: Returns a list of tuples with the issue rule name and the issue.

classmethod severity() → IssueGroupBy#: Returns a list of tuples with the issue severity and the issue.

class omni.asset_validator.core.IssueJSONEncoder(

rules: list[BaseRuleChecker] | None = None,

*args,

**kwargs,

)#

Custom JSON encoder for serializing various issue-related objects into a structured JSON format.

This encoder handles serializing Results, ResultsList, IssuesList, Issue, Suggestion, Identifier and list of Issues.

default(o: Any) → Any#

default( o: Results, ) → Any

default( o: ResultsList, ) → Any

default( o: IssuesList | list[Issue], ) → Any

default( o: Issue, ) → Any

default( o: Suggestion, ) → Any

default( o: PrimId, ) → Any

default( o: PropertyId, ) → Any

default( o: LayerId, ) → Any

default( o: StageId, ) → Any

default( o: EditTargetId, ) → Any

default( o: SchemaBaseId, ) → Any

default( o: IssueSeverity, ) → Any

default( o: Type, ) → Any

default(o: Path) → Any

default( o: type[BaseRuleChecker], ) → Any

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

class omni.asset_validator.core.IssuePredicate(*args, **kwargs)#

An IssuePredicate is a callable that returns True or False for a specific Issue.

Parameters:: issue (Issue) – The issue to check.
Returns:: True if the issue matches the predicate, False otherwise.
Return type:: (bool)

class omni.asset_validator.core.IssuePredicates#

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

import omni.asset_validator

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

static And( *predicates, ) → IssuePredicate#

Parameters:: predicates – One or more IssuePredicate.
Returns:: A predicate joining predicates by and condition.

static Any() → IssuePredicate#

Returns:: A dummy filter that does not filter.

static ContainsMessage( text: str, ) → IssuePredicate#

Parameters:: text – A specific text to filter the message in issues.
Returns:: A filter for messages containing text.

static HasCode() → IssuePredicate#

Returns:: A filter for issues with requirement identifier.

static HasFix() → IssuePredicate#

Returns:: A filter for issues with a fix.

static HasLocation() → IssuePredicate#

Returns:: A filter for issues with location, i.e. at

static HasRootLayer() → IssuePredicate#

Returns:: A filter for issues with a root layer.

static HasTag( tag: str, ) → IssuePredicate#

Returns:: A filter for issues with specific tag.

static IsError() → IssuePredicate#

Returns:: A filter for Issues marked as errors.

static IsFailure() → IssuePredicate#

Returns:: A filter for Issues marked as failure.

static IsInfo() → IssuePredicate#

Returns:: A filter for Issues marked as infos.

static IsRule( rule: str | RuleType, ) → IssuePredicate#

Parameters:: rule (str | RuleType) – The rule to filter.
Returns:: A filter for issues with the rule.

static IsSuccess() → IssuePredicate#

Returns:: A filter for Issues marked as success, i.e. IssueSeverity.NONE.

static IsWarning() → IssuePredicate#

Returns:: A filter for Issues marked as warnings.

static MatchesAnyCode( codes: Sequence[str], ) → IssuePredicate#

Returns:: A filter for issues with matching code.

static MatchesCode( code: str, ) → IssuePredicate#

Returns:: A filter for issues with matching code.

static MatchesToken( token: str, ) → IssuePredicate#

Returns:: A filter for issues with matching token.

static Not( predicate: IssuePredicate, ) → IssuePredicate#

Returns:: A predicate joining predicates by not condition.

static Or( *predicates, ) → IssuePredicate#

Parameters:: predicates – One or more IssuePredicate.
Returns:: A predicate joining predicates by or condition.

class omni.asset_validator.core.IssueSeverity( value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None, )#

Defines the severity of an issue.

ERROR = 0#: The issue is the result of an actual exception/failure in the code.

FAILURE = 1#: An indication that it is failing to comply with a specific rule.

INFO = 3#: Information that needs to be reported by the validation rules.

NONE = 4#: No issue.

WARNING = 2#: A warning is a suggestion to improve USD, it could be related to performance or memory.

class omni.asset_validator.core.IssuesList( issues: list[~omni.asset_validator._impl._issues.Issue] = <factory>, success: list[~omni.asset_validator._impl._issues.Issue] = <factory>, name: ~typing.Any | None = None, )#

A list of issues, provides convenient features to filter/group by issues.

issues#

The issues in the list.

Type:: list[Issue]

success#

The issues that are not issues.

Type:: list[Issue]

name#

The name of the list.

Type:: Any | None

filter_by( predicate: IssuePredicate | None = None, ) → IssuesList#

Parameters:: predicate – The predicate to filter issues.
Returns:: A subset of the issues for which the predicate is True.

group_by( group_by: IssueGroupBy | None = None, ) → list[IssuesList]#

Parameters:: group_by – A grouping function.
Returns:: All groups generated by the grouping function.

merge( other: IssuesList, ) → IssuesList#

Parameters:: other – Another issue group.
Returns:: A new group that combines both existing groups.

class omni.asset_validator.core.LayerId(identifier: str)#

A unique identifier to layer, i.e. identifier.

identifier#

The unique identifier of this layer.

Type:: str

classmethod from_( layer: Layer, ) → LayerId#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

get_spec_ids() → list[EditTargetId]#

Returns:: The list of all possible prim specs i.e., path and layer ids associated to this identifier.

restore(stage: Stage) → Layer#

Convert this stateful identifier to a live object.

Parameters:: stage (Usd.Stage) – The stage to use to restore the object.
Returns:: An Usd object.

class omni.asset_validator.core.PrimId( stage_id: StageId, path: Path, spec_ids: SpecIdList, variant_selection_path: Path = Sdf.Path.emptyPath, )#

A unique identifier of a prim, i.e. a combination of Stage definition and a list of Specs.

stage_id#

An identifier to the stage this prim exists.

Type:: StageId

path#

The path to this prim.

Type:: Sdf.Path

spec_ids#

The list of specifications as found in the stage.

Type:: SpecIdList

variant_selection_path#

The variant selection path for this prim.

Type:: Sdf.Path

classmethod from_( prim: Prim, ) → PrimId#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

get_spec_ids() → list[EditTargetId]#

Returns:: The list of all possible prim specs i.e., path and layer ids associated to this identifier.

restore(stage: Stage) → Prim#

Convert this stateful identifier to a live object.

Parameters:: stage (Usd.Stage) – The stage to use to restore the object.
Returns:: An Usd object.

class omni.asset_validator.core.Profile(*args, **kwargs)#

A protocol definition of profile.

id#

A unique identifier of the profile

Type:: str

version#

The version of the profile

Type:: str

path#

The path to the profile

Type:: str

capabilities#

The capabilities of the profile

Type:: list[omni.asset_validator._impl._capabilities.Capability]

omni.asset_validator.core.ProfileRegistry()#: A singleton class that keeps profiles.

class omni.asset_validator.core.PropertyId( prim_id: PrimId, path: Path, )#

A unique identifier of a property, i.e. a combination of prim definition and property path.

prim_id#

An identifier to the prim containing this property.

Type:: PrimId

path#

The path to this property.

Type:: Sdf.Path

classmethod from_( prop: Property, ) → PropertyId#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

get_spec_ids() → list[EditTargetId]#

Returns:: The list of all possible prim specs i.e., path and layer ids associated to this identifier.

restore(stage: Stage) → Property#

Convert this stateful identifier to a live object.

Parameters:: stage (Usd.Stage) – The stage to use to restore the object.
Returns:: An Usd object.

class omni.asset_validator.core.RepeatedValuesSet#

A class that finds and manages repetitions in a sequence of values.

This class identifies repeated values in a sequence and maps each value to its first occurrence. It supports both standard Python and NumPy implementations for performance optimization.

_indices#: List of indices where each index points to the first occurrence of its value.

class omni.asset_validator.core.Requirement(*args, **kwargs)#

A protocol definition of requirement.

code#

A unique identifier of the requirement

Type:: str

display_name#

The name of the requirement (optional)

Type:: str | None

message#

A basic description of the requirement (optional)

Type:: str | None

path#

Relative path in documentation (optional)

Type:: str | None

tags#

Tags of the requirement (optional)

Type:: tuple[str, …]

version#

The version of the requirement

Type:: str | None

parameters#

The collection of parameters associated with the requirement (optional)

Type:: tuple[omni.asset_validator._impl._parameters.Parameter, …]

omni.asset_validator.core.RequirementsRegistry()#: A singleton class that keeps requirements and maps them to rules.

class omni.asset_validator.core.Results( asset: str, issues: list[~omni.asset_validator._impl._issues.Issue] | ~omni.asset_validator._impl._issues.IssuesList = <factory>, )#

A collection of Issue.

Provides convenience mechanisms to filter Issue by IssuePredicates.

asset#

The asset.

Type:: str

issues#

The issues.

Type:: list[Issue] | IssuesList

classmethod create( asset: Stage | str, issues: Sequence[Issue], ) → Results#

Convenience method. The only difference with constructor is that it will link the issues with the asset.

Parameters:

asset (Usd.Stage | str) – The asset.
issues (List[Issue]) – A list of issues to associate with asset.

Returns:

A new Results object.

filter_by( predicate: IssuePredicate, ) → Results#: Filter the issues by the given predicate.

class omni.asset_validator.core.ResultsList(results: 'list[Results]' = <factory>)#

issues() → IssuesList#: Returns: A list with all the issues.

class omni.asset_validator.core.SchemaBaseId( prim_id: PrimId, schema_class: Any, instance_name: str | None, )#

A unique identifier of a UsdSchemaBase, i.e. a combination of prim definition and its real type class.

prim_id#

An identifier to the prim this schema is applied or typed to.

Type:: PrimId

schema_class#

The real type class that’s inherited from UsdSchemaBase.

Type:: Any

classmethod from_( instance: SchemaBase, ) → SchemaBaseId#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

get_spec_ids() → list[EditTargetId]#

Returns:: The list of all possible prim specs i.e., path and layer ids associated to this identifier.

restore(stage: Stage) → Any#

Convert this stateful identifier to a live object.

Parameters:: stage (Usd.Stage) – The stage to use to restore the object.
Returns:: An Usd object.

omni.asset_validator.core.SpecId#: alias of EditTargetId

class omni.asset_validator.core.SpecIdList( spec_ids: list[EditTargetId], )#

A snapshot of a list of PcpNodeRefs.

spec_ids#

The list of prim specifications.

Type:: list[SpecId]

class omni.asset_validator.core.StageId(root_layer: LayerId)#

A unique identifier to stage, i.e. identifier.

root_layer#

Identifier representing the root layer.

Type:: LayerId

classmethod from_( stage: Stage, ) → StageId#

Parameters:: obj (AtType) – An Usd Object.
Returns:: A stateful representation of an Usd object.

get_spec_ids() → list[EditTargetId]#

Returns:: The list of all possible prim specs i.e., path and layer ids associated to this identifier.

restore(stage: Stage) → Stage#

Convert this stateful identifier to a live object.

Parameters:: stage (Usd.Stage) – The stage to use to restore the object.
Returns:: An Usd object.

class omni.asset_validator.core.Suggestion( callable: Callable[[Stage, AtType], None], message: str, at: list[Identifier[AtType]] | None = None, )#

A suggestion is a combination of a callable and a message describing the suggestion.

callable#

A proposed fix to an issue.

Type:: Callable[[Usd.Stage, AtType], None]

message#

A proposed solution to an issue.

Type:: str

at#

Optional. The Layer/SdfLayer/etc… where the issue can be fixed.

Type:: List[Identifier[AtType]] | None

omni.asset_validator.core.ValidationArgsExec#: alias of ValidationNamespaceExec

class omni.asset_validator.core.ValidationEngine( *, init_rules: bool = True, variants: bool = True, 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()).

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') )

# 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 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 (e.g. Create, View)
import omni.usd
print( engine.validate( omni.usd.get_context().get_stage() ) )

property initialized_rules: list[type[BaseRuleChecker]]#: Returns: A list of rules that have been initialized.

class omni.asset_validator.core.ValidationRulesRegistry#

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

Rules must derive from BaseRuleChecker and should re-implement the necessary virtual methods required for their specific check, as well as documenting 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):
    '''Check that all prims are meshes for xforms'''

    def CheckPrim(self, prim) -> None:
        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” category. “AtomicAsset” rules have been default disabled via carb settings.

static add_registry_rule_callback( callback: Callable[[], None], ) → EventListener#: Add a callback to be called when a rule is registered or deregistered. It returns a subscription object that can be used to unsubscribe.

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 rules()

static category( rule: type[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

static deregisterRule( rule: type[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 init()#: This is a wrapper over the category rules registry. However, some rules appear under different names due to specialization happening in this kit extension package, to avoid these problems we clear the current registry.

static registerRule( rule: type[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 rule( name: str, ) → type[BaseRuleChecker] | None#

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 rules( category: str, enabledOnly: bool = False, ) → tuple[type[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

class omni.asset_validator.core.ValidationStats#

A specific implementation of statistics for validation. Apart from the generic methods, it includes: - add/get: A global counter. - time_rule: Measure the time spent executing a rule. - count_rule_severity: Keep track of rule, severity found in issues.

count_rule_severity( rule: _RuleType, severity: Enum, ) → None#: Keep track of rule, severity found in issues.

time_rule( rule: _RuleType, ) → _TimeStat#: Measure the time spent executing a rule.

class omni.asset_validator.core.VariantIdMixin#

Mixin class for handling variant selection paths for USD prims.

This class provides utility methods to retrieve and restore variant selections for USD prims, making it easier to work with variant hierarchies.

static get_variant_selection_path( prim: Prim, ) → Path#

Return a Sdf.Path with variant selection encoded.

For Example:: Sdf.Path(“/World/asset{variantA=aaa}child{variantB=bbb}{variantC=ccc}group/mesh.extent”)

omni.asset_validator.core.add_registry_rule_callback( callback: Callable[[], None], ) → EventListener#

Add a callback to be called when a rule is registered or deregistered. It returns a subscription object that can be used to unsubscribe.

Example:

subscription = add_registry_rule_callback(lambda: print("Rule registered"))

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

# Output:
# Rule registered

omni.asset_validator.core.create_validation_parser() → ArgumentParser#

Creates an argument parser with common options, this includes:

For ValidationEngine:

init-rules/no-init-rules: Optional. Default True. Sets ValidationEngine, init_rules argument.
variants/no-variants: Optional. Default True. Sets ValidationEngine, variants argument.
rule/disable-rule: Optional. Enables/Disable rules in ValidationEngine.
category/disable-category. Optional. Enable/Disable categories in ValidationEngine.
asset. Required. The asset in which to perform validation.

enable-rule and enable-category are alias for rule and category respectively.

For IssueFixer:

predicate: Optional. Issues to filter for IssueFixer.
fix/no-fix: Optional. Whether to apply IssueFixer after ValidationEngine.

Other options: - version: Print the version of omni.asset_validator.

omni.asset_validator.core.get_version()#

Returns: The version of this module.

omni.asset_validator.core.is_omni_path(path: Path) → bool#

Parameters:: path – An Sdf Path object.
Returns:: True if this is used internally by Omniverse.

omni.asset_validator.core.is_omni_skel_upgrade_disabled() → bool#: Returns: OmniSkelUpgradeChecker must be disabled for Kit 106.

omni.asset_validator.core.normalize_url(path_or_url: str) → str#: Normalizes url to create uniform format of url, which can be used to compare with other normalized urls to check the equality between urls. It does the following normalization: 1. It replaces backslashes into forward slashes. 2. It capitalizes disk drive letter for windows paths. 3. It simplifies parts of relative path.

omni.asset_validator.core.registerRule( category: str, skip: bool = False, overwrite: type[BaseRuleChecker] | None = None, ) → Callable[[type[BaseRuleChecker]], type[BaseRuleChecker]]#

Decorator. Register a new BaseRuleChecker 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 (str) – The label with which this rule will be associated
skip (bool) – Whether to skip rule registration. Default false.

omni.asset_validator.core.register_requirements( *requirements: Requirement, override: bool = False, ) → Callable[[type[BaseRuleChecker]], type[BaseRuleChecker]]#

Decorator. Register a new BaseRuleChecker to a set of requirements.

@register_requirements(Requirement1, Requirement2)
class MyRule(BaseRuleChecker):
    ...

To override a registered rule, use the override parameter.

@register_requirements(Requirement1, override=True)
class MyRule(BaseRuleChecker):
    ...

omni.asset_validator.core.to_identifier( value: AtType | None, ) → Identifier[AtType] | None#

omni.asset_validator.core.to_identifier( value: Identifier[AtType], ) → Identifier[AtType]

omni.asset_validator.core.to_identifier(value: None) → None

omni.asset_validator.core.to_identifier( value: Attribute, ) → AttributeId

omni.asset_validator.core.to_identifier( value: Property, ) → PropertyId

omni.asset_validator.core.to_identifier( value: Relationship, ) → RelationshipId

omni.asset_validator.core.to_identifier( value: Primvar, ) → PrimvarId

omni.asset_validator.core.to_identifier( value: Prim, ) → PrimId

omni.asset_validator.core.to_identifier( value: Stage, ) → StageId

omni.asset_validator.core.to_identifier( value: Layer, ) → LayerId

omni.asset_validator.core.to_identifier( value: Spec, ) → EditTargetId

omni.asset_validator.core.to_identifier( value: SchemaBase, ) → SchemaBaseId

Parameters:: value (AtType | None) – An USD object.
Returns:: An identifier (i.e. stateful representation) to a USD object.

omni.asset_validator.core.to_identifiers( value: list[AtType] | None, ) → list[Identifier[AtType]] | None#

Iterative version of to_identifier.

Parameters:: value (list[AtType] | None) – A list of USD objects.
Returns:: A list of identifiers (i.e. stateful representation) to a USD object.

omni.asset_validator.core.tests API#

class omni.asset_validator.core.tests.AsyncValidationRuleTestCase(*args: Any, **kwargs: Any)#: Specific implementation of AsyncioValidationTestCaseMixin for core tests.

class omni.asset_validator.core.tests.AsyncioValidationTestCaseMixin#

A mixin for asyncio test cases to simplify testing of individual Validation Rules.

Example

from unittest import IsolatedAsyncioTestCase
from omni.asset_validator.tests import AsyncioValidationTestCaseMixin

class AsyncioValidationTestCase(IsolatedAsyncioTestCase, AsyncioValidationTestCaseMixin):
    ...

class MyTestCase(AsyncioValidationTestCase):
    async def testMyRuleChecker(self):
        await self.assertRuleAsync(
            asset='example.usd',
            rule=MyRuleChecker,
            asserts=[
                IsAFailure("Prim.*has unsupported type.*"),
            ]
        )

async assertCapabilityAsync( *, asset: str | Stage, capability: Capability, asserts: list[IsAnIssue], ) → None#: Same as assertCapability, but for async tests.

async assertExamplesAsync( *, requirement: Requirement, ) → None#: Same as assertExamples, but for async tests.

async assertFailureAsync( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, predicate: IssuePredicate | None = None, ) → None#: Same as assertFailure, but for async tests.

async assertIssuesAsync( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, asserts: list[IsAnIssue], ) → None#: Same as assertIssues, but for async tests.

async assertRequirementAsync( *, asset: str | Stage, requirement: Requirement, asserts: list[IsAnIssue], ) → None#: Same as assertRequirement, but for async tests.

async assertRuleAsync( *, asset: str | Stage, rule: type[BaseRuleChecker], asserts: list[IsAnIssue], ) → None#: Same as assertRule, but for async tests.

async assertSuccessAsync( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, predicate: IssuePredicate | None = None, parameters: dict[str, int | float | bool | str] | None = None, ) → None#: Same as assertSuccess, but for async tests.

async assertSuggestionAsync( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, predicate: IssuePredicate | None = None, ) → None#: Same as assertSuggestion, but for async tests.

async validateAsync( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, parameters: dict[str, int | float | bool | str] | None = None, ) → Results#: Validate the asset using the rule.

class omni.asset_validator.core.tests.Failure(**kwargs)#

IsAFailure let us assert messages and locations of failure to match against the real issue found in Validation Engine. This class is used in conjuntion to ValidationRuleTestCase.assertRule.

message#

Regex pattern for the expected failure message.

Type:: str | re.Pattern | None

at#

Optional. The expected location of the expected failure.

Type:: str | pxr.Sdf.Path | None

IsAWarning let us assert messages and locations of warnings to match against the real issue found in Validation Engine. This class is used in conjuntion to ValidationRuleTestCase.assertRule.

message#

Regex pattern for the expected failure message.

Type:: str | re.Pattern | None

at#

Optional. The expected location of the expected failure.

Type:: str | pxr.Sdf.Path | None

IsAnError let us assert messages and locations of errors to match against the real issue found in Validation Engine. This class is used in conjuntion to ValidationRuleTestCase.assertRule.

message#

Regex pattern for the expected failure message.

Type:: str | re.Pattern | None

at#

Optional. The expected location of the expected failure.

Type:: str | pxr.Sdf.Path | None

IsAnInfo let us assert messages and locations of infos to match against the real info found in Validation Engine. This class is used in conjuntion to ValidationRuleTestCase.assertRule.

message#

Regex pattern for the expected info message.

Type:: str | re.Pattern | None

at#

Optional. The expected location of the expected info.

Type:: str | pxr.Sdf.Path | None

IsAnIssue let us assert severity, message and locations of issues to match against the real issues found in Validation Engine. Use IsAFailure, IsAWarning and IsAnError instead.

Parameters:

message – The expected message of the issue.
at – Optional. The expected location of the issue.
code – Optional. The expected code of the issue.
requirement – Optional. The expected requirement of the issue.
severity – Optional. The expected severity of the issue.

class omni.asset_validator.core.tests.ValidationRuleTestCase(*args: Any, **kwargs: Any)#

Specific implementation of ValidationTestCaseMixin for core tests.

assertRule( *, rule: type[BaseRuleChecker], asserts: list[IsAnIssue], asset: str | Stage | None = None, url: str | None = None, ) → None#

Parameters:

rule – The rule to use for validation.
asserts – A list of assertions.
asset – The asset to validate.
url – (Deprecated) Use asset instead.

assertRuleFailures( *, rule: type[BaseRuleChecker], expectedFailures: list[IsAFailure], asset: str | Stage | None = None, url: str | None = None, ) → None#

Parameters:

rule – The rule to use for validation.
expectedFailures – A list of expected failures.
asset – The asset to validate.
url – (Deprecated) Use asset instead.

assertSuggestion( *, rule: type[BaseRuleChecker], predicate: IssuePredicate | None = None, asset: str | Stage | None = None, url: str | None = None, ) → None#

Parameters:

rule – The rule to use for validation.
predicate – The predicate to use for validation.
asset – The asset to validate.
url – (Deprecated) Use asset instead.

class omni.asset_validator.core.tests.ValidationTestCaseMixin#

A mixin for test cases to simplify testing of individual Validation Rules.

Example

from unittest import TestCase
from omni.asset_validator.tests import ValidationTestCaseMixin

class ValidationTestCase(TestCase, ValidationTestCaseMixin):
    ...

class MyTestCase(ValidationTestCase):
    def testMyRuleChecker(self):
        self.assertRule(
            asset='example.usd',
            rule=MyRuleChecker,
            asserts=[
                IsAFailure("Prim.*has unsupported type.*"),
            ]
        )

assertCapability( *, asset: str | Stage, capability: Capability, asserts: list[IsAnIssue], ) → None#: Assert issues from validating one asset using one capability

assertExamples( *, requirement: Requirement, ) → None#

Assert the examples of a requirement.

Implementation is validated against the examples of the requirement.

Parameters:: requirement – The requirement to assert the examples of.

assertFailure( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, predicate: IssuePredicate | None = None, ) → None#: Assert that the asset is validated with failures.

assertIssues( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, asserts: list[IsAnIssue], ) → None#

Assert issues from validating one asset using either a rule, requirement or capability.

Derived classes may use this to simplify testing of new rules with less consideration for the structure of omni.asset_validator.Results.

Note there will be only one enabled rule for the validation run, so all results will have necessarily been produced by the provided rule or by the engine itself (eg non-existent file).

Parameters:

asset – A single asset to validate
rule – Either a BaseRuleChecker derived class or the str class name of such a class
asserts – A list of assertions.

assertRequirement( *, asset: str | Stage, requirement: Requirement, asserts: list[IsAnIssue], ) → None#: Assert issues from validating one asset using one requirement

assertRule( *, asset: str | Stage, rule: type[BaseRuleChecker], asserts: list[IsAnIssue], ) → None#: Assert issues from validating one asset using one rule

assertSuccess( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, predicate: IssuePredicate | None = None, ) → None#: Assert that the asset is validated successfully.

Assert expected failures from validating one asset using one rule will be fixed using auto fix framework.

Derived classes may use this to simplify testing of new rules with less consideration for the structure of omni.asset_validator.IssueFixer.

Note there will be only one enabled rule for the validation run, so all results will have necessarily been produced by the provided rule or by the engine itself (eg non-existent file).

Parameters:

asset – A single asset to validate
rule – Either a BaseRuleChecker derived class or the str class name of such a class
predicate – A predicate (i.e. Callable[[Issue], bool]) to filter out issues.

validate( *, asset: str | Stage, rule: type[BaseRuleChecker] | None = None, requirement: Requirement | None = None, capability: Capability | None = None, ) → Results#

Validate the asset using the rule.

Parameters:

asset – The asset to validate.
rule – The rule to use for validation.

Returns:

The results of the validation.