Material Soloing

New in Katana 6.0: Arbitrary ports can now be soloed through a set of new member functions on NetworkMaterialCreate and NetworkMaterialEdit nodes. To achieve this MaterialSoloingConverters are used.

Introduction

Any port can be soloed, given a compatible MaterialSoloingConverter plug-in has been registered using the standard PluginRegistry system. More details can be found in the Example User MaterialSoloingConverter section below.

A MaterialSoloingConverter defines a conversion network from a given port type, to a type which is appropriate for rendering. By default, some MaterialSoloingConverters are defined within Katana, however developers are free to inherit from BaseMaterialSoloingConverter and register their own.

Any material soloing is non-persistent, and will not be saved to disk, baked (e.g via: LookFileBake, LookFileMultiBake, UsdMaterialBake, and LookFileMaterialsOut nodes), or partake in disk renders.

MaterialSoloingConverter Base Class

class BaseMaterialSoloingConverter.BaseMaterialSoloingConverter

Bases: ABC

Base class for extending Network Material Soloing MaterialSoloingConverters.

Classes derived from this class should be registered as Katana plug-ins of type MaterialSoloingConverter.

A single derived class should represent the conversion from a single portToSolo to a network which can be used to solo that port.

abstract createConversionNetwork(portToSolo: Port, mscContainerGroup: GroupNode) tuple[NodegraphAPI.Port, dict[str, NodegraphAPI.Port]]

Creates the MaterialSoloingConverter network. This function should be overridden in derived classes and should have the following responsibilities: * Create an MSC network contained within an MSC container group node * Return the start port, and a mapping of terminal port names to MSC network end ports

Return type:

2-tuple of NodegraphAPI.Port and dict of str to NodegraphAPI.Port

Parameters:
  • portToSolo (NodegraphAPI.Port) – Port from which the implemented conversion network will take it’s input from.

  • mscContainerGroup (NodegraphAPI.GroupNode) – Group node to place conversion network nodes inside of.

Returns:

A tuple containing the starting port of the MSC network, and a mapping of terminal port names to the end ports of the network.

abstract getBaseShadingNodeType() str
Return type:

str

Returns:

Name of the base shading node type used by the derived class.

abstract getName() str
Return type:

str

Returns:

Human-readable name for this MSC class.

abstract isCompatible(portToSolo: Port) bool

Checks whether a given port can be used as input to this MaterialSoloingConverter’s network.

Return type:

bool

Parameters:

portToSolo (NodegraphAPI.Port) – The port which is to be checked for compatibility with this MaterialSoloingConverter.

Returns:

True if this MSC is compatible with the given port, False otherwise.

Example User MaterialSoloingConverter

Developers are free to write their own MaterialSoloingConverter, an example of this could look like the following:

from PluginsAPI.BaseMaterialSoloingConverter import BaseMaterialSoloingConverter

class MyMaterialSoloingConverter(BaseMaterialSoloingConverter):
    pass

PluginRegistry = [
    ("MaterialSoloingConverter", 1, "MyMaterialSoloingConverter", MyMaterialSoloingConverter)
]

The body of MyMaterialSoloingConverter should be replaced with implementations of methods marked abstract in the PluginsAPI.BaseMaterialSoloingConverter.BaseMaterialSoloingConverter class, example MaterialSoloingConverters for commonly used render plug-ins can be found under $KATANA_ROOT/plugins/Src/Resources/Core/Plugins.

To capture the plug-in, add it to your KATANA_RESOURCES env path variable in a Plugins subfolder. For example:

# For a plug-in at /home/Gandalf/katana_resources/Plugins/MyMaterialSoloingConverter.py:

KATANA_RESOURCES=/home/Gandalf/katana_resources

Material Solo Attribute Usage

See also

Attribute Conventions For Solo Materials for more information on the soloMaterial attribute.

When a MaterialResolve Op is run, the soloMaterial and material attribute groups are copied to the assignee (likely a geometry scene graph location).

A MaterialSoloResolve Op has been introduced as an implicit resolver, and is inserted at the front of all render plug-in terminal Op chains when a Live or Preview render is triggered (note: disk renders are exempt), and is also run before viewer implicit resolvers are run, meaning soloing works in the viewer as well. The MaterialSoloResolve Op moves any soloMaterial attribute groups to a material attribute group at the same scene graph location, effectively applying the solo material.

As well as the MaterialSoloResolve Op being added to Live and Preview renders, all soloMaterial attributes are removed on look file bake by being inserted at the start of any look file bake Op chains, e.g: LookFileBake, LookFileMultiBake, UsdMaterialBake, and LookFileMaterialsOut nodes are all included.