Glossary of Katana Terms

This glossary provides short descriptions of the most important terms used throughout the Katana application and documentation.

Knowledge of these core terms help you to understand the way Katana works and processes data more clearly, and enable you to make the most of the Katana documentation.

Katana Core Terms

Nodes

Nodes are the units used in the Katana interface to build the Recipe for a Katana project. Nodes feature Parameters that can be used to control their behavior. Nodes can be created and connected in Katana's Node Graph tab in the UI, and can also be modified through Python scripting using NodegraphAPI.

Katana ships with many built-in types of nodes, but custom node types can also be created through Python scripting. There are two major groups of node types shipped with Katana:

  • 3D nodes that produce scene graph that can be inspected in Katana's Scene Graph tab.
  • 2D nodes that produce images that can be viewed in Katana's Monitor tab.

Nodes and their Parameters effectively represent and control corresponding Ops that form Op graphs that are processed by Katana's geometry library to generate the scene data that can be viewed and inspected in Katana's Scene Graph and Attributes tabs.

Note:  For more information about working with nodes in the Katana UI, please see, Editing the Node Graph. For working with nodes through Python Scripting, please see the relevant Working With Nodes section of the Katana developer guide.

Node Graph

Node Graphs in Katana are Recipes of connected nodes that are part of a Katana project. The nodes in node graphs can be created and connected in Katana's Node Graph tab in the UI, and can also be modified through Python scripting using functionality from the NodegraphAPI Python package.

Parameters

Parameters are a part of nodes, and typically control their respective node's behavior. Parameters of nodes can be edited in Katana's Parameters tab in the UI, by setting the edit flag on a node in the Node Graph tab, and can also be edited through Python scripting using parts of the NodegraphAPI. Values of parameters can be either constant, determined by Python expressions, or driven by animation curves.

Recipe

Recipes in Katana are node graphs of connected nodes that are part of a Katana project. Recipes typically represent the steps taken or operations performed to create 3D scene data in a scene graph, or the image manipulations performed to create 2D images that can be viewed in Katana's Monitor tab and written out to file.

Note:  For more information about Recipes in Katana, see Creating a Katana Project.

Project

A Katana Project is the sum of all the nodes and their parameters that form the recipes that are expressed in the project's node graphs. Projects are saved in Katana project files with the .katana file extension.

Note:  For more information on working with projects, please see Creating a Project.

Ops

Ops are the building blocks of operations that create and manipulate 3D scene data in Katana, and produce the scene graphs that can be inspected at any point in a Katana node graph by setting the view flag on a particular node. Ops are instances of Op Types, which are plug-ins written in C++ that use a particular Katana API to define their inner workings: the Op API. Some functions available for C++ Ops are documented in the Katana Developer Guide.

Similar to the various node types, Katana ships with many built-in types of Ops, but custom Op types can also be created through C++ programming and using the Op API. When the view flag on a node is set, the node is queried for its corresponding Ops. The behavior of a node in terms of the creation or modification of 3D scene data can be defined by a single Op, but can also be defined by a number of Ops arranged in an Op Chain or Op Graph.

Op Arguments

Op Arguments control the behavior of Ops that define the effect of nodes in a Katana recipe. They roughly correspond to parameters on 3D nodes. When changing the parameter of a node, corresponding Op Arguments are updated. If the node or any node downstream is being viewed, the scene is recooked.

Cooking

Cooking is the act of executing the Ops that correspond to nodes in the Katana recipe, in order to create scene graph locations and their attributes, which can then be viewed and inspected in the Scene Graph and Attributes tabs. When setting the view flag on a node in the node graph, the Ops that correspond to that node and all of the nodes above it are executed/evaluated/cooked to produce the scene graph at that point in the node graph. In technical terms, the cook() function of each corresponding Op type plug-in, is being called to create or modify locations in the resulting scene graph.

Filters

Filters are the old equivalent in Katana 1.X releases, of Ops in Katana 2.X releases and above. They represent the building blocks of operations that create and manipulate 3D scene data in Katana 1.X releases.

Lazy Evaluation

One of the key aspects of Katana's processing paradigm, is that operations are only evaluated when their results are needed.

For example, the Ops that correspond to a particular node are only cooked when the node itself or a node downstream of it is being viewed, meaning it has its view flag set. In the context of the Scene Graph tab, data for scene graph locations is only produced when the scene graph hierarchy is expanded to reveal them in the tree view widget.

When working with Katana's APIs, lazy evaluation can have an effect on the results of certain function calls.

Note:  For an example of this, see the Knowledge Base Article How to Query Attributes of Scene Graph Locations via Python using a Geolib3 Client.

Lazy evaluation also applies to aspects of Katana's UI, where a mechanism named freezing and thawing ensures that the UI is only updated when necessary in response to user interactions.

Graph State

Katana maintains a Graph State data structure when traversing up the node graph. It contains information such as the current frame and the shutter timings, and is passed to Ops that are represented by nodes when cooking the scene graph. Nodes can read from and write to the Graph State as part of identifying their inputs.

For example, a TimeOffset node reads the current time and increments or decrements it by some amount, as controlled by its inputFrame parameter. The modified Graph State is then passed to the node above for cooking its Ops. It is important to realize that the Graph State information flows up the node graph, unlike scene data, which flows down the graph.

Some Python functions to work with Graph State are documented in the Katana Developer Guide.

Graph State Variables

Graph State Variables (sometimes abbreviated as GSV) essentially allow users to define key-value pairs within the Graph State, and can be set at the project or node level. They can then be referenced and manipulated by other nodes, allowing for a powerful workflow, where groups of nodes and entire node graph branches can be enabled and disabled with ease.

Note:  For more information, see Graph State Variables.

Project-level GSV are known as Global Graph State Variables, and node-level GSV are known as Local Graph State Variables. The following types of nodes are available for working with and/or modifying local GSV:

GenericAssign

GenericAssign is an advanced and powerful concept in Katana, in which parameters of nodes are associated with specific attributes on locations in the scene graph. Such parameters effectively control the values of their corresponding attributes. Their widgets in Parameters tabs are capable of showing values of attributes from the incoming scene, allowing users to inspect and modify those attribute values.

An example of a node type that uses GenericAssign-based parameters is the RenderSettings node type. The parameters of RenderSettings nodes correspond to attributes in the renderSettings group attribute on the /root location in the scene graph. When setting a value of a parameter of a RenderSettings node, the corresponding attribute in the renderSettings group is set. When connecting a RenderSettings node to an incoming node graph, the widgets of parameters of the node show the values of the attributes they correspond to.

State badges that are part of the parameters' widgets show the value states of the respective parameters, indicating whether the corresponding attributes are set to a specific value by nodes upstream of the node that is being edited (incoming value), or by the node itself (local value), or whether the attributes are not set to a specific value, in which case they use a default value instead.

Scene Graph

3D nodes that are part of Katana recipes produce a hierarchical set of data, called the Scene Graph, which can be interactively inspected in Katana's Scene Graph and Attributes tabs in the UI, and can be presented to a renderer or any output process.

Examples of data that can be held in the scene graph can include:

  • Geometry
  • Particle data
  • Lights
  • Instances of shaders
  • Global option settings for renderers.

Note:  For more information on the Scene Graph, see Using the Scene Graph.

Locations

Locations are the units that make up the Scene Graph hierarchy. Many other 3D applications refer to these as nodes, but in Katana they are referred to as locations to avoid confusion with the nodes used in the Node Graph. Locations can uniquely be identified using their name and the names of all of their ancestor locations in the scene graph, which form a scene graph location path, for example:
/root/world/geo/pony

Note:  For more examples of how to work with locations in the Scene Graph, see Using the Scene Graph and Manipulating the Scene Graph.

Attributes

Attributes are containers for data held on locations in the scene graph. Examples of data stored in attributes are:

  • 3D transforms such as 4x4 matrices
  • Vertex positions of geometry,
  • Value settings for an instance of a shader.

Attributes of a selected scene graph location can be inspected interactively in Katana's Attributes tab, but not edited, as their values are determined by nodes and parameters of the Katana project.

Note:  For examples of common attributes that locations can have, see Attribute Conventions in the Katana Developer Guide.
For more detailed information on creating, manipulating or deleting attributes, see Working with Attributes.

Attribute Types

There are different types of attributes for different basic types of data:

  • Integer numbers
  • Floating-point numbers
  • Double-precision numbers
  • Strings

In addition to these types of data attributes, attributes can be grouped in hierarchies using group attributes.

A special type of attribute, the null attribute, is used for specific cases, such as to declare a certain attribute as not set, so that a default value for the attribute is used instead.

Katana UI Terms

Value Policies

Value Policies in Katana provide data for display in widgets in Katana's UI. Value policies provide a layer in between underlying data sources, such as parameters of nodes in the node graph document, and UI widgets in tabs like the Parameters tab. There are different types of value policies, tailored to specific data sources and specific use cases.

The Python base class for value policies is QT4FormWidgets.AbstractValuePolicy. Value policies take care of translating from events in the underlying data sources to Qt widget events, for example, to repaint widgets after a parameter's value has been changed using a NodegraphAPI call.

Parameter Policies

Parameter Policies in Katana are value policies that provide a layer in between parameters of nodes in the node graph document and widgets in the Parameters tab. Those widgets show values of parameters, and can be used to edit those parameter values.

Parameter policies are most relevant when developing parameter UIs for custom types of nodes, for example SuperTools, using Python scripting APIs.

Note:  For examples of how this can be used in SuperTools, please see the respective Editor.py files of the example SuperTools that ship with Katana under:
$KATANA_ROOT/plugins/Src/Resources/Examples/SuperTools

The Python base class for parameter policies is UI4.FormMaster.BaseParameterPolicy. It is derived from the AbstractValuePolicy class. A parameter policy is typically created for a specific parameter of a specific node by passing a NodegraphAPI.Parameter instance that represents the respective parameter to the UI4.FormMaster.CreateParameterPolicy() function. This returns an instance of a class that is derived from the BaseParameterPolicy class.

Attribute Policies

Attribute Policies in Katana provide a layer in between attributes of locations in the scene graph and widgets in the Attributes tab that show values of those attributes.

Attribute policies are created internally by Katana to provide attribute data for display in the Attributes tab when locations in the Scene Graph tab are selected. There's rarely a need to create attribute policies manually.

The Python base class for Geolib3-based attribute policies is UI4.FormMaster.FnAttributePolicy.AttributePolicy. It is derived from the AbstractValuePolicy class.

GenericAssignParameterPolicy

GenericAssign Parameter Policies (GAPP) in Katana are parameter policies that provide a layer in between GenericAssign-powered parameters of nodes in the node graph document and widgets in the Parameters tab. They can be seen as a hybrid between parameter policies and attribute policies:

  • GenericAssign aspect: GAPPs receive the results of cooking the scene graph that is produced by nodes upstream of the respective GenericAssign-powered node by way of a built-in Geolib3 Client that receives events from the Geolib3 Runtime. This is similar to how attribute policies provide data from attributes of scene graph locations for display in the Attributes tab.
  • Parameter policy aspect: GAPPs provide cooked attribute data for use in parameter widgets in the Parameters tab. This is similar to how parameter policies provide data from parameters of nodes for display in the Parameters tab.

Freezing and Thawing

Freezing means that Katana-specific events that are normally processed when underlying data changes are temporarily ignored. It applies to value policies, and to tabs in Katana application windows. This ensures that they're not needlessly updated when changes are made to the node graph document or when scene graph location data is cooked, for example in the case that widgets or tabs are not actually visible to the user.

Thawing of value policies or tabs is the reverse of freezing: after the processing of Katana-specific events has temporarily been suspended, or has never been started before, thawing means that processing of such events and updating UI components as a result is resumed or started.

Freezing and thawing is implemented by registering and unregistering handlers for specific Katana event types, depending on whether the respective value policies or tabs are frozen.

Note:   For information on registering callbacks and event handlers, refer to Callbacks and Events in the developer guide.

Typically, when the user switches from one tab to the next in a pane inside of a Katana window, the previously visible tab is frozen, and the newly visible tab is thawed. Thus, no widgets in the now hidden tab are updated in response to Katana events, but widgets in the newly visible tab are. When working with parameter policies in the context of parameter UIs for custom types of nodes, for example SuperTools, it is important to note that Python callback functions need to be added to such a value policy in order to be notified when the underlying value of the policy changes. If no such callbacks are added to a value policy, the value policy is considered frozen.

Note:  For more information, see the descriptions of GenericAssign and Lazy Evaluation in the Katana Core Terms section of the Glossary, and GenericAssignParameterPolicy in the UI Terms section.

ScenegraphManager

The ScenegraphManager Python module is part of the Nodes3DAPI Python package. It maintains a single instance of a Scenegraph class that is responsible for tracking a number of Working Sets that maintain the open, closed, selection, and pinning states of locations in Katana's scene graph.

For more information about pinning, see Changing What is Shown in the Viewer.

The Scenegraph instance can be retrieved by calling ScenegraphManager.getActiveScenegraph(). The instance can then be used, for example, to access the list of paths of scene graph locations that are currently selected:

sg = ScenegraphManager.getActiveScenegraph()

print(sg.getSelectedLocations())

The Scenegraph class also maintains a history of selected scene graph locations, using an internal SelectionHistory class, for the purpose of allowing users to step through the history using the History Forward and History Backward commands in the Viewer tab.

Katana Rendering Terms

Preview Render

A Preview Render is a type of Interactive Render, meaning a render launched from a Katana UI session, in which the rendered image and a progress bar are displayed in Katana's Monitor tab. In a Preview Render, the renderer process quits when the rendered image is completed. This is different to a Live Render, in which the renderer process is kept alive.

Preview Rendering has historically been called interactive rendering in early versions of Katana.

Note:  For more information about Preview Rendering, see Performing a Render.

Live Render

A Live Render is a type of Interactive Render, meaning a render launched from a Katana UI session, in which the renderer process is kept alive while the rendered image is displayed in Katana's Monitor tab. When making changes to parameters of nodes in the Katana project, the renderer is notified of these changes, and the rendered image updated in the Monitor tab.

It's possible to limit for which scene graph locations updates are sent to the renderer during a Live Render session, by using the Live Render Updates column in Katana's Scene Graph tab. This is typically used for projects that produce very large scene graphs.

Live Rendering has historically been called re-rendering in early versions of Katana.

Note:  For more information about Live Rendering, see Performing a Render.

Disk Render

A Disk Render is a type of render in which the rendered image is written to a file on disk, and then loaded into the Monitor tab when the render has finished. The progress bars in the Monitor tab are not updated while a Disk Render is in progress.

Disk Rendering has historically been called hot-rendering in early versions of Katana.

While the Preview and Live Render options are available from any node's context menu, a Disk Render can only be triggered from a Render node.

Note:  For more information about Disk Rendering, see Render Types.

Interactive Render

An Interactive Render is a render launched from a Katana UI session. There are two types of interactive renders available in Katana:

Interactive Render Filters

Interactive Render Filters (commonly abbreviated as IRF) allow users to set up common recipe changes for interactive renders, meaning Preview Renders and Live Renders, without having to add nodes to effect such changes at various points in a project's recipe. An IRF can consist of more than one change to the recipe, and it is the equivalent of appending nodes to the end of the node from which an interactive render is started.

IRFs are defined in InteractiveRenderFilters nodes and can be selectively activated and deactivated in the Interactive Render Filters popup. This popup is accessible by clicking the Interactive Render Filters button at the top of the Katana interface.

Note:  Interactive Render Filters are ignored for Disk Renders.

An example use for IRFs is to set them up to reduce the render resolution for interactive renders without affecting Disk Renders, thus making debugging of such renders much quicker. Other examples of changes that can be set up by IRFs might include anti-aliasing settings, shading rate changes, or the number of light bounces.

Note:  For more information about setting up Interactive Render Filters, see Setting up Interactive Render Filters.
You can also refer to the Knowledge Base Article Increasing preview efficiency with Interactive Render Filters.

Render Dependency

When starting a render from a Render node, other render passes that the render may depend on can be rendered to disk automatically by rendering with dependencies.

Historically, this feature was used to produce shadow maps that are then used for a main render pass.

Note:  For more information, see Render Dependencies.