Download Katana 2.1v1 Technical Guide PDF

TitleKatana 2.1v1 Technical Guide
File Size2.1 MB
Total Pages246
Table of Contents
Katana For The Impatient
	What Is Katana?
	A Short History of Katana
	Scene Graph Iterators
	The Katana User Interface
	Katana in Look Development and Lighting
	Technical Docs and Examples
Scene Attributes and Hierarchy
	Common Attributes
	Generating Scene Graph Data
Locations and Attributes
	Inheritance Rules for Attributes
	Setting Group Inheritance using the API
		Light Linking
Katana Launch Modes
	Launching Katana
		Interactive Mode
		Batch Mode
		Script Mode
		Shell Mode
		Querying Launch Mode
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
	Dynamic Parameters
	Duplicating Nodes
		Serialize to XML
		Printing An XML Tree
	Group Nodes
		A Group Node Example
		Send and Return Ports
		Return Port Example
		Send Port Example
	Physical and Logical Connections
		Physical and Logical Source
	User Parameters
		Top Level User Parameters
		Nested User Parameters
		Parameter Hints
	Parameter Expressions
	Enableable Parameter Groups
	Dynamic Arrays for PRMan Shader Parameters
Shelf Item Scripts
	Running Shelf Item Scripts from the UI
	Types of Shelves
		Built-in Shelves
		User-defined Shelves
		Additional Shelves
	Directory Structure for Shelf Item Scripts
	Node-Specific Shelf Item Scripts
		Pre-Defined Variables in Node-Specific Shelf Item Scripts
		Targeting Node-Specific Shelf Item Scripts to Specific Types of Nodes
	Docstrings of Shelf Item Scripts
	Op API Basics
		The OpTree
	Core Concepts with Geolib3
		Geolib3: Into the Details
		Differences Between Geolib2 and Geolib3
		The Runtime
	The Op API Explained
		The Cook Interface
		Op Arguments
		Scene Graph Creation
		Reading Scene Graph Input
		CEL and Utilities
	Integrating Custom Ops
		Building Ops
		The NodeTypeBuilder Class
		Op Toolchain
	Client Configuration
	Advanced Topics
	ScenegraphAttr Porting Guide
		Overview of Changes
		Porting from 1.x ScenegraphAttr to 2.0 ScenegraphAttr
		Porting from 1.x ScenegraphAttr to 2.0 FnAttribute
	Op Best Practices Cheat Sheet
	Creating a New Node
		The buildOpChain Function in Detail
	Examples of NodeTypeBuilder
	How to Install Scripts that Use the NodeTypeBuilder
Super Tools
	Registering and Initialization
Scene Graph Generator Plug-Ins
	Running an SGG Plug-in
		Generated Scene Graph Structure
	SGG Plug-in API Classes
		Registering an SGG Plug-in
		Providing Error Feedback
Porting Plug-ins
		Implications for Existing Plug-ins
	Ops Versus Scene Graph Generators
	Ops Versus Attribute Modifiers
	Defining the getAttr and getOutputAttr Functions
	Recompiling Existing SGG and AMP Plug-ins
		Source Locations
		Additional Build-ins
		Behavioral Differences for SGGs
		Behavioral Differences for AMPs
	FAQ for Plug-in Porting
Message Logging
	Message Levels
		Root Logger
		Custom Logger
	Logging Exceptions
Asset Management System Plug-in API
		Asset ID
		Asset Fields
		Asset Attributes
		Asset Publishing
	Creating an Asset Plug-in
		Core Methods
	Publishing an Asset
	Asset Types and Contexts
	Accessing an Asset
	Additional Methods
	Top Level Asset API Functions
	LiveGroup Asset Functions
	Extending the User Interface with Asset Widget Delegate
		Configuring the Asset Browser
	The Asset Control Widget
		Implementing A Custom Asset Control Widget
		Asset Render Widget
		Additional Asset Widget Delegate Methods
	Locking Asset Versions Prior to Rendering
	Setting the Default Asset Management Plug-in
	The C++ API
Python Processes and Geolib3
Render Farm API
	What scripts work with the Farm API?
	Farm XML Example
	The onStartup Callback
	Farm Menu Options
		The Util Menu
		Render Farm Pop-Up Menu Option
		Farm Node Parameters
		Get Sorted Dependency List
		Get Sorted Dependency List Keys
	Render Dependencies
	Render Passes and Outputs
	File Browser Example
		Custom Dialog
	Errors, Warnings and Scene Validation
		Additional Utils
Custom Node Graph Menus
	LayeredMenuAPI Overview
	Creating a Custom Node Graph Menu Plug-in
	Example of Layered Menu Plug-in
Typed Connection Checking
	Shader Outputs
	Shader Inputs
		Logical Inputs
Args Files in Shaders
	Edit Shader Interface Interactively in the UI
		Enabling Editing the User Interface
		Edit Main Shader Description
		Export Args File
		Widget Types
		Widget Options
		Conditional Visibility Options
		Conditional Locking Options
		Editing Help Text
		Grouping Parameters into Pages
		Co-Shader Pairing
		Example Args File
		Args Files for Render Procedurals
		Defining presetsGroup Values
	UI Hints for Plug-ins Using Argument Templates
		Usage in Python Nodes
		Usage in C++ Nodes
Customizing the GafferThree
	Creating a Custom GafferThree Package Class
		Package Class
		Edit Package Class (Optional)
		UI Delegate Class
		Package Initialization File
		Example of Implementing a Custom GafferThree Package Class: Sky Dome
	Registering Callbacks
Creating New Importomatic Modules
	Importomatic Core Files
	Where to Place New Modules
	Minimum Implementation
		Importomatic Camera Asset Example
	Custom Hierarchy Structures and Extensions
		Creating a Tree Structure
		Updating the Node Graph
		Additional Context Menu Actions
		Registering the GUI
		Adding Importomatic Items Using a Script
Custom Render Resolutions
	Using the UI
	Modifying the Resolutions XML
	Using a Custom Resolutions XML
	Using the Python API
Managing Keyboard Shortcuts and the shortcuts.xml File
	Example of a shortcuts.xml File
Custom Node Colors
	Flavors and Rules
		Editing Rules
		Editing Flavors
		Updating Node Colors
		Making Updates Persist
	Flavor API
Appendix A: Custom Katana Filters
	Scene Graph Generators
	Attribute Modifiers
Appendix B: Other APIs
	File Sequence Plug-in API
	Attributes API
	Attribute History
	Render Farm API
	Importomatic API
	Gaffer Profiles API
	Viewer Manipulator API
	Viewer Modifier API
	Viewer Proxy Loader API
	Renderer API
Appendix C: Glossary
		Asset Fields
		Asset ID
		Asset Widget Delegate
		Katana Scene Graph
		Katana Node Graph
		Look File
		Node Parameter
		Scene Graph Attribute
		Scene Graph Location
Appendix D: Standard Attributes
	Key Locations
	Location Type Conventions
Appendix E: PRMan Technical Notes
	Use of the id Identifier Attribute
Document Text Contents
Page 2

Katana™ Technical Guide. Copyright © 2015 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. This Technical Guide,
the Katana software and all intellectual property rights relating thereto are and shall remain the sole property of The Foundry
Visionmongers Ltd. ("The Foundry") and/or The Foundry's licensors.

The EULA can be read in the Katana User Guide.

The Foundry assumes no responsibility or liability for any errors or inaccuracies that may appear in this Technical Guide and this
Technical Guide is subject to change without notice. The content of this Technical Guide is furnished for informational use only.

Except as permitted by the EULA, no part of this Technical Guide may be reproduced, stored in a retrieval system or transmitted, in any
form or by any means, electronic, mechanical, recording or otherwise, without the prior written permission of The Foundry. To the extent
that the EULA authorizes the making of copies of this Technical Guide, such copies shall be reproduced with all copyright, trademark
and other proprietary rights notices included herein. The EULA expressly prohibits any action that could adversely affect the property
rights of The Foundry and/or The Foundry's licensors, including, but not limited to, the removal of the following (or any other copyright,
trademark or other proprietary rights notice included herein):

Katana™ software © 2015 The Foundry Visionmongers Ltd. All Rights Reserved. Katana™ is a trademark of The Foundry Visionmongers

Sony Pictures Imageworks is a trademark of Sony Pictures Imageworks.

Mudbox™ is a trademark of Autodesk, Inc.

RenderMan ® is a registered trademark of Pixar.

In addition to those names set forth on this page, the names of other actual companies and products mentioned in this Technical Guide
(including, but not limited to, those set forth below) may be the trademarks or service marks, or registered trademarks or service marks,
of their respective owners in the United States and/or other countries. No association with any company or product is intended or
inferred by the mention of its name in this document.

Linux ® is a registered trademark of Linus Torvalds.

The Foundry

5 Golden Square,



Rev: 18 November 2015

Page 123


6. I make use of other SGGs, for example Alembic_In, at child locations created by my SGG. Is this a

Just swap the Op out at the child location, so for this example, to the Alembic_In Op. If you want it to be
deferred, use the ‘Ops’ top-level group attr syntax and OpResolve. Some Ops have helper classes to assist in
building their args.

7. What about threading?

You need to pay attention to what you set in setup and make sure you thread-safe your code accordingly, or set
it to ThreadModeGlobalUnsafe.

8. How do I pass data to the Op that runs at a child location?

Due to the cook function being static, you can’t use the practice of passing data to the constructor for the
context that represents the child or sibling location. The way this is handled in Geolib3 is to update the OpArgs
that are available to the cook function when running at that location.

This can be done either by calling replaceChildTraversalOp for the generic case of all children, or by specifying
the new OpArgs when calling createChild. OpArgs should use CamelCase for their names, with the first letter set
in lowercase, for example, “myOpArg”.

It is recommended to distinguish between ‘private’ internal OpArgs, only used for communication to child
locations, and ‘public’ top-level OpArgs by prefixing private names with an underscore. For example,
“numSubdivisions” would be public and “_currentDepth” would be private.

9. How do I define a custom node that users can create in the node graph for my Op?

The Katana.Nodes3DAPI.NodeTypeBuilder is your friend. It greatly simplifies the process of defining a new
node, and ensures the Op network is suitably updated as parameters change. Refer to the chapter on the
NodeTypeBuilder on page 91 for more info.

10. I want my Op to start running at “/root/world/geo/some/location”, in the way that
ScenegraphGeneratorSetup allowed me to. How do I do this with an Op?

The GenericOp node can do this when applyWhen is set to “create new location”. If you are creating a custom
node using NodeTypeBuilder, instead of instantiating your Op, configure a StaticSceneCreate Op in the
buildOpChain function to run your Op at a sub-location, that is to say:
sscb = FnGeolibServices.OpArgsBuilders.StaticSceneCreate()

sscb.addSubOpAtLocation(locationNameFromParam, “MyOp”,


The SubdividedSpaceOp example makes use of this technique.

11. How do Nodes/Ops deal with the Inputs? Do I have to manage merging myself?

Ops have the ability to see the incoming scene, from one or more inputs. When using NodeTypeBuilder to
define a custom node, it is simple to control the default set of inputs present on the node when it's created.

• In an ‘empty’ Op, the scene graph on the default input (first index) passes-through the Op unchanged. You do
not need to manually ‘copy input to output’.

• If you don’t want children or attributes to pass through, you need to explicitly delete them.

• If your Op creates a child that already exists, any attrSets you make simply update attributes at that location.

• If your Op is connected to multiple inputs, then you have to explicitly query, and merge in data from the
additional inputs in your code.


Page 124


It is recommended to omit inputs from any high-level ‘generator’ Ops that don’t need to see the incoming scene,
as it encourages users to make node graphs that are ‘wider’, rather than ‘deeper’. These can be more efficient
with multi-threading and permit better caching efficiency. This is by no means a requirement though.

NOTE: Deeply overlapping merges of many inputs can be expensive, while non-overlapping merges are
preferred and significantly cheaper.

12. How do I get system args or GraphState variables into my Op?

GenericOp adds these in for you if you enable ‘addSystemOpArgs’. Alternatively, with NodeTypeBuilder in your
buildOpChainFunc you can:
graphState = interface.getGraphState()

argsGb.set( 'system', graphState.getOpSystemArgs() )

13. I'm getting a bit mixed up about ‘swapping the Op for my children’. I thought the Op Tree was
‘immutable’ while the Scenegraph was being cooked?

One of the key differences between Katana 1.x and 2.x versions is that we keep the network of the Ops that the
nodes represent alive all the time, rather than regenerating them every time parameters change.

This is great for performance, but means the the topology of the Op Tree changes as you add nodes. However,
once the scene graph needs to be evaluated, this top-level Op Tree becomes immutable.

You may find it simpler to think of it as a fixed cookie-cutter template of ‘slots’ that Ops can sit in, rather than a
fixed set of specific Ops. Functions like replaceChildTraversalOp, and the ability to adjust the optype when
creating children, simply changes which Op is in a particular ‘slot’ in the cookie-cutter template when that child
location is cooked.

So, you can’t add new branches but you can easily swap Ops or call extra ones in your slot, in a serial fashion.


Similer Documents