Amazon VERSION 2.0V1 Betriebsanweisung

TECHNICAL GUIDEVERSION 2.0v1

Concepts204204Asset ID 204Asset Fields 205Asset Attributes 205Asset Publishing 205Transactions 205Creating an Asset Plug-in206Core Methods 206Publishi

100• Typically there is a third Python script for common shared utility functions needed by both the nodes and UIscripts.Registering and Initializatio

101<group_parameter> <string_parameter name='name' value=''/> <number_parameter name='value&apos

102""" QtGui.QWidget.__init__(self, parent)self.__node = node# Try to upgrade the given node in...# ...an undo stack groupnodeName =

103mainLayout.addWidget(widget)# Apply the layout to the widgetself.setLayout(mainLayout)ExamplesThe following code examples illustrate various Super

104The ShadowManager node then creates two output nodes for each render pass. The first one contains the modifiedscene (with the corresponding file pa

14 ResolversResolvers are filters that need to be run before actual rendering in order to get data into the correct final form.Typically they are used

106• Change what the material on every object that is assigned a material by changing the attributes of the originalmaterial.In essence they get to ma

107• RiProceduralResolve• This is similar to MaterialResolve but for renderer procedurals, such as RenderMan or Arnold procedurals. Itlooks for any lo

108• during material resolve: the script will be executed when local copies of materials are being created on anylocations with assigned materials. Th

15 Wrapping SGG Plug-Ins in aCustom NodeScene Graph Generator (SGG) plug-ins allow the arbitrary creation of scene graph locations and attributes. Thi

The C++ API22028 Render Farm APIWhat scripts work with the Farm API?221Farm XML Example221The onStartup Callback221Farm Menu Options222The Util Menu 2

110This document describes the process by which an SGG plug-in can be wrapped within a custom node, how to exposea UI in the Parameter tab and pass an

111https://docs.python.org/2/reference/lexical_analysis.html#identifiers.What Is A Node?A typical node is composed of:• Zero or more input ports, whic

112Declaring the Node ShellThe next step is to declare the class and its constructor, ensuring that the base class constructor is called and anoutput

113%s</group_parameter>""" % (GetTimingParameterXML(),)which corresponds to the following UI in the Parameters tab.We parse the X

114To pass this dictionary of hints to Katana we add a function to our node class:def addParameterHints(self, attrName, inputDict): inputDict.updat

115NOTE: This has been aliased to Attr in the example code:args = { "fileName" : SAttr.Attr("StringAttr", [abcAsset]), &qu

116Installing Your NodeInstalling your node is easy, simply place the Python file under one of your Plug-ins directories pointed to in your$KATANA_RES

16 Creating New ImportomaticModulesImportomatic Core FilesThe Importomatic is a SuperTool which means that it wraps the functionality of multiple node

118Importomatic Camera Asset ExampleIn this example, the main asset file is CameraAsset.py into which we need to import the Nodegraph API and plug-ins

119The registered type class CameraModule() is also instantiated when the user selects the module from the menu.The function setItemState is called, i

Appendix C: GlossaryGlossary235Node 235Asset Fields 235Asset ID 235Asset Widget Delegate 235Widget 235Hint 236Katana Scene Graph 236Katana Node Graph

120The parameter editor is resolved automatically in cases where the user is allowed to change properties. The UI4 andVpCore packages are imported wit

121• The main node, and any other nodes used to implement the custom Importomatic module, are placed in a Groupnode. This ensures a clean and clutter-

122Each class has to implement the setItemState function, which specifies the item name and type. If the item relatesto a particular node in the Node

123If this function returns True, a delete menu option is added to the context menu when the item is right-clicked. Themethod delete( self ) implement

124Adding Importomatic Items Using a ScriptUsing the Alembic module as a reference, adding a new Alembic item in the Importomatic is achieved by regis

17 Handling TexturesBecause textures are handled in a number of different ways by shader libraries and studio pipelines, Katana doesn'tenforce ri

126For instance, the fragment of AttributeScript below reads the attribute value contained in textures.SpecMap anduses it to override an Arnold shader

127Assignments created using {attr:yourParameter} are evaluated during material resolve. Therefore any materialusing those parameters must be explicit

128Using Primvars In RenderManRenderMan has a feature called primvars that allow you to directly override the value of any shader parameter. Thismeans

129Metadata on Imported GeometryArbitrary metadata can be read in with geometry on import, such as string data containing the texture paths writtenout

1 PrefaceThe aim of this guide is to provide an understanding of what Katana is, how it works, and how it can be used to solvereal-world production pr

130Procedurally Resolving TexturesYou could also use a resolver to procedurally set textures.xxx to appropriate file paths, including allowing theactu

18 Typed Connection CheckingThe constituent nodes of a Network Material can specify which connections are valid, based on simple string tags.Shaders c

132Shader InputsEach connectable input parameter for a shader can declare what tag values it requires for a connection to be valid.The user interface

133This tag states that the output of the shader connected to this parameter needs to provide all of the tags color,color4 and diffuse. If any tag is

19 Universal AttributesOne of the key strengths of Katana is its ability to deal efficiently with scenes of potentially unlimited complexity.Consider

135the command line as follows: katana –script <script name>Default AttributesAs discussed earlier, Katana only communicates values that have

136This code can be found in ViewSetAndDefaultParamsError.py and run using:katana –scripts ViewSetAndDefaultParamsError.pyHowever, you'll find th

137downstream node's parameters. We do this by using the universal attributes as these provide us with all the data weneed to be able to fully di

20 Args Files in ShadersArgs files provide hints about how parameters are presented in the user interface. One of their main uses isdescribing how sha

139Edit Shader Interface Interactively in the UIEnabling Editing the User InterfaceTo allow for editing of the shader interface, turn on Edit Shader I

2 Katana For The ImpatientThis guide starts at the point Katana is installed, and licensed. For more information on installation and licensing, seethe

140Edit Main Shader DescriptionBy choosing Edit Main Shader Description... from the wrench menu, you can add context help for the selectedshader. This

141The primary widget types and widget hint values for user parameters of type string and number are shown in thetable below:Widget Type Widget Hint V

142Widget Type Widget Hint Values Description and ExampleScript Button scriptButton A button executing a Python script when clicked.<param scriptTe

143Widget OptionsBased on the specified widget type, there are a number of options available. In case of a color parameters forexample, these options

144</param>Conditional Locking OptionsConditional Locking works exactly like the Conditional Visibility Options, except that parameters are lock

145This is achieved in one of two ways when editing .args files:1. Adding a page attribute with the name of the page to each parameter:<param name=

146Example Args FileAn example of an .args file using pages and different types of widgets is KatanaBlinn.args, saved in ${KATANA_ROOT}/plugins/Resour

147Args Files for Render ProceduralsSimilar to their use in shader interfaces, UI hints can be defined for PRMan and Arnold procedurals. TheRendererPr

148for (int i = 0; i < 4; ++i){csValues[i][0] = 1.0f; csValues[i][1] = 0.0f;csValues[i][2] = 0.0f;}//tokenize input stringstd::vector<cha

149{++i;if (i < tokens.size()){radius = atof(tokens[i]);}}}//free the copied parameter stringfree(inputParamStr);}};NOTE: Parameters are passed fro

15The scene data to be delivered to the renderer is described by a tree of filters, and the filters are evaluated ondemand in an iterative manner. Kat

150'Alembic_In.abcAsset':{ 'widget':'assetIdInput', 'assetTypeTags':'geometry|alembic','file

151FnKat::StringAttribute( "pageA" ) );FnKat::GroupBuilder gb_fileArg_hints;gb_fileArg_hints.set("widget", FnKat::StringAttribute(

21 Locations and AttributesThe Scene Graph in Katana consists of a hierarchy of Scene Graph Locations. Each location is of a specific typedepending on

153prmanSurfaceParams.Kd_color.value').getXML() )Returns:<numberarray_parameter name="value" size="3" tupleSize="3&qu

1545. Connect the output of the Merge node to the input of the Gaffer node.6. Add a LightLink node.7. Connect the output of the Gaffer node to the inp

22 PRMan Technical NotesUse of the "id" Identifier AttributeThe id pass that Katana uses in the Monitor for picking objects makes use of an

156Ci = Os * Cs * normalize(N).-normalize(I);Oi = Os;}22 PRMAN TECHNICAL NOTES |

23 Nodegraph APIThe Nodegraph API is a Python interface for creating Katana recipes by adding and connecting nodes, and settingParameters. The Nodegra

158example: help( NodegraphAPI.CreateNode )Referencing a NodeYou can reference a node using the function GetNode(). For example, to reference a node

159Node NamingEach node has a name, which is unique within the bounds of a Katana recipe. Name-spacing does not exist for nodenames, which means that

16Katana's initial focus was on RenderMan, particularly how to harness the power of RenderMan's recursiveprocedurals. In a RenderMan procedu

160print ( node.getParameters().getXML() )Which displays the XML of the selected node:<group_parameter name="PrimitiveCreate"><stri

161Ports can be added by index as well as by name which allows direct control of their ordering. For example, to add aninput port to the merge node cr

162node referenced by node enter the following:# Get the root noderoot = NodegraphAPI.GetRootNode()# Create a new node at root levelnode = NodegraphAP

163 <stringarray_parametername="preserveInheritedAttributes"size="0" tupleSize="1"/><group_parameter nam

164A Group Node ExampleThe following stand alone example produces a group node containing a network that produces a Scene Graph withsphere and cube lo

165merge.setName( 'Result' )NOTE: Ctrl+middle-click on the Group node to see its contents, and observe the PrimitiveCreate nodesnamed Sphere

166# Connect PrimitiveCreate output to Merge input# Get the out port of the PrimitiveCreate nodeprimitiveOut = primitive.getOutputPort( "out"

167NodegraphAPI.SetNodePosition( primitiveGroup,\primitivePosition )# Get the output port on the PrimitiveCreateprimitiveGroupOut = primitiveGroup.get

168The diagram below shows an example of physical and logical connections in the Node Graph. Nodes A and B havephysical connections to inputs on the S

169# Create a PrimitiveCreate node at root levelprimitive = NodegraphAPI.CreateNode\( 'PrimitiveCreate', root)# Create a Merge node at root

17hierarchy in the UI. Complexity is controlled by only executing filters on locations in the scene graph that the userhas expanded.A scene does not n

170switchOutput = switch.getOutputPort( "output" )# Create a Render node at root levelrender = NodegraphAPI.CreateNode( 'Render',

171• String ArrayAn array of string objects. Requires name and size arguments.Top Level User ParametersAs covered in Getting the Parameters of a Node

172# Get root levelroot = NodegraphAP.GetRootNode()# Create a PrimitiveCreate node at root levelprim = NodegraphAPI.CreateNode( 'PrimitiveCreate&

173It is possible to write an expression that will reference a node by name and not break when the node name changes,see Appendix B: Expressions In th

174Enableable Parameter GroupsAn Enableable Parameter Group is a parameter that has a default value, but can also take on a locally set value. Theloca

175Dynamic Arrays for PRMan Shader ParametersKatana has a widget type dynamicArray, which was added to support PRMan shaders with dynamic arrayparamet

24 Op APIThe Op API supersedes the Scene Graph Generator (SGG) and the Attribute Modifier Plug-in (AMP)APIs that were previously used in pre-2.0v1 ver

177also process incoming attributes - the equivalent to Attribute Modifiers. In fact, Geolib3 Ops are a super-set of bothAPIs and, in practice, no dis

178Core Concepts with Geolib3There are three core concepts in Geolib3 that pertains to the Op API: the Runtime, Ops and Clients. In the sectionsbelow,

179From a technical perspective, you can interact with the Runtime through a C++ or Python interface, which provides agreat deal of flexibility in how

3 Custom Render ResolutionsYou can define custom render resolutions to supplement or replace Katana's pre-defined resolutions. You can definereso

180change which Op runs at child locations, substituting out your OpArgs, the Optype, or even calling into another Opentirely, these can be ignored du

181ClientsIn order to view the scene graph locations and attributes generated as a result of evaluating Ops, such as to walk thescene graph to declare

182You can find concrete examples of the above concepts in the $KATANA_HOME/plugins/Src/Ops directory wherethe source code for a number of core Ops is

183For example, the StaticSceneCreate Op accepts a GroupAttribute called a that contains a list of attributes, whichcontain values to set at a given l

184The Op running at its current location will read a, c, and x. For each child GroupAttribute of c it creates a new childlocation with the GroupAttri

185NOTE: It is important to remember the distinction between the set of functions described here and thosedescribed in Reading Scene Graph Input on pa

186If you specify optype as an empty string, the same Op that called create child is evaluated at the child location.However, you can specify any othe

187 } interface.execOp(opType.getValue("", false), opArgs); }}The deleteSelf() Functionvoid deleteSelf();Thus far, we ha

188 /geo /taco /lightSo we use a StaticSceneCreate Op to create this additional hierarchy at the starting location /root/w

189WARNING: It is worth noting that, given the deferred processing model of Geolib3, the “get” functions,such as getAttr(), getPotentialChildren(), do

19are all nested in <formats> elements and take the form:<format width="[int]" height="[int]" pixelAspect="[float]&q

190The getPotentialChildren() FunctionFnAttribute::StringAttribute getPotentialChildren( const std::string& inputLocationPath = std::string(),

191CEL and UtilitiesThere are a number of tasks that Ops are frequently required to complete, such as:• Creating a hierarchy of locations,• Determinin

192Integrating Custom OpsAt start up, Katana looks for .so files in every Ops sub-folder for each entry within the KATANA_RESOURCESenvironment variabl

193The GenericOp node converts the contents of its opArgs parameter into the opArgs GroupAttribute required by theOp using an existing parameter-to-at

1942. The CreateOp.py script creates a folder in your current working directory for each <Op_Name> you specify. Thehierarchy of the directory cr

195locationDataChangeEvents = client.getAndResetChangedLocations()if not locationDataChangeEvents: return# Iterate over each location we've be

196Calling evict() has the effect of clearing the scattered query cache completely. This is data that was asked for in theprocess of cooking locations

197• Use the cook() function to determine what should happen for given locations, and delegate the logic for thoselocations to other static functions.

25 NodeTypeBuilderNodeTypeBuilder is a Python class that makes it easy to define new 3D nodes that a user caninstantiate in their Katana project. It i

199current Ops in the Op Tree from a previous run. If any changes have been made, those Ops are reconfigured/dirtied,and a re-cook triggered, if appro

Katana™ Technical Guide. Copyright © The Foundry Visionmongers Ltd. All Rights Reserved. Use of this Technical Guide and the Katanasoftware is subject

20Startup folder, under the path defined in the KATANA_RESOURCES environment variable. Alternatively, you can usea startup script in the form of an in

200The best way to install one of the custom nodes is to put the code in a Python file that calls itself, that is to say thatdefines the functions, an

26 Creating a GenericAssign-based Node TypeGenericAssign is a whole class of node types, which are defined by XML files that are usually kept in Gener

202Additionally, a GenericAssign can be called anywhere UI4 is available, though ideally at start-up. It can also bemanually called in the Python tab

203Editing GenericAssign MechanismsThe GenericAssign mechanism can be edited so that Katana recognizes the XML attribute "enabled/enabled" a

27 Asset Management SystemPlug-in APIThe Katana Asset plug-in API is a Python and C++ interface for integrating Katana with asset management systems.

205As it’s a single string, an Asset ID can be passed as part of an argument string to a subprocess, such as a shellcommand or a procedural. It is imp

206The transaction is final only after the endTransaction( commit ) operation.A transaction must have a commit method and a cancel method. The cancel

207Convert an Asset ID to a file path.• resolvePath()Convert an Asset ID and a frame number to a file path.Publishing an AssetThe methods for publishi

208A dictionary containing additional information about what asset type to create. For example, should we incrementthe asset version? Is it an image,

209Asset Types and ContextsThe following asset types are available to the AssetAPI module:• Katana projectkAssetTypeKatanaScene• MacrokAssetTypeMacro•

4 Custom Node ColorsYou can set the display color of individual nodes through the UI by selecting a node, then choosing Colors, then acolor from the p

210• kAssetContextLiveGroup.• kAssetContextImage.• kAssetContextLookFile.• kAssetContextLookFileMgrSettings.• kAssetContextAlembic.• kAssetContextScen

211reset()Triggered when the user requests that Katana flush its caches. This is used to clear local Asset ID caches to allowretrieval of the latest v

212createTransaction()It allows Katana to create assets in bulk. If createTransaction is implemented to return a custom transaction object,then the ob

213getRelatedAssetId()Given an Asset ID and a string representing a relationship or connection, returns another Asset ID. For example, witha shader fi

214The casting sheet example plug-in uses this method and Python expressions have access to an assetAttr built-inmethod that retrieves asset attribute

215• shot = ts520• show = srow• username = name• workstation = seatWhen the function to run a custom asset plug-in command is called the asset API plu

216Configuring the Asset BrowserThe entry point for extending the Katana asset browser is the method configureAssetBrowser(), which must beimplemented

217The Asset Control WidgetThe AssetWidgetDelegate plug-in API makes it possible to replace the default string widget that allows users to viewand edi

218Asset Render WidgetThe Asset Widget Delegate allows customization of the display of the render output location shown in a Rendernode’s Parameters t

219shouldAddStandardMenuItem()When False is returned from this method, the menu item to the right of an Asset ID in the Parameters tab is notdisplayed

22Editing RulesYou can edit rules and add new ones by overwriting list entries using Nodes2DAPI.NodeColorDelegate. Forexample, to edit the color assoc

220The C++ APIYou can implement an Asset plug-in in C++ as well as in Python. This is done by inheriting from the FnAsset class inthe C++ plug-in SDK.

28 Render Farm APIThe Render Farm Python API is an interface with hooks and utility functions for customizing the way jobs aresubmitted to a render fa

222initialization is complete:from Katana import Callbacksdef onStartup(**kwargs):passCallbacks.addCallback(Callbacks.Type.onStartup, onStartup)The on

223def runMyOption(**kwargs):print(“My Render Farm Menu Option has been clicked”)def onStartup(**kwargs):FarmAPI.AddFarmPopupMenuOption("My Rende

224Render nodes that depend on this render node require all of its outputs to complete before the next process islaunched.• forceFarmOutputGenerationF

225Key Type Description2Dor3D String Describes whether the node works with 2D or 3D data. AnImageWrite node is 2D, while a Render node is 3D.dependAll

226Render Passes and OutputsAs with Render Dependencies, the sequence of dictionaries returned by GetSortedDependcyList() contains thenames, paths, an

227The following example script defines a function that produces a sequence with each entry containing the name of anoutput, the path for the image fi

228renderNodeInfo = FarmAPI.GetSortedDependencyList()farmFilePath = UI4.Util.AssetId.BrowseForAsset( '', 'Specify a filename', \Tr

229• NODES_SELECTED• NODES_ALLThe function GetNodeList() retrieves the nodes specified by the nodeScope, if IsSceneValid() was successful. Forexample:

23Creating New FlavorsTo add a new flavor, enter the following in the Python tab:NodegraphAPI.Flavor.AddNodeFlavor( 'nodeName', 'flavor

230Name Type DescriptionGetClickedNode() Node Returns the node currently under the mouse, if themouse has been clicked.GetSceneFrameRange() Dictionary

Appendix A: Custom KatanaFiltersThere are two C++ APIs for writing new scene graph filters: the Scene Graph Generator API and Attribute ModifierAPI. S

232Documentation of the API classes is provided in:• ${KATANA_ROOT}/docs/plugin_apis/html/group__SG.htmlAttribute ModifiersAttribute Modifier plug-ins

Appendix B: Other APIsFile Sequence Plug-in APIAPI that tells how a file sequence should be described as a string, and how to resolve that string into

234Viewer Manipulator APIPython API to allow rules to be set up to connect OpenGL manipulators in the viewer to custom shaders, and tocreate new custo

Appendix C: GlossaryGlossaryNodeA reusable user interface component for processing a Katana Scene Graph in a deferred manner. A node containsparameter

236HintMetadata that contains information about how a piece of Katana data will be presented in the user interface.Katana Scene GraphA data tree conta

Appendix D Standard AttributesKey LocationsThe following table gives an overview of the standard attributes conventions at various important Scene Gra

238Attribute and Location Type DescriptionrenderSettings.cameraName(not inherited)string The scene graph location of the camera,for example,/root/worl

239Attribute and Location Type DescriptionrenderSettings.outputs.<passname> Contains a sub group for every renderpass. The default pass is named

24Making Updates PersistRules and flavors created or modified within the Python tab expire with the Katana session. Using the Node Graphand Nodes2DAPI

240Attribute and Location Type DescriptionrenderSettings.outputs.<passname>.rendererSettings.locationType (not inherited)string The type of loca

241Attribute and Location Type Descriptionviewer.default.drawOptions.smoothing string The smoothing setting used in theViewer.viewer.default.drawOptio

242Location Type or Attribute Type DescriptionGroup Attributes The following attributes are commonlyfound on groups but can be found at anylocation ty

243Location Type or Attribute Type DescriptionattributeModifiers.<modifierName>.recursiveEnable integer Indicates if recursion is enabled.attrib

244Location Type or Attribute Type Descriptionxform.<group> The xform attribute contains a sub-groupfor every transform in the order thesetransf

245Location Type or Attribute Type Descriptionxform.<group>.rotateX(not inherited)double4 The first number indicates the angle ofrotation. The r

246Location Type or Attribute Type Descriptiongeometry.point.P float3[ ] List of points. The geometry points areunique floating point positions in obj

247Location Type or Attribute Type Descriptiongeometry.poly.startIndex integer[ ] Is a list of indices defining the faces of amesh. For example, consi

248Location Type or Attribute Type Descriptiongeometry.poly.vertexList integer[ ] The vertexList describes the vertex data of amesh. There is a vertex

249Location Type or Attribute Type Descriptiongeometry.arbitrary.<group>.scope group The scope of the attribute. Valid values are:primitive (equ

25Flavor APIAPI UsageNodegraphAPI.FlavorAddNodeFlavor( ) Adds a new flavorSyntax:Takes two strings, the node type, and the flavor name.AddNodeFlavor(

250Location Type or Attribute Type Descriptiongeometry.arbitrary.<group>.index integer[ ] List of indexes (if no index is present, theindex is i

251Location Type or Attribute Type Descriptiongeometry.facevaryingpropagatecorners A single integer flag, used by PRMan in theRiHierarachicalSubdivisi

252Location Type or Attribute Type Descriptiongeometry.point.radius float[ ] The spheres radii.geometry.constantRadius float Can be used instead ofgeo

253Location Type or Attribute Type Descriptiongeometry.numVertices float[ ] The number of vertices in each curve.The following XML is from a Scene Gra

254Location Type or Attribute Type Descriptiongeometry.point.P float3 List of points. The geometry points areunique floating point positions in object

255Location Type or Attribute Type Descriptiongeometry.u.knotsgeometry.v.knotsfloat[ ] Knot vector, a sequence of parametervalues.geometry.trimcurves

256Location Type or Attribute Type DescriptionGeometry > lightlight Location type to declare a light.geometry Shares the same attributes as camera.

257Location Type or Attribute Type DescriptionInstancing > Arnold > geometryinstance.ID string A string attribute instance.ID. Locationssharing

258Location Type or Attribute Type Descriptioninstance.arbitrary group Follows the same conventions asgeometry.arbitrary for specifying per-instance p

259Location Type or Attribute Type Descriptiongeometry.type string This attribute controls how the volumelocation is interpreted. Different renderplug

26API UsageNodegraphAPI.FlavorGetFlavorNodes( ) Gets a list of all nodes in a given flavor.Syntax:Takes a single string, the name of the flavor.GetFla

260Location Type or Attribute Type DescriptionOther > riblobbydso The riblobbydso is a convenience type thatis mapped to a single 1004-opcodeRiBlob

261Location Type or Attribute Type DescriptionOther > rivolume The rivolume type is mapped to a PRManRiVolumeV call. The shape attribute valuemust

262Location Type or Attribute Type DescriptionOther > rivolumedso The rivolumedso type is mapped to aPRMan RiVolumeV call using theblobbydso: prefi

263Location Type or Attribute Type Descriptiongeometry.stringargs string[ ] String parameters of the primitive fields(optional).bounds double6 See Loc

264Location Type or Attribute Type DescriptionlodRanges float MinVisiblefloat maxVisiblefloat lowerTransitionfloat upperTransitionThese values can be

27API UsageNodegraphAPI.FlavorNodeMatchesFlavors( ) Checks to see if a specified node is in a specified flavor, and not in anyspecified ignore flavors

28API UsageNodegraphAPI.FlavorRemoveNodeFlavor( ) Deletes a flavor.Syntax:Takes a single string, the name of the flavor to remove.RemoveNodeFlavor( &a

5 Message LoggingError, warning, and informational messages are logged in Katana using the logging module of the Python StandardLibrary. Messages are

Contents1 PrefaceTerminology132 Katana For The ImpatientWhat Is Katana?14A Short History of Katana15Scene Graph Iterators16The Katana User Interface16

30logging.debug("This is a debugging message.")Custom LoggerInstead of using the root logger, you can create a custom logger object. The fol

31Logging ExceptionsExceptions can be logged in a way that automatically includes traceback information in the log message, as in thefollowing example

6 Katana Launch ModesLaunching KatanaYou can start Katana in a number of different modes, using command line arguments to start the application:Intera

331. Open a terminal.2. Navigate to the directory where you installed Katana.3. Enter:./katana /yourDirectory/yourScene.katanaYou can also specify an

34Option Usage--katana-file Specifies the Katana recipe to load.Syntax:--katana-file=<filename>Example:./katana --batch --katana-file=/tmp/test.

35Option Usage--threads2d Specifies the number of additional processors within the application.An additional processor is also used for Katana's

36Option Usage--render-internal-dependencies Allows any render nodes that don't produce asset outputs to berendered within a single katana --batc

37Option Usage--tile-render Used to render one tile of an image divided horizontally and verticallyinto tiles. For instance, using--tile-render=1,1,3,

38Option Usage--tile-stitch Used to assemble tiles rendered with the --tile-render flag into acomplete image.When stitching, you must still pass the -

39Option Usage--make-lookfilebake-scripts Used to write out a number of Python files that can be executed inbatch mode to write look files.Syntax:--ma

6 Katana Launch ModesLaunching Katana32Interactive Mode 32Batch Mode 33Script Mode 40Shell Mode 40Querying Launch Mode 417 Scene Attributes and Hierar

40Script ModeScript mode allows you to execute Python scripts in Katana's Python environment. Script mode requires the --scriptflag, followed by

412. Navigate to the directory where you installed Katana.3. Enter:./katana --shellQuerying Launch ModeTo query the current Katana launch mode, call Q

7 Scene Attributes andHierarchyA key principle to working with Katana is that it doesn't matter where scene graph data comes from, all that matte

43These requirements are broadly similar to Python's naming rules. For more information, refer tohttps://docs.python.org/2/reference/lexical_anal

44For cameras and lights.• geometry.arbitrary is used to hold arbitrary data to be sent to the renderer together with geometry, such asprimvars in Ren

45It is this filter tree description that is handed to output processes such as RenderMan or Arnold. This is done byhanding a serialized description o

46CEL In the User InterfaceIn the UI a standard CEL Widget interface is provided for CEL expressions. For the convenience of users this allowsusers to

47Make CEL Statements as Specific as PossibleThe expense is generally in running operations at nodes rather that evaluating if a location matches a CE

48Paths Versus RulesCEL has a number of optimizations for dealing with explicit lists of paths. This means using paths are the best way ofworking in m

8 Scene Graph Generator Plug-InsKatana's operation revolves around two graphs: the Node Graph and the Scene Graph. To reiterate, here are someof

Defining the getAttr and getOutputAttr Functions69Recompiling Existing SGG and AMP Plug-ins70Source Locations 70Additional Build-ins 70Behavioral Diff

50Running an SGG Plug-inThe creation of scene graph data by SGG plug-ins is executed through the ScenegraphGeneratorResolve node orthrough an implicit

51...numberOfCubes 23rotateCubes 1rotateCubes__hints group attribute (used for UIwidget "checkBox"resolveIds (optional).NOTE: The Scenegraph

52Generated Scene Graph StructureInternally, Scene Graph Generator plug-ins use contexts to create new locations in the scene graph. A scene graphloca

53SGG Plug-in API ClassesThis section details the two classes that are provided in the Scene Graph Generator plug-in API to implement acustom SGG:• Sc

54Class DiagramScenegraphGeneratorThe ScenegraphGenerator class provides the main entry point for the plug-in. Any new plug-in must extend thisinterfa

55responsible for generating the root location is. In order to write a custom SGG plug-in, both of these classes have tobe derived and their abstract

56The create() function is not declared in the ScenegraphGenerator class in the API, but is used in the DEFINE_SGG_PLUGIN(class) macro, which makes th

57Instance MethodsThe following instance methods are to be implemented in a class derived from the abstract ScenegraphGeneratorclass:• bool checkArgs(

58_numberOfCubes = numberOfCubesAttr.getValue(20, false);// Update the rotation flagFnKat::IntAttribute rotateCubesAttr = \ args.getChildByName(&quo

59void registerPlugins(){REGISTER_PLUGIN(CubeMaker, "CubeMaker", 0, 1);}DEFINE_SGG_PLUGIN(class)Declares a data structure of Katana's p

Groups93Macros94Adding User Parameters 94Conditional Behavior 96Super Tools99Registering and Initialization 100Node 100Editor 101103Examples 10314 Res

60ConstructorAs in a class derived from ScenegraphGenerator, the constructor in a class derived from ScenegraphContext can beused to initialize instan

61CubeRootContext::getFirstChild() const{if (_numberOfCubes > 0){return new CubeContext(_numberOfCubes, 0);}return 0x0;}The function checks if a nu

62Instance Methods for AttributesThe following two instance methods define the names, types, and values of attributes that should live on the currentc

63In certain cases, like when viewing all attributes of a scene graph location in the Attributes tab, Katana iterates overall names provided by the ge

64Attribute data for a "geometry" group attribute may consist of child group attributes like "point", "poly", "vert

65To provide an error message the getLocalAttrNames() function can add the errorMessage name to the list ofattribute names it modifies, and the getLoc

66else if (name == "xform"){FnKat::GroupBuilder gb; double translate[] = {0.0, 0.0, -10.0}; gb.set("translate",FnKat::Double

67return new CubeContext(_numberOfCubes,_rotateCubes,_index + 1);}return 0x0;}The files in $KATANA_ROOT/plugins/Src/ScenegraphGenerators/ offer more c

9 Porting Plug-insThis chapter covers information on how to port existing Scene Graph Generator and AttributeModifier Plugins to the new Op API in pos

69• Ops also have visibility on the incoming scene, whereas SGGs do not.This means you no longer patch together the data in a piecemeal fashion. This

Registering the GUI 123Adding Importomatic Items Using a Script 12417 Handling TexturesDifferent Approaches to Determine Texture125Materials With Expl

70If you wish to query an inherited attribute, you need to use the utility function in FnGeolibCookInterface.h:Foundry::Katana:GetGlobalAttr.To learn

71In Katana 2.0v1 and later, the SGG host Op only sets attributes that you name in getLocalAttrNames whencooking the location. Consequently, you may n

726. I make use of other SGGs, for example Alembic_In, at child locations created by my SGG. Is this aproblem?Just swap the Op out at the child locati

73It 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 g

10 Structured Scene Graph DataWhile Katana can handle quite arbitrarily structured scene graph data, there are a number of things worthconsidering, fr

75By default Katana understands proxies created using Alembic, which are simply declared using the path to therelevant .abc file. You can also customi

76be used. Under each of these locations you have separate branch of the hierarchy that declares the actual geometryused for that LOD representation o

77ScenegraphXMLScenegraphXML is provided with Katana as a simple reference format that can be using to bring structuredhierarchical scene data into Ka

11 Look FilesKatana's Look Files are a powerful general purpose tool that can be used in a number of ways. In essence theycontain a baked cache o

79Look File BakingLook Files are written out by using the LookFileBake node. Using this node you have to set one input to a point inthe nodegraph wher

21 Locations and AttributesInheritance Rules for Attributes153Setting Group Inheritance using the API153Light Linking 15322 PRMan Technical NotesUse o

80• Adding face-sets to objects for per-face shader assignment.• Per-object render settings, such as renderer specific tessellation settings.• Definin

81• Currently you can't delete scene graph locations using Look Files, you can only add new locations or modify existingones. For instance to hid

82pre-define standard shader sets for lights (including light shaders made out of network shaders) to be brought in forLighting.Materials can be writt

12 User Parameters and WidgetTypesNodes usually come with a predefined set of parameters that control their behavior. You can also add customparameter

84Parameter Type DescriptionColor, RGB A three element array of floats corresponding to the red, green, and bluechannel values of an RGB color.Color,

85Parameter Type DescriptionGroup You can place user adjustable variables, and other interface elements, in a Groupinside a Macro's User Interfac

86NOTE: The widget type of a parameter can also be defined by setting a widget hint string. See ParameterHints for more on this.Katana also has a dyna

87Type Description OptionsScenegraphLocationsOffers the user dialog boxesto browse for multiple scenegraph locations. Can be usedto pass the selected

88Type Description OptionsAsset Offers the user a dialog box tobrowse for an asset by assetID, and stores the selection.Can be used to pass theselecte

89Type Description OptionsFile Path Offers the user a dialog box tobrowse for an external file,and stores the selection. Canbe used to pass the select

24 Op APIOp API Basics176The OpTree 177Core Concepts with Geolib3178Differences Between Geolib2 and Geolib3 178The Runtime 178Ops 179Clients 181The Op

90Type Description OptionsMapping Pop-upMenuUsed to define a drop-downmenu, and return a differentvalue to the one shown in theselected menu entry. Fo

91Type Description OptionsMulti Mimics the structure of aCameraCreate node’sscreenWindow parameter.Unlike a screenWindow, aMulti is created empty, and

92User Parameter Available Widget TypesButton Default, Scenegraph Location, CEL Statement, Resolution, Asset, File Path,Boolean, Pop-up Menu, Mapping

13 Groups, Macros, and SuperToolsGroups, Macros and Super Tools are ways of creating higher level compound nodes out of other nodes. Groups andmacros

94MacrosMacros are nodes that wrap any single node, or group of nodes, and publish them so that their state is saved andthey can be recalled in other

95this works, the user could easily break it by entering an invalid string. It is better to present the user with a series ofknown, valid choices in t

966. Edit the pop-up menu to add new entries, each corresponding to a valid PrimitiveCreate node type.In the wrench menu of the new parameter, choose

97Conditional Visibility Example1. Create a Katana scene with a PrimitiveCreate node, a Material node, a CameraCreate node, and a Merge node.Connect t

98> Finish Editing User Parameters, the pop-up menu displays in the group’s Parameters tab, and its valueselects the renderer.The state of the pop-

993. In the Conditional Visibility Options window, click on the icon to choose the user parameter to testagainst, and select the pop-up menu from the