UsdSuperLayer

✨ New in Katana 8.5

Introduction

The UsdSuperLayer node type is a new base SuperTool node type whose underlying type is the UsdLayerSuperTool class. This SuperTool provides direct access to a USD Layer at the node graph level. The purpose is to use USD as its core source of truth, with parameters serving as UI elements. This is fundamentally different to other node types in Katana where, typically, parameters store the recipe that define the node. This base node type is not intended to replace our typical, fully procedural node types, since some proceduralism is lost. However, for certain workflows, there is a significant gain in performance and usability.

These are the derived node types that extend the UsdSuperLayer node type:

UsdGaffer

The common interface for the node types that derive from UsdSuperLayer:

class NodesUsdAPI.UsdSuperLayer.UsdLayerSuperTool

Bases: SuperTool

The node part of the UsdSuperLayer SuperTool.

FN_PROPERTIES_GROUP = 'fnPropertiesGroup'

__init__() → None: Initializes an instance of the class.

addParameterHints(attrName: str, inputDict: dict) → None

Adds parameter hints to the given dictionary of hints for a GenericAssign parameter that shows the value of an attribute from the incoming scene.

Parameters:

attrName (str) – The name of the scene graph attribute from the incoming scene for which to add parameter hints.
inputDict (dict) – The dictionary to which to add parameter hints.

Return type:

None

appendChangeDescription(description: str) → None

Appends a description of a change to the content layer. This description will be used to create a meaningful undo stack entry when the content layer is serialized.

This is primarily intended for use by ContextMenu plug-ins and other external code that modifies the content layer directly, allowing them to document their changes.

Parameters:: description (str) – A brief description of the change made to the content layer.
Return type:: None

buildParametersForPrimPath(primPath: str) → None

Rebuilds the dynamic parameters for the provided primsPath by relaying the request to each of the registered plug-ins via the buildOrUpdateParameters() method on each plug-in.

Parameters:: primPath (str) – The prim path to build or rebuild parameters for.
Return type:: None

canOverride(attrName: str) → bool

Checks if the given attribute is overridable or not in the node. This is required by manipulators.

Parameters:: attrName (str) – The name of the attribute to check if overridable.
Return type:: bool

checkDynamicParameters() → None

Checks the dynamic parameters for the prims in the target prim paths and rebuilds them if necessary.

Return type:: None

contentLayerChangedByNode(primPaths: list[Path]) → None

Post process after content layer has changed.

Parameters:: primPaths (list[Path]) – The list of prim paths that have changed.
Return type:: None

getBasePrimPath() → Path

Returns:: Path – The base prim path.

getComponentsFromPropertiesParameter(parameter: Parameter) → tuple[str, str, str, Parameter] | None

Returns all components from the provided parameter. This will return a list of tuples containing the prim path and the parameter name. An example for the input parameter: properties.parent.child.fnPropertiesGroup.PropertiesParametersHandlerPlugin.size.value would return: ``(‘parent/child’, ‘/root/parent/child’,

‘PropertiesParametersHandlerPlugin’, self.getParameter( ‘properties.parent.child.fnPropertiesGroup.PropertiesParametersHandlerPlugin’) )``.

Parameters:

param – The parameter to extract the components from.
parameter (Parameter)

Returns:

tuple[str, str, str, Parameter] | None – A tuple containing the relative prim path, absolute prim path, plug-in name, and plugin root parameter, or None if the parameter does not represent a plug-in parameter.

getEngineIds(graphState: GraphState) → list

Returns engine ids of the underlying StageSubtreeController node.

Parameters:: graphState (GraphState)
Return type:: list

getIncomingLocalUsgValue(prim: Prim, paramFullName: str) → Value | None

Called by the StageParameterPolicy to retrieve the usg.Value data from the prim.

Parameters:

prim (Prim) – The prim to extract the data provided by the UsgValueSource.
paramFullName (str) – Full name of the parameter used for the policy.

Returns:

Value | None – A usg.Value value or None.

getInternalLayerNode() → Node

Returns the hidden internal node responsible for managing the StageSubtreeController for the SuperTool.

Return type:: Node

getOverridableAttrs() → list[str]

Returns:: list[str] – The list of attributes that can be overridden using the setOverride function.

getParameterNameFromPropertiesParameter(parameter: Parameter) → str

Returns the parameter name component from a properties parameter path.

Extracts everything after the plugin name. For example: “properties.parent.child.fnPropertiesGroup.Plugin.size.value” returns “size.value”.

This assumes parameters are plugin-created with proper structure since malformed parameters won’t appear in the properties UI.

Parameters:: parameter (Parameter) – The parameter to extract the name from.
Returns:: str – The short name of the parameter from the provided prim parameter.

getPluginNameFromParam(parameter: Parameter) → str | None

Returns the name of the plug-in which created this parameter.

An example for the input parameter: properties.parent.child.fnPropertiesGroup.PropertiesParametersHandlerPlugin.size.value would return: 'PropertiesParametersHandlerPlugin'.

Param:: The parameter to extract the plug-in name from.
Returns:: str | None – The plug-in name as a string or None if the parameter does not represent a plug-in parameter.
Parameters:: parameter (Parameter)

getPluginParamRoot(parameter: Parameter) → Parameter | None

Returns the root group parameter for the plug-in which created the provided parameter.

An example for the input parameter: properties.parent.child.fnPropertiesGroup.PropertiesParametersHandlerPlugin.size.value would return: ``self.getParameter(

‘properties.parent.child.fnPropertiesGroup.PropertiesParametersHandlerPlugin’)``.

Param:: The parameter to extract the plug-in root group from.
Returns:: Parameter | None – The name of the plug-in root group parameter or None if the parameter does not represent a plug-in parameter.
Parameters:: parameter (Parameter)

getPrimPathFromPropertiesParameter(parameter: Parameter, absolutePath: bool = False) → Path | None

Returns the prim path from the provided parameter. Optional argument of absolutePath can be set to true to return the absolute prim path instead of the relative one. This adds the current base prim path to the relative prim path. An example for the input parameter: properties.parent.child.fnPropertiesGroup.PropertiesParametersHandlerPlugin.size.value would return: 'parent/child' or '/root/parent/child'.

Parameters:

param – The parameter to extract the prim path from.
absolutePath (bool, default: False) – Whether to return the absolute prim path or the relative one. False by default.
parameter (Parameter)

Returns:

Path | None – The prim path or None if the parameter does not represent a prim.

getStageAndStates(force: bool = False) → tuple[Stage, int, int]

Gets a stage and state from this point in the hierarchy from the internal _UsdLayerNode.

This will fetch the stage by performing a traversal and running the USD processing engine.

If force is True, the traversal will always be performed. If force is False(default) a traversal will only occur if the stage is empty. This node does not keep track of changes or updates.

It is important not to cache the returned stage to avoid keeping references to layers that may need to be flushed! Gets the state of the stage, or if there is no incoming stage, the hash of the current ContentLayer. If you do need to retain the stage. Ensure you implement a method on the event cacheManager_flush set the stage to None and re-fetch at the next idle event to prevent layers from not being reloaded on flush caches.

Parameters:: force (bool) – Whether to force re-traversal of the scene. False by default.
Return type:: tuple of (usg.Stage, int, int)
Returns:: The usg.Stage of the current node graph to this point, and the states of the

stage, and the contentLayer itself.

getStageParameterPolicyMaskPath() → str

Called by the StageParameterPolicy to determine the prim path to the USD Prim that will be utilised as the mask path for the UsdStage, if this method is not overriden, it will default to masking based on the path returned by the getStageParameterPolicyPrimPath method.

Returns:: str – The prim path to the USD Prim that is to be used as the mask path for the Stage.

getStageParameterPolicyPrimPath(frameTime: float = 0.0) → str

Called by the StageParameterPolicy to determine the prim path to the USD Prim that will be queried in the incoming USD Stage.

Parameters:: frameTime (float, default: 0.0) – The sample time to query data at.
Returns:: str – The prim path to the USD Prim that is to be queried in the incoming USD Stage.

getStageSubtreeController() → StageSubtreeController

Accessor for the internal nodes getStageSubtreeController method.

Return type:: usg.StageSubtreeController or None
Returns:: The usg.StageSubtreeController created by this node or None if it has not been

created.

getTargetPrimPath() → str

Returns:: str – The path to the currently selected prim, or an empty string if none.

getTargetPrimPaths() → list[str]

Returns:: list[str] – The list of target prim paths.

polish() → None

This method is automatically called on the SuperTool after it has finished loading and initialization. It will only be called once.

Return type:: None

setFilteredApiSchemas(apiSchemas: list[str]) → None

Sets the string array apiSchema parameter controlling which the tree view for this node should be filtered by. If empty the list will not be filtered by any api schemas.

Parameters:: apiSchemas (list[str]) – The list of apiSchemas to filter. If empty no filtering based on api schemas takes place.
Return type:: None

setFilteredConcreteSchemas(concreteSchemas: list[str]) → None

Sets the string array concreteSchema parameter controlling which the tree view for this node should be filtered by. If empty the list will not be filtered by any concrete schemas.

Parameters:: concreteSchemas (list[str]) – The list of concrete schemas to filter. If empty no filtering based on concrete schemas takes place.
Return type:: None

setOverride(path: str, attrName: str, time: float, attrData: list[float], args: list[str], index: int = 0, **kwargs: dict[str, object]) → bool

Applies the node’s transform parameter overrides from given attribute value. This is required by manipulators.

Parameters:

path (str) – The location to set override.
attrName (str) – The name of the attribute to override.
time (float) – The frameTime of current graph state.
attrData (list[float]) – The list of attribute data to override with.
args (list[str]) – Throw away argument, required to match pattern of AttributeEditors.
index (int, default: 0) – Throw away argument, required to match pattern of AttributeEditors.
kwargs (dict[str, object]) – Throw away argument, required to match pattern of AttributeEditors.

Return type:

bool

setTargetPrimPath(primPath: str, force: bool = False) → None

Sets the target prim path to the provided prim paths.

Parameters:

primPath (str) – The prim path to set, or empty to clear it.
force (bool, default: False) – Signal a change even when the prim path was already set as the target

Raises:

RuntimeError – If the target prim path is not a descendant of the base prim path.

Return type:

None

setTargetPrimPaths(primPaths: list[str], force: bool = False) → None

Sets the target prim paths to the provided list of prim paths.

Parameters:

primPaths (list[str]) – The list of prim paths to set.
force (bool, default: False) – Signal a change even when the prim path was already set as the target.

Raises:

RuntimeError – If the target prim path is not a descendant of the base prim path.

Return type:

None

syncLayerAndParameters() → bool

Reserializes the content layer, updates the internal state in the node, and rebuilds parameters for the target prim if the serialized content layer has changed.

Returns:: bool – Whether the serialized content layer has changed compared to the previous call.

property targetPrimPathsChanged: SignalInstance

Returns:: The reference to the targetPrimPathsChanged signal.

updateParameters(prim: Prim, paramFullName: str) → bool

Called by the StageParameterPolicy on potential changes upstream.

Parameters:

prim (Prim) – The USD Prim composed upstream.
paramFullName (str) – The name of the parameter being evaluated.

Returns:

bool – Whether parameters have triggered a change.

How to make your own SuperTool from UsdSuperLayer

This section explains how to extend the UsdSuperLayer node type to construct your own SuperTool. The SuperTool plug-in consists of its module, its registration, its editor and its node. They are defined in Python files placed within a subdirectory named /SuperTools under the KATANA_RESOURCES path. This allows Katana to automatically pick up and load the plug-in during startup.

First we need to register the new SuperTool as a plug-in.

./__init__.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Registering the CustomUsdSuperLayer SuperTool plug-in.
"""

import logging

import NodegraphAPI

log = logging.getLogger("CustomUsdSuperLayer")

try:
    from . import v1 as CustomUsdSuperLayer  # noqa: N812
except ImportError:
    log.exception("Error importing Super Tool Python package.")
    raise

PluginRegistry = [
    (
        "SuperTool",
        2,
        "CustomUsdSuperLayer",
        (CustomUsdSuperLayer.CustomUsdSuperLayerNode, CustomUsdSuperLayer.GetEditor),
    ),
]

NodegraphAPI.AddNodeFlavor("CustomUsdSuperLayer", "nativeusd")
NodegraphAPI.AddNodeFlavor("CustomUsdSuperLayer", "prims")

Next we initialize the module for our SuperTool. We define a GetEditor function, which will return the Editor class for this node.

./v1/__init__.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Initializing module for the CustomUsdSuperLayer SuperTool.
"""

from .Node import CustomUsdSuperLayerNode  # noqa: F401


def GetEditor() -> type:
    """
    :return: The class that implements the SuperTool's editor interface.
    """
    from .Editor import CustomUsdSuperLayerEditor  # noqa: PLC0415

    return CustomUsdSuperLayerEditor

Next we initialize our editor for the SuperTool, often containing functionality around the UI elements.

./v1/Editor.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Module implementing the Editor part of the CustomUsdSuperLayer SuperTool.
"""

from PySide6 import QtWidgets

from Katana import NodegraphAPI
from NodesUsdAPI.UsdSuperLayer.Editor import UsdSuperLayerEditor
from UI4.FormMaster import ParameterPolicy, StageParameterPolicy


class CustomUsdSuperLayerEditor(UsdSuperLayerEditor):
    """
    UI for the CustomUsdSuperLayer SuperTool.
    """

    def __init__(self, parent: QtWidgets.QWidget, group: NodegraphAPI.Node) -> None:
        """
        Initializes an instance of the Editor.
        """
        super().__init__(parent, group)

        # Customize which schema types the visibility column can effect in the stage.
        self.setVisibilityEnabledSchemas([
            "Xform",
        ])

        # Here we need to hook into our stage parameter policy delegate and register our new node
        # so that parameter types can be resolved.
        ParameterPolicy.RegisterPolicyDelegate(
            "CustomUsdSuperLayer",
            StageParameterPolicy.StageParameterPolicyDelegate(),
        )

Finally is the node for our SuperTool, this will contain functionality around parameters.

./v1/Node.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Module implementing the Node part of the CustomUsdSuperLayer SuperTool.
"""

import Utils
from NodesUsdAPI.UsdSuperLayer import ContextMenuPlugin, UsdLayerSuperTool

INITIAL_PRIM_PATH = '/root'


class CustomUsdSuperLayerNode(UsdLayerSuperTool):
    """
    Node for the CustomUsdSuperLayer SuperTool.
    """

    def __init__(self) -> None:
        """
        Initializer for the CustomUsdSuperLayer Node.
        """
        Utils.UndoStack.OpenGroup('Create CustomUsdSuperLayer node')
        try:
            super().__init__()
            # If for example, you only want to show "Scope" types then you can apply a filter.
            # self.setFilteredConcreteSchemas([
            #     "Scope",
            # ])

            self.getParameter('primPath').setValue(INITIAL_PRIM_PATH, 0)
            self.getInternalLayerNode()._changeBasePath(INITIAL_PRIM_PATH)  # noqa: SLF001
        finally:
            Utils.UndoStack.CloseGroup()

        # Add the example context menu to the entries available.
        reg = ContextMenuPlugin.GetRegistry()
        reg.setActive("SampleContextMenuPlugin", True)
        reg.registerNodeToPlugin("AddRigContextMenuPlugin", "CustomUsdSuperLayer")

Plug-ins

UsdSuperLayer-derived node types can be extended with various forms of Python plug-ins.

Context Menu Plug-ins

Overview

This section describes how to extend the available context menu actions in UsdSuperLayer-derived node types by registering UsdSuperLayerContextMenu plug-ins.

These extensions are written in the form of ContextMenuPluginBase-derived classes that are registered as regular Katana Python plug-ins. A ContextMenuPlugin is able to modify selected Prims in any way they wish so long as it affects the editable layer only. For example, this includes modifying in batch, bringing in entire sub-trees of prims, or creating new prims.

In addition to registering and unregistering plug-ins from the plug-in registry, which can be done at runtime with the ContextMenuPluginRegistry Python API, it is also possible to temporarily deactivate without unregistering plug-ins from the system.

The plug-in consists of a class and its registration, defined in a Python file placed within a subdirectory named /UIPlugins under the KATANA_RESOURCES path. This allows Katana to automatically pick up and load the plug-in during startup.

To define the class, it must derive from ContextMenuPluginBase and implement the menuPaths() and callbackOnClick() class methods.

class UsdSuperLayerSampleContextMenuPlugin(ContextMenuPluginBase):
   @classmethod
   def callbackOnClick(
       cls,
       menuPath: str,
       controller: usg.StageSubtreeController,
       selectedPrimPaths: usg.PathArray,
       node: UsdLayerSuperTool,
       editor: UsdSuperLayerEditor,
   ) -> bool:
      ...

   @classmethod
   def menuPaths(cls) -> list[str]:
      ...

The menuPaths() class method must return a list of menu paths. Each path string followed by forward slashes (/) will create a sub-menu. For example, a Add Prim/Rect Light entry will create a context menu Add Prim and a sub menu under it called Rect Light.

The callbackOnClick() class method is called when a user clicks on the corresponding menu action. If any modifications have been made at all to the editable layer, the function must return True; if it failed to return the correct value, there may be issues where the node becomes out of sync with the changes which have been made.

The base class also provides additional functions that can be overridden to further customize the ContextMenuPlugin:

callbackPostClick() Optional callback best suited for post-processing tasks, such as selecting created prims (runs after callbackOnClick, only if it has returned True).
shortcutKeys() returns QKeySequence for provided menu path, such as QKeySequence("Ctrl+A").
tooltip() returns a tool tip message that will be displayed when a user hovers over the menu action.
isVisible() returns a boolean to indicate whether the menu action should be visible.
isEnabled() returns a boolean to indicate whether the menu action should be enabled.
blocksNotifications() returns a boolean to indicate whether the menu action should be wrapped in an SdfChangeBlock stopping notifications to the stage from the layer. Documentation should be consulted before use.

To register the defined class as a plug-in, a top-level, global variable called PluginRegistry must be defined in the Python module. The variable is a list of tuples, with each tuple containing plug-in definitions. For example:

PluginRegistry = [
   (
      'UsdSuperLayerContextMenu',
      1,
      'SampleContextMenuPlugin',
      (
            UsdSuperLayerSampleContextMenuPlugin,
            {'priority': 0, 'active': False, 'appliedNodes': ['all']},
      ),
   ),
]

UsdSuperLayerContextMenu is the plug-in type name.
1 is the plug-in version.
SampleContextMenuPlugin is the unique plug-in name. A list of currently registered plug-in names can be found by querying the ContextMenuPlugin registry.
UsdSuperLayerSampleContextMenuPlugin is the class derived from the ContextMenuPluginBase class.

{'priority': 0, 'active': False, 'appliedNodes': ['all']} are plug-in options, which currently supports the following:

priority defines the order in which plug-ins of this type will be loaded, where 0 is the default. Lower values are higher priority, and thus will appear higher up in the created context menus. The priorities of the registered plug-ins can be checked via ContextMenuPluginRegistry.getPriority(). Here is an example script to check the priorities for UsdGaffer.
from NodesUsdAPI.UsdSuperLayer import ContextMenuPlugin
reg = ContextMenuPlugin.GetRegistry()
for plugin in reg.getPluginsForNode("UsdGaffer"):
    pluginName = reg.getPluginName(plugin)
    print(f"{pluginName}: {reg.getPriority(pluginName)}")

# This is a sample output, which could change in future versions of Katana.
# AddLightContextMenuPlugin: 1000
# AddRigContextMenuPlugin: 1100
# AddScopeContextMenuPlugin: 1200
# ...
active defines whether the plug-in is initially active. The default value is True. Plug-ins’ active state can be changed at a later time via ContextMenuPluginRegistry.setActive().

appliedNodes is a list of node type names. Node instances of these node types will get this plug-in applied. If all is included in the list, the plug-in is applied to all node types. Plug-ins’ nodes list can be added to at a later time via ParametersHandlerPluginRegistry.registerNodeToPlugin().
from NodesUsdAPI.UsdSuperLayer import ContextMenuPlugin
reg = ContextMenuPlugin.GetRegistry()
print(reg.getNodesRegisteredToPlugin("AddRigContextMenuPlugin"))
reg.unregisterNodeFromPlugin("AddRigContextMenuPlugin", "UsdGaffer")
print(reg.getNodesRegisteredToPlugin("AddRigContextMenuPlugin"))
reg.registerNodeToPlugin("AddRigContextMenuPlugin", "UsdGaffer")
print(reg.getNodesRegisteredToPlugin("AddRigContextMenuPlugin"))

# This is a sample output, which could change in future versions of Katana.
# ['UsdGaffer', 'UsdSuperLayer']
# ['UsdSuperLayer']
# ['UsdGaffer', 'UsdSuperLayer']
# ...

Examples

UsdSuperLayerSampleContextMenuPlugin.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Module containing an example UsdSuperLayer ContextMenuPlugin.
"""

import logging
from typing import TYPE_CHECKING

import usg
from PySide6 import QtGui

from NodesUsdAPI.UsdSuperLayer import ContextMenuPlugin
from NodesUsdAPI.UsdSuperLayer.Node import UsdLayerSuperTool

if TYPE_CHECKING:
    from NodesUsdAPI.UsdSuperLayer.Editor import UsdSuperLayerEditor

log = logging.getLogger("SampleContextMenuPlugin")


class UsdSuperLayerSampleContextMenuPlugin(ContextMenuPlugin.ContextMenuPluginBase):
    @classmethod
    def callbackOnClick(
        cls,
        menuPath: str,
        controller: usg.StageSubtreeController,
        selectedPrimPaths: usg.PathArray,
        node: UsdLayerSuperTool,
        editor: "UsdSuperLayerEditor",
    ) -> bool:
        """
        Must be implemented in subclasses. Called when a menu is clicked by user.

        :param menuPath: The menu path. See menuPaths() for details.
        :param controller: The StageSubtreeController stored in UsdSuperLayer.
        :param selectedPrimPaths: The prim paths selected by user.
        :param node: The node which this callback was called from.
        :param editor: The editor associated with the node this callback was called from.
        :return: True if StageSubtreeController is changed, otherwise False.
        """
        print("Hello from sample context menu plugin!")
        del node, editor
        result = False
        if menuPath.startswith("DefPrim"):
            controller.createPrim(usg.Path("defines"))
            result = True
        elif menuPath.startswith("OverPrim"):
            for selectedPath in selectedPrimPaths:
                controller.createPrim(
                    selectedPath.appendChild("overrides"),
                    specifier=usg.PrimSpecifier.Over,
                )
                result = True
        return result

    @classmethod
    def menuPaths(cls) -> list[str]:
        """
        Must be implemented in subclasses. Returns the list of menu paths, where each path is
        a string formed by the menu titles separated by slashes, such as "File/Open" and
        "Setting/UI/Color".

        @return: The menu paths.
        @rtype: C{list[str]}
        """
        return [
            "RootItem1",
            "RootItem2",
            ContextMenuPlugin.MENU_NAME_SEPARATOR,
            "DefPrim",
            "OverPrim",
            "DisabledItem",
        ]

    @classmethod
    def shortcutKeys(cls, menuPath: str) -> QtGui.QKeySequence:
        """
        Returns shortcut key for the menu specified by the provided menuPath.

        @param menuPath: The menu path.
        @type menuPath: C{str}
        @return: The shortcut key.
        @rtype: C{QtGui.QKeySequence}
        """
        if menuPath == "RootItem1":
            return QtGui.QKeySequence("Ctrl+A")
        if menuPath == "RootItem2":
            return QtGui.QKeySequence("Ctrl+B")
        return QtGui.QKeySequence()

    @classmethod
    def tooltip(cls, menuPath: str) -> str:
        """
        Returns tooltip message showed on the menu specified by the provided menuPath.

        @param menuPath: The menu path.
        @type menuPath: C{str}
        @return: The tooltip message.
        @rtype: C{str}
        """
        if menuPath == "DefPrim":
            return "Create def prim"
        if menuPath == "OverPrim":
            return "Create over prim"
        return ""

    @classmethod
    def isEnabled(
        cls,
        menuPath: str,
        controller: usg.StageSubtreeController,
        selectedPrimPaths: usg.PathArray,
    ) -> bool:
        """
        Return True if the menu specified by the given menuPath should be enabled, otherwise
        False.

        @param menuPath: The menu path that is enabled or disabled.
        @type menuPath: C{type}
        @param controller: The content layer.
        @type stageSubtreeController: C{usg.StageSubtreeController}
        @param selectedPrimPaths: The prim paths selected when building menus.
        @type primPaths: C{usg.PathArray}
        @return: True if the menu is enable, otherwise False.
        @rtype: C{bool}
        """
        del controller, selectedPrimPaths
        return menuPath != "DisabledItem"


PluginRegistry = [
    (
        "UsdSuperLayerContextMenu",
        1,
        "SampleContextMenuPlugin",
        (
            UsdSuperLayerSampleContextMenuPlugin,
            {
                "active": False,
                "priority": 0,
                "appliedNodes": ["all"],
            },
        ),
    )
]

API

class NodesUsdAPI.UsdSuperLayer.ContextMenuPlugin.ContextMenuPluginBase

Bases: object

Base class of ContextMenu plugin. All methods are supposed to be classmethod.

classmethod blocksNotifications() → bool

Return True if the notifications to the stage on the subtree controller should be blocked whilst performing menu actions.

Returns:: bool – True if to block, otherwise False.

classmethod callbackOnClick(menuPath: str, controller: StageSubtreeController, selectedPrimPaths: PathArray, node: UsdLayerSuperTool, editor: UsdSuperLayerEditor) → bool

Must be implemented in subclasses. Called when a menu is clicked by user.

Parameters:

menuPath (str) – The menu path. See menuPaths() for details.
controller (StageSubtreeController) – The StageSubtreeController stored in UsdSuperLayer.
selectedPrimPaths (PathArray) – The prim paths selected by user.
node (UsdLayerSuperTool) – The UsdSuperLayer node instance.
editor (UsdSuperLayerEditor) – The Qt widget instance that triggered this callback.

Raises:

NotImplementedError –

Returns:

bool – True if controller is changed, otherwise False.

classmethod callbackPostClick(menuPath: str, controller: StageSubtreeController, selectedPrimPaths: PathArray, node: UsdLayerSuperTool, editor: UsdSuperLayerEditor) → None

Optional callback best suited for post-processing tasks, such as selecting created prims (runs after callbackOnClick, only if it has returned True).

Best suited for post-processing tasks, such as selecting the created prims.

Parameters:

menuPath (str) – The menu path. See menuPaths() for details.
controller (StageSubtreeController) – The StageSubtreeController stored in UsdSuperLayer.
selectedPrimPaths (PathArray) – The prim paths selected by user.
node (UsdLayerSuperTool) – The UsdSuperLayer node instance.
editor (UsdSuperLayerEditor) – The Qt widget instance that triggered this callback.

Return type:

None

classmethod isEnabled(menuPath: str, controller: StageSubtreeController, selectedPrimPaths: PathArray) → bool

Return True if the menu specified by the given menuPath should be enabled, otherwise False.

Parameters:

menuPath (str) – The menu path that is enabled or disabled.
controller (StageSubtreeController) – The StageSubtreeController stored in UsdSuperLayer.
selectedPrimPaths (PathArray) – The prim paths selected when building menus.

Returns:

bool – True if the menu is enable, otherwise False.

classmethod isVisible(menuPath: str, controller: StageSubtreeController, selectedPrimPaths: PathArray) → bool

Return True if the menu specified by the given menuPath should be visible, otherwise False.

Parameters:

menuPath (str) – The menu path that is should be visible or not.
controller (StageSubtreeController) – The content layer
selectedPrimPaths (PathArray) – The prim paths selected when building menus.

Returns:

bool – True if the menu should be visible, otherwise False.

classmethod menuPaths() → list[str]

Must be implemented in subclasses. Returns the list of menu paths, where each path is a string formed by the menu titles separated by slashes.

Additionally, MENU_NAME_SEPARATOR inserts a separator in menu. For example, the return value is [“File/Open”, MENU_NAME_SEPARATOR, “Setting/UI/Color”].

Raises:: NotImplementedError –
Returns:: list[str] – The menu paths.

classmethod shortcutKeys(menuPath: str) → QKeySequence

Returns shortcut key for the menu specified by the provided menuPath.

Parameters:: menuPath (str) – The menu path.
Returns:: QKeySequence – The shortcut key.

classmethod tooltip(menuPath: str) → str

Returns tooltip message showed on the menu specified by the provided menuPath.

Parameters:: menuPath (str) – The menu path.
Returns:: str – The tooltip message.

class NodesUsdAPI.UsdSuperLayer.ContextMenuPlugin.PluginRegistry.ContextMenuPluginRegistry

Bases: PluginRegistryBase

PLUGIN_TYPE_NAME = 'UsdSuperLayerContextMenu'

__init__(): Initializer.

classmethod __new__(*args, **kwargs)

getActive(pluginName: str) → bool | None

Returns the active value of the plug-in specified by pluginName. If there is no corresponding plug-in, returns None.

Parameters:: pluginName (str) – plug-in name.
Returns:: bool | None – The active value.

getNodesRegisteredToPlugin(pluginName: str) → list[str] | None

Returns the list of nodes that the plug-in specified will construct for when building a context menu.

Parameters:: pluginName (str) – The name of the plug-in.
Returns:: list[str] | None – The nodes the plug-in constructs for.

getPlugin(pluginName: str) → type | None

Returns the registered plug-in.

Parameters:: pluginName (str) – The name of the plug-in to find.
Returns:: type | None – The registered plug-in. Returns None if the Plugin with the provided name cannot be found.

getPluginName(plugin: type) → str | None

Returns the plug-in name of the specified plugin. If there is no corresponding plug-in, returns None.

A plug-in can be retrieved via getPlugin().

Parameters:: plugin (type) – The registered plug-in.
Returns:: str | None – The plug-in name.

getPluginNames(onlyActive: bool = True) → list[str]

Returns registered active plug-in names by default. The names are returned in a sorted order based on priority and then plug-in name if priorities match.

Parameters:: onlyActive (bool, default: True) – If True, gather active plug-ins only; otherwise all plug-ins (active and inactive) will be selected. Defaults to True.
Returns:: list[str] – The names of plug-ins.

classmethod getPluginTypeName() → str

Returns:: str – The type of the plug-in.

getPlugins(onlyActive: bool = True) → list[type]

Return the registered active plug-ins by default. The plug-ins are returned in a sorted order based on priority and then plug-in name if priorities match.

Parameters:: onlyActive (bool, default: True) – If True, gather active plug-ins only; otherwise all plug-ins (active and inactive) will be selected. Defaults to True.
Returns:: list[type] – The registered active plug-ins.

getPluginsForNode(nodeTypeName: str, onlyActive: bool = True) → list[type]

Returns active plug-ins for a given node by default.

Parameters:

nodeTypeName (str) – The name of the node.
onlyActive (bool, default: True) – If True, gather active plug-ins only; otherwise all plug-ins (active and inactive) will be selected. Defaults to True.

Returns:

list[type] – The plug-ins for the given node.

getPriority(pluginName: str) → int | None

Returns the priority value of the plug-in specified by pluginName. if there is no corresponding plug-in, returns None.

Parameters:: pluginName (str) – The name of the plug-in.
Returns:: int | None – The priority value.

loadPluginsFromKatanaResources(reloadCached: bool = False) → None

Loads the plug-ins from the “UIPlugins” subfolder of all folders registered to the KATANA_RESOURCES environment variable.

Parameters:: reloadCached (bool, default: False) – Decides whether it should reload modules this plug-in system has already searched and added. By default this is set to False.
Return type:: None

registerNodeToPlugin(pluginName: str, nodeName: str) → bool

Registers the specified nodeName to the list of nodes that the plug-in specified will construct for when building a context menu. Will return False if the node is already registered.

Parameters:

pluginName (str) – The name of the plug-in.
nodeName (str) – The name of the node.

Returns:

bool – True if the given pluginName is successfully registered; False otherwise.

registerPlugin(plugin: Plugin) → bool

Registers the plug-in with the plug-in name into self._registeredPlugins. If the plug-in was already found with the same plug-in name, this plug-in will not be registered.

Parameters:: plugin (Plugin) – The plug-in registered.
Returns:: bool – True if the registration is successful; False otherwise.

setActive(pluginName: str, active: bool = True) → bool

Sets the given active value for the plugin specified by the provided name. The active value is used to determine which plug-ins are gathered in functions like getPlugins, GetPluginNames, etc.

Parameters:

pluginName (str) – plug-in name.
active (bool, default: True) – active value set for plug-in, defaults to True.

Returns:

bool – True if this the given active is successfully set, False otherwise.

setPriority(pluginName: str, priority: int) → bool

Sets the given priority value for the plug-in specified by the provided name. The priority value is used to determine which plug-ins are returned first in functions like getPlugins, GetPluginNames, etc.

Parameters:

pluginName (str) – The name of the plug-in.
priority (int) – Priority value set for plug-in.

Returns:

bool – True if the given priority is successfully set; False otherwise.

unregisterNodeFromPlugin(pluginName: str, nodeName: str) → bool

Unregister the specified nodeName from the list of nodes that the plug-in specified will construct for when building a context menu. Will return False if the node isn’t already registered.

Parameters:

pluginName (str) – The name of the plug-in.
nodeName (str) – The name of the node.

Returns:

bool – True if the given pluginName is successfully unregistered; False otherwise.

unregisterPlugin(pluginName: str) → None

Removes a plug-in from the UsdLayerSuperTool plug-ins, preventing it from running whilst performing a UsdLayerSuperTool.

Parameters:: pluginName (str) – The name of the plug-in to find.
Return type:: None

validatePlugin(pluginName: str, plugcls: type, args: dict) → str

Re-implemented. Pure virtual method that is to be implemented in subclasses. The implementation must validate the given plug-in, returning a non-empty error message if it is not valid.

Parameters:

pluginName (str) – The plug-in name.
pluginCls – The plug-in class.
args (dict) – The plug-in arguments.
plugcls (type)

Raises:

NotImplementedError – This method must be implemented in subclasses.

Returns:

str – An error message if the validation does not succeed.

Parameters Handler Plug-ins

Overview

This section describes how extra parameters can be created with UsdSuperLayerParametersHandler plug-ins registered for UsdSuperLayer-derived node types.

These extensions are written in the form of ParametersHandlerPluginBase-derived classes that are registered as regular Katana Python plug-ins. A ParametersHandlerPlugin defines the parameters that are shown in the Parameters tab when a target prim is selected; handling of parameter changes is implemented in the plug-in too: the plug-in can modify the USD Prim in the content layer.

In addition to registering and unregistering plug-ins from the plug-in registry, which can be done at runtime with the ParametersHandlerPluginRegistry Python API, it is also possible to temporarily deactivate without unregistering plug-ins from the system.

The plug-in consists of a class and its registration, defined in a Python file placed within a subdirectory named /Plugins under the KATANA_RESOURCES path. This allows Katana to automatically pick up and load the plug-in during startup.

To define the class, it must derive from ParametersHandlerPluginBase and implement the isPrimSupported(), buildOrUpdateParameters(), and onParameterChanged() class methods.

class UsdSuperLayerExampleParametersHandlerPlugin(ParametersHandlerPluginBase):
    @classmethod
    def isPrimSupported(
        cls,
        node: NodegraphAPI.Node,
        primPath: str,
        usdPrim: usg.Prim | None,
        sdfPrim: usg.Prim | None,
    ) -> bool:
        ...

      @classmethod
    def buildOrUpdateParameters(
        cls,
        node: NodegraphAPI.Node,
        primPath: str,
        usdPrim: usg.Prim | None,
        sdfPrim: usg.Prim | None,
        groupParam: NodegraphAPI.Parameter,
    ) -> None:
        ...

      @classmethod
    def onParameterChanged(
        cls,
        node: NodegraphAPI.Node,
        primPath: str,
        sdfPrim: usg.Prim,
        groupParam: NodegraphAPI.Parameter,
        parameter: NodegraphAPI.Parameter,
        parameterSampleTime: float,
        usdSampleTime: float,
    ) -> bool:
        ...

The isPrimSupported() class method must return True to indicate that the target prim, as specified by the prim path argument, is to be managed by the plug-in. For example, the predicate can be based on the existence of a certain USD Schema applied in the prim.

The buildOrUpdateParameters() class method is called on prims that have been stated as supported by the isPrimSupported() method. The method is in charge of defining (or updating) parameters for the target prim.

The onParameterChanged() class method is invoked when parameters previously created by the buildOrUpdateParameters() method change. It gives the plug-in an opportunity to make persistent changes in the content layer from the UsdSuperLayer-derived node.

To register the defined class as a plug-in, a top-level, global variable called PluginRegistry must be defined in the Python module. The variable is a list of tuples, with each tuple containing plug-in definitions. For example:

PluginRegistry = [
    (
        'UsdSuperLayerParametersHandler',
        1,
        'ExampleParametersHandlerPlugin',
        (
            UsdSuperLayerExampleParametersHandlerPlugin,
            {
                'active': True,
                'priority': 0,
                'appliedNodes': ['all'],
            },
        ),
    ),
]

UsdSuperLayerParametersHandler is the plug-in type name.
1 is the plug-in version.
ExampleParametersHandlerPlugin is the unique plug-in name. A list of currently registered plug-in names can be found by querying the ParametersHandlerPlugin registry.
UsdSuperLayerExampleParametersHandlerPlugin is the class derived from the ParametersHandlerPluginBase class.
{'active': True, 'priority': 0, 'appliedNodes': ['all']} are plug-in options, which currently supports the following:
- active defines whether the plug-in is initially active. The default value is True. Plug-ins’ active state can be changed at a later time via ParametersHandlerPluginRegistry.setActive().
- priority defines the order in which plug-ins of this type will be loaded, where 0 is the default. Lower values are higher priority, and thus will appear higher up in the parameter list in the UI.
- appliedNodes is a list of node type names. The plug-in will apply to node instances of the given node type(s). If all is included in the list, the plug-in is applied to all node types. Plug-ins’ nodes list can be added to at a later time via ParametersHandlerPluginRegistry.registerNodeToPlugin().

Examples

UsdSuperLayerExampleParametersHandlerPlugin.py

# Copyright (c) 2025 The Foundry Visionmongers Ltd. All Rights Reserved.
"""
Module containing an example Parameters Handler plug-in for UsdSuperLayer-derived node types.
"""

import logging

import usg

import NodegraphAPI
from NodesUsdAPI.UsdSuperLayer import ParametersHandlerPlugin, Utils

log = logging.getLogger("ExampleParametersHandlerPlugin")


class UsdSuperLayerExampleParametersHandlerPlugin(
    ParametersHandlerPlugin.ParametersHandlerPluginBase,
):
    """
    An example of a ``UsdSuperLayerParametersHandler`` plug-in that adds a new parameter group called
    ``'image'`` that includes some user-defined parameters that are then translated into USD
    Attributes on the target USD Prim in the UsdSuperLayer-derived nodes.
    """

    @classmethod
    def isPrimSupported(
        cls,
        node: NodegraphAPI.Node,
        primPath: str,
        usdPrim: usg.Prim | None,
        sdfPrim: usg.Prim | None,
    ) -> bool:
        """
        Implements `ParametersHandlerPluginBase.isPrimSupported()`.

        Invoked by UsdSuperLayer-derived nodes when the selected prim in the node changes, the prim
        in the incoming USD Stage changes, or the prim in the content layer changes.

        Plug-ins must implement the function to specify whether a given prim is to be handled by
        this plug-in. If supported, :py:obj:`buildOrUpdateParameters()` will be invoked next after
        a dedicated group parameter has been created for this prim path and plug-in.

        :param node: The UsdSuperLayer-derived node.
        :param primPath: The absolute path to the prim.
        :param usdPrim: The USD Prim in the stage if it exists.
        :param sdfPrim: The USD Prim in the content layer if it exists.
        :return: Whether the prim should be handled by the plug-in, in which case
            :py:obj:`buildOrUpdateParameters()` will be invoked next.
        """
        # All prims are supported and will create parameters defined by this plug-in.
        return True

    @classmethod
    def getGroupParameterLabel(cls) -> str:
        """
        Implements `ParametersHandlerPluginBase.getGroupParameterLabel()`.

        Invoked by UsdSuperLayer-derived nodes.

        Plug-ins can implement the function to define the label that will be used for the group
        parameter widget that holds the parameters that the plug-in creates.

        :return: The label for the group parameter that will hold the parameters that the plug-in
            creates. Common labels can be ``'properties'``, ``'inputs'``, or ``'transform'``.
        """
        return 'image'

    @classmethod
    def buildOrUpdateParameters(
        cls,
        node: NodegraphAPI.Node,
        primPath: str,
        usdPrim: usg.Prim | None,
        sdfPrim: usg.Prim | None,
        groupParam: NodegraphAPI.Parameter,
    ) -> None:
        """
        Implements `ParametersHandlerPluginBase.buildOrUpdateParameters()`.

        Invoked by UsdSuperLayer-derived nodes if :py:obj:`isPrimSupported()` in the plug-in has
        returned ``True``.

        Plug-ins can implement the function to create their own parameters based on the prim in the
        incoming stage.

        :param node: The UsdSuperLayer-derived node.
        :param primPath: The absolute path to the prim.
        :param usdPrim: The USD Prim in the stage if it exists.
        :param sdfPrim: The USD Prim in the content layer if it exists.
        :param groupParam: The group parameter, previously manufactured for the plug-in only, in
            which the plug-in can create its relevant child parameters.
        """
        # Build parameters if not yet created. These parameters include a **stageparameter** child
        # parameter that enables the StageParameterPolicy in the group parameter.
        filepathGroupParam = groupParam.getChild('filepath')
        if filepathGroupParam is None:
            filepathGroupParam = groupParam.createChildGroup('filepath')
            filepathGroupParam.createChildNumber('enable', 0)
            filepathGroupParam.createChildString('default', '')
            filepathGroupParam.createChildString('value', '')
            filepathGroupParam.createChildNumber('stageparameter', 0.0)
            filepathGroupParam.setHintString(
                str({
                    'widget': 'assetIdInput',
                    'fileTypes': 'png|gif|jpg|webp',
                    'help': 'An example parameter where the user can select an image filepath.',
                }),
            )
        scaleGroupParam = groupParam.getChild('scale')
        if scaleGroupParam is None:
            scaleGroupParam = groupParam.createChildGroup('scale')
            scaleGroupParam.createChildNumber('enable', 0)
            scaleGroupParam.createChildNumber('default', 0.0)
            scaleGroupParam.createChildNumber('value', 0.0)
            scaleGroupParam.createChildNumber('stageparameter', 0.0)
            scaleGroupParam.setHintString(
                str({'help': 'Another parameter with a hypothetical image scale.'}),
            )
        modeGroupParam = groupParam.getChild('mode')
        if modeGroupParam is None:
            modeGroupParam = groupParam.createChildGroup('mode')
            modeGroupParam.createChildNumber('enable', 0)
            modeGroupParam.createChildString('default', '')
            modeGroupParam.createChildString('value', '')
            modeGroupParam.createChildNumber('stageparameter', 0.0)
            modeGroupParam.setHintString(
                str({
                    'widget': 'popup',
                    'options': ('', 'RGBA', 'RGB', 'Grayscale'),
                    'help': 'Yet another parameter to select a color mode.',
                }),
            )

        # Update state based on content layer.
        if sdfPrim is not None:
            attr = sdfPrim.getAttr('image:filepath')
            enableState = 0.0
            value = None
            if attr is not None:
                if attr.isBlocked():
                    enableState = -1.0
                else:
                    enableState = 1.0
                    value = attr.get()
            filepathGroupParam.getChild('enable').setValue(enableState, 0.0)
            if value is not None:
                filepathGroupParam.getChild('value').setValue(value, 0.0)

            attr = sdfPrim.getAttr('image:scale')
            enableState = 0.0
            value = None
            if attr is not None:
                if attr.isBlocked():
                    enableState = -1.0
                else:
                    enableState = 1.0
                    value = attr.get()
            scaleGroupParam.getChild('enable').setValue(enableState, 0.0)
            if value is not None:
                scaleGroupParam.getChild('value').setValue(value, 0.0)

            attr = sdfPrim.getAttr('image:mode')
            enableState = 0.0
            value = None
            if attr is not None:
                if attr.isBlocked():
                    enableState = -1.0
                else:
                    enableState = 1.0
                    value = attr.get()
            modeGroupParam.getChild('enable').setValue(enableState, 0.0)
            if value is not None:
                modeGroupParam.getChild('value').setValue(value, 0.0)
        else:
            # Remove the enable state from all the parameters if the prim is not valid, since they
            # will no longer be local.
            filepathGroupParam.getChild('enable').setValue(0, 0.0)
            scaleGroupParam.getChild('enable').setValue(0, 0.0)
            modeGroupParam.getChild('enable').setValue(0, 0.0)

    @classmethod
    def onParameterChanged(
        cls,
        node: NodegraphAPI.Node,
        primPath: str,
        sdfPrim: usg.Prim,
        groupParam: NodegraphAPI.Parameter,
        parameter: NodegraphAPI.Parameter,
        parameterSampleTime: float,
        usdSampleTime: float,
    ) -> bool:
        """
        Implements `ParametersHandlerPluginBase.onParameterChanged()`.

        Invoked by UsdSuperLayer-derived nodes when a parameter created previously by
        :meth:`buildOrUpdateParameters()` changes.

        Plug-ins can implement the function to react to parameter changes.

        :param node: The UsdSuperLayer-derived node.
        :param primPath: The absolute path to the prim.
        :param sdfPrim: The prim in the content layer that the plug-in can modify.
        :param groupParam: The group parameter that holds all the plug-in-defined parameters for the
            target prim.
        :param parameter: The parameter, created previously by :meth:`buildOrUpdateParameters()`,
            that has changed.
        :param parameterSampleTime: The time at which to sample the parameter to retrieve the value.
        :param usdSampleTime: The sample time at which to store the USD property. During an
            interactive session, this will typically be the defaultTimeSample. Whilst exporting or
            rendering, this will be called for all required time samples.
        :return: ``True`` if the ``sdfPrim`` was modified as a result of the parameter change;
            otherwise ``False``.
        """
        # Select the children of the StageParameterPolicy group parameter.
        parameterParts = Utils.getEnableParameterParts(parameter)
        if parameterParts is None:
            return False
        sppGroupParam, _valueParamType, enableState, valueParam, _defaultParam = parameterParts

        paramName = sppGroupParam.getName()
        attributeName = f'image:{paramName}'

        # Incoming value.
        if enableState == 0.0:
            # If no local value is set, the property is cleared
            sdfPrim.removeProperty(attributeName)
        else:
            # If a local value is set, an attribute will be created (if it does not exist yet), and
            # the value will be set.
            attr = sdfPrim.getAttr(attributeName)
            if attr is None:
                # In this example, only two types are used: either string or double.
                if valueParam.getType() == 'string':
                    attributeType = usg.Value.Type.String
                else:
                    attributeType = usg.Value.Type.Double
                attr = sdfPrim.createAttr(attributeName, attributeType)

            # Local value.
            if enableState == 1.0:
                # Here we use the parameter sample time to read the value from the parameter, and
                # the usd sample time to set the value on the attribute.
                attr.set(valueParam.getValue(parameterSampleTime), usdSampleTime)
            # Force default.
            else:
                attr.block()

        # The method must return `True` if a change has been made to the `sdfPrim` prim. In this
        # example, all code paths lead to a change.
        return True

    @classmethod
    def getIncomingLocalUsgValue(
        cls,
        node: NodegraphAPI.Node,
        prim: usg.Prim,
        groupParam: NodegraphAPI.Parameter,
        parameter: NodegraphAPI.Parameter,
    ) -> usg.Value | None:
        """
        Implements `ParametersHandlerPluginBase.getIncomingLocalUsgValue()`.

        Invoked by UsdSuperLayer-derived nodes when a parameter, created previously by
        :meth:`buildOrUpdateParameters()`, requires the local value from the incoming USD Stage.

        Plug-ins must implement this function if the parameters created in
        :meth:`buildOrUpdateParameters()` are managed by the StageParameterPolicy.

        :param node: The UsdSuperLayer-derived node.
        :param prim: The USD Prim from which to source the `usg.Value`.
        :param groupParam: The group parameter that holds all the plug-in-defined parameters for the
            target prim.
        :param parameter: The parameter; a descendant of the `groupParam` group parameter; that is
            associated to the incoming local value request. Plug-in implementations can use it to
            determine how to source or synthesize the value.
        :return: The `usg.Value` retrieved from the given USD Prim based on the parameter.
        """
        paramName = parameter.getName()
        attributeName = f'image:{paramName}'

        # The method needs to query the incoming USD Stage to retrieve the potential incoming value
        # from the target attribute.
        attr = prim.getAttr(attributeName)
        if attr is None or not attr.isValid():
            return None

        return attr.getUsgValue()


PluginRegistry = [
    (
        'UsdSuperLayerParametersHandler',
        1,
        'ExampleParametersHandlerPlugin',
        (
            UsdSuperLayerExampleParametersHandlerPlugin,
            {
                'active': True,
                'priority': 0,
                'appliedNodes': ['all'],
            },
        ),
    ),
]

API

class NodesUsdAPI.UsdSuperLayer.ParametersHandlerPlugin.ParametersHandlerPluginBase

Bases: ABC

Base class for ParametersHandler plug-ins.

abstractmethod classmethod buildOrUpdateParameters(node: Node, primPath: str, usdPrim: Prim | None, sdfPrim: Prim | None, groupParam: Parameter) → None

Invoked by UsdSuperLayer-derived nodes if isPrimSupported() in the plug-in has returned True.

Plug-ins can implement the function to create their own parameters based on the prim in the incoming stage.

Parameters:

node (Node) – The UsdSuperLayer-derived node.
primPath (str) – The absolute path to the prim.
usdPrim (Prim | None) – The USD Prim in the stage if it exists.
sdfPrim (Prim | None) – The USD Prim in the content layer if it exists.
groupParam (Parameter) – The group parameter, previously manufactured for the plug-in only, in which the plug-in can create its relevant child parameters.

Return type:

None

abstractmethod classmethod getGroupParameterLabel() → str

Invoked by UsdSuperLayer-derived nodes.

Plug-ins can implement the function to define the label that will be used for the group parameter widget that holds the parameters that the plug-in creates.

Returns:: str – The label for the group parameter that will hold the parameters that the plug-in creates. Common labels can be 'properties', 'inputs', or 'transform'.

abstractmethod classmethod getIncomingLocalUsgValue(node: Node, prim: Prim, groupParam: Parameter, parameter: Parameter) → Value | None

Invoked by UsdSuperLayer-derived nodes when a parameter, created previously by buildOrUpdateParameters(), requires the local value from the incoming USD Stage.

Plug-ins must implement this function if the parameters created in buildOrUpdateParameters() are managed by the StageParameterPolicy.

Parameters:

node (Node) – The UsdSuperLayer-derived node.
prim (Prim) – The USD Prim from which to source the usg.Value.
groupParam (Parameter) – The group parameter that holds all the plug-in-defined parameters for the target prim.
parameter (Parameter) – The parameter; a descendant of the groupParam group parameter; that is associated to the incoming local value request. Plug-in implementations can use it to determine how to source or synthesize the value.

Returns:

Value | None – The usg.Value retrieved from the given USD Prim based on the parameter.

abstractmethod classmethod isPrimSupported(node: Node, primPath: str, usdPrim: Prim | None, sdfPrim: Prim | None) → bool

Invoked by UsdSuperLayer-derived nodes when the selected prim in the node changes, the prim in the incoming USD Stage changes, or the prim in the content layer changes.

Plug-ins must implement the function to specify whether a given prim is to be handled by this plug-in. If supported, buildOrUpdateParameters() will be invoked next after a dedicated group parameter has been created for this prim path and plug-in.

Parameters:

node (Node) – The UsdSuperLayer-derived node.
primPath (str) – The absolute path to the prim.
usdPrim (Prim | None) – The USD Prim in the stage if it exists.
sdfPrim (Prim | None) – The USD Prim in the content layer if it exists.

Returns:

bool – Whether the prim should be handled by the plug-in, in which case buildOrUpdateParameters() will be invoked next.

abstractmethod classmethod onParameterChanged(node: Node, primPath: str, sdfPrim: Prim, groupParam: Parameter, parameter: Parameter, parameterSampleTime: float, usdSampleTime: float) → bool

Invoked by UsdSuperLayer-derived nodes when a parameter created previously by buildOrUpdateParameters() changes.

Plug-ins can implement the function to react to parameter changes.

Parameters:

node (Node) – The UsdSuperLayer-derived node.
primPath (str) – The absolute path to the prim.
sdfPrim (Prim) – The prim in the content layer that the plug-in can modify.
groupParam (Parameter) – The group parameter that holds all the plug-in-defined parameters for the target prim.
parameter (Parameter) – The parameter, created previously by buildOrUpdateParameters(), that has changed.
parameterSampleTime (float) – The time at which to sample the parameter to retrieve the value.
usdSampleTime (float) – The sample time at which to store the USD property. During an interactive session, this will typically be the defaultTimeSample. Whilst exporting or rendering, this will be called for all required time samples.

Returns:

bool – True if the sdfPrim was modified as a result of the parameter change, otherwise False.

classmethod setOverride(node: Node, propertiesParam: Parameter, attrName: str, time: float, attrData: list[float]) → bool

Applies the node’s transform parameter overrides from given attribute value. This is required by manipulators. The Parameter Handler Plug-ins are responsible for handling this if they want to. The default is that they do not, and return False.

Parameters:

node (Node) – The node to which the parameters belong.
propertiesParam (Parameter) – The group parameter that holds all the plug-in-defined parameters for the target prim.
attrName (str) – The name of the attribute to be overriden.
time (float) – The frameTime of current graph state.
attrData (list[float]) – The list of attribute data to override with.

Returns:

bool – Whether the plug-in has acted on this method.

class NodesUsdAPI.UsdSuperLayer.ParametersHandlerPlugin.PluginRegistry.ParametersHandlerPluginRegistry

Bases: PluginRegistryBase

PLUGIN_TYPE_NAME = 'UsdSuperLayerParametersHandler'

__init__(): Initializer.

classmethod __new__(*args, **kwargs)

getActive(pluginName: str) → bool | None

Returns the active value of the plug-in specified by pluginName. If there is no corresponding plug-in, returns None.

Parameters:: pluginName (str) – plug-in name.
Returns:: bool | None – The active value.

getNodesRegisteredToPlugin(pluginName: str) → list[str] | None

Returns the list of nodes that the plug-in specified will construct for when building a context menu.

Parameters:: pluginName (str) – The name of the plug-in.
Returns:: list[str] | None – The nodes the plug-in constructs for.

getPlugin(pluginName: str) → type | None

Returns the registered plug-in.

Parameters:: pluginName (str) – The name of the plug-in to find.
Returns:: type | None – The registered plug-in. Returns None if the Plugin with the provided name cannot be found.

getPluginName(plugin: type) → str | None

Returns the plug-in name of the specified plugin. If there is no corresponding plug-in, returns None.

A plug-in can be retrieved via getPlugin().

Parameters:: plugin (type) – The registered plug-in.
Returns:: str | None – The plug-in name.

getPluginNames(onlyActive: bool = True) → list[str]

Returns registered active plug-in names by default. The names are returned in a sorted order based on priority and then plug-in name if priorities match.

Parameters:: onlyActive (bool, default: True) – If True, gather active plug-ins only; otherwise all plug-ins (active and inactive) will be selected. Defaults to True.
Returns:: list[str] – The names of plug-ins.

classmethod getPluginTypeName() → str

Returns:: str – The type of the plug-in.

getPlugins(onlyActive: bool = True) → list[type]

Return the registered active plug-ins by default. The plug-ins are returned in a sorted order based on priority and then plug-in name if priorities match.

Parameters:: onlyActive (bool, default: True) – If True, gather active plug-ins only; otherwise all plug-ins (active and inactive) will be selected. Defaults to True.
Returns:: list[type] – The registered active plug-ins.

getPluginsForNodeType(nodeTypeName: str, onlyActive: bool = True) → list[type]

Retrieves the plug-in types registered for a given node type name.

By default, only the plug-in type of active plug-ins is returned.

Parameters:

nodeTypeName (str) – The name of the node type.
onlyActive (bool, default: True) – If True, gather active plug-ins only; otherwise all plug-ins (active and inactive) will be selected. Defaults to True.

Returns:

list[type] – The plug-in types for the given node type.

getPriority(pluginName: str) → int | None

Returns the priority value of the plug-in specified by pluginName. if there is no corresponding plug-in, returns None.

Parameters:: pluginName (str) – The name of the plug-in.
Returns:: int | None – The priority value.

loadPluginsFromKatanaResources(reloadCached: bool = False) → None

Loads the plug-ins from the “Plugins” subfolder of all folders registered to the KATANA_RESOURCES environment variable.

Parameters:: reloadCached (bool, default: False) – Decides whether it should reload modules this plug-in system has already searched and added. By default this is set to False.
Return type:: None

registerNodeToPlugin(pluginName: str, nodeName: str) → bool

Registers the specified nodeName to the list of nodes that the plug-in specified will construct for when building a context menu. Will return False if the node is already registered.

Parameters:

pluginName (str) – The name of the plug-in.
nodeName (str) – The name of the node.

Returns:

bool – True if the given pluginName is successfully registered; False otherwise.

registerPlugin(plugin: Plugin) → bool

Registers the plug-in with the plug-in name into self._registeredPlugins. If the plug-in was already found with the same plug-in name, this plug-in will not be registered.

Parameters:: plugin (Plugin) – The plug-in registered.
Returns:: bool – True if the registration is successful; False otherwise.

setActive(pluginName: str, active: bool = True) → bool

Sets the given active value for the plugin specified by the provided name. The active value is used to determine which plug-ins are gathered in functions like getPlugins, GetPluginNames, etc.

Parameters:

pluginName (str) – plug-in name.
active (bool, default: True) – active value set for plug-in, defaults to True.

Returns:

bool – True if this the given active is successfully set, False otherwise.

setPriority(pluginName: str, priority: int) → bool

Sets the given priority value for the plug-in specified by the provided name. The priority value is used to determine which plug-ins are returned first in functions like getPlugins, GetPluginNames, etc.

Parameters:

pluginName (str) – The name of the plug-in.
priority (int) – Priority value set for plug-in.

Returns:

bool – True if the given priority is successfully set; False otherwise.

unregisterNodeFromPlugin(pluginName: str, nodeName: str) → bool

Unregister the specified nodeName from the list of nodes that the plug-in specified will construct for when building a context menu. Will return False if the node isn’t already registered.

Parameters:

pluginName (str) – The name of the plug-in.
nodeName (str) – The name of the node.

Returns:

bool – True if the given pluginName is successfully unregistered; False otherwise.

unregisterPlugin(pluginName: str) → None

Removes a plug-in from the UsdLayerSuperTool plug-ins, preventing it from running whilst performing a UsdLayerSuperTool.

Parameters:: pluginName (str) – The name of the plug-in to find.
Return type:: None

validatePlugin(pluginName: str, pluginClass: type, args: dict) → str

Implements the PluginRegistryBase.validatePlugin() virtual method to validate plug-ins.

Parameters:

pluginName (str) – The plug-in name.
pluginClass (type) – The plug-in class.
args (dict) – The plug-in arguments.

Returns:

str – A non-empty error message if the validation fails.