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 4.0v5 Release Notes

# Release Date

30 June 2021

# Previous Releases

- Katana 4.0v4 Release Notes

# What's New in Katana 4.0

These release notes describe changes from Katana 4.0v4 to 4.0v5.

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

# Feature Enhancements

### API/SDK Changes

- Support for placement of multiple nodes created by Node Graph Layered Menu actions has been added:

  Where a Layered Menu action returns a sequence of top-level nodes to be placed in (and potentially connected to) the node graph, the nodes' relative positions and connections are now preserved, fixing Bug ID 443107 (see Bug Fixes below). The first and last nodes of the sequence are considered input and output nodes, respectively, with the input node's input ports being candidates for connection to the existing node graph.

  Auto-placement of created nodes (placement and connection based on the current node selection, controlled with the nodegraph/autoConnectOnCreate preference) is not currently supported in the Network Material node graph context (e.g. within a NetworkMaterialCreate node), and is no longer attempted.

### Configuration

- ID 250552 - Support for loading layout files from directories whose paths are added to the `KATANA_RESOURCES` environment variable has been added.

  Layouts are loaded from files that are named `KatanaLayout2.xml`, or whose filenames end on `.katanalayout.xml`, which are placed in `Layouts` folders inside of those Katana resource directories. Layouts that are saved from the Layouts main menu in the Katana UI are still saved in the `KatanaLayout2.xml` file in the current user's Katana resource directory in their home directory (e.g. `~/.katana/KatanaLayout2.xml` on Linux).

### Katana Developer Guide

- Documentation of Terminal Op Delegates has been added to the Scripting in Katana > Cooking a Scene section of the Katana Developer Guide.

### Node Graph

- ID 46936 / BZ 21714 - When creating a node while another node is selected that contains outgoing connections and while Auto-Connect New Nodes Based on Selection is turned on, the new node will now be inserted into all branches of outgoing connections of the selected node, instead of creating a new branch.

- ID 79117 / BZ 38478 - When creating a Backdrop node using a node creation menu in the Node Graph tab while nodes are selected, the new Backdrop node is now placed and sized to fit those selected nodes.

### OpWrite Node Type

- ID 473985 - A basic CMake syntax highlighter has been introduced. Primary use is highlighting CMake code in OpWrite nodes.

### Python

- ID 447015 - The Python syntax highlighter, primarily used in the Python tab, has been enhanced to also format built-in objects (e.g. `hasattr()`, `range()`, `tuple`, ...), special keywords (e.g. `assert`, `import`, `raise`, `try`, ...) and numbers. Also a number of fixes to string formatting have been applied.

- The line number of the line that contains the text cursor in the Python tab is now being highlighted.

### Rendering

- ID 473791 - Documentation for the `KATANA_RENDER_INTERCEPT` environment variable, which has been available since Katana 2.0v1, has been added to the Debugging section of the Environment Variables page in the Katana Developer Guide.

### Scene Graph

- ID 241939 - Working Set state icons in the Working Set columns of the Scene Graph tab are now dimmed when the use of the respective Working Set is turned off.

# Bug Fixes

### Catalog

- ID 56695 / BZ 28666 - When large render logs with hundreds of thousands of lines were being displayed in the Render Log tab as part of switching between items in the Catalog tab, a considerable delay could occur, freezing the UI.

- ID 80276 / BZ 39035 - When exceeding the configured memory limits for catalog items, Katana crashed without prior warning.

  The memory limits can be configured using the `KATANA_IMAGE_MEMORY` and `KATANA_IMAGE_DISK_MEMORY` environment variables, as well as their Python equivalents: `Nodes2DAPI.SetMaxImageMemory()` and `Nodes2DAPI.SetMaxDiskUsage()`.

  The following two environment variables have been added to further configure Katana's behavior regarding these memory limits:

  - `KATANA_CATALOG_MEMORY_WARNING`: Specify the memory usage threshold (as a percentage e.g. `70` would issue a warning when memory consumption reached 70% of the available RAM and disk space) above which a warning will be raised and further rendering will be suspended until memory is freed from the Catalog. By default this is 90% of the available RAM and disk space reserved for the Catalog.
  - `KATANA_HARD_MEMORY_LIMIT`: If set (to any value), Katana will raise an un-recoverable `OutOfMemory` exception when it is unable to allocate image buffer memory for the Catalog. The raised exception will cause Katana to crash. If not set, Katana will continue to allocate memory (ignoring any soft limits set by `KATANA_IMAGE_MEMORY` and `KATANA_IMAGE_DISK_MEMORY`).

### Gaffer

- ID 477377 - When creating a light for V-Ray with an RGBA color value in the table of objects of an edited GafferThree node in the Parameters tab, an error message about the display data not containing exactly 3 values was logged. (This issue was a regression in Katana 4.0v1.)

  The GafferThree table of objects and the Scene Graph tab will now accept RGBA color values without error, but will still only consider up to the first three color component values when painting a color swatch. A separate feature enhancement is logged to add support for drawing color swatches with an indication of alpha components in the GafferThree table of objects: ID 415071.

### Hydra Viewer

- ID 446435 - When the user attempted to apply a transform manipulation (by means of a viewer manipulator) in a TransformEdit node, exceptions were raised if the TransformEdit node's parameters had not been shown in the Parameters tab yet.

- ID 472931 - Experimental support for switching to and between custom Hydra Render Delegates, which was first added in Katana 3.2v1, was temporarily deactivated in the Katana 4.0 line due to changes to the underlying bridging code from Katana to Hydra/USD (see Known Issues below). The menu items for changing between Render Delegates in the Hydra Viewer have now been removed from the Katana 4.0 line, as they were leading to crashes with certain Render Delegates.

  Support for switching between Render Delegates will be added again in a future minor release of Katana, based on a newer version of USD.

- ID 473204 - When attempting to snap an object to a piece of geometry for the first time, a warning message was logged. (This issue was a regression in Katana 4.0v1.)

- ID 478997 - When attempting to change the subdivision level of a location that was hidden via the Viewer Visibility Working Set, Katana crashed.

### Live Groups

- ID 84019 / BZ 40599 - When reloading the parameters and contents of a LiveGroup node from its source, for example by choosing the Reload command in the context menu of the LiveGroup node in the Node Graph tab, any user parameters that were added to the LiveGroup node that didn't match the names of user parameters loaded from the LiveGroup source asset were silently discarded. Now, only those user parameters whose parameter types do not match the types of the user parameters that are loaded from the LiveGroup source asset are discarded, and a warning message is logged alerting the user about the removed user parameters.

- ID 232554 - User parameters of type number that have been added for LiveGroup user parameter interfaces can be animated with keyframes, just like number parameters on any other node. When such animated number parameters were modified after loading animation curves for them from the LiveGroup source, and then reloading the LiveGroup, the original animation keyframes from the LiveGroup source file were wrongly restored, and any changes made to curve segments or keyframes on the LiveGroup node's user parameters were lost.

  This longstanding bug was caused by incorrect behavior of the `NodegraphAPI.Xio.Parameter_setValue()` function: Rather than replacing an existing `<fcurve>` child element in the given parameter XML element, the function wrongly appended another `<fcurve>` element to the list of child elements, thereby accumulating `<fcurve>` child elements. Only the last `<fcurve>` child element added in this way actually took effect in the corresponding `NodegraphAPI.Xio.Parameter_getValueDict()` function.

### Network Materials

- ID 437666 - When opening the Find Nodes popup while a NetworkMaterialCreate or NetworkMaterialEdit node were entered (by pressing Ctrl+F or clicking the Find Nodes tool button), the popup listed internal nodes of these SuperTools which were meant to be hidden.

- ID 473696 - When a NetworkMaterialEdit node inherited a legacy Network Material, and one of the inherited connections had been intentionally set to `FnAttribute::NullAttribute`, an exception was raised, and the Network Material's scene graph location was set on error, disrupting the rest of the connections and the rest of the attributes.

  Now, if a connection is set to `FnAttribute::NullAttribute`, it is gracefully skipped.

- ID 479435 - When numeric shader parameters of type `int` or `double` were overridden in NetworkMaterialEdit nodes, their number type was not retained, and the numeric parameter would then switch its type to `float` (the default when no type hint is provided). Renderers that were expecting `int` or `double` would then receive a `float` value, which was then generally ignored.

### Node Graph

- ID 443107 - Where a Layered Menu action returns a sequence of top-level nodes to be placed in (and potentially connected to) the node graph, the nodes' relative positions and connections were not preserved.

### OpWrite Node Type

- ID 473983 - When OpWrite nodes were cooked concurrently by both Katana and `renderboot`, a potential race condition could occur when the temporary dynamic library was written to the temporary directory.

### Parameters

- ID 45979 / BZ 20846 - When clicking the Insert Image button in the Edit Help Text dialog while editing a parameter's help text, a legacy file browser dialog was opened, instead of a standard Qt file dialog.

- ID 471960 - When exporting an Args File for a shader that uses conditional locking options or conditional visibility options for one or more of its parameters, those options were not stored in `<hintdict>` elements with type, name, and value, e.g. `<string name="conditionalLockPath" value="../anisotropicReflectivity"/>`, but rather wrongly stored in `<hintlist>` elements with only a type and the name stored as a value, e.g. `<string value="conditionalLockPath"/>`. (This issue was a regression in Katana 3.1v1.)

- ID 476201 - When clicking the Insert Image button in the Edit Help Text dialog while editing a parameter's help text, a Python exception was raised. (This issue was a regression in Katana 3.1v1.)

### Python

- ID 429780 - The `pytil_cmodule.BezierModule` module has been deprecated, and should no longer be used. It will be removed in an upcoming minor release.

- ID 469810 - (Windows only) Protected members were displayed in the auto-completion popup of the Python tab.

- ID 472496 - The name of the `LoadBookmark()` function was not included in the `__all__` variable of the `ScenegraphBookmarkManager` module, meaning it could only be called after importing the function name from the module manually.

- ID 476167 - The order of paths added via `PYTHONPATH` and `sitecustomize.py` scripts was not respected.

### Rendering

- ID 351640 - When renaming the node from which a Live Render was started, while an Interactive Render Filter (IRF) was active, a Python exception was raised.

- ID 392451 - When Live Renders were combined with Interactive Render Filters, the Live Rendering session could break if the nodes of the active Render Filters nodes had a Geolib3 Client observing the scene from their output ports. (This issue was a regression in Katana 2.6v1.)

- ID 472412 - When processing chains of Merge Ops containing adjacent single-input Merge Ops, the FlattenMergeHierarchies Op Tree optimization pass crashed, leading to render failure when using the Geolib-MT Runtime with Op Tree optimizations enabled. (This issue was a regression in Katana 3.5v2.)

- ID 477101 - When using the Render Dependencies Only command from the context menu of a Render node with multiple inputs, a Python exception was raised, and the render failed to start. (This issue was a regression in Katana 4.0v1.)

- ID 478818 - When starting a Live Render from the context menu of a node, while the 3D Update Mode was set to Manual or Pen-Up, the Live Render was wrongly only started when a change to the node graph was made, or when the node was right-clicked again. (This issue was a regression in Katana 3.6v1.)

- ID 480721 - When `RenderManager.ResolutionTableUtils.SaveResolutionTables()` was invoked, the XML file was only being generated if the directory in which the file is to be written did not exit. If the directory existed, the function would return immediately, without re-writing the file. (This issue was a regression in Katana 4.0v1.)

  This issue manifested itself when extra resolution entries were added to the `ResolutionTable` after the first render. As the XML file was not rewritten, the render process was unable to locate newer resolution entries.

  As a workaround, users could run the following snippet in a Python tab to delete the `Resolutions` directory contained in Katana's temporary directory, therefore ensuring that the XML file would be regenerated again when the next render is started:

      shutil.rmtree(
          os.path.dirname(
              RenderManager.ResolutionTableUtils.GetTempResolutionTablePath()))

### Scene Graph

- ID 474329 - When pressing navigation keys and keyboard shortcuts like Left, Right, Ctrl+Left, Ctrl+Right, Home, and End, while the tree widget of the Scene Graph tab helps the input focus, actions on Katana's timeline were triggered instead of changing the expansion or selection of items in the Scene Graph tab. (This issue was a regression in Katana 4.0v1, where customizable main timeline keyboard shortcuts were introduced.)

### UI

- ID 466613 - When zooming very far into the Curve Editor tab's viewport canvas using the mouse wheel, Katana froze.

- ID 474414 - When connecting a Render node to a node graph that does not contain a CameraCreate (or other camera-creating) node, a collapsed event handler error was logged, and the Render node did not show any render outputs in the Parameters tab. (This issue was a regression in Katana 4.0v1.)

### USD Export

- ID 470559 - When attempting to bake a Network Material containing a shading node whose name contained spaces to USD files using a UsdMaterialBake node, a Python exception was raised.

- ID 471351 - When attempting to bake a Network Material containing custom OSL shaders to USD files using a UsdMaterialBake node, a Python exception was raised, due to an apparent `TfToken` type mismatch. A resulting USD file then contained shader inputs appearing with a wrong type and default value, for example `color3f inputs:MyFloat = (0, 0, 0)` instead of `float inputs:MyFloat = 0.58`.

  Shader inputs not found in the `SdrRegistry` but with valid shader output tags may now assume their respective USD data type. Note that this is an estimation, and is not guaranteed to always be correct, if the input attributes are not found in the USD `SdrRegistry`.

# 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 468318 - Experimental support for switching to and between custom Hydra Render Delegates, which was first added in Katana 3.2v1, has been deactivated in the Katana 4.0 line due to changes to the underlying bridging code from Katana to Hydra/USD.

- 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 437433 - When repeatedly changing the value of the sceneGraphLocation parameter of a NetworkMaterialEdit node, the node may fail to populate its contents, and exceptions may be 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 429206 - Parameter expressions when promoted from shading nodes in a NetworkMaterialCreate node are of a constant value, relative to the resolved expression at time of creation.

- 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.

### 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.

- ID 446730 - When trying to overwrite variants already baked from a UsdMaterialBake node, an error can be printed to the terminal, resulting in the USD file not being written. In this instance, flushing caches before overwriting the file should act as a workaround.

### 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 337653 - Katana logs deprecation warnings when loading the `PyMockAsset`, `PyMultiMockAsset`, and `PyMockFileSeq` shipping example Asset API plug-ins.

- 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 6 (64-bit), and later

## 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.