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.0v1 Release Notes

# Release Date

29 October 2020

# Previous Releases

- Katana 3.6v3 Release Notes

# System Requirements

## Officially Supported Operating Systems

- Windows 7 64-bit or higher
- Linux 64-bit operating system (CentOS/RHEL 6)

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

'Recommended' does not guarantee that it meets your particular needs

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

# What's New in Katana 4.0

These release notes describe changes from Katana 3.6v2 to 4.0v1.

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.

# New Features

## Artist-focused Lighting Tools

- Katana 4.0 introduces a new Lighting Tools feature set that represents the first part of the new digital cinematography workflows. Artists can interact more creatively with the image as everything they need for light creation, manipulation and editing, is now right at their fingertips.

  New lights are created simply by Shift + Click on a polymesh or subdmesh object in the Viewer (Hydra) tab. The newly created light can continue to be moved using the arrowhead manipulator.

  Once created, you can use gestures to manipulate the lights:

  - Ctrl+left dragging away from or towards the light moves the light closer or further away from its center of interest.
  - Ctrl+Shift+left dragging towards or away from the light uniformly scales it.

  The options for creating and interacting with the lights are split into a number of areas designed to mimic the thought process of a cinematographer on a live set. You can place the lights relative to how their light falls on a surface using Lighting Modes such as:

  - Normal
  - Specular
  - Reflection

  You can also decide on light placement with the goal of casting a shadow, using:

  - Shadow

  Alternatively, you can create lights using a subset of the snapping feature:

  - Face - Center
  - Face - Center - Oriented to Normal
  - Object Surface
  - Object Surface - Oriented to Normal
  - Object - Center

  We have also added the ability to lock the current orientation of a light and nudge it into position using:

  - Fixed Rotation (this mode can be engaged independently using the O key or temporarily by holding the O key)

  Selected lights also display a floating parameter UI that defaults to the same parameters that are shown in the GafferThree table of objects (intensity, exposure, and color) but they can easily be expanded with a ViewerObjectSettings node. You can decide which parameters are important to your artists. You also have the ability to favorite certain lights by clicking the star icon.

  There's an indicator arrow that's displayed by default that shows the light's center of interest. This can be used to select lights that are off screen. This handle respects the color attribute viewer.default.color which can be easily changed with a ViewerObjectSettings node with the drawOptions > color parameter. You can also choose to hide the handle with a ViewerObjectSettings node's lightingTools > hideHandle parameter.

  There are a number of additional tools available:

  - Clone (under the light types menu) — duplicates the currently selected light and moves it to the new location
  - Clone as Template (under the light types menu) — similar to Clone, but also a new Template Material (formerly known as Master Materials) is shared between the lights
  - Duplicate — creates a new light in the same place as the original
  - Camera Position — creates a light at the current camera position

## Hydra Viewer: Image-based Selection

- The new Image-based Selection feature in the Viewer (Hydra) tab allows users to more directly access the ID pass that can be created in parallel with a render. This allows seamless selection of scene graph locations with no distinction as to whether the underlying data (such as geometry) has been loaded into Katana or not. Once selected, these locations can be used in all the same places as a normal selection, such as in CEL editor widgets.

  The ID buffer being used does not have to be from a current render and can be from a catalog item that was saved in a previous session. This allows users to address some review notes instantly without having to expand locations or load geometry.

## Katana Foresight

- ### Improved Render Farm Integration

  Katana's `FarmAPI` Python package allows developers to integrate render farms with Katana. This allows artists to start renders on a render farm right from within Katana’s user interface.

  In Katana 4.0, the `FarmAPI` Python package now provides a base class for a new type of plug-in that allows developers to even more closely integrate a specific render farm system with Katana: `FarmAPI.BaseFarmPlugin`.

  The `FarmAPI.BaseFarmPlugin` class provides an interface that allows Katana to:

  - Send Preview Render, Live Render, and Disk Render jobs to a render farm to be executed remotely.
  - View the list of jobs running on the render farm.
  - Retrieve information about a particular render farm job, such as the current state and the job’s render log.
  - Stop/restart previously submitted jobs.

  For every render farm plug-in that is defined using a class derived from `FarmAPI.BaseFarmPlugin` and registered with Katana, menu commands for starting renders on the respective render farm are added to the context menu of any 3D node in the Node Graph tab (not just Render nodes).

  Katana ships with a Katana Queue farm plug-in as source, which demonstrate the use of the new APIs. You can find its Python module in the Katana installation directory: `$KATANA_ROOT/plugins/Src/Resources/Core/Plugins/KatanaQueueFarmPlugin.py`.

  You can find more information about the new APIs in the completely revised FarmAPI documentation in the Rendering a Scene section of the Katana Developer Guide.

- ### Katana Queue and Remote Rendering

  Katana now ships with a minimal render farm implementation, named Katana Queue (or kq for short), which is integrated with Katana using a custom render farm plug-in via Katana's extended `FarmAPI`, as described above.

  The Katana Queue system uses a certain number of Agent processes on the local workstation to host `renderboot` processes for performing renders. It is possible to configure the number of Agents running on the local machine using an environment variable named `KQ_NUM_AGENTS`. It is also possible to launch Agents on another machine that is accessible on the network (Remote Agents), and to add them to the pool of Agents that are managed by the local Katana Queue.

  Documentation on Adding Remote Agents to the local Katana Queue can be found in the Katana Developer Guide. A new shelf named KatanaQueue is available, which contains a Launch Remote Agents shelf item that opens a dialog that makes it easy to remotely launch Agents for use with the Katana Queue of the current Katana session on a machine that is accessible in the current network.

  To start a render on Katana Queue, right-click a 3D node in the Node Graph tab, and choose Katana Queue > Preview Render.

  A dedicated Katana Queue tab is provided, which lists jobs that are managed by the local Katana Queue, with the ability to filter the list of jobs by job state, select jobs, display their render log, and stop and restart them. You can open a Katana Queue tab by choosing Render > Show Katana Queue in Katana's main window, but you can also find the Katana Queue tab in the Tabs main menu.

  Both the Katana Queue farm plug-in and the Katana Queue tab are shipped as source, providing developers with `FarmAPI` example code.

  ### Multiple Simultaneous Renders

  Katana 4.0 allows artists to have multiple Preview Renders running in parallel at the same time. Previously, when starting a new render, a currently running render was cancelled. One use case for running multiple Preview Renders in parallel is to explore variations of looks as part of a Live Render, and start Preview Renders of desired looks. By default, when starting a Live Render, previous renders are still cancelled. This behavior can be changed by setting an environment variable, but this is still experimental.

  In order to support both the running of multiple renders, and the starting of renders on render farms, Katana's Render main menu has been revised: The Cancel Renders (Esc) command has been replaced with a Cancel Current Render (Esc) command, that acts on the render that is chosen as the Front image in the Monitor tab (by clicking its thumbnail in a Catalog tab or view). A new Cancel All Renders (Shift+Esc) command cancels all renders that are currently in progress, including those that were started on render farms via the `FarmAPI`.

  For every render farm plug-in that is built and registered using Katana's extended `FarmAPI`, as described above, a dedicated menu command for stopping all jobs that were started on the respective render farm is added to a new Render Farms section in Katana's Render main menu, for example Render > Stop Katana Queue Jobs.

- ### Catalog and Monitor UI Improvements

  In order to improve the artist experience when rendering multiple simultaneous renders, we have added a number of improvements to the Catalog and Monitor tabs.

  - Thumbnails in the Catalog tab now update as pixel data is received, and are also resizable via their column header

  - ID 98604 - Global Graph State Variables (GSVs) and Interactive Render Filters (IRFs) are now stored with the catalog entry and are displayed in their own columns. It is also possible to add individual GSV columns by right-clicking on the column headers and choosing them from the context menu.

  - A new side-by-side Multi View in the Monitor tab for the Front and Back image buffers. This view can be split either vertically or horizontally and the framing of the entries can be synced or not.

  - A new pinning mechanism for the currently viewed Front image buffer is available to prevent the Front image buffer automatically jumping to new catalog items. This is accessed via Ctrl+left clicking the catalog item thumbnail.

## Network Material UI Enhancements

- ### Multiple Network Materials in NetworkMaterialCreate Nodes

  It is now possible to create multiple Network Material locations from within a single NetworkMaterialCreate node, reusing parts of shading networks between them. The user interface of NetworkMaterialCreate nodes in the Parameters tab has been extended with a tree view of Network Materials, in which Network Materials can be added and organized into namespaces. The resulting material locations are all created under a common root location, whose path can be specified using the new rootLocation parameter. A new instance method named `getRootLocation()` was added to the NetworkMaterialCreate node type class, for consistency with the method of the same name in the GafferThree node type class.

  Features supported in the NetworkMaterialCreate parameter interface:

  - Access menu commands via menu bar or context menu.
  - Add and delete Network Materials and namespaces.
  - Reorder items using the Middle-Click drag modifier.
  - Rename Network Materials and namespaces.
  - Disable Network Materials either in the parameter interface or hovering over the Network Material in the sidebar and pressing D.
  - Duplicate Network Materials including the penultimate shader node and its upstream shader connections.
  - Duplicate namespaces including any child items.
  - Expand All / Collapse All commands for a selected namespace and any of its child namespaces.
  - View the number of Renderers and Terminals connected to each Network Material.
  - An Interactive checkbox column. When checked, you can drag objects in the Viewer and Katana retains the information from the Viewer.
  - Set color chip display of a Network Material from a Color column.

  Node Graph tab interaction support:

  - Paste Network Materials into the NetworkMaterialCreate
  - Drag NetworkMaterial nodes onto a MaterialAssign node using Shift+Middle-Click drag modifier.

- ### Node State Filtering in NetworkMaterialEdit Nodes

  NetworkMaterialEdit nodes now provide an ability to dim or highlight nodes based on their edit state inside the node. This allows users to see the changes they care about inside the node at a glance. An additional red node color has been included for disconnected nodes.

  When viewing the contents of a NetworkMaterialEdit node, the toolbar of the Node Graph tab now displays a new filtering UI for the contained nodes' state. Users can choose to dim certain nodes based on the nature and origin of the changes made to those nodes in the shading network.

## USD Export using UsdMaterialBake

- The UsdMaterialBake node type has been added to support baking of materials and their assignments to USD files.

  In order to make the USD export feature available in Katana, a couple of environment variables need to be set in the Katana launch environment:

  On Linux:

      export KATANA_ROOT=/path/to/katanaInstallationDirectory
      export KATANA_RESOURCES=${KATANA_RESOURCES}:${KATANA_ROOT}/plugins/Resources/Usd/plugin
      export PYTHONPATH=${PYTHONPATH}:${KATANA_ROOT}/plugins/Resources/Usd/lib/python
      export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${KATANA_ROOT}/plugins/Resources/Usd/lib

  On Windows:

      set KATANA_ROOT=C:/path/to/katanaInstallationDirectory
      set KATANA_RESOURCES=%KATANA_RESOURCES%;${KATANA_ROOT}/plugins/Resources/Usd/lib/python
      set PYTHONPATH=%PYTHONPATH%;${KATANA_ROOT}/plugins/Resources/Usd/lib/python
      set LD_LIBRARY_PATH=%LD_LIBRARY_PATH%;${KATANA_ROOT}/plugins/Resources/Usd/lib

  UsdMaterialBake is implemented as a SuperTool, and has been designed to provide an example of the new ability to write custom nodes for export using extensions in the existing `LookFileBakeAPI` and `Nodes3DAPI` Python modules, in particular `LookFileBakeAPI.LookFileBaker` and `Nodes3DAPI.LookFileBaking`. The node type is designed to provide an override layer that needs to be applied back in USD over the asset that is being look-developed.

  A typical workflow would be:

  1. Use a UsdIn node to import an asset that would form the payload of an asset.
  2. Apply the desired look by adding nodes to the recipe.
  3. Use a UsdMaterialBake node to write the override layer.
  4. Create a USD file that references the original asset and the new shading layer.
  5. Import the complete USD asset into the DCC of your choice.

  The feature set supported by USD export from Katana includes the following:

  - Material assignments
  - Shaders (as long as they are registered with USD's `SdrRegistry`).
  - Child Materials written out as siblings with a LookAPI Schema applied.
  - Different input ports written out as multiple Variants.

  Note: The source code of the UsdMaterialBake node type will be made available in our external open source repository on GitHub, and documentation will be made available in the Katana Developer Guide.

  Warning: There is a current limitation that materials must exist alongside the assets being exported, and not in the usual /root/materials location.

  Note: Out of the box, only UsdPreviewSurface materials can be exported. To support other renderers, their render delegate must be available. More information is available in the documentation.

## USD Scene Delegate Improvements

- As part of our USD development, a new Katana Scene Delegate has been implemented, which handles communication between Katana and the Hydra Viewer's render delegates. This allows for more robust use of the HdStorm render delegate features such as lights with shadows and USD Preview Surface materials for assets.

  As part of this work, additional Network Material support has been added, and UsdPreviewSurface materials are now supported (including its supporting nodes like UsdUVTexture). On top of this, it is also possible to author UsdLux-based lights to illuminate these materials, thus creating a much richer visual experience.

  A new section titled Render Delegate has been added to the View menu of the Viewer (Hydra) tab. The section features the following menu items:

  - Basic Material — a toggled menu item that is turned on by default, which can be turned off to turn the use of UsdPreviewSurface materials for the HdStorm render delegate on.
  - Default Lighting — a toggled menu item that is turned on by default, which can be turned off to turn the use of UsdLux-based lights for illuminating UsdPreviewSurface materials for the HdStorm render delegate on.
  - A set of menu items that control the appearance of shadows for objects rendered by the HdStorm render delegate:
    - No Shadows
    - Shadows from All Lights
    - Shadows from Selected Lights

# Feature Enhancements

## API/SDK Changes

- The `UI4.Widgets.ViewportWidget` class that forms a part of Katana's Viewer API has been reimplemented to be derived from the `QOpenGLWidget` class. One objective of this work was to be able to draw semi-transparent widgets on top of Viewer API-based viewer tabs.

  Previously, the `ViewportWidget` class was derived from `QWidget` and provided with a native window. Drawing was performed directly on the back buffer of the screen, disallowing any kind of compositing at application level. Compositing was still possible at system level, but only if the system had a compositing window manager enabled, and only if the transparent widgets were configured as native windows as well.

  With the new `QOpenGLWidget`-based implementation, the viewport is now drawn onto an internal framebuffer object. Once the draw function has completed, the internal framebuffer object is then transferred onto the `QOpenGLWidget`'s default framebuffer object. This allows Qt to apply further compositing before the final framebuffer object is transferred to the screen.

- ID 448056 - A new class variable named `Hidden` was added to the `LookFileBakeAPI.BaseLookFileBakeOutputFormat` class, with a default value of `False`. The class variable can be defined as `True` in derived classes in order to hide the corresponding Output Format from the list of options available for the outputFormats parameter of LookFileBake nodes.

  A new keyword argument named `includeHidden` was added to get functions in the `LookFileBakeAPI.OutputFormatAPI` module — `GetOutputFormats()`, `GetOutputFormatNames()`, and `GetOutputFormatFileExtensions()` — with a default value of `False`. Setting the keyword argument to `True` forcibly includes Output Formats which have their `Hidden` class variable set to `True`.

- The `writeToDisk()` and `writeToAsset()` methods of the `LookFileBakeAPI.LookFileBaker` class have been renamed to `bake()` and `bakeAndPublish()`, respectively, for clarity and correctness.

## Catalog

- The new catalog/createPerRenderProjectSnapshot preference can now be used to specify if additional metadata about a Katana project should be created and stored in new catalog items when starting a render.

  You can choose between one of three options:

  - Minimal: Stores names, values, and enabled states of global Graph State Variables, and names of Interactive Render Filters that are active.
  - Full: Stores the entire node graph, including details of global GSVs and IRFs.
  - Off: Stores no project snapshot data.

- Hovering the pointer over the table view header in the Catalog tab will now reveal informative tooltips for each column.

## Deprecated and Removed Features

- The `ScenegraphAttr` and `PyScenegraphAttrFnAttributeBridge` Python modules, which were added as a compatibility layer in Katana 2.0v1, are now marked as deprecated in their docstrings. They will be removed in an upcoming major release. `FnAttribute` should be used instead.

- Legacy OpenSceneGraph-based Viewer tabs are now deprecated and appear with a dismissible warning banner at their top. Please use Viewer (Hydra) tabs instead.

- ID 110195 / BZ 48556 - The application/rendering/saveKatanaScriptOnRender preference, which never had any effect in commercial Katana, was removed. As part of this removal, the corresponding `saveRenderXML` member of the `RenderingSettings` class was removed as well.

- ID 433836 - The defunct `GeoAPI.Util.MeshCombine` Python module was removed.

- ID 449548 - The `UI4.Tabs.Catalog.CatalogWidget.CatalogWidget.getMonitorSwipeMode()` method is now deprecated. Please use `UI4.Tabs.Monitor.MonitorWidget.MonitorWidget.getImageMode()` instead.

## Documentation

- Developer documentation for exporting data in USD format has been added to the Katana USD Plug-ins section in the Katana Developer Guide, focusing on exporting material information using the new UsdMaterialBake node type.

- The Katana Developer Guide has been updated to accommodate changes in the `LookFileBakeAPI` and the addition of the `Nodes3DAPI.LookFileBaking` Python module.

## Gaffer

- Master Materials in GafferThree have been renamed to Template Materials, and relevant APIs have been updated accordingly. Previous names of functions have been left in the codebase, and forward to the new functions, while logging deprecation warnings.

## Hydra Viewer

- The Viewer (Hydra) tab's toolbar has been cleaned up by removing certain decoration labels and providing icons to the Transform Space buttons (previously text buttons).

## Logging

- ID 62853 / BZ 33396 - The LookFileBake node's Writing <pass filename> log/progress update message has been changed to Writing pass: <pass name> for clarity/correctness.

## Node Graph

- ID 352914 - The default values of time sampling parameters — maximum number of time samples, shutter open, and shutter close — can now be customized by adding project settings parameters to the Katana project's root node:

  - maxTimeSamples — expected to be a number parameter hinted to represent an integer number that defaults to 1.
  - shutterOpen — expected to be a number parameter for a floating-point value that defaults to 0.0.
  - shutterClose — expected to be a number parameter for a floating-point value that defaults to 0.0.

  The default value for Graph State shutterClose has changed from 1.0 to 0.0, matching the default renderSettings attribute (and corresponding RenderSettings node parameter).

  The Render Settings DAP now respects time sampling parameters specified in System Op Args, and so default values displayed in Katana's UI respect Graph State time sampling parameters.

  Note: Where maxTimeSamples (numSamples) is 1, shutter intervals of (0.0, 1.0) and (0.0, 0.0) are both interpreted as yielding a single sample at 0.0, so the change to the shutterClose default value does not affect sampling in the default case.

- A new Edit > Duplicate with Connections command is now available in the menu bar of Node Graph tabs while in the NetworkMaterialCreate/Edit context. The command duplicates all selected nodes along with their input connections. Additionally, keyboard shortcuts Ctrl+D and Ctrl+Shift+D have been added for Duplicate and Duplicate with Connections, respectively.

## Rendering

- ID 128699 / BZ 51682 - The parsing of Katana's Render Log text lines to detect render progress messages has been revised to be more robust, leading to more stable catalog item progress bar behavior.

- ID 411343 - Support for adding and removing render outputs/AOVs during a Live Render session has been added. When adding or removing a render output, Katana now sends an updated renderSettings.seqIDMap attribute to the render plug-in in the form of a Live Render Update Attribute for the /root location.

  Note: Support for adding and removing render outputs/AOVs during a Live Render session depends on the render plug-in being used.

- ID 422728 - A new `KATANA_DISPLAYDRIVER_PRECISION` environment variable has been added, which can be set to `float`, `half`, or `byte`, to set the data type to use for encoding pixels that are transmitted between a render process and Katana. The setting can be used to reduce the bandwidth required for transmitting images, but at the cost of a loss of fidelity. A corresponding interactivePrecision parameter has been added to RenderSettings nodes.

  Warning: When setting interactive precision to half or byte, features that rely on an ID pass being rendered, like the Pixel Probe tool in the Monitor tab, and the ID Buffer tool in the Viewer (Hydra) tab, will only work when a render plug-in is used that has been rebuilt against the Katana 4.0v1 Display Driver API.

## UI Improvements

- The View Messages button's icon now displays the color corresponding to the highest active (enabled) level with records, except while notifying the user of a message of severity warning or above (regardless of the currently active levels). The indicator now also incorporates messages that were logged prior to the button being initialized.

- The HSL tab in color editor widgets and Color Picker dialogs has been replaced with a more artist-friendly TML tab for controlling temperature, magenta, and luminance.

  Authors of custom parameters can use a new widget hint named `color_defaultColorComponentTab` to specify which color component tab will be selected by default for the respective parameter. Valid values for that new hint are: `'RGB'`, `'TML'`, and `'HSV'`.

## USD

- The list of renderers that are available inside NetworkMaterialCreate nodes, which can be accessed by pressing the Shift+Tab keyboard shortcut, adds all items where their `RenderInfoPlugin` returns `true` to `isNodeTypeSupported("ShadingNode")`. In order to support the display of USD shading nodes, the list now also includes renderers for which render info plug-ins, but no render plug-ins are available (viewer-only renderers), if they meet this condition.

- The Katana USD plug-ins used to always use the default renderer as the `"target"` for the shaders. We now use `"usd"` as the renderer name for shaders which start with `"Usd"`, which includes the shading node designed for UsdPreviewSurface.

- UsdLux light shaders, such as UsdLuxDiskLight and UsdLuxRectLight, are now available for use in GafferThree nodes.

- ID 447533 - The UsdExport Output Format plug-in, which is designed to work with UsdMaterialBake nodes, has been hidden from the outputFormat parameter of LookFileBake nodes using the new `Hidden` class variable introduced in feature enhancement ID 448056 (see above).

- ID 447802 - The `USD_KATANA_ALLOW_CUSTOM_MATERIAL_SCOPES` environment variable of the Katana USD Plug-ins is now set to `true` by default. If set to `false`, this will limit material assignments to materials scoped under a Looks location.

- ID 447804 - The `USD_KATANA_ADD_CUSTOM_PROPERTIES` environment variable of the Katana USD Plug-ins is now set to `true` by default. If set to `false`, this will silently ignore custom properties.

# Bug Fixes

## API/SDK Changes

- ID 391242 - The `getInputPortAndGraphState()` method of node types implemented using `NodeTypeBuilder` were wrongly called for nodes in a disabled/bypassed state.

- ID 415459 - Developer documentation of the following functions in the `FarmAPI` Python package was wrong or inaccurate, and has been corrected:

  - `FarmAPI.AddFarmMenuOption()`
  - `FarmAPI.AddFarmPopupMenuOption()`
  - `FarmAPI.GetFarmMenuOptions()`
  - `FarmAPI.GetFarmPopupMenuOptions()`

  As part of this work, the `handle` parameter of the `FarmAPI.OpenDefaultDialog()` function has been renamed to `callback`, for consistency and clarity.

- ID 433835 - When attempting to import all names from various Python modules in Katana's codebase using wildcard imports, exceptions were raised. The following modules were affected:

  - `Nodes2DAPI`
  - `Nodes2DAPI.GradientNodeUtil`
  - `Nodes3DAPI.TimingUtils`
  - `UI4.FormMaster.ItemEditors.Number`
  - `UI4.Tabs.OSGViewerTab.ProxyLoader`

  Note: Wildcard imports in Python should be avoided. The `UI4.FormMaster.ItemEditors` Python package should not be used for new code. The `UI4.Tabs.OSGViewerTab` module is deprecated now.

- ID 442192 - When interacting with parameters on the root node that relate to region of interest, such that only a subset of ROI parameters on the root node were set, Katana crashed. The issue occurred when invoking certain ROI functions from the `RenderManager` module, e.g. `RenderManager.SetRenderUseROI()`, before creating a Monitor tab in the UI session.

- ID 442251 - When events were queued with `eventID` set as `None`, Katana's `EventModule` module wrongly processed them twice. (This issue was a regression in Katana 3.1v1. Only the Katana UI was affected.)

- ID 443480 - When attempting to use the `UI4.Util.ExternalTools` Python module without explicitly importing it first, a Python exception was raised.

## Catalog

- ID 450123 - When opening a Katana project with persistent catalog items, then starting a Live Render, then reverting the project or quitting Katana, Python exceptions occurred, and subsequent renders all failed. (This issue was a regression in Katana 3.5v1.)

## Gaffer

- ID 445018 - When a light material using a Template Material with a non-default color parameter forced the default value to be set, the GafferThree editor would show the non-default color coming from the Template Material, rather than its default color.

## Hydra Viewer

- ID 431869 - When selecting a light or camera while the Center of Interest manipulator was selected, Katana was stalling briefly before the manipulator's handles appeared. (This issue was a regression in Katana 3.6v1.)

- ID 444689 - When updating the render region of interest (ROI) during a Live Render session using Arnold while viewing the rendered image in the Viewer (Hydra) tab's Monitor Layer, the Monitor Layer overlay was wrongly squashed or stretched.

## Logging

- ID 433775 - The Python root logger was configured to suppress debugging messages by default, so they could not be turned on in Messages tabs and the View Messages popup. The Python root logger now lets debugging messages pass through to logging handlers, allowing Messages tabs and the View Messages popup to display them.

- ID 433776 - Valid conditional visibility and locking options were wrongly flagged as invalid in debug log messages. (This issue was a regression in Katana 1.1v3.)

- ID 437934 - When using the `GeoAPI.Util.GenericAppenderUtil.ParseArgsFile()` function to parse an Args File or GenericAssign XML file, warnings might have been logged about seemingly invalid attributes for `<page>` elements which did not correspond to the documented Args File schema.

## Network Materials

- ID 425396 - When setting the name of a Network Material or terminal port in a NetworkMaterialCreate node to a long names, the name was cut off at the width of the sidebar without an ellipsis indicating the cropping.

- ID 438898 - When attempting to turn the Enable Display Transform checkbox in Katana's color picker dialog on or off for color parameters of shading nodes, the state of the checkbox immediately reverted back to its previous state. (This issue was a regression in Katana 3.0v1.)

- ID 440626 - When starting Katana in an environment without 3Delight available and without setting the `DEFAULT_RENDERER` environment variable to a renderer other than `dl`, the node creation menu within NetworkMaterialCreate and NetworkMaterialEdit nodes was not showing the shading nodes available for another registered renderer, and a warning message was logged about the `dl` renderer plug-in not being available.

- ID 444738 - When editing the sceneGraphLocation parameter of a NetworkMaterialEdit node in the Parameters tab and pressing Enter whilst leaving the input focus on the editor widget, the widget wrongly replaced the sceneGraphLocation value with the path of whatever location was selected in the Scene Graph tab.

## Network Materials UI

- ID 409240 - When attempting to delete a newly-created node inside of a NetworkMaterialCreate node while it is still floating with the pointer, a warning message was logged.

- ID 431181 - When viewing the contents of a NetworkMaterial context node, e.g. a NetworkMaterialCreate node, the node creation menu (accessible using the Tab key) wrongly displayed any custom SuperTool nodes with the same styling as built-in Katana node types, which appear with a yellow border. (This issue was a regression in Katana 3.6v1.)

- ID 434474 - A passthrough port will be made in the NetworkMaterial context if the evaluation of the expression between the input and output tags of a input and output ports of matching name is true.

## NetworkMaterialEdit

- ID 441881 - Undoing certain edits in a NetworkMaterialEdit node with a Look File source material could cause the undo to fail and hence reset the Undo History, if the source material changed to no longer include the edited node.

## Performance

- ID 427164 - When changing the value of a render setting that does not affect render output paths, for example when setting the maxTimeSample parameter on a RenderSettings node, while the parameters of a Render node with a large number of render outputs were shown in a Parameters tab, a noticeable UI lag could be observed, as the render output widgets were updated unnecessarily.

  In order to facility a fix for this, a comparison function has been implemented for the attribute types provided by the `ScenegraphAttr` Python module, similar to the comparison function that previously existed for attribute types in the `FnAttribute` Python module. This means that two instances of the same type of attribute which hold the same value (for example `ScenegraphAttr.DoubleAttr(0)`) are now considered equal, whereas before they were not.

  Note: The `ScenegraphAttr` Python module is now deprecated. Please use `FnAttribute` instead.

- ID 438904 - Node names that are driven by an expression parameter are re-evaluated for every node graph parameter change (outside of a node graph parsing context). Where the number of such nodes is significant, performance can be significantly degraded, particularly in batch (scripted) operations.

  To address this, re-evaluations are now compressed. This means that an idle event or call to `ProcessEvents()` is now required in order to update node names that are driven by an expression that depends on another parameter that has changed.

## Rendering

- ID 71794 / BZ 36570 - When cancelling a Live Render, a render plug-in's `stopLiveEditing()` and `stop()` functions were not called. Instead, the render process was terminated rather ungracefully. This prevented render plug-ins from performing teardown/cleanup operations at the end of a Live Render session.

- ID 94052 / BZ 44199 - When choosing the Repeat Previous Render command from the Render menu after previously starting a render by choosing Preview Render View Node or Live Render View Node from the Render main menu or pressing their corresponding keyboard shortcuts, nothing happened. (This issue was a regression in Katana 2.0v1.)

  As part of fixing this issue, those commands are now only made available when a node has the view flag set on it, and the Repeat Previous Render command is only made available when a render has previously been started.

- ID 339293 - When starting a Batch Render of a scene without a camera present in the scene graph, a default camera was created at the origin of the scene, instead of immediately aborting the render.

  When starting a Disk Render of a scene without a camera present in the scene graph, the render was aborted only after starting up, instead of immediately aborting the render.

- ID 435008 - When using render plug-ins whose primary layer was not named as "primary" (e.g. Arnold or V-Ray), ID buffers were not correctly allocated. This prevented the Pixel Probe tool in the Monitor tab from working.

  (This issue was a regression in Katana 3.5v3. As a workaround in releases since then, users could set `KATANA_CATALOG_ALLOCATE_ID_BUFFER_PER_AOV` to `1`, enforcing the creation of the ID buffer for every AOV.)

- ID 444425 - When attempting to repeat a render that was previously started from a node that was subsequently deleted, a Python exception was raised.

- ID 445220 - When a render was aborted due to a render error, the corresponding catalog item wrongly appeared as completed instead of failed, the render process exit code was wrongly given as a very large number, and the render error node name was missing.

- ID 446588 - When `renderboot` exited abnormally, for example returning `-1`, leading to an exit code of `255`, the corresponding catalog item and render log showed a render state of "completed", instead "failed".

## Scene Graph

- ID 446117 - When Implicit Resolvers were toggled on (or off), components that use the `UI4.Util.ClientManager` class were not correctly updating their Op chain, therefore failing to apply resolvers at the correct time. For instance, this was preventing the Scene Graph tab from correctly showing deferred locations that depend on resolvers for being cooked. (This issue was a regression in the `UI4.Util.ClientManager` class that was introduced in Katana 3.6v1.)

## UI

- ID 329575 - When setting the value of a string parameter that uses the key/value mapper widget type via Python scripting to the text of a key (rather than that of the key's corresponding value), that key was wrongly shown as a valid value, even if the mapper widget was not configured with that text as a valid value.

## USD

- ID 447538 - When importing materials from USD assets via a UsdIn node, Network Material terminals were not named correctly, leading to textures and materials not loading correctly.

  UsdIn will now convert terminals to those the render plug-ins understand based on the NetworkMaterialSelector prefix.

- ID 448002 - When attempting to bake materials to USD assets using a UsdMaterialBake node, ill-formed `SdfPath` values could be generated from scene graph location paths, causing the export to fail with a Python exception being raised.

  Ill-formed `SdfPath` values created from Katana scene graph locations with unsupported characters are now validated, and unsupported characters are replaced with underscores.

- ID 448021 - When baking materials to USD assets using a UsdMaterialBake node, materials under /root/materials were wrongly written to the resulting USD file.

  Only differences between a particular input and the first input of a UsdMaterialBake node will be written to the resulting USD file now.

- ID 449449 - When baking materials to USD assets using a UsdMaterialBake node, material interface parameters with default values were not preserved.

  Material interface parameters with default values are now written to USD via `UsdExport` and UsdMaterialBake nodes.

# Known Issues

## Catalog

- ID 446840 - When changing the value of a global Graph State Variable during a Live Render, if a corresponding GSV column in the Catalog tab is shown, the value of the GSV is not updated accordingly in that column.

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

## Gaffer

- ID 456657 - Adopted Master Materials that were created in previous releases of Katana, e.g. Katana 3.6v2, are not updated to the new Template Material naming correctly, leading to warning messages being logged, and those edit packages becoming unusable. (This issue is a regression in Katana 4.0v1.)

## Hydra Viewer

- ID 456548 - Scrollbars in the Lighting Tools' parameter UI in the Viewer (Hydra) tab are overly transparent, making them hard to see and interact with.

- ID 454031 - Changes of color to the default shader, such as via ViewerObjectSettings or attributes such as geometry.arbitrary.displayColor.value will not display correctly in Solid or FlatShaded view modes. (This issue is a regression in Katana 4.0v1.)

- ID 453503 - When using UsdLuxLights to preview scene shadows in a Viewer (Hydra) tab, the shadow parameters on the light material have no effect. This means the shadow distance value can not be tweaked depending on the scene scale, such that there's always a sliver of lit scene before the shadow "starts".

- ID 452128 - Parameters whose values are driven by parameter expressions are not displayed correctly in the Lighting Tools' parameter UI in the Viewer (Hydra) tab.

- ID 447830 - Currently, USD assets with UDIM textures will not be shaded correctly in the Hydra viewport, due to lack of support for relative paths to these textures. UDIM textures will work correctly on UsdPreviewSurface materials created in Katana directly.

- ID 446725 - Katana projects set up with the previous Hydra Shaders for lights and materials are not working correctly. (This issue is a regression in Katana 4.0v1.)

- ID 444355 - Currently, the Lighting Tools' parameter UI only shows values backed by node graph parameters.

  If a light location does not represent a Light Package in the currently selected GafferThree node in the Lighting Tools' target node selection widget, but the light location provides attributes generated by a different Light Package in an upstream GafferThree node, the Lighting Tools' parameter UI will not correctly display the actual light location's attributes.

  This issue affects light locations that use an adopted Template Material, but that do not have a Light Edit Package in the same GafferThree node.

- 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 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 84019 / BZ 40599 - Parameters that are added to LiveGroup nodes are wrongly discarded when performing a reload from source, leading to loss of data.

- 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 446721 - When using a single (non networked) material location to define simple UsdPreviewSurface parameters, the utility shaders needed for Network Materials are also included in the dropdown list. Picking these causes an invalid material that would not render correctly in the Hydra Viewer.

- 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 438255 - When a filter is active in a NetworkMaterial sidebar, its pages cannot be expanded or collapsed.

- 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 427353 - NetworkMaterialEdit nodes support editing of network materials that were created by NetworkMaterialCreate nodes only, not network materials that were created with legacy shading nodes in the classic node graph context.

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

- ID 410474 - In a NetworkMaterialCreate context, shading nodes appear to shake during view state changes if the node's width is adjusted.

- 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 442994 - When rendering with Katana Queue agents using 3Delight, additional, empty 3Delight Display windows may be spawned, even though all the rendered images are contained correctly in a single 3Delight Display session.

- 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 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 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 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 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 455245 - When entering a NetworkMaterialEdit node that targets a Network Material that was exported and imported via USD, connections from a contained UsdPreviewSurface node to the terminals in the right-hand sidebar are not established correctly.

- ID 453348 - When importing a USD file thats been exported via `UsdExport` with child materials, the child material is not bound correctly on input. For example, the materialAssign attribute on a bound location is updated from NetworkMaterial1_material1 to NetworkMaterial1/material1 (as it was before it was exported), but the location of the material in the scene graph is still NetworkMaterial1_material1. This means the location is unbound and produces incorrect rendering results; breaking the round trip.

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

- ID 446728 - When clicking the Write button of an edited UsdMaterialBake node that is not connected to an input scene, a Python exception is raised.

## Miscellaneous

- ID 337653 - Katana logs deprecation warnings when loading the `PyMockAsset`, `PyMultiMockAsset`, and `PyMockFileSeq` shipping example Asset API plug-ins.

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

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