Search Tips

Search is based on keyword.

`Ex: "Procedures"`

Do not search with natural language

`Ex: "How do I write a new procedure?"`

Give Feedback Support Portal

# Katana 5.0v1 Release Notes

Contents

- New Features
- Feature Enhancements
- Bug Fixes
- Known Issues
- System Requirements

# Release Date

13 December 2021

# Previous Releases

- Katana 4.0v5 Release Notes

# What's New in Katana 5.0

These release notes describe changes from Katana 4.0v5 to 5.0v1.

For a high-level overview of important changes in the Katana 5.0 line, please see the accompanying What's New in Katana 5.0 document.

# New Features

## Foresight+

- Katana's Live Render system has been enhanced to support more flexible and scalable workflows.

  The processing of Live Render Updates has been moved from the Katana process to the `renderboot` process, with the potential of freeing up the artist’s local workstation when rendering remotely using a Farm API plug-in, e.g. via the Katana Queue using remote agents. Updates to a Katana project’s node graph are now sent as resulting Op Tree Deltas to the `renderboot` process, where they are turned into Live Render Update Attributes, as it was previously done in the Katana process.

  No changes are required for render plug-ins to take advantage of this feature, as Katana’s Render Plug-in APIs are left unchanged.

  When starting a Live Render, the values of global Graph State Variables (those stored in Project Settings) are now pinned to their current values, meaning that subsequent changes to global GSVs won't be reflected in the render. Checkboxes now appear in columns of GSVs in the Catalog tab, indicating this new pinned state, which can be used to unpin specific GSVs, so that values of global GSVs are reflected during a Live Render. This feature allows you to pick and choose exactly which renders should be updated in response to changes of specific global GSVs, and which GSVs you'd like to leave unchanged to the values they had when the Live Render was started.

  For even greater flexibility, it is now possible to access the values of local Graph State Variables, in addition to global Graph State Variables, in the context of parameter expressions. Details on this are available in the release notes summary of feature enhancement ID 166141.

  A Sync to Project Settings checkbox has been added at the top of the Catalog tab, which determines whether choosing a Catalog item as the Front buffer item will update the project’s global Graph State Variables and current time to match it. This feature can be used to quickly switch between different shots, assets, and/or frames, while keeping a number of renders running at the same time.

## Katana <> Nuke

- Katana now ships with a Nuke Bridge tab that can be used to launch Nuke for live streaming of image data from Katana's Catalog to Nuke.

  The Nuke Bridge tab allows you to specify the name of a Nuke Script file which, once selected, will be checked for new Katana provided nodes called KatanaReader and KatanaWriter. The KatanaReader nodes are then listed in a Nuke Input Points group, allowing you to associate them with specific Katana catalog items. An Output Node widget allows you to select a particular KatanaWriter node from the specified Nuke script, which will be used to stream rendered pixels from Nuke back to Katana's catalog system.

  It's possible to launch the Nuke process in one of three ways, by clicking one of three buttons at the bottom of the Nuke Bridge tab:

  1. Preview Comp for running Nuke without a GUI and having the resulting pixels stream back to Katana before finishing the process. (This mode can be run remotely.)
  2. Live Comp for running Nuke without a GUI but allowing the user to continue to stream updated pixels from one or more Catalog entries, as well as allowing the user to change Catalog entries on the fly. (This mode can be run remotely.)
  3. Interactive Comp for launching Nuke locally with a GUI, and maintaining a live link between the two applications for the lifetime of the corresponding catalog entry inside Katana. You are able to make changes inside the Nuke comp while also streaming continuous live updates from Katana.

  Active and completed Nuke comps are listed at the top of the Nuke Bridge tab.

  Note: When launching Nuke with the Interactive Comp button, the Viewer node must be connected (and evaluating) downstream of the KatanaWriter node to force evaluation, otherwise pixels won't stream back to Katana's Catalog.

## USD 21.05 / Hydra Render Delegates

- The version of USD used in Katana has been upgraded to USD 21.05, re-introducing support for using different Hydra Render Delegates in Katana's Hydra-powered Viewer tab.

  As part of this work, the menus of the Viewer tab have been rearranged for clarity:

  - Menu items for materials, lighting, shadows, and the available Hydra Render Delegates were moved from the View menu to a new Display menu.
  - The Display menu also features new Selection and Purposes submenus for controlling the appearance of selected objects and choosing the USD purposes to use.
  - In addition, the new Render Delegate Settings menu command opens a dialog with settings for the Hydra Render Delegate that was chosen for drawing the scene.
  - The Set Subdivision Level submenu was moved from the Edit menu to the View menu, and the Edit menu was removed.

  A new Render Delegate Toolbar appears in the top-right corner of viewports in the tab, and allows for pausing, resuming, and stopping of drawing with the chosen Hydra Render Delegate -- provided that Render Delegate supports these features.

## Hydra Viewer: Instancing and AVP

- The Viewer tab now supports rendering of instanced geometry via instance array locations. The attributes of these instance array locations are expected to follow Katana's Attribute Conventions for Instancing. In particular, instance sources must be scene graph locations of type instance source. These instance sources may also contain other instance arrays, resulting in nested instancing.

  Instanced geometry in the Viewer tab supports per-instance primvar data. These attributes must be set on an instance array location, with a primvar value per index in the geometry.instanceIndex attribute. The scope of each primvar must be instance, which implies a constant value per instance. In particular, other interpolation types per-instance are not supported. If the source geometry or multiple instance arrays in a hierarchy contain the same primvar, the one closest to the geometry takes precedence.

- Foundry's Advanced Viewport (AVP) is now available to choose as a Hydra Render Delegate named AVP in the Viewer tab's new Display menu.

## Network Material Enhancements

- A new Parameters subtab has been added to the Material Interface of NetworkMaterialCreate nodes, replacing the previous Node Parameters subtab, which was renamed to Defaults, and which is now deprecated.

  When using the new Parameters subtab, exposed shading node parameters are now directly represented in the Material Interface allowing users to modify values directly on the node itself, as opposed to overriding them on the NMC's hidden material node.

  The Defaults subtab of NetworkMaterialCreate nodes that were created in Katana releases prior to Katana 4.5v1 now features a deprecation warning, which provides an Upgrade button. The Upgrade button opens a dialog with two options that allow users to manually choose whether to apply their overrides made in the Defaults subtab or to discard them:

  Apply Overrides:

  - Applies overrides made on the Defaults subtab to parameters of shading nodes within the NetworkMaterialCreate node (which are shown on the new Parameters subtab),
  - Clears those overrides from the underlying Material node, and
  - Removes the Defaults subtab from the UI.

  Discard Overrides:

  - Clears the overrides made on the Defaults subtab from the underlying Material node, and
  - Removes the Defaults subtab from the UI.

  Users wanting to work in the same way as in previous releases will be able to use a downstream Material or NetworkMaterialEdit node to apply overrides on top of existing values.

  Several changes have also been made to the way Katana handles parameters that are exposed in the Material Interface, including:

  - The parameter wrench menu now exposes an Add to Material Interface option which will promote the parameters from nested nodes with a single click. The wrench menu now also appears in the Parameters tab to make it easier to remove parameters from the Material Interface.
  - A new menu item Edit Material Interface Options can be used to specify exactly how the parameter will appear in the Material Interface once exposed by providing options to edit the Name, Page, and Label of the parameter.
  - A new jump button has been added to parameters whose widget hints contain a nodeName and a parameterName hint.

- The order of exposed parameters that can be defined via the Material Interface tab of ShadingGroup nodes inside NetworkMaterialCreate nodes is now respected in the resulting Network Material. In order to record the desired ordering information, ShadingGroup nodes to which exposed parameters have been added now create a shading node subnet location in the scene graph, just like ShadingNodeSubnet nodes in the legacy Network Material workflow did.

  When adding exposed parameters from shading nodes inside of a ShadingGroup node to that node's Material Interface tab using the Add Exposed Parameters context menu command, the exposed parameters are now added in the order that was defined by any nested ShadingGroup nodes within.

- ShadingGroup nodes now allow for specifying name and page prefixes to be applied to exposed parameters of shading nodes contained within them, by way of a new publicInterface group parameter containing a namePrefix and pagePrefix child parameter. This gives creators of shading node networks flexibility in the naming of shading node parameters in the public interface of the resulting Network Material.

  The name and page prefixes of ShadingGroups are combined with the name and page prefixes specified in the publicInterface group parameter on shading nodes contained within them. Just like on shading nodes themselves, the publicInterface.pagePrefix parameter on ShadingGroup nodes allows for specifying nested page titles and prefixes by using dots (.), e.g. Top-level Page.Nested Page.Prefix.

- Katana 4.5v1 and Katana 5.0v1 include a number of improvements for authoring shading node networks in NetworkMaterialCreate and NetworkMaterialEdit nodes:

  - Changes to shading node view states:
    - The view state of shading nodes is now indicated with an icon in the top-left corner of the shading node's shape. When clicking that icon, the appearance of the shading node cycles through the available view states, which have been renamed to be clearer and more accurate:
      - Collapsed
      - Connected Only
      - Expanded

    - When creating a connection between shading nodes, shading nodes that appear in the Collapsed or Connected Only view states are now temporarily Expanded while pointing at them. This makes it easier to quickly create connections without having to manually change the view states of shading nodes.

    - A new showPagesConnectedOnly preference has been added to the nodegraph category of preferences, to control whether pages are shown when shading nodes appear in the Connected Only view state.

  - Appearance and behavior of Dot nodes:

    - Dot nodes have been redesigned to be smaller, and their ports have been removed.

    - Connections between Dot nodes are now drawn as straight lines instead of bezier curves, allowing for a more organized appearance of shading node networks.

  - Input connections on selected shading nodes can now optionally be hidden, in order to declutter shading node networks.

  - User parameters can now be added to NetworkMaterialCreate and ShadingGroup nodes.

  - Macros created from within NetworkMaterialCreate or NetworkMaterialEdit nodes can now easily be created in those types of nodes from the node creation menus.

  - The size of the footer of a shading node is now smaller and no longer contains the node type name.

  Additionally, the parameter interface of NetworkMaterialCreate and NetworkMaterialEdit nodes has been revised as follows:

  - A Material Interface label was added above the nested tabs.
  - The parameters group header was removed from the nested Node Parameters tab.
  - The NetworkMaterialInterfaceControls label was removed from the top of the nested Interface Controls tab.
  - The Interactive column was removed from the tree view of materials of NetworkMaterialCreate nodes.
  - The makeInteractive parameter was removed from the nested Node Parameters tab of NetworkMaterialEdit nodes.
  - The sceneGraphLocation parameter was moved from the nested Node Parameters tab of NetworkMaterialEdit nodes to the top of the parameter interface, and was given a label: Material Location to Edit
  - The nested Node Parameters tab was renamed to Defaults and is now deprecated. It was replaced by the new Parameters subtab.
  - The nested Interface Controls tab was renamed to Visibility & Locking.
  - The nested Material Interface tab was renamed to Sources & Order.

## USD Export

- USD Export has been enhanced with the ability to export light locations, including light linking information, via UsdMaterialBake nodes using the UsdLux APIs.

  A new type of plug-in has been added to allow further customization of the USD Export process without the need to rebuild the Katana USD plug-ins. The USD Export plug-in system is implemented with its own dedicated plug-in registry, whose API is accessible via the new `UsdExport.pluginAPI` and `UsdExport.pluginRegistry` Python modules.

  USD Export plug-ins are registered during application startup using the standard Katana plug-in registry mechanism, by adding a `UsdExportPlugins` folder to a directory whose file system location path is referenced in the `KATANA_RESOURCES` environment variable, and defining a `PluginRegistry` module variable in a Python module in that folder.

  Here's a simple example of defining and registering an export plug-in using such a plug-in Python module:

      from UsdExport.pluginAPI import BaseUsdExportPlugin

      class MyUsdExportPlugin(BaseUsdExportPlugin):

          priority = 1000

          @staticmethod
          def WritePrim(stage, sdfLocationPath, attrDict):
              print('MyUsdExportPlugin.WritePrim(): Exporting "{}"...'.format(sdfLocationPath))

      PluginRegistry = [
          ('UsdExport', 1, 'MyUsdExportPlugin', (['light'], MyUsdExportPlugin)),
      ]

  The plug-in's `WritePrim()` function will be called as part of exporting USD on each location which matches the location types for which the plug-in is registered. In the example above, the `WritePrim()` function will be called for light locations.

  Using the new `UsdExport.pluginRegistry` APIs, it is also possible to register and deregister an export plug-in interactively at runtime, for example in a Python tab. This can be used for quickly iterating over a new plug-in that is in development. Here's an example:

      from UsdExport.pluginAPI import BaseUsdExportPlugin
      import UsdExport.pluginRegistry

      class MyUsdExportPlugin(BaseUsdExportPlugin):

          priority = 1000

          @staticmethod
          def WritePrim(stage, sdfLocationPath, attrDict):
              print('MyUsdExportPlugin.WritePrim(): Exporting "{}"...'.format(sdfLocationPath))

      UsdExport.pluginRegistry.RegisterUsdExportPlugin('MyUsdExportPlugin', ['light'], MyUsdExportPlugin)

  We plan to continue expanding on this behavior by utilizing the `SdrRegistry` information available for light shaders to write out accurate USD data for each light type.

  A new Schema, `LightAPI`, has been added to allow for attributes required to define the light's shader ID, such that round-tripping of a light will work in the future for all light types.

  Locations with transform attributes will also be exported to an Xform Prim.

## VFX Reference Platform CY2020

- The versions of third-party libraries used in Katana have been updated to match those of the calendar year 2020 specification of the VFX Reference Platform, including Python, which is upgraded to Python 3.7.7 in Katana 5.0v1. (Note that Katana 4.5v1 remains on Python 2.7, allowing studios that are not quite ready to make the jump to Python 3 to still benefit from the new features introduced in the Katana 4.5v1/5.0v1 dual release.)

  In support of the upgrade to Python 3 in Katana 5.0v1, almost all of Katana's Python C extension APIs in Katana 4.5v1/5.0v1 have been rewritten using pybind11, introducing improved docstrings and better error feedback. All imports of Python modules across the Katana codebase have been updated to work in Python 3, where imports are absolute by default.

## 3Delight

- The version of 3Delight that we ship with Katana has been upgraded to 3Delight 2.6.4, introducing support for Python 3 in 3Delight for Katana.

  For more information, please refer to the 3Delight for Katana Changelog.

## Removal of Deprecated Features

- A number of features that were deprecated in previous lines of releases have been removed, in order to avoid porting work that would have otherwise been necessary to make them compatible with new versions of third-party libraries in Katana 4.5v1/5.0v1 and with Python 3 in Katana 5.0v1:

  - Attribute Modifier Plug-ins (AMP) (also known as ScenegraphLocationModifiers [SLM])
  - Scene Graph Generator Plug-ins (SGG)
  - Classic Gaffer node type
  - AttributeScript nodes and underlying Op type
  - Python-based Asset API plug-ins, as well as underlying ProcessManager mechanism
  - AttributeUpgrade nodes and underlying Op type
  - Legacy OpenSceneGraph-based Viewer tab
  - Plug-in types for the legacy OpenSceneGraph-based Viewer tab, in particular Viewer Modifier Plug-ins (VMP) and Viewer Manipulator Plug-ins (VMP)
  - ScenegraphXML
  - ViewerMaterialEdit nodes and its corresponding material.viewerShaderSource attribute convention
  NOTE: The Hydra-powered Viewer (Hydra) tab, which replaced the legacy OSG-based Viewer tab, was renamed to just Viewer. Katana layouts are automatically updated.

# Feature Enhancements

## API/SDK Changes

- ID 124108 / BZ 51004 - It is now possible to configure the columns that are shown in the table of objects of an edited GafferThree node in the Parameters tab, by registering callbacks that are called when setting up the GafferThree node's `SceneGraphView` widget, and when setting up the tab widget below the table of objects.

  The following new API functions have been added:

  - `GafferThreeAPI`:
    - `RegisterSceneGraphViewSetupCallback(callback: callable)`
    - `RegisterTabWidgetSetupCallback(callback: callable)`
  - `PackageSuperToolAPI.BaseEditor.BaseEditor` class:
    - `setupTabWidget()`
    - `getTabWidget() -> QtWidgets.QTabWidget`
    - `addTab(tabName: str) -> QtWidgets.QWidget`
    - `removeTab(tabName: str)`

  Here's a usage example, showing how callbacks can be set up from a `UIPlugins` Python module, e.g. `~/.katana/UIPlugins/RegisterGafferThreeCallbacks.py`:

      from Katana import Plugins
      from UI4.Widgets.SceneGraphView import ColumnDataType

      GafferThreeAPI = Plugins.GafferThreeAPI

      def configureGafferThreeSceneGraphView(objectHash, node, editor, sceneGraphView):
          # Hide some standard columns of GafferThree
          for columnName in ('Int', 'Exp', 'Linking'):
              column = sceneGraphView.getColumnByName(columnName)
              column.setVisible(False)

          # Add a new column for editing the diffuse contribution of 3Delight lights
          diffColumn = sceneGraphView.addColumn('Diff')
          diffColumn.setAttributeName('material.dlLightParams.diffuse_contribution')
          diffColumn.setDataType(ColumnDataType.Number)
          diffColumn.setEditable(True)

      def configureGafferThreeTabWidget(objectHash, node, editor, tabWidget):
          editor.removeTab('Linking')
          editor.addTab('Look')

      GafferThreeAPI.RegisterSceneGraphViewSetupCallback(configureGafferThreeSceneGraphView)
      GafferThreeAPI.RegisterTabWidgetSetupCallback(configureGafferThreeTabWidget)

- ID 229109 - In Katana Python scripting contexts, `sys.executable` now points to the absolute path of the executable binary for the Python interpreter that ships with Katana.

- The following functions have been added to the `PyFnGeolibServices.XFormUtil` Python module:

  - `PushTranslateAttr()`
  - `PushRotateAttr()`
  - `PushScaleAttr()`
  - `PushMatrixAttr()`
  - `PushOriginAttr()`

  These functions are equivalent to those in the `PyFnScenegraphAttr` module, which is no longer available (see below).

  Refer to the ScenegraphAttr Porting Guide in the Katana Developer Guide for more information.

- Creators of SuperTool-based node types can now opt out of allowing users to edit user parameters on their custom SuperTool nodes, by implementing the following function on their node type class:

          def isUserParameterEditingAllowed(self):
              return False

- The following changes have been made in support of creation of node networks in Layered Menu actions:

  - The sequence of floating nodes (returned by `NodegraphAPI.GetAllFloatingNodes()`) is now in order of flotation.
  - The following single node `NodegraphWidget` methods are deprecated in favor of their multi-node counterparts:
    - `placeNode()`: use `placeNodes()` instead.
    - `removeFloatingNode()`: use `removeFloatingNodes()` instead.
  - The [internal] `MenuLayer` replaced node callback (set using `setReplacedNodeCallback()`) now provides a sequence of created nodes as its first argument, rather than a single node.

- The boost libraries shipped with Katana are now namespaced as `foundryboost`.

## Deprecated and Removed Features

- ID 126100 / BZ 51298 - The defunct applyAtLeaves parameter, which was shown when setting the attributeType parameter of an AttributeSet node to group, has been removed from AttributeSet nodes.

- The `Vecmath` Python module, which included the `vec2`, `vec3`, `vec4`, `quat`, `mat3`, and `mat4` classes, has been removed. Consider using `PyImath` as a replacement instead.

- The deprecated `PyFnScenegraphAttr` and `PyScenegraphAttrFnAttributeBridge` modules have been removed.

  Functions that previously returned `PyFnScenegraphAttr` objects now return `FnAttribute` objects directly, so the conversion previously provided by the bridge is no longer necessary.

  Refer to the ScenegraphAttr Porting Guide in the Katana Developer Guide for more information.

- The `ColorTimer`, `IBL`, and `Math` submodules of the `Nodes2DAPI_cmodule` Python module have been removed.

- ViewerMaterialEdit nodes, which were deprecated in Katana 4.0v2, are no longer available in Katana 4.5v1.

  The material.viewerShaderSource attribute convention, which only applied to the OpenSceneGraph-based legacy Viewer tab in Katana releases prior to Katana 4.5v1, was removed from the Katana Developer Guide.

- The legacy `FnKatImport` module was removed. Python modules that were previously imported with the `FnKatImport` module can now be imported using standard Python `import` statements.

- The `pyutil_cmodule` Python C extension module and the `PyUtilModule.BezierModule` Python module that it defined were removed.

- The `GeoAPI.Util.GenericAppenderUtil` module is now deprecated. New functions in the existing `Nodes3DAPI.GenericAssign` module and the new `Nodes3DAPI.GenericAssignRegistry` module should be used instead.

- The hydra and viewer viewer render plug-ins have been removed. They were superseded by the use of UsdPreviewSurface materials in Katana 4.0v1.

  Unused `ViewerAPI` options related to the Viewer tab have been removed:

  - `Global.Select.Mode.Faces.Available`
  - `Global.View.Cull Style`
  - `Global.View.Depth Mode`
  - `ResourceAllocation`
  - `Viewport.LookThroughCamera`

## Foresight+

- ID 166141 / BZ 51870 - The following functions have been added for use in Python-based Parameter Expressions, allowing you to work with Local Graph State:

  - `getVar()`, for querying Local Graph State Variables
  - `getFrameTime()`, for querying Local Graph State Frame Time
  - `matchGraphStateVariable()`, an equivalent to the existing `matchGlobalGraphStateVariable()` function that does account for Local Graph State

  Equivalent functionality is available for Reference Expressions:

  - `$<variable_name>` for querying the value of the variable
  - `####` for querying the frame time (as integer)

  Other changes in Python-based Parameter Expressions:

  - The `frame` global has been renamed to `sampleTime`. The old name is deprecated.

  Authors of custom node types are encouraged to consult the Supporting Local Graph State in Parameter Evaluation section in the Katana Developer Guide for more information.

## Geolib

- ID 432536 - A new geometry processing Runtime named Geolib3-MT (Experimental) has been added, which makes use of a new caching subsystem that optimizes for low peak memory usage. The new Runtime can be chosen via the geolibRuntime parameter of RenderSettings nodes.

## Hydra Viewer

- When selecting objects while a Render Delegate other than GL (`HdStorm`) is chosen, the selected objects will now be highlighted as filled by default, since wireframes cannot be drawn out-of-the-box by most other Render Delegates. A new Display > Selection menu in the Viewer tab allows users to choose between this Fill appearance and an Outline appearance.

- All Network Materials will be passed through to Hydra and the chosen Render Delegate starting from the terminal nodes described in the material.terminals attribute. In order to find the correct terminals to use, the chosen Render Delegate's material render context will take precedence over a fallback of the `usdSurface` terminal, which will always be checked. If no terminals exist, the default material will be used.

  For each terminal token under `HdMaterialTerminalTokens` we generate a terminal to search for by concatenating the material render context with the terminal token, e.g: `glslfxSurface` or `glslfxDisplacement` for `HdStorm`. If we find a terminal which matches this, we return the attached Material Network. If no match is found, we look through some known naming differences. For example, `HdStorm`'s Render Delegate returns `glslfx`, but we know that the terminal name to look for is `usdSurface` for the `surface` token type. There are a few other instances of this for Render Delegates we have tested. If a known naming conversion fails, we will always fall back to reading the `usd` prefixed terminal, e.g `usdSurface`, `usdDisplacement`, or `usdVolume`.

- The Hydra Viewer now supports reading arbitrary primvar data, which can be passed to `UsdPrimvarReader_<type>` nodes, e.g. `UsdPrimvarReader_float2`. The structure of this data must follow Katana's attribute convention for Arbitrary Attributes, and is read from `GroupAttribute`s under the geometry.arbitrary attribute on a geometry location.

- The Katana Scene Delegate will now read any parameter asked for via the `GetLightParam()` method in Hydra from the renderer's LightParams attributes for the light location. We convert the Hydra naming convention of colon-separated words into lower camel-case to match the majority of Katana attributes. For example, my:light:param becomes myLightParam. We will always check for usdLightParams as a fallback if we can't find requested attributes under the renderer's LightParams.

- The Katana Basic Material now uses a `UsdPreviewSurface` shader node with a `UsdPrimvarReader_float3` node reading the displayColor attribute plugged into the diffuseColor, using a fallback color value of `0.2f, 0.2f, 0.2f`.

- The menus of the Viewer tab have been rearranged for clarity:

  - Menu items for materials, lighting, shadows, and the available Hydra Render Delegates were moved from the View menu to a new Display menu.
  - The Set Subdivision Level submenu was moved from the Edit menu to the View menu, and the Edit menu was removed.

- A dialog for editing settings of the Render Delegate that has been chosen for drawing the scene has been added to the Viewer tab. It can be opened by choosing Display > Render Delegate Settings from the Viewer tab's menu bar.

  While the choice of Render Delegate is not saved to Katana's layout files, values for settings can be, so that they are applied automatically when switching between layouts or Render Delegates.

- A new Render Delegate Toolbar appears in the top-right corner of viewports in the Viewer tab. It contains tool buttons for pausing, resuming, and stopping of drawing with the chosen Hydra Render Delegate, provided that Render Delegate supports these features.

  If the chosen Render Delegate supports pausing and resuming of rendering, the pause button will temporarily pause the render, halting the use of CPU resources, but not freeing memory resources.

  If the chosen Render Delegate supports stopping of rendering, the stop button will stop the render at its current level of convergence, freeing CPU and memory resources.

  Note: Not all Hydra Render Delegates support pausing and resuming of rendering, and/or stopping of rendering.

  Tip: The Render Delegate Toolbar can be shown and hidden by toggling the Display > Render Delegate Toolbar toggled menu item from the Viewer tab's menu bar.

- Hydra Render Delegates will now always draw until they have converged. The View > Hydra Renderer > Redraw Until Converged toggled menu item, which was previously provided to control this behavior, has been removed.

  TIP: If the chosen Render Delegate supports pause or stop, the new tool buttons in the top-right corner of the viewport can be used to pause or stop the render before having fully converged.

- Light parameters are cast to the type matching the node input in USD's `SdrRegistry` where a node exists for the light and a matching input name is found.

- ID 486373 - The performance of faceset generation for geometry within the Hydra Viewer has been optimized. In the special case of a single faceset covering an entire mesh, generation should now be a no-op.

## Katana <> Nuke

- The format of catalog item IDs has changed. As a consequence, IDs in the Catalog tab will always be unique, with no overlap possible when persisted entries are present in the project.

## Katana Developer Guide

- Descriptions of environment variables used for Katana USD Plug-ins have been added to the Environment Variables page of the Katana Developer Guide.

- Documentation of the advanced `NodegraphAPI.RegisterPythonNodeFactory()`, `NodegraphAPI.RegisterPythonNodeType()`, and `NodegraphAPI.RegisterPythonGroupType()` functions has been added to the Katana Developer Guide.

- The contents of the Node Properties and Connecting Nodes pages in the Working with Nodes section of the Katana Developer Guide have been revised.

- The documentation of USD Export in the Katana Developer Guide has been updated to outline how exporting of USD lights works.

## Network Material Enhancements

- Dot nodes in NetworkMaterialCreate and NetworkMaterialEdit nodes have been redesigned to be smaller, and their ports have been removed. Connections can now be made by interacting with the body of the Dot node itself, by either dropping a connection on it to finish a new connection coming from another node, or by pressing the backtick character (```) key while pointing at the Dot node to start a new connection from the Dot node.

- Connections between Dot nodes in NetworkMaterialCreate and NetworkMaterialEdit nodes are now drawn as straight lines instead of bezier curves, allowing for a more organized appearance of shading node networks.

- ID 401794 - The filter box on nodes is hidden by default and its visibility is toggled by the keyboard shortcut Alt+Return.

- Macros saved from within a NetworkMaterialCreate or NetworkMaterialEdit node can now easily be created in those types of nodes, as they now appear in the node creation menus when a node of one of those types has been entered.

- ID 410640 - When creating a connection between shading nodes in a NetworkMaterialCreate or NetworkMaterialEdit node, shading nodes that appear in the Collapsed or Connected Only view states are now temporarily Expanded while pointing at them, in order to make it easier to quickly create connections without having to manually change the view states of shading nodes.

- ID 471638 - The view state of shading nodes in NetworkMaterialCreate and NetworkMaterialEdit nodes is now indicated with an icon in the top-left corner of the shading node's shape. When clicking that icon, the appearance of the shading node cycles through the available view states:

  - Collapsed: Ports will not be visible.
  - Connected Only: Only connected ports will be visible.
  - Expanded: Shows all ports and pages under the top-level Outputs and Parameters pages (the default).

  The defaultShadingNodeViewState preference has been added to the nodegraph category of preferences, allowing you to specify the view state that is set by default when creating new shading nodes in a NetworkMaterialCreate or NetworkMaterialEdit node.

  As part of this work, the names of the customizable keyboard shortcut actions for these view states have been modified to be more accurate, and to appear within the Node Graph Tab > Network Materials group:

  - Network Materials
    - View States of Selected Shading Nodes
      - Collapsed (default: Alt+1)
      - Connected Only (default: Alt+2)
      - Expanded (default: Alt+3)

  Previously, the three actions appeared as:

  - NetworkMaterialCreate: Collapse All Ports on Selected Nodes
  - NetworkMaterialCreate: Only Show Connected Ports on Selected Nodes
  - NetworkMaterialCreate: Show All Ports on Selected Nodes

- ID 471642 - The new showPagesConnectedOnly preference has been added to the nodegraph category of preferences. The new preference controls whether pages are shown when shading nodes in NetworkMaterialCreate or NetworkMaterialEdit nodes appear in the Connected Only view state. The value of the preference can be changed from the new Show Pages (Connected Only) toggle menu item in the View menu of the Node Graph tab, when a NetworkMaterialCreate or NetworkMaterialEdit node has been entered.

- ID 473828 - The color of connections between shading node ports is now by default determined by the type of the target port of the connection (an input port), rather than the type of the source port (an output port). A new preference named useColorFromInputPortForConnections has been added to the nodegraph category of preferences to control this appearance.

- ID 475290 - It is now possible to open the node creation context menu by right-clicking into the Node Graph tab's canvas after a NetworkMaterialCreate or NetworkMaterialEdit node has been entered.

- The visibility of incoming connections for selected shading nodes within NetworkMaterialCreate and NetworkMaterialEdit nodes can now be toggled by using the Edit > Toggle Input Connections Visibility menu item in the Node Graph tab (default keyboard shortcut: Alt+H).

  While no node is selected, the Alt+H keyboard shortcut can be held down in order to temporarily show input connections on all shading nodes for which input connections were previously hidden.

- ID 482201 - When copying and pasting a shading node inside of a NetworkMaterialEdit node, the name parameter of the new node is now set based on the name of the new node.

- The size of the footer of a shading node is now smaller and no longer contains the node type name.

- In the Network Material Create/Edit context when zooming out it was often difficult to move and select nodes due to the interactive elements of the node. After a certain zoom level, these interactive elements are now disabled for mouse interactions.

- In the Network Material context, connections that are hidden (by pressing Alt+H) are now temporarily shown when their connected node is selected.

## Node Graph

- It is now possible to create Dot nodes by pressing the `.` key, which was previously only possible while creating connections between nodes, or while nodes were selected. When pressing `.` while no connection is being created and while no nodes are selected, the new Dot node floats with the pointer, ready to be placed.

- ID 463192 - It is now possible to edit user parameters for nodes that are implemented as SuperTools, for example:

  - GafferThree
  - Importomatic
  - NetworkMaterialCreate

  This applies to all SuperTool-based node types, including custom SuperTools.

  Note: It is possible for creators of SuperTool-based node types to opt out of allowing user parameters to be added to their custom SuperTool nodes by implementing the `isUserParameterEditingAllowed()` function to `return False`.

## OpWrite Node Type

- OpWrite nodes now default to C++14. On Windows, the default CMake generator is now Visual Studio 15 2017 Win64.

## Performance

- NetworkMaterial nodes now cache their Op Graph to avoid evaluating their shading node graph on changes that cannot invalidate it. This improves the interactive performance of projects that contain NetworkMaterial nodes with large shading node graphs.

## Rendering

- ID 485099 - In order to allow renderer vendors and customers to make use of shadow linking updates during Live Renders, the geoShadowEnable integer attribute is now included in the localizedLightList group attribute, in addition to the existing path, enable, and parentEnable attributes.

- A new preference named application/rendering.allowConcurrentRenders has been added. When turned on, a newly-started render will run concurrently along with already-running renders, as opposed to cancelling already-running renders.

  The preference is off by default, and supersedes the environment variables that were introduced in Katana 4.0, which have now been removed:

  - `KATANA_OVERRIDE_ALLOW_CONCURRENT_PREVIEW_RENDERS` (was on by default)
  - `KATANA_OVERRIDE_ALLOW_CONCURRENT_LIVE_RENDERS` (was off by default)

  All render methods are now affected by this single preference.

  In addition, the Start Multiple Renders dialog, accessible through the Start Multiple Renders shelf item under the Katana Queue shelf, now enforces concurrent renders, regardless of the value of the new preference.

## UI Improvements

- ID 278590 - The splitter in the Example Projects window can now be resized to avoid cutting off the project names.

- When pointing at layout menu items in the Layouts menu of Katana's main window, a thumbnail of the layout is now shown.

  When a layout is saved, a preview image of the layout is generated and stored in the user's home directory. Layouts generated by previous versions of Katana won't have an associated image generated for them, and will subsequently not show such a layout previewed when pointing at their menu items.

- ID 434351 - The image shown in Katana's splash screen can now be customized by setting the new `KATANA_SPLASH_IMAGE_FILE` environment variable to the filename of an image file.

  - The default size of the Katana splash screen image is 700 × 318 pixels.
  - Supports alpha channels.
  - Can be a list of image filenames separated by the OS-specific path separator, in which case one of the images will be chosen at random, for example:

      export KATANA_SPLASH_IMAGE_FILE=~/Pictures/taco.png:~/Pictures/bell.png

      export KATANA_SPLASH_IMAGE_FILE=`ls /path/to/splash_screens/*.png | tr '\n' ':'`

- The fixed-size message type icons for informational messages, warning messages, error messages, and questions that were used in message dialogs were replaced with new, scalable, Katana-style message type icons.

- The tiny square icons that indicated log message types in the Messages tab and the View Messages popup have been replaced with the new scalable message type icons.

- ID 475786 - The type of widget for displaying help text in Katana's help popups has been changed from `QWebEngineView` to `QTextBrowser`. `QTextBrowser` is a much more light-weight type of widget and loads help text much faster than `QWebEngineView`. A Help button has been added to the HTML editor widget type in Katana to link to the Qt documentation regarding the Supported HTML Subset in help text.

  `QTextBrowser` was already used for the preview of help text in the Edit Help Text dialog, so that the preview and the resulting help popup now actually match. The help text in help popups also now scales with the application/fontSize preference, rather than being determined by separate font size and zoom factor settings.

  The HTML editor widget type including its `QTextBrowser`-based preview area is also used for the text parameter of InfoCreate nodes.

- The representation of partially checked checkboxes has been tweaked so that a filled square is now drawn, similar to Nuke, instead of the classic checkmark.

## USD

- The visibility of locations with the usd.purpose attribute can now be toggled via the Display > Purposes submenu in the Viewer tab. See the entry on Purpose in the USD Glossary for a description of how this attribute is used by Hydra Render Delegates.

- Katana's USD 21.05 package has been built with a `PXR_LIB_PREFIX` of `fn`, and the Python package for USD has been changed from `pxr` to `fnpxr` to ensure it does not clash with local USD Python packages.

  The `PXR_PLUGINPATH_NAME` variable has been set to `FNPXR_PLUGINPATH` to match Katana 4.0.

- The schema classes that are part of the Katana USD Plug-ins have been rebuilt using the `usdGenSchema` code generator script that ships with USD 21.05.

- ID 486637 - The following tools that are part of the USD Toolset are now made available in Katana's `bin` folder:

  - `sdfdump`
  - `sdffilter`
  - `usdGenSchema`
  - `usdcat`
  - `usdchecker`
  - `usddiff`
  - `usddumpcrate`
  - `usdedit`
  - `usdresolve`
  - `usdstitch`
  - `usdstitchclips`
  - `usdtree`
  - `usdzip`

  You may require jinja2 within your Python environment, and will require adding these environment variables on Linux:

      export PYTHONPATH=<KATANA_ROOT>/bin/python
      export LD_LIBRARY_PATH=<KATANA_ROOT>/bin

- The `USD_IMPORT_USD_LUX_LIGHTS_WITH_PRMAN_SHADERS` environment variable was added to the Katana USD Plug-ins to determine whether base UsdLux lights should import with RenderMan light attributes in addition to USD attributes, if the RenderMan renderer is detected. This behavior is off by default.

- The USD plug-ins shipped with Katana are now loaded by default. To prevent this, and to use your own custom-built Katana USD Plug-ins, you can set the new environment variable `KATANA_USD_PLUGINS_DISABLED` to `1` in your Katana launch environment.

## USD Export

- ID 487661 - Default Prims will now have a Kind assigned to them:

  - Assembly file default Prim will be of Kind `assembly`.
  - Shading file default Prim will be of Kind `component`.

- A USD Export plugin has been added to write light location attributes based on parameters from the Sdr Registry. Where a node exists for a light shader, attribute names which match an input identifier are written with the input's type information. This process occurs after light locations are written via the UsdLux API and any parameters written through that are preserved.

- A LightAPI schema is applied to lights exported through the UsdMaterialBake node containing Katana-specific parameters.

- UsdExport will now parse the exported USD file for any exported lights using the UsdLuxListAPI and write this to the Root Prim, for each variant.

- UsdExport will now export light and shadow linking information. Resolved light linking paths will be written to USD, so long as the location linked to, and the light are under the same rootLocation specified on UsdMaterialBake

## USD Import

- Lights imported via UsdIn nodes can now be edited with the Lighting Tools in the Viewer tab.

- PxrUsdIn no longer reads and writes camera or light lists to the location provided by a UsdIn node's location parameter.

  A new Op `PxrUsdInUpdateGlobalListsOp`, which runs after UsdIn's current Op(s), has been added to set globals.cameraList and lightList directly on the /root/world location; provided they are within a model hierarchy with the USD Stage.

- Lights using the LightAPI schema with katana:id attributes will be imported as the provided shader type, with all the renderer name-spaced attributes being loaded into that renderers light parameters. If multiple shaders are mentioned in the katana:id attribute, multiple shaders will be imported, and this is why the namespaced attributes are important. You may not have multiple shaders for the same renderer. We utilize the SdrRegistry to discover the light shader and to read in the relevant attributes, and understand the context required; this means it is required that the light shader is registered to the SdrRegistry for the USD library the Katana USD Plug-ins are utilizing. UsdLux Light information will be imported as before using the UsdLuxAPI.

  The logic to import UsdLux information into prmanLightShader and prmanLightParameters has been moved to a location decorator, and will be skipped if the prman renderer isn't present in the environment, or if prmanLightShader has been populated by the SdrRegistry-based logic mentioned above.

# Bug Fixes

## API/SDK Changes

- ID 281274 - The `FnAttribute.DelimiterEncode()` function replaces forward slash (`/`) and period (`.`) characters in a given name or scene graph location path with other characters. The resulting encoded name can then be used as a child attribute name in `GroupAttribute` structures, where periods are used to denote attribute hierarchy.

  Unfortunately, the previously-chosen other characters were not valid in the context of XML, so could not be written to and read from Katana project files. To address this, slashes and periods are now replaced by `FnAttribute.DelimiterEncode()` with Line Feed (`\n`) and Tab (`\t`) characters, respectively, which are safe to use in XML documents that follow the XML 1.0 specification. This change allows for round-tripping of attributes via XML text, as demonstrated in the following Python code example:

      gb = FnAttribute.GroupBuilder()
      inputAttr = gb.set(FnAttribute.DelimiterEncode('/root/world/taco'), 'xxx').build()
      print(inputAttr.getXML())
      outputAttr = FnAttribute.Attribute.parseXML(inputAttr.getXML())
      print(outputAttr.getXML())

  In previous lines of releases of Katana, the call of `getXML()` raised a `ValueError` exception with the following error message:

      ValueError: Given string is not valid FnAttribute XML

- ID 310448 - When retrieving the XML text representation of a Katana attribute using the `getXML()` method, the resulting XML text contained an extra space in the text of the attribute's value.

- ID 438370 - The implementation of the Render API function `RenderSettings::calculateCropWindow()` incorrectly returned values based on a rounded "region of interest".

- ID 468072 - When a custom RenderMethod inherits from `RenderInfo::DiskRenderMethod`, Katana was not propagating the RenderMethod's original render method name to `renderboot`; instead, it would always set the name to `RenderModes.DISK_RENDER` (a.k.a. `'diskRender'`).

- ID 476581 - The order in which plug-ins were loading during application startup was previously implicitly determined by the presence of the legacy Gaffer SuperTool: Python modules in `Plugins` folders in Katana resource directories were loaded as part of loading Python modules for SuperTools from `SuperTools` folders.

  Python modules in `Plugins` folders are now explicitly loaded before Python modules in `SuperTools` folders.

- ID 486470 - `FnPlatform/StringView.h`, part of the Katana public API, was missing the `<ostream>` header.

## Catalog

- ID 482178 - When toggling the checked state of columns in the header context menu of the Catalog tab's catalog item view, the context menu flickered.

## Hydra Viewer

- ID 458746 - When sRGB textures were used as UDIM tiles, they were wrongly gamma-corrected twice, and subsequently appeared too bright.

- ID 473602 - The Viewer caused a flush of caches when changing render delegates.

- ID 473813 - Setting the geometry.arbitrary.displayOpacity attribute had no effect on the default material used by the Hydra Viewer.

- ID 476538 - When expanding a faceset location with bounds while in Faces mode, Katana crashed. (This issue was a regression in Katana 4.0v1.)

- ID 476717 - When switching render delegate, the shadow mode selected from the Viewer tab's Display menu was not respected. Instead, shadows would be shown for all lights until the shadow mode was next changed.

- ID 479097 - When using multiple Viewer (Hydra) tabs in a layout and making changes to a built-in (virtual) camera followed by starting a Live Render, a Python exception was raised from an event handler for camera changes. (This issue was a regression in Katana 3.6v1.)

- ID 485147 - When using unsupported characters in expressions used for scene graph location names, notably hyphen-minus characters (`-`), a warning message was logged, and the corresponding objects in the Viewer tab were not displayed correctly. (This issue was a regression in Katana 4.0v1.)

- ID 488113 - Removing lights whilst they are disabled did not remove them from the Viewer once re-enabling.

- ID 488534 - Viewing tiffs with un-associated alpha channels could cause the OpenImageIO plugin for USD to crash.

  Viewing materials with a UDIM texture resolving to a path with no tiles in it could cause Hydra to crash.

## Hydra Viewer: Lighting Tools

- ID 490839 - When the Distance manipulator handle, part of the Lighting Tools manipulators, was used on geometry located far away from the world's origin, the manipulator handle would greatly misbehave.

## Hydra Viewer: Render Delegates

- ID 479479 - When using monolithic materials on objects while a Hydra Render Delegate that uses renderer plug-in-based shaders was chosen, the materials were not applied and rendered correctly in the Hydra Viewer.

- ID 481666 - When using shading node connections to array parameters of shading nodes in NetworkMaterialCreate nodes, such as those for ramp shaders, the objects that used the relevant materials were not rendered in the Hydra Viewer correctly, due to a lack of parsing of `FnAttribute` values to `VtValue` values for Hydra shader attributes allowing array type inputs.

- ID 481929 - When setting HdArnold as the render delegate with multiple Viewer tabs open, Katana would crash. While having multiple Viewer tabs using HdArnold is still not supported, the second viewport will now gracefully fallback to the previous render delegate.

- ID 488069 - The options read from the Render Delegates should now preserve the order they were provided to us when displayed in the UI.

- ID 488968 - When modifying the position or view states of nodes inside of a NetworkMaterialCreate node (meaning UI changes that should not affect the rendered image), depending on the chosen Hydra Render Delegate, the render in the Hydra Viewer may have wrongly been restarted.

## Katana Developer Guide

- ID 472937 - Enumerators of the `ThreadMode` enumeration were documented in an obfuscated way, with descriptions of enumerators preceding the names of enumerators, making it hard to decipher and make sense of the documentation presented.

- ID 488496 - In the documentation of Hydra Render Delegates in the Katana Developer Guide, hdStorm was shown incorrectly under its former name hdStream.

## Logging

- ID 488790 - When errors were recorded while parsing a GenericAssign XML/Args File, no warning or error message was logged to let users know about this. This could later lead to obscure issues when trying to use a node of a particular GenericAssign-based node type.

  Now, when errors were recorded while parsing a GenericAssign XML/Args File, a warning message is logged.

- ID 494847 - When Katana's CEL parser detected an unrecognized character, notably the hyphen-minus character `-` (ASCII code 45), a somewhat cryptic message was written to the terminal. That message has now been prefixed with `CEL Parser:`, to make the origin of the message a little clearer.

## Network Materials

- ID 118312 / BZ 50039 - When resetting or clearing custom hints on a shader parameter, the underlying hints child parameter of the shader parameter was set to the string representation of an empty Python dictionary (`"{}"`) or an empty string (`""`), rather than deleting the hints child parameter.

- ID 118557 / BZ 50084 - When adding any custom hints to a shader parameter without adding a particular destination name or page, the shader parameter was exposed in the public interface of the resulting Network Material, which was both undesirable and unexpected.

- ID 410528 - When editing the contents of NetworkMaterialCreate or ShadingGroup nodes using multiple Node Graph tabs, and filtering in the right-hand sidebar, the filtering across the Node Graph tabs could get out of sync with the underlying data.

- ID 454806 - In the NetworkMaterialEdit node, Shading node page headers sometimes do not update when the source material's Shading node page headers are changed.

- ID 481353 - When choosing the Fit Backdrop Node to Selected Nodes command in the Node Graph tab's Edit menu for a number of selected nodes inside of a NetworkMaterialCreate or NetworkMaterialEdit node, the resulting Backdrop node is not positioned correctly. (This issue was a regression in Katana 4.0v5.)

- ID 481447 - When deleting shading nodes inside of NetworkMaterialEdit nodes, stale references to those shading nodes were left in the resulting material.nodes, material.interface, and material.layout attributes.

- ID 481978 - When using the Network Material context at higher resolutions, especially across multiple monitors and/or with a large number of shading nodes, the refresh rate was impacted. Re-draw performance has been improved by around 60%.

- ID 482158 - In an NMC/NME, there were some cases where connections from a shading node to a ShadingGroup's output sidebar were hidden when only shading node input connections should have the option to be hidden.

- ID 487648 - When attempting to move an exposed parameter in the Sources & Order subtab of a NetworkMaterialCreate node to the bottom of the list, the move wrongly did not take effect.

- ID 488920 - In the NetworkMaterialCreate/Edit context, when viewing shading nodes as Connected Only without page headers displayed, sometimes a line was drawn horizontally across the node between two ports.

- ID 488962 - In the NetworkMaterialCreate/Edit context, Dot nodes were not aligned correctly with other nodes in the Collapsed view state.

- ID 488964 - In a ShadingGroup node, it was impossible to create connections from Dot nodes to the Input sidebar.

- ID 492429 - When utilizing modifier key shortcuts recorded in Katana's shortcut manager, for example Alt+H to toggle the visibility of input connections in a NetworkMaterialCreate node, releasing the modifier key before the shortcut key would result in the key release event for that shortcut to not fire, for example leading to temporarily shown input connections remaining visible after letting go of the shortcut keys pressed.

- ID 493444 - When editing a NetworkMaterialCreate node, conditional visibility options would sometimes fail to hide exposed Network Material Interface parameters if that parameter referenced another node in the shading network.

## Node Graph

- ID 478987 - When attempting to remove an input port or output port from a Group node that was locked, Katana crashed.

- ID 478989 - When attempting to undo the removal of a port on a locked node, an exception was raised, and the undo history was cleared. (This issue was a regression in Katana 3.2v1.)

## Node Types

- ID 480689 - When setting a RenderScript node as the view node while Render > 2D Update Mode was set to Continuous, Katana would crash.

## Parameters

- ID 317214 - TeleParameter widgets did not respect the grid layout of surrounding parameter widgets, in terms of their label and edit widget alignment.

## Performance

- ID 480325 - When opening the context menu of a node in the Node Graph tab, a synchronous scene graph cook and a 'Manual 3D Update' were triggered, potentially freezing the UI. (This issue was a regression in Katana 3.5v1.)

  With changes introduced in Katana 3.5v1, the intention was to determine the availability of the menu command for starting a Preview Render with Profiling, depending on whether the Geolib3-MT Runtime was chosen in the render settings.

  Renders commissioned with runtime profiling enabled, but configured by render settings to use the Classic Geolib runtime (which were previously precluded by the context menu), now fail with an appropriate error message.

- ID 481971 - When minimizing the OUTPUT sidebar of a NetworkMaterialCreate node that has been entered in the Node Graph tab, CPU utilization unexpectedly spiked. (This issue was a regression in Katana 4.0v1.)

## Rendering

- ID 453349 - Catalog item thumbnails were sometimes not rendered correctly due to stale, thread-local error flags.

- ID 477061 - `tbb::global_control` provides a mechanism to control the total number of threads that can participate in concurrent processing tasks. Katana's `renderboot` process did not set a value for `tbb::global_control`'s `max_allowed_parallelism` parameter, and therefore, by default, TBB used all available cores.

  `renderboot` now sets `tbb::global_control::max_allowed_parallelism` to the value that it receives via its `-threads` command-line option, which corresponds to Katana's application/rendering.interactiveRenderThreads3D preference in UI mode and the `--threads3d` command-line option in batch mode.

## UI

- ID 472942 - The Add tool button menu of the scenegraph > userColumns preference in Katana's Preferences dialog lists registered GenericAssign-based node types, to make it easy for users to add custom columns to the Scene Graph tab to show values of attributes that correspond to parameters of GenericAssign-powered nodes. The list of node types was not sorted alphabetically, and included names of node types that are meant to be hidden, for example GafferThree_LightMuteAndSolo (which is a type of node that is used internally in GafferThree).

## USD

- ID 446730 - When trying to overwrite variants already baked from a UsdMaterialBake node, an error could be printed to the terminal, resulting in the USD file not being written.

- ID 447830 - When loading USD assets with UDIM textures that used filenames relative to the file system location of the USD file, the Hydra Viewer was not loading the textures, and objects were shaded incorrectly.

- ID 479726 - When setting the isolatePath parameter on a UsdIn node, and then trying to use a UsdInIsolate node, UsdIn failed with an error message: UsdIn: Failed to compute katana path for usd path

  The value of the isolatePath parameter is now prefixed onto the USD stage mask path set up by UsdInIsolate.

  When using isolatePath and UsdInIsolate in the same node graph, the mask created by UsdInIsolate (using Katana scene graph locations) did not take account of the UsdIn mask path which did not contain the locations cut out by setting UsdIn's isolatePath. This meant the USD stage was masked by locations which did not exist, causing errors.

- ID 479729 - When using a UsdInIsolate node to isolate a location that did not exist, Katana crashed.

- ID 482198 - When using the isolatePath parameter on a UsdIn node that is loading a USD asset that uses light lists, UsdIn failed with an error message: UsdIn: Failed to compute katana path for usd path

- ID 484299 - `usdImagingGL` has been replaced by `usdImaging` as a dependency for the `usdKatana` library in `KatanaUsdPlugins`.

- ID 485192 - When using a UsdIn node to import a USD file containing a 3-dimensional texture coordinate primvar named <primname>, the attributes under geometry.arbitrary.<primname> were not loaded completely.

- ID 488546 - When attempting to solo a light that was imported from a USD asset in a light edit package of a GafferThree node, a Python exception was raised.

- ID 490802 - When importing lights via UsdIn nodes, the lightList attribute enabled was wrongly set to true by default.

# Known Issues

## Catalog

- ID 114182 / BZ 49288 - When exporting a Catalog item you need to specify the export folder path to an existing folder. If the folder you're trying to export to does not exist on disk Katana will fail to export. (This issue is a regression in Katana 2.0v1.)

## Hydra Viewer

- ID 427252 - Locators created via PrimitiveCreate nodes can be snapped to in all modes, rather than just the Lights, Cameras, and Locators mode.

- ID 420882 - Changing between the Viewer (Hydra) tab's multipane layout options quickly can cause a crash or many error messages to be written to the terminal/console.

- ID 380129 - Use of non-conformant GL anti-aliasing modes that employ supersampling reduces rendered point size by the supersampling scaling factor. Katana currently employs any reported anti-aliasing mode (up to a maximum sample count of 16): as a workaround, change the viewerHydra.antiAliasing preference to a lesser anti-aliasing mode.

- ID 352167 - Textures loaded from Hydra shaders are not cleared or reloaded from disk when flushing caches.

## Live Groups

- ID 85118 / BZ 41152 - When editing parameters of a node that is part of a LiveGroup node and reloading the parent LiveGroup node, the UI state of the Parameters tab is reset. This includes scroll bar positions, selections of items, and selections of nested tabs (for example Object, Material and Linking tabs for a Gaffer node).

- ID 84998 / BZ 41092 - When reloading a LiveGroup node's parameter interface and contents from its source, parameters of child nodes that are edited in floating panes disappear from those panes.

- ID 84020 / BZ 40598 - Reverting a LiveGroup node does not revert its user parameters.

- ID 84018 / BZ 40600 - Undoing a revert of an unpublished LiveGroup node does not restore the LiveGroup's editable and modified state.

- ID 83061 / BZ 40237 - Nodes can be dragged into the Group bubble of a non-editable LiveGroup node.

## Materials

- ID 442604 - When "exploding" a NetworkMaterialEdit node in the Node Graph tab into its parts by selecting it and choosing Edit > Explode Selected Groups or pressing the U key, Python exceptions are raised.

- ID 429775 - NetworkMaterialEdit nodes do not currently respect local Graph State changes, for example as performed by VariableSet nodes downstream.

- ID 429302 - When editing a locked node inside a NetworkMaterialEdit node graph, the parameters will be shown at their default state.

- ID 427408 - When entering a NetworkMaterialEdit node whose sceneGraphLocation parameter is empty, warnings are logged by the Geolib3 Runtime.

- ID 423341 - In a NetworkMaterialEdit node graph, connections can be displayed incorrectly if a node's name begins with a number.

- ID 402064 - In a ShadingGroup node graph, the connection between a Dot node and a shading node port can be wrongly colored in some cases.

- ID 269449 - Choosing Edit Shader Parameters from the main wrench menu of Material nodes does not show wrench buttons next to shader parameters. This can be worked around by toggling the edit flag on the node. (This issue is a regression in Katana 2.5v1.)

- ID 199304 - The namespace parameter on Material nodes wrongly allows the insertion of Unicode codepoints outside the ASCII range.

- ID 191052 - Katana does not have any support for the texture reference object workflows of V-Ray for Maya.

## Parameter Expressions

- ID 188533 - Expressions linked to non-local parameters on not previously edited Material nodes can't be evaluated.

- ID 105434 / BZ 47520 - Reference Expressions may not refer to dynamic parameters such as shader parameters.

- ID 60457 / BZ 31790 - Setting an array or group parameter to an expression results in an invalid expression. Upon setting a valid expression (for example, an evaluation of an equivalent parameter on another node using getParam), the parameter is not immediately updated. To workaround this issue, close and reopen the parameter, or flush caches while the node is not edited.

## Python

- ID 496659 - When loading a website into a `PyQt5.QtWebEngineWidgets.QWebEngineView` widget, warning and error messages may be issued by the underling Qt WebEngine classes, leading to certain websites not being displayed correctly, or not being displayed at all. (This issue is a regression in Katana 4.5v1 / Katana 5.0v1.)

- ID 494168 - In the Katana Developer Guide, some members of C++ classes that are marked as `friend` incorrectly appear as `friend friend`. (This issue is a regression in Katana 5.0v1, and may be related to an issue in Breathe.)

## Rendering

- ID 381284 - The 3Delight renderer plug-in makes use of source material locations rather than resolved material attributes as a means of de-duplication. This can result in material data being lost when excluding material locations from the Render Working Set during a Live Render session.

- ID 176598 - Use of nodes that modify Graph State Variables in Interactive Render Filters is not currently supported.

- ID 74799 / BZ 36926 - The rendererSettings > displayOptions parameter of a RenderOutputDefine node for the PRMan renderer, shown when its type parameter is set to 'raw', cannot be set using the Parameters tab.

- ID 70217 / BZ 36176 - The 2D node Disk Render Upstream Render Outputs option does not use the batch render method, batchRender, for upstream render nodes, instead using diskRender.

- ID 70016 / BZ 36137 - Rendering repeatedly with a large number of AOVs consumes more and more memory, possibly leading to a crash when running out of memory.

- ID 12517 / BZ 16168 - Only one Monitor tab may display the results of a Preview Render. The use of multiple Monitor tabs is not currently supported.

## UI

- ID 373702 - Clicking in the Viewport and pressing a shortcut whilst the mouse is hovered in another widget will still send the event back to the 'focused' Viewport widget, for shortcuts where the widget hovered over does not handle the shortcut.

- ID 208802 - Closing the Histogram tab after use leaves the Monitor tab unable to display rendered images.

- ID 123558 / BZ 50911 - When changing an array parameter's tuple count/size, any corresponding attributes are not properly updated in the Attributes tab.

- ID 112544 / BZ 49051 - The Viewer tab may lose sync with the Scene Graph tab when changes to expansion state are interrupted.

- ID 107038 / BZ 47853 - Indication of attribute source nodes (such as the yellow 'glow' in the Node Graph tab) is unavailable as of Katana 2.0v1.

- ID 71965 / BZ 36691 - State badges are currently shown for attribute values of dynamic array child parameters, even though only their parent array parameter should appear with a state badge.

- ID 65347 / BZ 34949 - Using Compiz can lead to text fields not receiving focus events correctly due to an incompatibility between Compiz and Qt. Depending on your configuration, disabling Compiz "desktop effects" may resolve the problem.

## USD

- ID 468287 - UsdIn is not retaining expanded view state information for shading nodes in a Network Material context.

## Windows

- ID 381692 - (Windows only) When logging out and logging back in again, the colors in the UI are incorrect. For example, certain parts of certain types of tabs may appear with a white background color. (This issue is a regression in Katana 3.1v1, possibly caused by QTBUG-52728 - Paint bug and palette errors after some events in Windows)

- ID 344118 - (Windows only) When installing Katana and opting to install the bundled version of 3Delight, the installation of 3Delight is made by modifying system-wide environment variables such as `KATANA_RESOURCES`. Thereafter, launching any version of Katana will pick up this installation of 3Delight, which may be incompatible with the version of Katana being launched.

  NOTE: This issue does not affect Linux, where a bundled 3Delight installation is tied to its corresponding Katana installation.

- ID 218742 - (Windows only) Katana must be installed to a path no longer than ~140 characters. Attempting to install to a longer path results in an unintuitive error: "The system cannot find the path specified."

## Miscellaneous

- ID 84326 / BZ 40709 - The Alembic library does not support multiple process or thread access to an Alembic file. This means that a crash occurs when modifying an Alembic file outside Katana, while it's loaded in an open Katana scene. To avoid this, you must Flush Caches before attempting to update any modified Alembic files.

- ID 80738 / BZ 39261 - Operations that lock and unlock nodes do not currently create entries in the Undo History, which can lead to an incorrect node graph state when undoing and redoing operations.

- ID 70196 / BZ 36170 - Control keys (notably arrow keys) do not function as expected in shell mode.

# System Requirements

### Officially Supported Operating Systems

- Windows 10 (64-bit)
- Linux CentOS 7 (64-bit)

### Hardware Requirements

| Minimum | Recommended
--- | --- | ---
CPU | Dual-core processor
Storage | 1+ GB available for installation
System RAM | 1+ GB available
Graphics RAM | 1+ GB available | 2+ GB available
Display | 800 x 600 | 1920 x 1080
OpenGL | OpenGL 4.3+ (see note below)

Note: AMD-based graphics cards are currently not supported.

### Tested Workstation Hardware

The configurations listed below are those that Foundry have tested with Katana. Due to the constantly changing nature and wide variety of computer hardware available in the market, Foundry is unable to officially certify hardware. The list below can be used as a recommendation and does not guarantee that it meets your particular needs.

- NVIDIA Quadro M4000

- NVIDIA Quadro P4000

- NVIDIA Quadro K4000

- NVIDIA Quadro K6000

Please download and install the latest graphics driver from the NVIDIA website.

If you encounter any issues, please contact Customer Support directly through the Support Portal at the following address: https://support.foundry.com.