Contact Support

Katana 3.1v1 Release Notes

Release Date

20 November 2018

Previous Releases

• Katana 3.0v8 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 3.1

These release notes describe changes from Katana 3.0v6 to 3.1v1.

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

Feature Enhancements

Qt

As part of Katana 3.1, we have updated the version of Qt used by Katana from 4.8.5 to 5.6.1, as specified in the VFX Reference Platform CY2017. This means that any UI plugins that utilize Qt should be updated. These changes are detailed below:

• Any Qt widget that opted in to Katana's 'key-based-dragging' protocol must be updated as follows. Previously, Katana would emit a dynamic PyQt keyBasedDragRequested signal from a widget when the user hovered the mouse over it and pressed Ctrl+B. As of Katana 3.1, your widget must instead override the customEvent() method to handle QT4Widgets.GlobalEventFilter.KeyBasedDragEvent Qt events. A widget should accept the event, and initiate a drag using a QT4Widgets.InteractiveDrag object.

• Any Qt widget that previously set a Python attribute of drawInteractiveHighlight to False should now set a boolean QObject property of the same name instead. This property allows a widget to opt out of the standard highlight effect Katana applies to a target widget of a drag-and-drop operation.

• Any Qt widget that previously set a Python attribute of STOP_GLOBAL_SCROLLING or SKIP_GLOBAL_SCROLLING should now set a boolean QObject property of the same name instead. This property allows a widget to opt out of Katana's default 'global scrolling' behaviour, initiated by holding Alt and dragging with the middle mouse button while the cursor is over a QScrollArea-based widget.

Performance

• The performance of application startup, user interface, and idle CPU usage was improved by dispatching more Qt events in C++ instead of Python.

• The Catalog tab now uses push-based events to update the display. The number of render draw events that are buffered before an event is pushed can be controlled by the environment variable KATANA_CATALOG_RECT_UPDATE_BUFFER_SIZE. The default value is 256.

• A number of Katana's polling mechanisms have been optimized to use an event-based system as opposed to continuously polling for state changes in certain flags. This has lead to a noticeable reduction in idle CPU usage when running in UI mode.

• TP 247799 - The amount of computation triggered by calls to the Geolib Runtime Client setLocationsOpen() and setLocationsOpenRecursive() functions, where many locations are watched, was significantly reduced.

  A substantial effect of this change is a reduction in completion time of a recursive expansion triggered by one UI element, typically the Scene Graph tab, that is also applied to another, such as a Viewer tab.

• TP 253458 - The Alembic_In node type and associated Op type now use a modified Alembic library to read Ogawa-format Alembic files using memory-mapped I/O. This allows faster reads in general, and better multi-threaded performance with fewer locks.

  An environment variable named KATANA_ALEMBICIN_DISABLE_MMAP has been added that, if set to 1 or true, disables this memory-mapped I/O extension, in which case Alembic_In reverts to using file streams to read Alembic files.

• The performance of the Katana event system was improved. During a UI session, Katana now makes use of Qt's built in event loop to dispatch its application specific events. This provides a number of benefits partly resulting from the use of a performant priority queue and the ability to indicate a priority level for a given event.

  As a result of these changes, during UI sessions, collapsed event handlers will now only ever be called with a single event. If event buffering is required on the consumer side (for example, for performance reasons), then buffering should be implemented in the consumer.

Hydra Viewer

• The Viewer API has been reworked to add support for a single OpenGL context, shared between all the Viewports. The ViewportWidget class now inherits from QWidget.

• The Hydra Viewer now supports display of object annotations, which can be added via ViewerObjectSettings nodes.

• Ambient occlusion in the Hydra Viewer has been improved to better utilize the OpenGL resources.

Other Feature Enhancements

• A new advanced.mergeGroupAttributes parameter has been added to Merge nodes, which can be used to specify group attributes which should be merged from the different input scenes. This can be used to merge different types of materials, or materials for different renderers, for example.

Bug Fixes

Hydra Viewer

• TP 342503 - Changes to the viewerHydra/antiAliasing preference did not effect already-open Viewer (Hydra) tabs.

• TP 356083 - Katana crashed when a Viewer (Hydra) tab was initialized before any other OpenGL-based tab.

• TP 351330 - The Hydra Viewer did not correctly initialize when using RenderMan 22.0.

• TP 358293 - Katana crashed when attempting to close, or quitting a Katana UI session that contained, a hidden Viewer (Hydra) tab in its layout of panes.

• TP 364947 - When viewing objects with authored normals in the Viewer (Hydra) tab, the Flat Shaded option did not render correctly.

• TP 366425 - When geometry was updated, all of the geometry with scene-provided normals was queried for its points. This was wasteful and detrimental to performance.

UI

• TP 71954 / BZ 36663 - It was not possible to sort notifications in the Notifications popup window.

• TP 345580 - Passing a Python exception tuple as the exc_info parameter of logging.log() (and related functions) did not always result in the log record in Katana's Messages tab displaying the exception's text and traceback.

Performance

• TP 249655 - A new class ConstVector has been introduced as part of the PyFnAttribute module. Both getData() and getNearestSample(float), whose previous return type was list, have been reimplemented to return this new type. Unlike list, ConstVector is immutable. This new type is a wrapper for the Geolib's C++FnConstVector classes, and provides an alternative, faster way of retrieving the attribute's values at a given sample time without constructing a list that could take a long time.

• TP 334348 - Flushing caches did not reclaim all memory used by Geolib3's scene data store.

• Geolib3's scene data store did not release memory for deleted Ops until they were reused. This memory is now reclaimed when committing the next transaction.

• TP 197934 - OpScript can now inspect and create attributes with more than 2²⁷ values per time sample using a new getSamples() method; available on any data attribute. The 'sample accessor' object returned by getSamples() supports inspecting a read-only view of time sample data, as well as creating a mutable copy of a sample buffer in order to manipulate the existing data. Full documentation is available in the Katana Developer Guide, but a contrived example is as follows:

  local myIntAttr = Interface.GetAttr('myAttr')
  
  local newSamples = {}
  for _, sample in ipairs(myIntAttr:getSamples()) do
    -- Create a mutable copy of the sample buffer
    local buffer = sample:toArray()
    for i, elem in ipairs(buffer) do
      buffer:set(i, elem * 2)
    end
  
    local t = sample:getSampleTime()
    newSamples[t] = buffer
  end
  
  Interface.SetAttr('myAttr', IntAttribute(newSamples))
  

  For backwards compatibility, myDataAttr:getNearestSample(time) continues to return a copy of a time sample as a Lua table, and is subject to a maximum of 2²⁷ values. Please note that the getSamples() API requires the new LuaJIT-based OpScript backend, and is not available in the legacy Lua 5.1 backend.

• TP 350291 - OpScript: calling tostring() (or print()) on an attribute with more than 2²⁷ values resulted in a 'table overflow' error being raised.

• TP 344932 - Flushing caches did not clear Katana's image header cache.

• TP 346628 - The performance of the 2D node subsystem, when no rendering jobs are active, was improved. Note that this change also decreases CPU usage in batch renders.

Multisampled Parameters

• TP 262569 - AttributeSet and AttributeEditor nodes, as well as TransformEdit nodes (used by edit packages of the GafferThree SuperTool, and other PackageSuperToolAPI-based SuperTools) now support multisampling.

  TransformEdit nodes now generate multisampled transforms where appropriate, and respect incoming multisampled transforms. Their parameter UI now displays incoming transform values sampled at frame-relative time 0.0 precisely, rather than values from existing samples nearest to it.

  The new multisample parameter of AttributeSet nodes (which are used internally by AttributeEditor nodes) can be used to disable multisampling. To preserve the behaviour of existing (upgraded) nodes, they are configured with multisampling disabled, while newly-created nodes allow multisample support by default. Note that the AttributeEditor node's parameter interface does not currently expose the multisample parameter for its edits.

  The NodeTypeBuilder.buildAttrFromParam() function now respects number type specifier parameters (string parameters of the form '__type__[siblingParameterName]', with a value of 'IntAttr', 'FloatAttr' or 'DoubleAttr'). It is also now faster, notably for large groups, as it wraps C++ functions that may also be used directly from NodegraphAPI.

  The NodegraphAPI module has been extended with the following utility functions:

  GetSampleTimes(shutterOpen, shutterClose, maxTimeSamples, useSinglePrecision=False)
  GetSampleTimesFromGraphState(graphState, useSinglePrecision=False)
  
  GetSingleSampleTimeFromGraphState(graphState)
  
  IsParameterConstant(parameter)
  
  BuildIntAttrFromNumberParameter(parameter, graphState=None, multisample=False)
  BuildFloatAttrFromNumberParameter(parameter, graphState=None, multisample=False)
  BuildDoubleAttrFromNumberParameter(parameter, graphState=None, multisample=False)
  BuildAttrFromNumberParameter(parameter, graphState=None, multisample=False, attrType=FnAttribute.FloatAttribute)
  BuildAttrFromStringParameter(parameter, graphState=None, multisample=False)
  BuildAttrFromGroupParameter(parameter, graphState=None, multisampleDefault=False, numberAttrTypeDefault=FnAttribute.FloatAttribute, includeEmptyGroups=False, groupInherit=True)
  

  For further information, inspect using the Python help() function.

  GetSingleSampleTimeFromGraphState() is provided as a means to unify behavior for single-sampled, time-varying parameters, being equivalent to taking the first (and only) sample returned by GetSampleTimesFromGraphState() if the graph state has maxTimeSamples of 1. See GetSampleTimes() help for details.

• TP 358791 - TransformEdit nodes (used by GafferThree edit packages) produced incorrectly interpreted valid incoming transforms whose component order (transform order, rotation order, or both) differed from that used by the node (i.e. 'Scale Rotate Translate' and the given rotation order). Such transforms are now converted for the output order, such that a TransformEdit node with no parameter overrides does not alter the effective transform.

• TP 365348 - The uniformScale parameter of Transform3D nodes was sampled at a time incorrectly offset by shutterOpen. This affected only time-varying (curve or time-dependent expression) uniformScale parameters, and only where render settings shutterOpen is non-zero.

Other Bug Fixes

• TP 350224 - FnAttribute and PyScenegraphAttr's getHash64() method returned different hash values on Windows and Linux. It now returns the same value on both platforms.

• TP 345913 - When the number of rendering threads was set to use the system's default number of threads, an exception was raised.

• TP 352396 - Plug-ins that made use of the Viewer Delegate API were triggering a crash unless they were rebuilt after a plug-in suite upgrade.

• TP 360361 - When a matching '/root' collection is also defined at the Look File baking root, the original '/root' collection took precedence over the the baked 'root' collection.

• TP 364380 - Several modules in Katana were making use of isinstance(..., list) to determine whether a given object was a sequence. This issue was discovered when the ConstVector type was introduced. The fix consists of using collections.Sequence or collections.Iterable to determine whether something is a sequence or an iterable.

• TP 335066 - The ShadowManager example SuperTool is no longer relevant and was removed. (It demonstrated managing render passes for rendering shadow maps in the old PRMan Reyes architecture.)

• TP 351317 - ViewerAPI-based viewers sometimes presented a low refresh rate. After some recent performance improvements, the frequency of the event_idle event in Katana was reduced from 72 Hz to 24 Hz. Viewers were bound to that refresh rate to repaint viewports when they are dirty, which is too slow for interaction. The fix consists of adding a separate, specific timer with a higher refresh rate.

• The Example Viewer was not using OpenGL resources efficiently and has been updated to take better advantage of the Viewer API.

3Delight

Documentation

• The ViewerModifier page in the Katana Developer Guide was moved to sit within Legacy, to reflect the outdated nature of its content.

• The Developer Guide now shows library versions used by Katana 3.1.

• Katana now supports creating attributes with 2³² or more values per time sample, and error handing relating to internal size limits has been made more robust. Previously, Katana could crash or generate malformed attributes if certain internal limits were breached, and there was no formal documentation for these limits. Internal data limits of FnAttribute (which are now documented in the C++ headers) are as follows:

  • DataAttribute (int, float, double, string):
    • value count (per time sample): [0, 2⁶³]
    • time sample count: [0, 2¹³]
    • tuple size: [0, 2¹⁶]
  • GroupAttribute
    • child count: [0, 2²⁸]

• Documentation was added to the Batch Rendering topic regarding the new --var argument.

• TP 370343 - The Katana Developer Guide included references to both QGLWidget and the incorrect QGlWidget. These references have now been updated or removed.

• TP 371060 - The Katana Developer Guide contained references to the legacy QtGui module. These have now been updated or removed.

Example Projects

• TP 370884 - The Secondary Images (AOVs) (RenderMan) example project was wrongly set to render with 3Delight in a RenderSettings node.

• The Hello Pony example project has been updated to use the new dlPrincipled shader on the material node.

Third-Party Libraries

Known Issues

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