omni.flux.property_widget_builder.model.usd#

SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

class omni.flux.property_widget_builder.model.usd.BoundsAdapter( raw_bounds_step_data: dict[str, Any] | Any | None = None, normalized_data: NormalizedBoundsStepData | None = None, )#

Base bounds adapter that normalizes raw bounds metadata once.

Normalized values may be scalar (int/float) or scalar sequences; consumers that render per-channel drag widgets resolve sequence components later.

Return normalized (min, max, hard_min, hard_max) tuple.

min/max prefer soft bounds and fall back to hard bounds when soft bounds are absent.

property has_hard_bounds: bool#: Return whether this adapter has any source hard-bound value.

property has_soft_bounds: bool#: Return whether this adapter has any source soft-bound value.

classmethod merge_bounds_adapters( adapters: list[BoundsAdapter], ) → BoundsAdapter#

Merge multiple adapters into one adapter instance.

This method is intentionally post-normalization so pane producers can reuse one merge policy regardless of original metadata source.

Merge policy is as follows. A single adapter input passes through unchanged. Multi-adapter inputs intersect numeric min/max values across payloads. Step values use the coarsest numeric step encountered. The soft channel is emitted only when all adapters provide soft bounds, or when the selection is mixed (soft and hard both present). The hard channel is emitted only when all adapters provide hard bounds, or when the selection is mixed (soft and hard both present). A channel is left unset when no selected adapter provides it.

Additional behavior: single-item input returns the same adapter instance (alias) instead of constructing a new one. Callers should not assume a new object identity from merge and should avoid mutating adapter internals after merge. When the intersected runtime-safe range is empty, merged bounds are cleared on both channels and only the merged step is preserved.

property step: int | float | ScalarSequence | None#: Return the normalized step value, if present.

class omni.flux.property_widget_builder.model.usd.ComboboxField( style_name: str = 'PropertiesWidgetField', identifier: str | None = None, )#

class omni.flux.property_widget_builder.model.usd.ConditionalVisibilityOrchestrator#

Shared conditional visibility lifecycle manager for opt-in property panels.

bind_attribute( *, attr_id: str | None = None, condition: str | None = None, metadata_source: Any | None = None, item_or_items: Any | None = None, ) → None#

Bind one attribute entry and its rendered row item or companion row items.

Parameters:

attr_id – Stable attribute identifier used for condition matching.
condition – Optional condition expression that controls this attribute’s visibility.
metadata_source – Optional schema or metadata object associated with the attribute.
item_or_items – Rendered item object or related rendered item objects controlled by this entry.

Each normalized attribute ID should be bound once per setup pass. Rebinding the same ID replaces its rendered item references rather than merging old and new rows.

can_bind_attribute( attr_id: str | None, ) → bool#

Return whether an attribute identifier can participate in conditional visibility.

Parameters:: attr_id – Raw attribute identifier to inspect.
Returns:: Whether the attribute should be bound by the orchestrator.

sync_and_evaluate_bindings() → None#

Build condition bindings, wire driver subscriptions, and apply initial visibility.

Call this after all attributes and row items have been registered with bind_attribute().

class omni.flux.property_widget_builder.model.usd.DisableAllListenersBlock(listener_instance)#

Temporarily disables all USD listeners.

Parameters:: listener_instance – USD listener whose model registrations should be suspended.

Example

If you add multiple entity at the same time, you can do:

>>> with DisableAllListenersBlock(usd_listener_instance):
>>>     for i in range(100):
>>>         pass  # usd action

class omni.flux.property_widget_builder.model.usd.FileTexturePicker( file_extension_options: list[tuple[str, str]] | None = None, style_name: str = 'PropertiesWidgetField', regex_hash: Pattern[str] | None = None, )#: Delegate of the tree

class omni.flux.property_widget_builder.model.usd.USDAttrListItem( context_name: str, attribute_paths: list[Path], default_value: str, options: list[str], read_only: bool = False, value_type_name: ValueTypeName | None = None, metadata: dict | None = None, display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, metadata_key: str | None = None, )#

Item of the model

value_model_class#: alias of UsdListModelAttrValueModel

class omni.flux.property_widget_builder.model.usd.USDAttributeDef( path: Path, attr_type: ValueTypeNames, op: XformOp | None = None, value: Any | None = None, exists: bool = False, documentation: str | None = None, display_group: str | None = None, )#: Holds arguments for a USD attribute that may be created at a later time.

class omni.flux.property_widget_builder.model.usd.USDAttributeEditGroupItem( edit_group_layout: dict, context_name: str, prim_path: str, )#

Accessor outlet for a group of curve attributes.

Not backed by a USD attribute. The consumer places it in an ItemGroup to show a button that opens the curve editor in multi-curve mode.

Parameters:

edit_group_layout – Panel-level layout dict (shared instance with tagged items).
context_name – USD context name.
prim_path – Prim path the curves live on.

class omni.flux.property_widget_builder.model.usd.USDAttributeItem( context_name: str, attribute_paths: list[Path], display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, default_value: Any | None = None, read_only: bool = False, value_type_name: ValueTypeName | None = None, ui_metadata: dict | None = None, bounds_adapter: BoundsAdapter | None = None, )#

Item that represent a USD attribute on the tree

Parameters:

context_name – the context name
attribute_paths – the list of USD attribute(s) the item will represent
display_attr_names – override the name(s) of the attribute(s) to show by those one
display_attr_names_tooltip – tooltip to show on the attribute name
default_value – optional override for the default value
read_only – show the attribute(s) as read only
value_type_name – if None, the type name will be inferred
ui_metadata – optional dict of UI hints used only when constructing the default BoundsAdapter. Treat as a producer payload for bounds normalization rather than a direct bounds source.
bounds_adapter – optional preconfigured bounds adapter instance. When provided, this is the canonical source of bounds/step values. When omitted, BoundsAdapter is constructed with ui_metadata.

property element_count#: Number of channel the attribute has (for example, float3 is 3 channels)

Get normalized bounds metadata from the configured adapter instance.

Bounds come from the adapter payload provided at item construction. Partial bounds are allowed, so any tuple element may be None.

Returns:: (min_value, max_value, hard_min_value, hard_max_value) when bounds metadata exists, or None when no bounds metadata is present. Callers that require both min and max (for example, slider widgets) must validate that both are non-None.

get_step_value() → int | float | ScalarSequence | None#

Get the UI step size for this attribute, if any.

Resolves step from the configured adapter instance.

Returns:: The step value as a float or int, or None if no step is defined.

property has_bounds_data: bool#: True if any normalized bounds metadata is present on the configured adapter.

class omni.flux.property_widget_builder.model.usd.USDAttributeItemStub( name: str, context_name: str, attribute_defs: Sequence[USDAttributeDef], )#

Holds USD attribute(s) that may be created at a later time.

create_attributes()#: Create the USD attributes.

refresh()#

Trigger a task to determine if the attributes should be created.

This can happen if the attributes are created by some mechanism besides interacting with widgets presented in the TreeView.

subscribe_create_attributes_begin(function)#: Return the object that will automatically unsubscribe when destroyed.

subscribe_create_attributes_end(function)#: Return the object that will automatically unsubscribe when destroyed.

class omni.flux.property_widget_builder.model.usd.USDAttributeXformItem( context_name: str, attribute_paths: list[Path], display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, read_only: bool = False, value_type_name: ValueTypeName | None = None, )#

get_all_attributes() → list[Usd.Attribute]#

Xform items should return all xform attributes, not just the selected attribute.

Returns:: List of authored USD attributes the item acts on.

class omni.flux.property_widget_builder.model.usd.USDAttributeXformItemStub( name: str, context_name: str, attribute_defs: Sequence[USDAttributeDef], )#: Holds USD XForm attribute(s) that may be created at a later time.

class omni.flux.property_widget_builder.model.usd.USDBuilderList(iterable=(), /)#

An extension of the FieldBuilderList that has some additional USD specific registration helpers for constructing FieldBuilder instances.

append_builder_by_attr_name( names: str | Iterable[str], build_func: Callable[[_Item], ui.Widget | list[ui.Widget] | None], *, supports_field_cleanup: bool = False, )#: A simple helper which allows users to register a FieldBuilder with just attribute names and a build_func.

static claim_by_name(*names: str)#: Get a FieldBuilder claim_func that will claim items whose USD attribute name matches names.

register_by_name( *names, supports_field_cleanup: bool = False, )#: Decorator to simplify registering a build function for USDAttributeItem for specific attribute name(s).

register_by_type( *types, supports_field_cleanup: bool = False, )#: Decorator to simplify registering a build function for USDAttributeItem of specific type(s).

class omni.flux.property_widget_builder.model.usd.USDDelegate( field_builders: list[FieldBuilder] | None = None, right_aligned_labels: bool = True, layer_transfer_menu_fn: Callable[[Any, Any, list[PropertySpec], set[str], bool], None] | None = None, )#

Delegate of the tree

build_branch( model: _USDModel, item: _Item, column_id: int = 0, level: int = 0, expanded: bool = False, )#: Create a branch widget that opens or closes the subtree for item that can have children, or the default & override widgets for items that can’t.

reset()#

Resets any state stored on the delegate.

This method is called when the parent widget is hidden.

property selection: list[_Item]#: Get the currently selected items

value_model_updated(item: _Item)#: Callback ran whenever an item’s value model updates.

USD float drag delegate that applies adapter-normalized constraints.

Why this exists:: Provides the USD integration layer over the generic FloatDragFieldGroup by injecting item-level bounds/step metadata before constructing UI.

build_ui(

item,

**kwargs,

) → list[Widget]#: Apply USD metadata bounds and step, then build the drag UI.

USD int drag delegate that applies adapter-normalized constraints.

Why this exists:: Mirrors USDFloatDragField behavior for integer attributes so both numeric delegate types consume the same normalized USD metadata path.

build_ui(item, **kwargs) → list[Widget]#: Apply USD metadata bounds and step, then build the drag UI.

class omni.flux.property_widget_builder.model.usd.USDMetadataListItem( context_name: str, attribute_paths: list[Path], default_value: str, options: list[str], read_only: bool = False, value_type_name: ValueTypeName | None = None, metadata: dict | None = None, display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, metadata_key: str | None = None, )#

Item of the model

value_model_class#: alias of UsdListModelAttrMetadataValueModel

class omni.flux.property_widget_builder.model.usd.USDModel(context_name: str = '')#

Basic list model

property context_name: str#: The current used context

property prim_paths: list[Path]#: The current used attribute paths

set_items(items: list[_ItemGroup | _USDAttributeItem])#

Set the items to show

Parameters:: items – the items to show

set_prim_paths(value: list[Path])#: The current used attribute paths

property stage: Stage#: The current used stage

subscribe_attribute_created(function)#: Return the object that will automatically unsubscribe when destroyed.

subscribe_item_model_end_edit(function)#: Return the object that will automatically unsubscribe when destroyed.

subscribe_override_removed(function)#: Return the object that will automatically unsubscribe when destroyed.

class omni.flux.property_widget_builder.model.usd.USDPropertyWidget( context_name: str = '', model: _Model | None = None, delegate: _Delegate | None = None, tree_column_widths: list[ui.Length] = None, columns_resizable: bool = False, refresh_callback: Callable[[], None] | Callable[[], Awaitable[None]] | None = None, )#: Widget that let you build property widget(s) from any data

class omni.flux.property_widget_builder.model.usd.USDPropertyWidgetExtension#: Create Final Configuration

class omni.flux.property_widget_builder.model.usd.USDRelationshipItem( context_name: str, relationship_paths: list[Path], display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, read_only: bool = False, ui_metadata: dict[str, Any] | None = None, )#

Item representing USD relationship properties.

Parallel to USDAttributeItem but uses UsdRelationshipValueModel. Relationships are always single-target (element_count = 1).

property ui_metadata: dict[str, Any]#

Get UI metadata hints for field builders.

Returns:: Dict of UI hints (e.g., picker configuration). Framework stores this opaquely; consumers interpret the contents.

class omni.flux.property_widget_builder.model.usd.VirtualUSDAttrListItem( context_name: str, attribute_paths: list[Path], default_value: str, options: list[str], read_only: bool = False, value_type_name: ValueTypeName | None = None, metadata: dict | None = None, display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, metadata_key: str | None = None, )#

Item of the model

value_model_class#: alias of VirtualUsdListModelAttrValueModel

class omni.flux.property_widget_builder.model.usd.VirtualUSDAttributeItem( context_name: str, attribute_paths: list[Path], value_type_name: ValueTypeName, default_value: Any, display_attr_names: list[str] | None = None, display_attr_names_tooltip: list[str] | None = None, read_only: bool = False, metadata: dict | None = None, bounds_adapter: BoundsAdapter | None = None, create_callback: Callable[[Any], None] | None = None, )#: Item of the model