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

# What's New in Katana 7.5

This document describes notable changes introduced in Katana 7.5:

# USD Native Exporting

Exporting from USD is now possible in Katana. The core of exporting from the native USD stage is built around two new native USD nodes: UsdLayerDefine and UsdLayerExport.

- The UsdLayerDefine node acts as a start point for the exported layer. Stage changes between this node and the connected UsdLayerExport node are exported as a whole.
  - If a layer is specified in the asset parameter, it serves as the base from which the exported USD information is composed into with the goal of replacing that layer in a subsequent composition.
  - It is a requirement to be the only node connected to the first (left) input of the UsdLayerExport node as it also acts as a break point for where to start recording the USD changes.
  - If this node has no layer set on its asset parameter, the base layer is an empty layer.
- The UsdLayerExport node is used to export a USD layer. It comes with a variety of different parameters including: a toggle to read in your previously exported layer, the ability to choose a desired file type, time related settings, export options, and several options for setting up layer metadata.
  - To load in the exported USD layer, enable the useExported checkbox. This is particularly helpful for performance improvements or comparing against an exported layer.
  - Multiple export methods are supported, such as 'Keep Composition Arcs', 'Flatten Sublayers' and 'Flatten All'.

Setting up the export process can be done by placing down a UsdLayerDefine node, a UsdLayerExport node and connecting the UsdLayerDefine's output port to both inputs on the UsdLayerExport node. Any additional stage manipulation that happens on the right branch forms the export layer and the left branch should remain empty.

Additionally, to collapse a selection of nodes into a new UsdLayerExportGroup node through the Node Graph tab's menu option Edit > Collapse Selected Nodes to UsdLayerExportGroup. This automatically connects the selection between UsdLayerDefine and UsdLayerExport nodes while their respective parameters are promoted to a newly created UsdLayerExportGroup node. This allows for node graph organization and access to export settings without having to dive into the node network. The UsdLayerExportGroup node can also be created by more traditional means.

Two new shelf scripts have also been added to quickly enable or disable the useExported toggle on all UsdLayerExport nodes in the project.

Finally, A new UsdLayerExporter Plug-in system has been added to provide access to the USD layer prior to exporting. This can be used for modification, validation, or performing any action on the layer in memory before exporting. More information is available in the Developer Guide under Usd Processing Engine > UsdLayerExport, with examples in: `<KATANA_ROOT>/plugins` and available through a new KATANA_RESOURCES subfolder, `/UsdLayerExporterPlugins.`

Note: See Native USD Layer Export, UsdLayerDefine, UsdLayerExport, UsdLayerExportGroup.

# KatanaToUSD

Katana completes its USD roundtrip toolset with the addition of the KatanaToUsd node. Together with the UsdToKatana node, Katana workflows can be fully leveraged alongside USD. The KatanaToUsd node converts Geolib data to USD data without the need to bake out layers.

This node supports all types of material conversion, including those created and/or edited within the Material, NetworkMaterialCreate and NetworkMaterialEdit nodes. Additionally, lights are converted to its USD counterpart, as long as a matching shader identifier is found in the USD shader registry.

The KatanaToUsd node converts all mesh types to USD data, including subdivided meshes. FaceSets are converted to its USD equivalent; UsdGeomSubsets. Additionally, conversion of sampled information is also supported, such as multi-sampled and time-sampled attributes.

The KatanaToUsd node allows for generic conversion of Katana to USD attributes, to allow the transfer of custom attributes. Further information on this, as well as the attribute convention can be found in the developer guide, under `<KATANA_ROOT>/docs/dev_guide/UsdProcessingEngine/KatanaToUsd/index.html`.

The KatanaToUsd node provides several options including:

- ignore: This is used to skip over the paths defined on this parameter, to be ignored during the conversion process over to USD data.
- options > PrimitiveTypes > grousAsXforms: When enabled, group location types are defined as Xform Prims. When disabled, the locations are defined as Scope Prims, which do not contain transform attributes.
- options > Camera: Both perspective and orthographic cameras can be converted. However, attributes not present in Geolib's convention for cameras, such as focal length are set to a default value when saved to info.usd. The default value for focal length is 50mm. Additionally, this page contains two options:
  - focalLengthUnitScate: Scale for the focal length. Only applies when a perspective camera is being converted. Set to 1 by default.
  - apertureUnitScale: Scale for aperture. Only applied when an orthographic camera is being converted. The USD standard unit for aperture is millimeters. Set to 1 by default.
- options > Materials > onlyConvertIfMaterialExists: When enabled, the material assignments are not carried over to USD prims if the target material doesn't exist.
- options > Lights > lightListLocation: This option defines the location path in which the light list attributes are set. If none is specified, no light list information is written.

Note: the KatanaToUsd node currently supports the Prim types mentioned above as well as custom Prim Decorators.

Note: See Conversion Nodes - KatanaToUsd/ UsdToKatana, KatanaToUsd.

# Pattern Based Collections

- Bringing the power of CEL to Katana's Native USD space with Pattern-Based Collections.

  Pattern-Based Collections was introduced in USD 23.11 and is now fully integrated into Katana, with the addition of a new Pattern-Based Collection (PBC) widget and the UsdCollection node.

  A new PBC widget has been added to the relevant USD nodes in Katana, such as the UsdActiveSet, the UsdVariantSet, the UsdRelationshipSet nodes and many more.

  Similar to Katana’s pre-existing Collection Expression Language (CEL), USD’s Pattern-Based Collections (PBC) includes the following functionality:

- Paths, Collections and Custom statements are used as inputs
- When multiple statements are set, additional options are provided to determine the relationship between them, such as Union, Difference, Intersect, and Complements.

Note: For a full overview of supported Pattern-Based Collection Expressions, see OpenUSD's documentation: Collections and Patterns — Universal Scene Description documentation.

The new UsdCollection node has two modes, that are found in the action parameter’s dropdown:

- action > create: This mode defines a USD collection. A primitive path and collection name is required. The expansionRule dropdown determines the expansion rule which is set to 'expandPrims' by default. Prim paths are added to the collection by using the membershipExpression, include and exclude widgets.
- action > edit: This mode allows modifying incoming collections, by specifying its primPath parameter and selecting the collection within the collectionName parameter. After defining an incoming collection, inputs are automatically pre-populated with the paths set within the collection, and can then be further edited.

Finally, a new PBC Scratch Pad tab can be used in a similar way as the CEL Scratch Pad tab. When searchCollapsedLocations is enabled, the pattern is matched against collapsed primitives in the Scene Explorer. When disabled, the result only shows expanded prim paths.

Collections are now supported in the Scene Explorer tab for both Geolib and USD using a new Collections panel above the main scene tree which is controlled through a new Collections Working Set.

By default, the visibility of the Collections panel is hidden. The expansion of this panel can be toggled by clicking the Collections icon at the top of the Scene Explorer tab, located in between the Katana and Bookmark options; this Collections panel will remain empty until a Collection is added from the Collections working set.

Note: The Collections panel is split into Geolib and USD sections. Hiding the Geolib or USD section of the main Scene Explorer tab by clicking the USD & Katana icons at the top of the tab, also causes the respective section of the Collections panel to hide.

A Collections working set was also added against Katana locations and USD prim paths to indicate where one or more collections are present. To view which collections are available, click the collection icon in the collections working set. Once selected, the collection is displayed in the Collections panel above. Any selected collection in the working set can also be saved as a bookmark.

Any right-click action made on either a Geolib or USD Collection within the Collections panel will display the same menu items previously seen on a Collection in the Scene Graph tab. Once a selection is made on any Collection in the Collections panel, will either highlight any location or prim contributing to a Collection in the scene tree, otherwise it will display them in a secondary window.

Note: See Pattern-Based Collections with USD, UsdCollection, Using the Scene Explorer.

# UI Improvements

In the Scene Explorer tab, the styling for the tree lines have been modified to indicate:

- Class (abstract) prims will be shown as purple
- Instance proxy prims will be shown via dotted lines

Additionally, font styling is used to indicate the following:

- Over prims that are undefined will be indicated dimmed/darker. This is to indicate their presence in the USD document but not on the stage, until it is brought or referenced to a defined prim. Additionally, prims that have their visibility disabled, will also be dimmed.
- Inactive prims are displayed as dimmed and strike-through, which is consistent with how pruned locations in Geolib are displayed.

Note: See Styling in the Scene Explorer.

# USD Debugging

- A new USD Text View tab
  - When selecting a node, the USD Text View tab displays the USD of either: that node's contribution layer (default) or the composed stage up to that node.
- New Error schemas
  - An FnErrorAPI schema and an FnWarningAPI schema have been added to the list of available USD schemas.

Note: See USD Debugging, USD Text View, USD Error Handling.

# Additional USD Nodes

Several new native-USD nodes are now available as part of Katana's USD offering.

- UsdCamera
  - This node creates a prim of type Camera, with transformation parameters that are interactive by default.
- UsdKindSet
  - Allows you to assign a kind to a primitive.
- UsdLight
  - Consisting of a create and edit mode, this node dynamically queries lightTypes, allowing the user to set up a USD light directly from the SdrRegistry.
  - Switching to edit mode automatically populates incoming property values in the parameters and registers any changes made as an o ver. When in create mode, this option is turned off, with an option to specify a prim spec.
- UsdMaterialAssign
  - A node that assigns materials to a primitive, either using Paths or PBC expressions. Its assignmentStrength and materialPurpose can also be set.
- UsdScope
  - Allows the creation of a Scope primitive, with options for its primSpec as well as its primTypeHierarchy.
- UsdStageDefine
  - Provides the ability to set AssetResolverContexts and population masks per stage.
  - This has to be set at the top of the Node Graph tab, hence this node has no input.
- UsdTransformEdit
  - This node allows you to overwrite a prim's transform, similar to Katana's TransformEdit node set to replace global transform.
- UsdXform
  - This node creates a transformable Xform primitive. Similar to the UsdScope node, its primSpec and primTypeHierarchy can be specified.

Note: See UsdCamera, UsdKindSet, UsdLight, UsdMaterialAssign, UsdScope, UsdStageDefine, UsdTransformEdit, UsdXform, Native USD Prims, Using UsdLight, Creating Native USD Cameras, UsdMaterialAssign Workflows, Native USD Transformations.

# USD Metadata

The Attributes tab now supports USD prim and property metadata. This includes:

- Prim metadata is displayed when the prim path is selected, and is displayed under the Metadata group within the Attributes tab. Additionally, the kind, assetInfo, active, and instanceable metadata fields are brought to the top of the list for easy access.
- Property metadata is shown in the Attributes tab via a metadata "M" button next to each property.

Note: See Inspecting USD Properties Using the Attributes Tab.

# USD Camera and Lights in the Viewer

A first version of USD native camera and light locators can now be seen in the Viewer tab. This provides a visual representation in the Viewer tab for the following prim types:

- Camera
- CylinderLight
- DiskLight
- DistantLight
- DomeLight
- PortalLight
- RectLight
- SphereLight

Additionally, prims which have the applied API schema `LightAPI`, `MeshLightAPI` and `VolumeLightAPI` will use a generic locator.

An example plug-in that demonstrates how custom USD viewer locators can be created is available in the installation directory at `<katana_installation_path>/plugins/Src/ViewerPlugins/ExampleUsdSpatialAudioLocator`.

Within the Look-Through Lights and Cameras menu dropdown in the Viewer tab, USD cameras can now be selected as the looked-through camera. By default, the dropdown shows cameras that are part of the model hierarchy. This is for performance reasons to save traversing the entire stage. To ensure cameras are part of the model hierarchy, they (as well as their ancestor prims) require their kind to be set to group, component, or assembly. Alternatively, an option is available to enable traversal of the entire stage, removing the need for the prims to be specified in the model hierarchy, this option is under the Look-Through Lights and Cameras menu under the Full USD Traversal checkbox option.

Note: Using UsdLight, Creating Native USD Cameras.

# USD Interactive Transformation

We can now use Viewer transform manipulators against USD native prims, the nodes that support this feature are as follows:

- UsdTransformSet
- UsdTransformEdit
- UsdXform
- UsdLight
- UsdCamera

A makeInteractive parameter was added to allow interactive manipulation in the Viewer tab, which is set to Yes by default. When active, viewer manipulators can be obtained through the UI in the Viewer tab, or the use of shortcuts to Translate 'W', Scale 'E' and Rotate 'R'.

Interactive transformations against USD prims are available exclusively when the mode parameter is set to Single Path. When set to multiple prim paths, interactive transformations through the Viewer are currently unavailable.

With these additions, the following changes were made to the UsdTransformSet node:

- Transformations are now displayed in the Attributes tab in components, rather than Matrices (as it was in Katana 6.5 and Katana 7.0), to view them as individual translate, scale and rotate components.
- When makeInteractive is set to No, the asMatrix parameter is available as an option, to set these attributes as a matrix.
- When appendTransform is enabled, the transformations set on the UsdTransformSet node are added to pre-existing transformations set on the prim.

Note: See Native USD Transformations.

# Performance

Katana's Node Graph traversal process has largely been ported over from Python to C++ for efficiency. Artists will notice improvements in interactivity when larger Node Graphs are being evaluated, most notably when changing a parameter within a node.

This update may introduce breaking changes, however, this only applies to custom actions created after Katana 6.5. These changes impact the following areas:

- There are a number of changes to the CommonNodesAPI (Python) module, including the deprecation of Python implementations of nodes using `onTraversalVisit()`method
- Customers who've written custom 3D nodes inheriting from Nodes3DAPI.Node3D without making use of NodeTypeBuilder will see a number of changes to Nodes3DAPI (Python)
- The FnGeolibRuntime::Transaction (C++) , GeolibRuntimeTransaction (Python), class is now an interface, with the standard implementation named StandardTransaction (C++), GeolibRuntimeStandardTransaction (Python). It's important to note that any custom implementations of the GeolibRuntimeTransaction interface cannot be implemented in Python

# Performance Tab

The Performance tab now has a Python Profiling section that provides a simple interface for collecting and displaying Python profiling data of the application. This can be accessed using the dropdown menu at the top of the Performance tab.

To begin a profile, click the Profile button to begin and then click the Profile button again to see the results. By default the profile results are sorted by the function with the most expensive cumulative time. This can be adjusted by selecting any of the available column headers to sort the results in ascending or descending order. These layout changes will not be saved and the sort order reverts back to the default state once the Performance tab is closed.

For more details on each function listed in their results, a right-click menu is available to review either Callers and Callees contributing to the selected function call. These will be shown in a popup window, with the option to swap results between Callers or Callees using the buttons on the right-hand side of the popup window.

Note: Caller results are operations that the function has called, while Callees results are operations that called to the function prior.

Note: See Using the Python Profiler.

# Example Projects

New USD-based projects and extended workflows are now available in the Help > Example Projects tab. This includes:

- A new-starter example, built with 3Delight, Arnold, Redshift and Renderman
- A look development template using downloadable assets
- A lighting template using downloadable multi-shot assets
- A Native USD category has been added. These projects showcase USD-native workflows in Katana, from ways of composing USD into projects, manipulating data, through to exporting. Additionally, templates paired with downloadable assets are also available to provide examples of how USD-native workflows can be utilized in a look development and a multi-shot lighting template.

# VFX Reference Platform CY2023

As part of this release this line will follow the same VFX Reference Platform as Katana 7.0; VFX Reference Platform 2023. Some highlights of the specific versions are included below but for a complete list, please refer to the Developer Guide.

| VFX Reference Platform 2023 | Katana 7.0
--- | --- | ---
GCC | 11.2.1 | 11.2.1
glibc | 2.28 | 2.28
Windows Toolset | Visual Studio 2022 | Visual Studio 2022
Windows SDK | 10.0.19041 | 10.0.22621
Python | 3.10.x | 3.10.10
Qt | 5.15.x | 5.15.2 (modified)
PyQt | 5.15 | 5.15.9
OpenEXR | 3.1.x | 3.1.4
OpenSubdiv | 3.5.x | 3.5.0
Alembic | 1.8.x | 1.8.6
OpenColorIO | 2.2.x | 2.2.1
Boost | 1.80 | 1.80.0
Intel TBB | 2020 Update 3 | 2020 Update 3
OpenVDB | 10.x | 10.0.1
NumPy | 1.23.x | 1.23.5

Outside of the VFX Reference Platform, we have also updated to USD 24.05.