Serializing Nodes

Duplicating Nodes

Serialize to XML

Katana uses a copy and paste pattern to duplicate node graph nodes, which means that to copy a node you must serialize it to XML using BuildNodesXmlIO(), then deserialize. For example, to create then serialize a PrimitiveCreate node referenced by node enter the following:

# Get the root node
rootNode = NodegraphAPI.GetRootNode()

# Create a new node at root level
rootNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)
nodesToSerialize = [rootNode]
xmlTree = NodegraphAPI.BuildNodesXmlIO(nodesToSerialize)

Note

BuildNodesXmlIO() accepts a sequence of nodes, so a network of nodes can be serialized in a single operation.

Deserialize

Use KatanaFile.Paste() to deserialize an XML tree. The XML tree can contain an arbitrary number of nodes, and the contents are pasted under a given location, which can be either the node graph top level (the root node) or any Group-like node.

For example, to paste the XML created earlier under the root node enter the following:

rootNode = NodegraphAPI.GetRootNode()
KatanaFile.Paste(xmlTree, rootNode)

Printing An XML Tree

It can be useful to print the serialized XML tree of a node to see what it contains. For example, to view the XML of the merge in the example above node enter the following:

print(xmlTree.writeString())

which, depending on your Katana version, prints:

<katana release="1.5" version="1.5.1.000001">
  <node name="__SAVE_exportedNodes" type="Group">
    <node baseType="Merge" name="Merge" type="Merge" x="228.000000" y="-311.000000">
      <port name="input" type="in"/>
      <port name="Second" type="in"/>
      <port name="output" type="out"/>
      <group_parameter name="Merge">
        <string_parameter name="showAdvancedOptions" value="No"/>
        <group_parameter name="advanced">
          <string_parameter name="sumBounds" value="No"/>
          <string_parameter name="preserveWorldSpaceXform" value="No"/>
          <stringarray_parameter name="preserveInheritedAttributes" size="0" tupleSize="1"/>
          <group_parameter name="preferredInputAttributes">
            <stringarray_parameter name="name" size="0" tupleSize="1"/>
            <numberarray_parameter name="index" size="0" tupleSize="1"/>
          </group_parameter>
        </group_parameter>
      </group_parameter>
    </node>
  </node>
</katana>

Project Serialization

NodegraphAPI.GetNodegraphVersionString(xmlString)

Get the nodegraph version string. When loading from a file, the nodegraph gets a version.

Return type:

str

NodegraphAPI.LoadXmlFromFile(fileName)

Load a Katana file into a string of XML. Normally the xml intermediate format is not required. Use LoadElementsFromFile to get the direct xml tree.

NodegraphAPI.WriteKatanaFile(filename, element, compress=True, archive=True, opaqueParams=None)

Writes an XML text representation of the given XML element and its contents, optionally in compressed and/or archived form, to the file with the given filename on disk.

Parameters:

  • filename (str) – The name of the file to write.

  • element (PyXmlIO.Element) – An XML element representing the document for which to create an XML text representation.

  • compress (bool) – Flag that controls whether to use zlib to compress the data to write to the file. Only applicable when archive is False.

  • archive (bool) – Flag that controls whether to bundle the XML representation of the given element in a file named scene/scene.katana inside of a tarball that is copmressed using gzip.

  • opaqueParams (dict or None) – A dictionary with full names of parameters as keys and parameter objects as values, whose opaque data info, as retrieved by calling NodegraphAPI.Parameter.getOpaqueDataInfo(), to store in additional files named scene/<fullParameterName>/opaque<index>.data in the tarball. Only applicable when archive is True.

NodegraphAPI.LoadXmlFromString(stringData)

Load a Katana string into a string of XML. Normally the xml intermediate format is not required. Use LoadElementsFromString to get the direct xml tree.

NodegraphAPI.WriteKatanaString(element, compress=True, archive=True, opaqueParams=None)

Creates and returns an XML text representation of the given XML element and its contents, optionally in compressed and/or archived form.

Return type:

str

Parameters:

  • element (PyXmlIO.Element) – An XML element representing the document for which to return an XML text representation.

  • compress (bool) – Flag that controls whether to use zlib to compress the data in the returned string. Only applicable when archive is False.

  • archive (bool) – Flag that controls whether to bundle the XML representation of the given element in a file named scene/scene.katana inside of a tarball that is copmressed using gzip.

  • opaqueParams (dict or None) – A dictionary with full names of parameters as keys and parameter objects as values, whose opaque data info, as retrieved by calling NodegraphAPI.Parameter.getOpaqueDataInfo(), to store in additional files named scene/<fullParameterName>/opaque<index>.data in the tarball. Only applicable when archive is True.

Returns:

An XML text representation of the given XML element and its contents.

Node Graph Serialization

NodegraphAPI.ParseNodegraphXmlIO(element, sourcePath='', isCrashFile=False)

Replaces the current Katana scene with a new scene loaded from the given XML element. The XML node graph will be upgraded to the current version.

Parameters:

  • element (PyXmlIO.Element) – An XML element that represents the root of the new Katana scene to create.

  • sourcePath (str) – The full path of a Katana file from which the given element was created, or an empty string to reset the current Katana scene filename.

  • isCrashFile (bool) – Flag indicating whether the file with the given source path has been saved as an autosave from which a project can be restored after a crash.

NodegraphAPI.BuildNodegraphXmlIO(forcePersistant=False, opaqueParams=None, isAutoSave=False)

Build XmlIO element tree from node graph. This returns the top element encapsulated in a root katana element.

NodegraphAPI.ParseNodesXmlIO(element, emit=True, floatNodes=False, sourcePath='', loadLiveGroups=True, lockLiveGroups=True, isParentContextNME=False)

Loads a scene from the given XML element into the current Katana scene. The XML node graph will be upgraded to the current version.

Return type:

list

Parameters:

  • element (PyXmlIO.Element) – An XML element that represents the root of the Katana scene to load into the current Katana scene.

  • emit (bool) – Flag that controls the type of events added to Katana’s event queue. It set to True, "nodegraph_loadBegin" and "nodegraph_loadEnd" events are added at the start and end of the loading process, respectively. If set to False, "nodegraph_silentLoadBegin" and "nodegraph_silentLoadEnd" events are used instead.

  • floatNodes (bool) – Flag that controls whether the loaded nodes are to be floating in the B{Node Graph} tab, so that the user can place them manually, or whether the node positions stored in the given node graph are used to place the loaded nodes in the current Katana scene.

  • sourcePath (str) – The full path of a Katana file from which the given element was created, or an empty string if the element was not created from a Katana file. Only used for log messages.

  • loadLiveGroups (bool) – Flag that controls whether to load all new LiveGroup nodes in the scene.

  • lockLiveGroups (bool) – Flag that controls whether to lock all new LiveGroup nodes in the scene. Only effective when loadLiveGroups is set to True.

Returns:

A list of nodes that are present in the root level of the loaded Katana scene.

NodegraphAPI.BuildNodesXmlIO(nodes, forcePersistant=False, opaqueParams=None, requireSiblings=True, progressCallback=None, includeNonPersistentNodes=False)

Creates a <katana> XML element that represents a Katana node graph document, with child XML elements that describe the given nodes with all of their ports, connections, parameters, and children.

Adds the XML elements that represent the given nodes underneath a <node> XML element that represents a Group within the resulting <katana> XML element. The name of that Group is set to "__SAVE_exportedNodes", possibly followed by a numeric suffix.

Adds a <shared> XML element to the resulting <katana> XML element, to which <liveGroup> XML elements are added that describe LiveGroup assets that are shared between a couple of LiveGroup nodes, so that they are defined in the resulting node graph XML document only once. The <shared> XML element is not added if the KATANA_NEVER_SHARE_LIVE_GROUPS environment variable is set.

Return type:

PyXmlIO.Element or None

Parameters:

  • nodes (list of NodegraphAPI.Node) – The list of nodes for which to create XML elements.

  • forcePersistant (bool) – Flag that controls whether non-persistent parameters are to be included in the XML representation of a node.

  • opaqueParams (dict or None) – An optional dictionary that will be modified to store opaque parameters, with full names of opaque parameters as keys and NodegraphAPI.Parameter instances as values.

  • requireSiblings (bool) – Flag that controls whether a ValueError exception is raised if the given nodes don’t all have the same parent node.

  • progressCallback (callable or None) – An optional callable object that is expected to return a boolean to indicate whether the operation can continue (True) or should be aborted (False). Can be used to update a progress dialog in the UI which lets the user cancel the operation that the call of this function is a part of.

Returns:

A <katana> XML element that represents a Katana node graph document, with child XML elements that describe the given nodes with all of their ports, connections, parameters, and children, or None if the operation has been aborted, as determined by the optional progress callback.

Note:

Opaque parameters are those whose data is written to external file(s) or that are included as opaque child XML elements.

Raises:

ValueError – If the given list of nodes is empty, or if requireSiblings is True and the given nodes don’t all have the same parent node.

NodegraphAPI.LoadElementsFromFile(fileName, versionUp=True)

Get the XmlIO element tree from file on disk. Returns the element and a boolean if the data was upgraded.

NodegraphAPI.LoadElementsFromString(xmlString, versionUp=True)

Get the XmlIO element tree from string in memory. Returns the element and a boolean if the data was upgraded.

NodegraphAPI.GetUserNodesXmlRootAttrs()
NodegraphAPI.SetUserNodesXmlRootAttrs(attrDict)