Katana 3.5v1 Release Notes

Release Date

19 December 2019

Previous Releases

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 3.5

These release notes describe changes from Katana 3.2v3 to 3.5v1.

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

New Features

  • Geolib3-MT: This is the evolution of Geolib3 - Katana’s scene graph processing engine - to provide native multi-threaded scene graph expansion. The goals of the just as a Geolib3-MT project are:
    • To fully utilize the resources available on modern multi-core systems.
    • To provide shared, intelligent caching technology to better manage memory resources during scene graph traversal.
    • To reduce time-to-first-pixel (TTFP), allowing artists to efficiently iterate on shots and receive timely feedback.
    • To improve artist productivity through improved UI performance.
  • Analysis & Profiling Tools are provided, which help users debug the most time-costly Ops in a given Katana session.
  • Optimized Key Workflows, improving performance of scenes where large numbers of locations are created.
  • We now build and ship USD plug-ins based on USD 19.11, including the USD node types with some minor changes, as an opt-in set of resources in the plugins/Resources/Usd/ directory as part of a Katana installation. Documentation for how to opt into the USD plug-ins has been added to the Katana Developer Guide in form of the new Writing Plug-ins > Katana USD Plug-ins section. That section also outlines the differences between the USD plug-ins that now ship with Katana from those shipped in the Pixar USD repository.
  • The experimental Monitor Layer feature is now integrated in the Viewer (Hydra) tab and can be turned on and off via a toggle button, menu item, or keyboard shortcut (`). The Monitor Layer allows you to see a render overlayed onto the scene shown in the viewer.
  • A new mode for optimizing the launch of the renderboot process that hosts the render plug-in has been added to Katana's batch mode, which can be turned on by passing the new --reuse-render-process command-line option to the Katana executable (in addition to --batch). When running Katana in batch mode with this option turned on, multiple frames will be rendered with a single instance of renderboot hosting the render plug-in, rather than launching a new renderboot process for every frame. Using this option can greatly improve performance of rendering sequences of frames, as the render plug-in and all other Katana plug-ins don't have to be reloaded for every frame.

Feature Enhancements

Performance

  • The following methods have been added to the Plug-ins API:

    void Foundry::Katana::FnScenegraphIterator::finalizeRuntime();
void Foundry::Katana::GeolibRuntime::finalize();

    Render plug-ins can invoke finalizeRuntime() to free the resources that the Geolib3 Runtime may have allocated during scene traversal. Invoking the function invalidates all iterators associated with the iterator's Runtime. The function should be invoked after scene traversal has been completed.

  • In order to aid in debugging scene graph traversal and to help gather performance statistics, the scenewalker command-line tool now ships in the bin folder of the Katana installation directory:

    Usage: scenewalker [OPTION]... FILE...
Cooks the scene graph produced by the Op Tree loaded from FILE, and traverses
the scene as quickly as possible, optionally using multiple threads.

Examples:
scenewalker optree.optree                # Evaluate optree.optree using 1 thread.
scenewalker --threads=4 optree.optree    # Evaluate optree.optree using 4 threads.
scenewalker --verbose optree.optree      # Print each location and its type

Options: 
  --help                Show this help.
  --location arg        If specified, evaluate only this scene graph location.
  --print-attributes    If specified, prints a location's attribute data.
  --verbose             If specified, prints additional information about the 
                        cooking process.
  --profile arg         If specified, output runtime profiling data to the 
                        given path.
  --threads arg (=1)    Number of threads available for scene graph traversal.
  --optree arg          File path of Op tree to evaluate.

    The scenewalker command-line tool is documented in the Katana Developer Guide as well.

  • The ScenegraphXml Op has been improved to support cook() calls from multiple threads.

  • The FnAttribute Python API and Lua Attribute APIs have been extended with an additional function, GetTotalSize(), which returns the total memory currently allocated by the FnAttribute library in bytes.

  • A new render command named Preview Render with Profiling has been added to the context menu of Render nodes, in a new section named Profiling Renders. This command starts a Preview Render while gathering timing and memory consumption information about the render and writing it out to a JSON file.

    The JSON file contains the following information:

    • Basic information about the render, including the renderer name, render method name, and some key environment variables.
    • Total CPU time (in seconds), memory usage (in bytes), and wall clock duration (in seconds) for the render.
    • A list of all Ops that ran during scene traversal, with their corresponding node graph node names and node types, and how much CPU time/memory they contributed to the overall totals.

    By default, the JSON file is written to Katana's temporary directory, with a filename pattern matching profile_<renderer-name>_<render-method-name>_<timestamp>.json.

    The JSON file can be saved to an alternative directory by setting the --profiling-dir command-line option to a desired target directory.

    The profiling report is written when a renderer plug-in calls the new finalizeRuntime() method on the root scene graph iterator obtained via getRootIterator(), or after the render completes if the renderer plug-in does not call finalizeRuntime().

  • The memory allocator used by the Lua interpreter for OpScript.Lua Ops has been changed to a scalable allocator in order to improve OpScript evaluation performance in multithreaded evaluation contexts, reducing cook time.

  • Geolib3-MT includes a number of settings to control the behaviour of the caching subsystem. The caching subsystem is responsible for the storage and retrieval of previously cooked scene graph locations, known as cook results. These settings can be modified from RenderSettings nodes on a project-by-project basis. Sensible defaults have been provided based on testing against production-scale scenes. Further information about each of the settings is provided below:

    • sceneTraversal.cache.cacheEviction - turned on by default. If turned off, no cook results will be evicted from the cache. Whilst initially it might seem counter-intuitive to disable cache eviction, there may exist some scenes where this is appropriate. In particular, when the size of the scene and data structures required by the renderer can comfortably fit into available memory; even larger scenes could benefit to some degree, as once the scene generation phase of rendering is complete, the memory pages occupied by Geolib3-MT's cook results will no longer be accessed and hence be eligible for paging to disk, as these pages won't be re-paged to main memory during rendering, the performance penalty is minimal.
    • sceneTraversal.cache.cacheSoftLimit - if cache eviction is turned on, the soft limit governs how many cook results will be stored in local caches before entries are evicted using a least-recently used eviction policy. Note: Whilst these entries may be evicted from a local cache, they may be shared amongst a number of other local caches or the central (shared cache), in which case the entries' memory won't immediately be reclaimed.
    • sceneTraversal.cache.collectionFrequency - if cache eviction is turned on, the collection frequency governs the time (in milliseconds) between collection cycles. During a collection cycle, Geolib3-MT will gather all cache entries evicted since the previous collection cycle, and if the cook result is no longer used, evict and reclaim the memory for the cook result.

    Notes

    Caching, and the trade-off between memory usage and time-to-first-pixel can have a significant impact on the performance of scene traversal time and rendering. Using the settings provided by Geolib3-MT, it's possible to tune the memory footprint during the scene traversal phase of rendering. Here are some considerations when deciding to experiment with these settings:

    • Consider the maximum depth of the scene graph and Op tree: the cache soft limit controls the size of the recently-used cook results on a per-thread basis. This means any locations cooked on a particular thread or, any locations accessed during the cooking process (such as via getAttr()) will be stored in the local cache and subject to eviction based on the value of sceneTraversal.cache.cacheSoftLimit.
    • Reducing the collection frequency interval will cause more aggressive eviction of cook results leading to a reduced memory footprint, but potentially at the cost of scene traversal time.

  • Geolib3-MT does not impose a restriction on thread-unsafe Ops and respects the value set during an Op's setup() call to GeolibSetupInterface::setThreading(). Thread-unsafe Ops will cause the Geolib3-MT Runtime to acquire the Global Execution Lock (GEL), which may reduce the performance of scene traversal when rendering with multiple threads.

  • Several optimizations across a number of APIs were made:

    • Optimized FnScenegraphIterator::getChildByName() by reducing the number of std::string allocations.
    • Optimized FnXFormUtil::CalcTransformedBoundsAtExistingTimes() to scale better to many threads.
    • Optimized several internal functions in libFnGeolibProducers.so, which improves efficiency of various functions in the user-facing libraries FnScenegraphIterator and FnGeolibServices.

  • The performance of the Scene Graph tab when expanding locations with many children has been improved.

  • The performance of the HierarchyCopy Op has been improved slightly, by reducing the number of std::string allocations.

  • If the sceneTraversal.opTreeOptimizations render setting is turned on, Geolib3-MT will now collapse chains of ConstraintSetup Ops into a single Op, reducing the required memory footprint.

  • TP 417079 - The handling of FnAttribute objects during scene traversal has been improved, resulting in reduced memory consumption and scene traversal times.

  • The geolibRuntime parameter was added to RenderSettings nodes, which can be used to select which Geolib3 Runtime to use for scene traversal as part of rendering a scene. If set to Geolib3-MT, the new multithreaded Runtime distributed with Katana 3.5 will be used; if set to Classic, the Runtime distributed with Katana 3.2 will be used. The default value is Geolib3-MT, which is the recommended Runtime.

USD

  • The USD plug-ins that now build and ship with Katana have been upgraded to USD 19.11. They include the USD node types with some minor changes, as an opt-in set of resources in the plugins/Resources/Usd/ directory as part of a Katana installation. Documentation for how to opt into the USD plug-ins is available in the Katana Developer Guide in form of the Writing Plug-ins > Katana USD Plug-ins section. That section also outlines the differences between the USD plug-ins that ship with Katana from those shipped in the Pixar USD repository.

  • The Viewer (Hydra) tab has been upgraded to use USD 19.11 and the renamed hdStorm as the GL render delegate.

Network Material UI

  • In the NetworkMaterialCreate context, Shift+Middle-Click drag now allows the user to drag references to specific ports into other tabs, such as the Python tab.

  • While hovering over an existing connection inside of NetworkMaterialCreate nodes, the dot key [.] can now be pressed in order to create a Dot node in between the connected ports.

Monitor Layer in Hydra Viewer

  • The environment variable KATANA_EXPERIMENTAL_MONITOR_OVERLAY is no longer used. The Monitor Layer feature is now an experimental feature of the Viewer (Hydra) tab and can be turned on and off via a toggle button, toggled menu item, or keyboard shortcut (`).

  • The Ignore Alpha toggled menu item has been added to the View > Monitor Layer Options submenu in the Viewer (Hydra) tab, to allow users to control whether or not to ignore the alpha channel from the rendered image when displaying the Monitor Layer as a layer on top of the GL preview.

  • A new Viewer Delegate Component and Layer were added to draw the wireframe of selected locations on top of the Monitor Layer.

  • The image to be displayed in the Monitor Layer is no longer transmitted via a file on disk. A Frame Buffer wrapper is used that allows to keep all the data in memory and improve performance notably.

  • TP 405921 - In a Viewer (Hydra) tab, the Face Selection mode has been deactivated while the Monitor Layer is in use.

  • A menu button for choosing a particular AOV to display in the Monitor Layer has been added in a Monitor Layer toolbar that is shown when the Monitor Layer in a Viewer (Hydra) tab is turned on. The functionality of this new AOV control is similar to the existing layer selection menu label of Katana's Monitor tab.

  • A tool button for toggling the use of a LUT has been added in a Monitor Layer toolbar that is shown when the Monitor Layer in a Viewer (Hydra) tab is turned on. Next to the tool button, a menu button allows users to choose a particular LUT to apply to the rendered image that is shown in the Monitor Layer. The functionality of these new LUT controls is similar to the existing filmlook visualization menu label of Katana's Monitor tab, and similar to the View Transform toggle button in Mari's View Transform toolbar.

  • When activating the Monitor Layer in a Viewer (Hydra) tab, the viewer camera will automatically switch to that of the active render camera.

Reusing the Render Process in a Batch Render

  • A new mode for optimizing the launch of the renderboot process that hosts the render plug-in has been added to Katana's batch mode, which can be turned on by passing the new --reuse-render-process command-line option to the Katana executable (in addition to --batch). When running Katana in batch mode with this option turned on, multiple frames will be rendered with a single instance of renderboot hosting the render plug-in, rather than launching a new renderboot process for every frame. Using this option can greatly improve performance of rendering sequences of frames, as the render plug-in and all other Katana plug-ins don't have to be reloaded for every frame.

    NOTE: Render plug-ins have to be recompiled against the Katana 3.5v1 Rendering API in order to support the --reuse-render-process command-line option in batch mode.

  • Some new functions named setup(), cleanup() and setRootIterator() have been added to the RenderBase class for renderer plug-ins in the plugin_apis/include/FnRender/plugin/RenderBase.h header. These enable render plug-ins to render multiple frames in a single instance instead of creating a new instance of the plug-in for each frame.

  • The -t command-line argument of the Katana application is now forwarded to the renderboot process. The value will typically match the -renderTime value (also present in the command), except when --reuse-render-process is used, in which case, all the frame ranges will be given to renderboot, for rendering all frames within the same process instance.

Katana Developer Guide

  • A Performance Optimization Guide has been added to the Katana Developer Guide, describing ways to profile and optimize Katana projects.

Other Feature Enhancements

  • TP 55592 / BZ 27736 - A new -V / --verbose command-line option for controlling the level of verbosity of logging informational messages has been added to the Katana executable:

      -V LEVEL, --verbose=LEVEL
                        The level of verbosity of logging informational
                        messages. Defaults to 1. Set to 0 to suppress most
                        informational messages.

  • TP 79226 / BZ 38513 - When a Katana project containing persistent catalog items with multiple AOVs was saved, and then reloaded, the persistent catalog items would be missing all the AOVs, except the default/primary one.

  • TP 127707 / BZ 51541 - LiveGroupStack nodes have been deprecated, and are no longer available in node creation menus of the Node Graph tab. (They can still be created from scripting contexts, and projects containing LiveGroupStack nodes continue to work as before.)

  • TP 231121 - The Geolib3 Runtime API now provides the getNodeName() and getNodeType() functions, which return the name and type of the Katana node that created a given Op. The value returned will be "_NoName_" or "_NoType_" if the Op was not created by a node (for example appended as a terminal Op instead).

  • TP 409366 - The level of verbosity specified using Katana's --verbose command-line option is now forwarded to the renderboot executable in its new -verbose command-line option.

  • The UI of GroupStack nodes (including InteractiveRenderFilter and RenderFilter nodes) has been revised to make better use of spacing.

  • Ambient Occlusion has been removed from the GL Hydra Viewer.

  • The keyboard shortcuts for cycling through available AOVs in the Monitor tab and the Viewer (Hydra) tab, while the Monitor Layer is active, have been changed to the following:

    • Shift+PgUp selects the previous available AOV.
    • Shift+PgDown selects the next available AOV.
    • Shift+Home toggles between the default and a previously selected AOV.

  • 3Delight has been upgraded to version 1.6.21. For more information, refer to the 3Delight Cloud Changelog.

Bug Fixes

Network Material UI

  • TP 386412 - Creating multiple shading nodes via the Tab menu in a NetworkMaterialCreate context would naively auto-connect them, despite the connection usually being invalid and unwanted.

  • TP 386963 - The Display As Dot checkbox of Dot nodes had no effect on the appearance of Dot nodes within NetworkMaterialCreate nodes.

  • TP 405898 - Clicking in the hit box of a shading node's Filter would focus it even if the hit area was hidden behind another node.

  • TP 416297 - When hovering over the connection of a selected node in a NetworkMaterialCreate node, and pressing the Delete key to delete the node, Katana crashed.

  • TP 416306 - When creating nodes inside of a NetworkMaterialCreate node, the new nodes could briefly appear away from the pointer position.

Other Bug Fixes

  • TP 402004 - When the Viewer (Hydra) tab was opened in a system where OpenGL 4 was not supported, Katana would crash.

  • TP 408141 - When starting a Disk Render, the value for the -sequenceID argument of the renderboot executable was passed as None instead of the ID of the catalog item that represents the Disk Render.

  • TP 409386 - The parameter UI of GroupStack nodes (including InteractiveRenderFilters and RenderFilter nodes) did not respect the locked state of edited nodes.

  • TP 412074 - When attempting to kill an external render that no longer exists, Katana would incorrectly kill the last render (Linux), or crash (Windows).

  • TP 412369 - When Katana was launched as a different user on Windows, detached processes would fail to start. This was affecting Katana's cleanup process (katanaCleanup.exe), as well as external render processes. Also, running Katana as a scheduled task would cause the same issues.

  • TP 417167 - In the Network Material Create context, attempting to collapse multiple nodes that share an upstream connection into a Shading Group caused a Python Error to be printed to the console, and in some cases, also caused Katana to crash.

Known Issues

Hydra Viewer

  • TP 418289 - When launching Katana with a layout which contains a Viewer (Hydra) tab, that was saved with the Monitor Layer turned on, an invalid camera warning is printed to the terminal.

  • TP 418273 - GL ERROR warnings can be printed to the terminal when using the Monitor Layer when custom Crop Window attributes are present.

Live Groups

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

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

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

  • TP 84019 / BZ 40599 - Parameters that are added to LiveGroup nodes are wrongly discarded when performing a reload from source, leading to loss of data.

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

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

Materials

  • TP 410474 - In a NetworkMaterialCreate context, shading nodes will appear to shake during ViewState changes, if the node's width is adjusted.

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

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

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

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

Parameter Expressions

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

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

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

Qt 5

  • TP 356345 - Partially covering the Hydra Viewport with a floating tab will cause it to repaint continuously.

Rendering

  • TP 418940 - When pressing Ctrl+Shift+P or choosing the Render > Live Render View Node command from Katana's main menu in order to start a Live Render from the first node with the view flag, nothing happens.

  • TP 410428 - When starting a debug output render by choosing the Debug > Open [renderer name] [file extension] Output in External Editor command in the context menu of a node, an exception is raised. (This issue was a regression in Katana 3.2v1.)

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

  • TP 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 does not affect Linux, where a bundled 3Delight installation is tied to its corresponding Katana installation.

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

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

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

  • TP 94052 / BZ 44199 - The Repeat Previous Render menu command only works on renders started from a 3D node's context menu.

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

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

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

Widgets

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

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

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

Miscellaneous

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

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

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

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

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

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

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

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

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

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