Download Katana 2.1v2 Technical Guide PDF

TitleKatana 2.1v2 Technical Guide
File Size2.1 MB
Total Pages251
Table of Contents
Katana For The Impatient
	What Is Katana?
	A Short History of Katana
	Scene Graph Iterators
	The 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
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
	Fast Expressions
		Node References
		Parameter References
	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
		Customize Ops Evaluation at Child Locations
	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
	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
		Python Message Levels
		Root Logger
		Custom Logger
	Logging Exceptions
	Verbose Mode Logging
		Renderer Logging
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
	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 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
	Creating User Attributes in the PrmanObjectSetting Node
Document Text Contents
Page 2

Katana™ Technical Guide. Copyright © 2016 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 © 2016 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: 04 March 2016

Page 125


responding to them before. This also includes the errorMessage attribute that is used for error reporting, which you
may not have previously added to that list.

In Katana 2.0v1 and later, default values are no longer provided for args that weren’t filled in by the node. As such,
you may want to adjust calls to getAttr accordingly, in order to use the non-excepting variant, complete with the
known default values. For example:
FnKatana::IntAttribute attr = args.getChildByName( “myNumberAttr” );

const int value = attr.getValue( 20 /*default*/, false /*don’t throw*/ );

Behavioral Differences for AMPs

Locations are explicitly named upon declaration in Geolib3. The “name” attribute is no longer used and behaves just
like ‘any other attr’. As such, you can’t rename a location using setAttr( “name” ) any more. Additionally getAttr(
“name” ) won’t return the location name, only whatever value another Op may have set it to, which is usually

If you need to rename locations, the Rename Node/Op is available, and similar functionality is present within the
CookInterface (copyLocationToChild) if you port your AMP to an Op.

FAQ for Plug-in Porting
1. Can I use my pre-2.0v1 plug-ins?

Yes, you can recompile SGG and AMP plug-in as full Ops, with some header and mild behavioral changes, which
are listed in Recompiling Existing SGG and AMP Plug-ins on the previous page.

2. Why are Ops better?
The Op API is the same API as is used internally by Katana, and this replaces both SGGs and AMPs. That is to say
that you can finally write a Merge or an Instancing Op without jumping through hoops.

3. Anything major I should be aware of now?
The new ‘granularity of data’ is now per-location, in cook, and you have to calculate all of your attributes at the
same time, as well as name your children. Additionally, the name attribute is no longer used, as locations are
explicitly named upon declaration and cook is performed at a named location path.

4. I used ‘ScenegraphContext’ to adapt behavior. How can I replace it?
The simplest match is to port these Contexts to different Ops, and replace the Op for children as you define
them in the way you would construct a different Context when returning getFirstChild or getNextSibiling.

5. I previously passed data to the constructor of my ScenegraphContext. How do I pass down
data now?
OpArgs are the key to this. Replace the OpArgs for the Op with your children. If it's a complex handle, try using
static Op-level caching (though, beware threading), or use the blind data void*.

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


Page 126


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 93 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 251


Ci = Os * Cs * normalize(N).-normalize(I);

Oi = Os;


Creating User Attributes in the PrmanObjectSetting
There is a convention that attributes under prmanSettings.attributes.user get translated into PRMan user attributes.
For instance, if you set this in an AttributeScript:

SetAttr("prmanStatements.attributes.user.wibble", [1.0])
SetAttr("prmanStatements.attributes.user.wobble", ["someString"])

you should get this in the rib stream:

Attribute "user" "constant float wibble" [1]
Attribute "user" "uniform string wobble" ["someString"]

Support is limited in the UI but you can explicitly create appropriately named parameters on PrmanObjectSettings
nodes using Python scripting to give something to the user. However, there currently isn't a way to create these
settings from scratch purely from the UI without running a custom script.


Similer Documents