Serializing Nodes
=================

.. currentmodule:: NodegraphAPI

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 :func:`BuildNodesXmlIO`,
then deserialize. For example, to create then serialize a
:kat:node:`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:: :func:`BuildNodesXmlIO` accepts a sequence of nodes, so a network of
    nodes can be serialized in a single operation.

Deserialize
'''''''''''

Use :func:`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
:kat:node:`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:

.. code-block:: xml

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

.. autofunction:: GetNodegraphVersionString
.. autofunction:: LoadXmlFromFile
.. autofunction:: WriteKatanaFile
.. autofunction:: LoadXmlFromString
.. autofunction:: WriteKatanaString


Node Graph Serialization
------------------------

.. autofunction:: ParseNodegraphXmlIO
.. autofunction:: BuildNodegraphXmlIO
.. autofunction:: ParseNodesXmlIO
.. autofunction:: BuildNodesXmlIO
.. autofunction:: LoadElementsFromFile
.. autofunction:: LoadElementsFromString
.. autofunction:: GetUserNodesXmlRootAttrs
.. autofunction:: SetUserNodesXmlRootAttrs