TECHNICAL GUIDE VERSION 2.
Katana™ Technical Guide. Copyright © The Foundry Visionmongers Ltd. All Rights Reserved. Use of this Technical Guide and the Katana software is subject to an End User License Agreement (the "EULA"), the terms of which are incorporated herein by reference. This Technical Guide and the Katana software may be used or copied only in accordance with the terms of the EULA.
Contents 1 Preface Terminology 13 2 Katana For The Impatient What Is Katana? 14 A Short History of Katana 15 Scene Graph Iterators 16 The Katana User Interface 16 Katana in Look Development and Lighting 17 Technical Docs and Examples 17 3 Custom Render Resolutions Using the UI 18 Modifying the Resolutions XML 18 Using a Custom Resolutions XML 19 Using the Python API 19 4 Custom Node Colors Flavors and Rules Editing Rules Editing Flavors Updating Node Colors Making Updates Persist Flav
6 Katana Launch Modes Launching Katana Interactive Mode Batch Mode Script Mode Shell Mode Querying Launch Mode 32 32 33 40 40 41 7 Scene Attributes and Hierarchy Common Attributes 43 Generating Scene Graph Data 44 Collections and CEL 45 CEL In the User Interface 46 Guidelines for Using CEL 46 46 46 47 47 47 47 48 48 Using CEL to Specify Light Lists in the LightLink Node 'Collect and Select' isn't a Good Test of Efficiency Make CEL Statements as Specific as Possible Avoid Using Deep Collections A
Defining the getAttr and getOutputAttr Functions 69 Recompiling Existing SGG and AMP Plug-ins 70 70 70 70 71 Source Locations Additional Build-ins Behavioral Differences for SGGs Behavioral Differences for AMPs FAQ for Plug-in Porting 71 10 Structured Scene Graph Data Bounding Boxes and Good Data 74 Proxies and Good Data 74 Level of Detail Groups 75 Alembic and Other Input Data Formats 76 ScenegraphXML 77 11 Look Files Handing Off Looks 78 Look File Baking 79 Other Uses For Look Files
Groups 93 Macros 94 94 96 Adding User Parameters Conditional Behavior Super Tools Registering and Initialization Node Editor Examples 99 100 100 101 103 103 14 Resolvers Examples of Resolvers 106 Implicit Resolvers 106 Creating Your Own Resolvers 107 15 Wrapping SGG Plug-Ins in a Custom Node Creating A Custom Node 110 What Is A Node? 111 Defining Your Node Class 111 111 112 112 112 Importing Required Modules Declaring the Node Shell Registering with NodegraphAPI Defining the User Interfac
Registering the GUI Adding Importomatic Items Using a Script 123 124 17 Handling Textures Different Approaches to Determine Texture Materials With Explicit Textures Using Material Overrides to Specify Textures Using the {attr:xxx} Syntax for Shader Parameters Using Primvars In RenderMan Using Custom User Data Using Pipeline Data to Set Textures 125 125 125 126 128 128 128 18 Typed Connection Checking Shader Outputs 131 Shader Inputs 132 132 Logical Inputs 19 Universal Attributes Default Attributes
21 Locations and Attributes Inheritance Rules for Attributes 153 Setting Group Inheritance using the API 153 153 Light Linking 22 PRMan Technical Notes Use of the "id" Identifier Attribute 155 23 Nodegraph API Nodegraph API Basics Creating a New Node Referencing a Node Referencing a Parameter Node Position Node Naming Getting the Parameters of a Node Setting the Parameters of a Node Input and Output Ports Duplicating Nodes Serialize to XML Deserialize Printing An XML Tree Group Nodes A Group Node E
24 Op API Op API Basics The OpTree Core Concepts with Geolib3 Differences Between Geolib2 and Geolib3 The Runtime Ops Clients The Op API Explained The Cook Interface Op Arguments Scene Graph Creation Reading Scene Graph Input CEL and Utilities Integrating Custom Ops Building Ops GenericOp The NodeTypeBuilder Class Op Toolchain 176 177 178 178 178 179 181 181 182 182 184 188 191 192 192 192 193 193 Client Configuration 194 Advanced Topics 195 195 Caching Op Best Practices Cheat Sheet 196 25 NodeT
Concepts Asset ID Asset Fields Asset Attributes Asset Publishing Transactions Creating an Asset Plug-in Core Methods Publishing an Asset createAssetAndPath() postCreateAsset() Examples 204 204 204 205 205 205 205 206 206 207 207 208 208 Asset Types and Contexts 209 Accessing an Asset 210 Additional Methods 210 211 211 211 211 212 212 212 212 212 213 213 213 213 reset() resolveAllAssets() resolvePath() resolveAssetVersion() createTransaction() containsAssetId() getAssetDisplayName() getAssetVersion
The C++ API 220 28 Render Farm API What scripts work with the Farm API? 221 Farm XML Example 221 The onStartup Callback 221 Farm Menu Options 222 222 222 223 224 224 The Util Menu Render Farm Pop-Up Menu Option Farm Node Parameters Get Sorted Dependency List Get Sorted Dependency List Keys Render Dependencies 225 Render Passes and Outputs 226 File Browser Example 227 228 Custom Dialog Errors, Warnings and Scene Validation Additional Utils 228 229 Appendix A: Custom Katana Filters Scene G
Appendix C: Glossary Glossary Node Asset Fields Asset ID Asset Widget Delegate Widget Hint Katana Scene Graph Katana Node Graph Look File Node Parameter Scene Graph Attribute Scene Graph Location 235 235 235 235 235 235 236 236 236 236 236 236 236 Appendix D Standard Attributes Key Locations 237 Location Type Conventions 241
1 Preface The aim of this guide is to provide an understanding of what Katana is, how it works, and how it can be used to solve real-world production problems. It is aimed at users who are familiar with technical content, such as plug-in writers, R&D TDs, pipeline engineers, and effects uber-artists. Terminology To avoid confusion certain terminology conventions are used in this document. These naming conventions are also those used in Katana itself.
2 Katana For The Impatient This guide starts at the point Katana is installed, and licensed. For more information on installation and licensing, see the Installation and Licensing chapter in the Katana User Guide. What Is Katana? Essentially Katana is a system that allows you to define what to render by using filters that can create and modify 3D scene data.
2 KATANA FOR THE IMPATIENT | A SHORT HISTORY OF KATANA The scene data to be delivered to the renderer is described by a tree of filters, and the filters are evaluated on demand in an iterative manner. Katana is designed to work well with renderers that are capable of deferred recursive procedurals, such as RenderMan and Arnold. Using recursive procedurals, the tree of filters is handed directly to the renderer, with scene data calculated on demand, as the renderer requests it (lazy-evaluation).
2 KATANA FOR THE IMPATIENT | SCENE GRAPH ITERATORS Katana's initial focus was on RenderMan, particularly how to harness the power of RenderMan's recursive procedurals. In a RenderMan procedural it is possible to perform arbitrary creation of scene data on demand, but their full capabilities are rarely exploited. The Katana approach is to have a single procedural powerful enough to handle arbitrary generation and filtering.
2 KATANA FOR THE IMPATIENT | KATANA IN LOOK DEVELOPMENT AND LIGHTING hierarchy in the UI. Complexity is controlled by only executing filters on locations in the scene graph that the user has expanded. A scene does not need to be entirely loaded in order to be lit. In Katana, you create recipes that allow scene data to be generated, rather than directly authoring the scene data itself. It is only the renderer that needs the ability to see all of the scene data, and then only when it needs it.
3 Custom Render Resolutions You can define custom render resolutions to supplement or replace Katana's pre-defined resolutions. You can define resolutions in Katana through the UI, using Python, by modifying the Katana resolutions XML file, or by creating your own XML file of resolutions. Using the UI You can set the render resolution through any node with a resolution field, such as a RenderSettings or ImageColor node.
3 CUSTOM RENDER RESOLUTIONS | USING A CUSTOM RESOLUTIONS XML are all nested in elements and take the form: You can edit existing resolutions, or add resolutions within the tags, using the existing form. Using a Custom Resolutions XML You can use custom resolutions in an .
3 CUSTOM RENDER RESOLUTIONS | USING THE PYTHON API Startup folder, under the path defined in the KATANA_RESOURCES environment variable. Alternatively, you can use a startup script in the form of an init.py file placed in the .katana folder in your $HOME directory.
4 Custom Node Colors You can set the display color of individual nodes through the UI by selecting a node, then choosing Colors, then a color from the presets available in the Node Graph's Colors menu. You can also apply a custom color by selecting a node, then choosing Colors > Set Custom Color, which brings up a color picker window. NOTE: To reset a node's color back to the default, select the node, then choose Colors > None.
4 CUSTOM NODE COLORS | Editing Rules You can edit rules and add new ones by overwriting list entries using Nodes2DAPI.NodeColorDelegate. For example, to edit the color associated with the flavor composite to pure red, enter the following in the Python tab: Nodes2DAPI.NodeColorDelegate.rules[ 2 ] = ( 'composite', ( 0, 0, 1 ) ) Creating New Rules You can create a new rule using: NodegraphAPI.Flavor.AddNodeFlavor( 'nodeName', 'flavorName') To append a rule to the active rules use: import Nodes2DAPI.
4 CUSTOM NODE COLORS | Creating New Flavors To add a new flavor, enter the following in the Python tab: NodegraphAPI.Flavor.AddNodeFlavor( 'nodeName', 'flavorName' ) For example, to add the node type Render to a flavor called myRenderFlavor, enter the following: NodegraphAPI.Flavor.AddNodeFlavor( 'Render', 'myRenderFlavor' ) NOTE: If you want to completely customize node creation, you can also create a class derived from NodegraphAPI.NodeDelegateManager.
4 CUSTOM NODE COLORS | Making Updates Persist Rules and flavors created or modified within the Python tab expire with the Katana session. Using the Node Graph and Nodes2DAPI.NodeColorDelegate Python APIs, you can include your rules and flavor changes in Python startup scripts, making them persistent across Katana sessions. To do this, add your code to one of Katana's startup scripts. These are files named init.
4 CUSTOM NODE COLORS | FLAVOR API Flavor API API Usage NodegraphAPI.Flavor AddNodeFlavor( ) Adds a new flavor Syntax: Takes two strings, the node type, and the flavor name. AddNodeFlavor( 'nodeType', 'flavorName' ) Example: NodegraphAPI>Flavor.AddNodeFlavor( 'Render', 'myNewFlavor' ) Adds nodes of type Render to a new flavor named myNewFlavor. ClearFlavorNodes( ) Clears all entries in a flavor Syntax: Takes a single string, the flavor name. ClearFlavorNodes( 'flavorName' ) Example: NodegraphAPI.
4 CUSTOM NODE COLORS | FLAVOR API API Usage NodegraphAPI.Flavor GetFlavorNodes( ) Gets a list of all nodes in a given flavor. Syntax: Takes a single string, the name of the flavor. GetFlavorNodes( 'flavorName' ) Example: NodegraphAPI.Flavor.GetFlavorNodes('2d' ) Gets a list of all nodes in the flavor named 2d. GetNodeFlavors( ) Gets a list of the flavors stored on a given node. Syntax: Takes a single string, the name of the node type. GetNodeFlavors( 'nodeType' ) Example: NodegraphAPI.Flavor.
4 CUSTOM NODE COLORS | FLAVOR API API Usage NodegraphAPI.Flavor NodeMatchesFlavors( ) Checks to see if a specified node is in a specified flavor, and not in any specified ignore flavors. Returns a Boolean. Syntax: Takes three strings, node type, flavor to match, and ignore flavors. The node type must be a single string, while flavor, and ignore flavors can be any sequence of strings. Flavor, and ignore flavors can each also be None.
4 CUSTOM NODE COLORS | FLAVOR API API Usage NodegraphAPI.Flavor RemoveNodeFlavor( ) Deletes a flavor. Syntax: Takes a single string, the name of the flavor to remove. RemoveNodeFlavor( 'flavorName' ) Example: NodegraphAPI.Flavor.RemoveNodeFlavor( 'myFlavor' ) Removes the flavor named myFlavor.
5 Message Logging Error, warning, and informational messages are logged in Katana using the logging module of the Python Standard Library. Messages are logged from contexts including the Python tab, shelf scripts, and Python startup scripts. NOTE: More information on logger objects in Python is available in the Python documentation. You can filter the level of messages generated, and the level of messages displayed.
5 MESSAGE LOGGING | logging.debug("This is a debugging message.") Custom Logger Instead of using the root logger, you can create a custom logger object. The following example creates a custom logger and generates a message of each level using that logger: import logging log = logging.getLogger("myLogger") log.info("This is an informational message.") log.warning("This is a warning message.") log.error("This is an error message.") log.critical("This is a fatal error message.") log.
5 MESSAGE LOGGING | LOGGING EXCEPTIONS Logging Exceptions Exceptions can be logged in a way that automatically includes traceback information in the log message, as in the following example: import logging try: i = 1 / 0 except Exception as exception: logging.
6 Katana Launch Modes Launching Katana You can start Katana in a number of different modes, using command line arguments to start the application: Interactive no flags Runs Katana with the standard GUI. Batch --batch Runs Katana without a GUI to render the output of a specific node in the Node Graph. Script --script Runs Katana without a GUI, and executes the specified Python script. Shell --shell Runs Katana without a GUI, and allows Python commands to be run interactively.
6 KATANA LAUNCH MODES | 1. Open a terminal. 2. Navigate to the directory where you installed Katana. 3. Enter: ./katana /yourDirectory/yourScene.katana You can also specify an asset ID using the --asset flag, to resolve and open a file from your asset management system. The --asset flag takes a single argument, which is the asset ID to resolve. For example: .
6 KATANA LAUNCH MODES | Option Usage --katana-file Specifies the Katana recipe to load. Syntax: --katana-file= Example: ./katana --batch --katana-file=/tmp/test.katana --t=1 --render-node=beauty --asset Specifies the asset ID to resolve. Syntax: --asset- Example: ./katana --asset-mock:///show/shot/name/version -t or --t Specifies the frame range to render.
6 KATANA LAUNCH MODES | Option Usage --threads2d Specifies the number of additional processors within the application. An additional processor is also used for Katana's main thread. This means that Katana uses 3 processors when --threads2d=2. Syntax: --threads2d= Example: ./katana --batch --katana-file=/tmp/test.katana --t=1 --threads2d=2 --render-node=beauty --threads3d Specifies the number of simultaneous threads the renderer uses. Syntax: --threads3d= Example: .
6 KATANA LAUNCH MODES | Option Usage --render-internal-dependencies Allows any render nodes that don't produce asset outputs to be rendered within a single katana --batch process. Asset outputs are determined by asking the current asset plug-in if the output location is an assetId, using isAssetId(). The default file asset plug-in that ships with Katana classes everything as an asset.
6 KATANA LAUNCH MODES | Option Usage --tile-render Used to render one tile of an image divided horizontally and vertically into tiles. For instance, using --tile-render=1,1,3,3 splits the image into 9 smaller images (or tiles) in a 3x3 square and then renders the middle tile as the index for tile renders starts at the bottom left corner with 0,0.
6 KATANA LAUNCH MODES | Option Usage --tile-stitch Used to assemble tiles rendered with the --tile-render flag into a complete image. When stitching, you must still pass the --tile-render argument, with the number of x and y tiles, so that the stitch knows how many tiles to expect, and their configuration. Syntax: --tile-render=, , , --tile-stitch Example: ./katana --batch --katana-file=/tmp/test.
6 KATANA LAUNCH MODES | Option Usage --make-lookfilebake-scripts Used to write out a number of Python files that can be executed in batch mode to write look files. Syntax: --make-lookfilebake-scripts=
