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 4.0

# Introduction

This document describes notable changes introduced in Katana 4.0.

# New Features in the Hydra Viewer

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

Note: To learn more about Katana's Lighting Tools, see the Lighting Tools documentation.

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

Note: To learn more about Katana's Image-based Selection mode, see the Image-Based Selection in the Monitor Layer documentation.

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

Note: To learn more about the Katana Queue, see the Katana Queue documentation.

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

Note: To learn more about rendering multiple images simultaneously, see the Performing Multiple Simultaneous Preview Renders documentation, or for information about the Start Multiple Renders script, see Starting Multiple Renders.

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

Note: For more information, see the documentation for the Catalog Tab and Comparing Front and Back Images in the Monitor tab.

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

Note: For more information, see the Multiple NetworkMaterials with NetworkMaterialCreate documentation.

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

Note: For more information, see the Filtering section of the NetworkMaterialEdit node documentation.

# USD

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

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

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.

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.

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

Note: For more information, see the UsdPreviewSurface in the Hydra Viewer documentation.