UsdBase#

class omni.kit.property.usd.UsdBase(

stage: Stage,

object_paths: List[Path],

self_refresh: bool,

metadata: dict = None,

change_on_edit_end: bool = True,

treat_array_entry_as_comp: bool = False,

**kwargs,

)#

Bases: object

A base class for USD attributes and properties management.

This class provides functionality to handle USD stage interactions, listen to changes, manage control states, and perform value manipulation for USD attributes. It is designed to be a common base class for USD model implementations, offering a rich set of features for USD data handling.

Parameters:

stage (Usd.Stage) – The USD stage to interact with.
object_paths (List[Sdf.Path]) – A list of Sdf.Path objects representing the USD attributes or properties.
self_refresh (bool) – If True, the model will listen for USD changes itself; otherwise, it will rely on external update triggers.
metadata (Optional[dict]) – Additional metadata associated with the USD attributes or properties. Defaults to None.
change_on_edit_end (bool) – If True, changes to the USD are only committed when the edit ends (e.g., focus lost), improving performance during rapid edits. Defaults to True.
treat_array_entry_as_comp (bool) – Treats each entry in an array as a separate component, which is useful for building UI widgets that indicate non-default or ambiguous states at the entry level.

Keyword Arguments:

auto_target_session_layer_def (bool) – Targets session layer definition for edits by default.
min – The minimum allowed value for the attribute; this acts as a lower bound.
max – The maximum allowed value for the attribute; this acts as an upper bound.

Methods

`__init__`(stage, object_paths, self_refresh)	Initializes the UsdBase instance.
`begin_edit`()	Begins an edit operation by increasing the internal editing counter.
`clean`()	Cleans up the instance by removing listeners and resetting state.
`create_placeholder_attribute`(name[, prim, ...])	Creates a placeholder attribute.
`end_edit`()	Ends an edit operation by decreasing the internal editing counter and updating the value if changed.
`get_all_comp_ambiguous`()	Retrieves a list indicating which components of the attribute's value are ambiguous.
`get_attribute_paths`()	Retrieves the attribute paths associated with this instance.
`get_attributes`()
`get_bad_connection`()	Retrieves the bad connection status and error message.
`get_connections`()	Returns the list of connections for the last attribute in the model.
`get_current_time_code`()	Gets the current time code of the stage.
`get_layers_with_strongest_value_opinions`()	Gets a list of strongest layers that contribute to the value of each attributes in the model.
`get_objects`()
`get_prim_paths`(stage)	Returns the list of Sdf.Paths for the prims associated with this USD model.
`get_property_paths`()	Retrieves the property paths associated with this instance.
`get_stage`()	Gets the stage of the attribute.
`get_valid_stage_adapter_read`(path)	Gets the stage adapter that can read the given path.
`get_valid_stage_adapter_write`(path)	Gets the stage adapter that can write to the given path.
`get_value`()	Gets the value of the attribute.
`get_value_by_comp`(comp)	Gets the value of a specific component of the attribute value.
`has_connections`()	Checks if the last attribute in the model has connections.
`is_ambiguous`()	Determines if the attribute's value is ambiguous due to multiple sources.
`is_array_type`()	Determines if the attribute's value is of an array type.
`is_comp_ambiguous`(index)	Determines if a specific component of the attribute's value is ambiguous.
`is_different_from_default`()	Determines if the current value is different from the default value.
`is_editing`()	Checks if the model is currently in an editing state.
`is_instance_proxy`()	Checks if the object is an instance proxy.
`is_locked`()	Checks if the attributes are locked.
`is_readonly`()	Determines if the attribute is read-only.
`is_value_array`()	Checks if the attribute value is an array.
`might_be_time_varying`()	Determines if the associated attribute might vary over time.
`set_default`([comp])	Set the UsdAttribute default value if it exists in metadata.
`set_locked`(locked)	Sets the locked state of the attributes.
`set_on_control_state_changed_fn`(fn)	Sets a callback function to be called when the control state changes.
`set_on_set_default_fn`(fn)	Sets a callback function to be called when the default value is set.
`set_soft_range_userdata`(soft_range_min, ...)	Sets the soft range for the attributes.
`set_value`(value[, comp])	Sets the value of the attribute.
`update_control_state`()	Updates the control state based on the current conditions.
`update_value_by_comp`(from_value, to_value, comp)	Updates the value of a specific component.

Attributes

`control_state`	Gets the current control state, it's the icon on the right side of the line with widgets.
`metadata`	Gets the metadata associated with this instance.
`stage`	Gets the USD stage associated with this instance.

__init__(

stage: Stage,

object_paths: List[Path],

self_refresh: bool,

metadata: dict = None,

change_on_edit_end: bool = True,

treat_array_entry_as_comp: bool = False,

**kwargs,

)#: Initializes the UsdBase instance.

begin_edit()#: Begins an edit operation by increasing the internal editing counter.

clean()#: Cleans up the instance by removing listeners and resetting state.

create_placeholder_attribute(name, prim=None, metadata=None)#

Creates a placeholder attribute.

Parameters:

name (str) – The name of the placeholder attribute to create.
prim (Optional[Usd.Prim]) – The USD primitive associated with the attribute.
metadata (dict) – The metadata to associate with the placeholder attribute.

end_edit()#: Ends an edit operation by decreasing the internal editing counter and updating the value if changed.

get_all_comp_ambiguous() → List[bool]#

Retrieves a list indicating which components of the attribute’s value are ambiguous.

Returns:: A list with each element indicating ambiguity of the corresponding component.
Return type:: List[bool]

get_attribute_paths() → List[Path]#

Retrieves the attribute paths associated with this instance.

Returns:: The list of attribute paths.
Return type:: List[Sdf.Path]

get_bad_connection() → tuple[bool, str]#

Retrieves the bad connection status and error message.

Returns:

A tuple containing two elements:

bool: True if there is a bad connection, False otherwise.
str: The error message associated with the bad connection.

Return type:

tuple

get_connections()#

Returns the list of connections for the last attribute in the model.

Returns:: The list of connections.
Return type:: list

get_current_time_code()#

Gets the current time code of the stage.

Returns:: The current time code.
Return type:: Usd.TimeCode

get_layers_with_strongest_value_opinions() → list[Layer]#

Gets a list of strongest layers that contribute to the value of each attributes in the model.

Returns:: The list of layers contributed to each attribute.
Return type:: list[Sdf.Layer]

get_prim_paths(stage) → List[Path]#

Returns the list of Sdf.Paths for the prims associated with this USD model.

Parameters:: stage (Usd.Stage) – The stage to query for prim paths.
Returns:: The list of prim paths.
Return type:: List[Sdf.Path]

get_property_paths() → List[Path]#

Retrieves the property paths associated with this instance.

Returns:: The list of property paths.
Return type:: List[Sdf.Path]

get_stage()#

Gets the stage of the attribute.

Returns:: The stage of the attribute.
Return type:: Usd.Stage

get_valid_stage_adapter_read(path)#

Gets the stage adapter that can read the given path.

Parameters:: path (str) – The path to check for a valid stage adapter.
Returns:: The stage that can read from the given path.
Return type:: Usd.Stage

get_valid_stage_adapter_write(path)#

Gets the stage adapter that can write to the given path.

Parameters:: path (str) – The path to check for a valid stage adapter.
Returns:: The stage that can write to the given path.
Return type:: Usd.Stage

get_value()#

Gets the value of the attribute.

Returns:: The current value of the attribute.
Return type:: Any

get_value_by_comp(comp: int)#

Gets the value of a specific component of the attribute value.

Parameters:: comp (int) – The component index to get the value for.
Returns:: The value of the specified component.
Return type:: Any

has_connections()#

Checks if the last attribute in the model has connections.

Returns:: True if there are connections, False otherwise.
Return type:: bool

is_ambiguous() → bool#

Determines if the attribute’s value is ambiguous due to multiple sources.

Returns:: True if ambiguous, False otherwise.
Return type:: bool

is_array_type() → bool#

Determines if the attribute’s value is of an array type.

Returns:: True if an array type, False otherwise.
Return type:: bool

is_comp_ambiguous(index: int) → bool#

Determines if a specific component of the attribute’s value is ambiguous.

Parameters:: index (int) – The index of the component to check.
Returns:: True if the specified component is ambiguous, False otherwise.
Return type:: bool

is_different_from_default() → bool#

Determines if the current value is different from the default value.

Returns:: True if different, False otherwise.
Return type:: bool

is_editing() → bool#

Checks if the model is currently in an editing state.

Returns:: True if editing, False otherwise.
Return type:: bool

is_instance_proxy()#

Checks if the object is an instance proxy.

Returns:: True if the object is an instance proxy, False otherwise.
Return type:: bool

is_locked()#

Checks if the attributes are locked.

Returns:: True if attributes are locked, False otherwise.
Return type:: bool

is_readonly() → bool#

Determines if the attribute is read-only.

Returns:: True if read-only, False otherwise.
Return type:: bool

is_value_array()#

Checks if the attribute value is an array.

Returns:: True if the attribute value is an array, False otherwise.
Return type:: bool

might_be_time_varying() → bool#

Determines if the associated attribute might vary over time.

Returns:: True if it might vary, False otherwise.
Return type:: bool

set_default(comp=-1)#

Set the UsdAttribute default value if it exists in metadata.

Parameters:: comp (int) – The component index to set default for. -1 means all components.

set_locked(locked)#

Sets the locked state of the attributes.

Parameters:: locked (bool) – Whether to lock or unlock the attributes.

set_on_control_state_changed_fn(fn)#

Sets a callback function to be called when the control state changes.

Parameters:: fn (function) – The callback function to be set.

set_on_set_default_fn(fn)#

Sets a callback function to be called when the default value is set.

Parameters:: fn (function) – The callback function to be set.

set_soft_range_userdata(soft_range_min, soft_range_max)#

Sets the soft range for the attributes.

Parameters:

soft_range_min (float) – The minimum value of the soft range.
soft_range_max (float) – The maximum value of the soft range.

set_value(value, comp: int = -1) → bool#

Sets the value of the attribute. Can set value for a specific component.

Parameters:

value (Any) – The new value to set.
comp (int) – The component index to set the value for.

update_control_state()#: Updates the control state based on the current conditions.

static update_value_by_comp(from_value, to_value, comp: int)#

Updates the value of a specific component.

Parameters:

from_value (Any) – The value to update from.
to_value (Any) – The value to update to.
comp (int) – The component index to update.

property control_state#: Gets the current control state, it’s the icon on the right side of the line with widgets.

property metadata#: Gets the metadata associated with this instance.

property stage#: Gets the USD stage associated with this instance.