OMC::Node Class Reference

Detailed Description

The node wrapping object. Represents a specific node in the scene.

The node object represents a node within a scene. This object will maintain its link, even if the node is renamed. Some operations, such as copying and pasting, as well as moving nodes will result in this object no longer being valid.
The node object provides access to the node's details, ports and attributes and is useful for automatic rig tasks in a scene.

There exists multiple subclasses of the node object, these provide custom utilities for specialized node types:

• OMC::CameraNode : Represents a Camera node.
• OMC::DisplayNode : Represents a Display node.
• OMC::GroupNode : Represents a Group node.
• OMC::PegNode : Represents a Peg.
• OMC::ReadNode : Represents a Read/Drawing node.
  Each node specialization provides unique methods and properties for that node type, which simplifies automation with that specific node. This means that different node types will have different methods and properties available, but all nodes will inherit all standard methods from this base class.
  
  Identify All Nodes in a Scene:

  from ToonBoom import harmony                                 #Import the Harmony Module
  sess = harmony.session()                                     #Get access to the Harmony session, this class.
  proj = sess.project                                          #Get the active session's currently loaded project.
  scene = proj.scene                                           #Get the top scene in the project.
  nodes = scene.nodes                                          #Get the node list of the scene.
  
  #Iterating on the node list with a for-loop
  for node in nodes:                                            #For loop on the node list.
    print( "Node : %s"%(node.path) )

  
  

  ---

  
  Find Only Pegs in the Scene

  from ToonBoom import harmony                                 #Import the Harmony Module
  sess = harmony.session()                                     #Get access to the Harmony session, this class.
  proj = sess.project                                          #Get the active session's currently loaded project.
  scene = proj.scene                                           #Get the top scene in the project.
  nodes = scene.nodes                                          #Get the node list of the scene.
  
  #Iterating on the node list with a for-loop
  for node in nodes:                                            #For loop on the node list.
    if node.type.upper() == "PEG":                             #A upper-case comparison is useful for case-insensitivity. 
      print( "Peg : %s"%(node.path) )                           

  
  

  ---

Public Member Functions
OMC::Scene *	parent_scene () const
	Getaaa the parent scene for the node. More...
OMC::GroupNode *	parent_group () const
	Gets the parent group for the node. More...
void	move_to (const QString &groupPath, int x=0, int y=0)
	Moves the node into a group. More...
void	move_to (OMC::GroupNode *groupPath, int x=0, int y=0)
	Moves the node into a group. More...

Public Attributes
OMC::AttributeList *	attributes
	Provides the list of attributes of the node. More...
OMC::PortList *	ports_in
	Provides the list of input ports belonging to the node. More...
OMC::PortList *	ports_out
	Provides the list of output ports belonging to the node. More...
QString	name
	Get/set the name of the node. More...
QString	path
	Get the path of the node. The path of the node is the absolute location of a node within a scene, including its name. The node's path provides the absolute location and the name of the node and can be used to both move and rename the node as needed. More...
QString	type
	Get the type of the node. More...
OMC::Node_Coordinates *	position
	The position of the node in the node view. More...
bool	enabled
	Get/set whether the node is enabled. More...
bool	cached
	Get/set whether the node is cached. More...
bool	locked
	Get/set whether the node is locked. More...
OMC::Node::Colour *	colour
	Get/set the colour of the node. More...
bool	cacheable
	Get whether the node can be cached. More...
int	version_max
	Get the max version of the node available. More...
int	version
	Get and set the version of the node. More...
OMC::Port *	matte_port
	Returns the matte port, if one exists. More...
bool	thumbnail_timeline
	Get and set whether the node shows a thumbnail in the timeline. More...
OMC::NodeDataHandler *	data
	The data handler that manages node data for views and tools. More...
OMC::MetaDataHandler *	metadata
	The metadata handler object to provide metadata information. More...
bool	valid
	Whether the bool is currently valid and the node still exists in the scene. More...
OMC::NodeSubselectionList *	subselections
	A list of subselectable objects that belong to the node. More...

Member Function Documentation

move_to() [1/2]

void OMC::Node::move_to	(	const QString &	groupPath,
		int	x = 0,
		int	y = 0
	)

Moves the node into a group.

Similar to OMC::NodeList::move, moves this node from one group to another based on the provided group path – but the OMC::Node connection is maintained. Fails with an error if the move fails.

Parameters

groupPath	- The path to the group into which this node will be placed.
x	- The x coordinate of the node in the node view.
y	- The y coordinate of the node in the node view.

Move a Group Node into the Top Scene Group

import random
from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
nodes = scene.nodes                                          #Get the node list of the scene.

original_node = nodes["Top/Group1/Node"]                     #Get a node by name.
original_node.move_to( "Top" )                               #Move the node to the new path.

print( "New Node Path: %s"%(original_node.path) )            #Print the new path for the node.

move_to() [2/2]

void OMC::Node::move_to	(	OMC::GroupNode *	groupPath,
		int	x = 0,
		int	y = 0
	)

Moves the node into a group.

Similar to OMC::NodeList::move, moves this node from one group to another based on the provided group object (OMC::GroupNode) – but the OMC::Node connection is maintained. Fails with an error if the move fails.

Parameters

groupPath	- The path to the group into which this node will be placed.
x	- The x coordinate of the node in the node view.
y	- The y coordinate of the node in the node view. Move a Group Node into the Top Scene Group import random from ToonBoom import harmony #Import the Harmony Module sess = harmony.session() #Get access to the Harmony session, this class. proj = sess.project #Get the active session's currently loaded project. scene = proj.scene #Get the top scene in the project. nodes = scene.nodes #Get the node list of the scene. original_node = nodes["Top/Group1/Node"] #Get a node by name. original_node.move_to( scene.top ) #Move the node to the new path. print( "New Node Path: %s"%(original_node.path) ) #Print the new path for the node.

parent_group()

OMC::GroupNode* OMC::Node::parent_group

(

)

const

Gets the parent group for the node.

Retrieves the group-object in which this node belong (OMC::GroupNode). Every node belongs within a group – even the top-level nodes belong to a transparent group named 'Top'. The 'Top' group node behaves in the same manner as any other group, but is not visible within the node view (See OMC::Scene::top).

Identify the Group of a Random Node in the Scene

import random
from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
nodes = scene.nodes                                          #Get the node list of the scene.

try:
  random_node = nodes[random.randint(0,len(nodes))]          #Get a random node, and find its parent group.
except:
  random_node = False

node_group = random_node.parent_group()                      #In this case, redundant as we already have the scene owner above.4
print( "Parent Group: %s"%(node_group) )

parent_scene()

OMC::Scene* OMC::Node::parent_scene

(

)

const

Getaaa the parent scene for the node.

Every node belongs within a scene, this method provides the scene (OMC::Scene, or OMH::Scene) object to which this node belongs.

Identify the Scene of the Current Node

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
nodes = scene.nodes                                          #Get the node list of the scene.

try:
  first_node = nodes[0]                                      #Just using the first node as an example.
except:
  first_node = False

node_scene = first_node.parent_scene()                       #In this case, redundant as we already have the scene owner above.4
print( "Same Scene: %s"%( node_scene == scene ) )            #Expectation: "Same Scene: True"

Member Data Documentation

attributes

OMC::Node::attributes

Provides the list of attributes of the node.

The attribute-list is a dynamic list object (OMC::AttributeList) that provides the manipulatable attribute objects for the node. These attribute objects are useful for changing node attribute values both statically and over time (if the attribute is animateable).

Print All Attributes for All Nodes (This could take time in heavier scenes)

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
nodes = scene.nodes                                          #Get the node list of the scene.

#Iterating on the node list with a for-loop
for node in nodes:                                            #For loop on the node list.
  print( "Node: %s"%(node.path) )
  for attribute in node.attributes:                           #Get available attributes on the node.
    print( "  -- Attribute: %s"%(attribute) )                 #Print All available attributes on the node.

cacheable

bool OMC::Node::cacheable

read

Get whether the node can be cached.

Identifies if the node is cacheable, and can be cached with the OMC::Node::cached node property.

cached

bool OMC::Node::cached

readwrite

Get/set whether the node is cached.

A boolean property that defines whether or not the node is cached as part of the rig cache. Nodes with caching enabled will use a cached bitmap when rendering to OpenGL.

colour

OMC::Node::colour

Get/set the colour of the node.

Sets the node's colour in the scene. The node colour is used in the node view as a coloured swatch and in the timeline as a tint on the timeline layer. The property is a colour object specific to the given node – and it accepts colours defined by OMC::Colour.

Tint All Selected Nodes Red

from PySide6 import QtWidgets
from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

proj.history.begin( "Tinting Nodes" )
sess.notify_enabled = False

node_sel = scene.selection.nodes

colour = QtWidgets.QColorDialog.getColor()
if colour.isValid():
  for node in node_sel:
    node.colour = harmony.Colour( colour.red(), colour.green(), colour.blue(), colour.alpha() )

sess.notify_enabled = True
proj.history.end()

data

OMC::Node::data

The data handler that manages node data for views and tools.

The OMC::Node::data property will provide a map of custom data handlers that are dynamic properties defined by the application in specific contexts. These contexts include data for specific views (timeline, xsheet, node-view) and data for specific tools. This will be implemented and expanded in future versions of the DOM.

enabled

bool OMC::Node::enabled

readwrite

Get/set whether the node is enabled.

Nodes that are disabled (enabled = False) have specific behaviour based on the type of node that is disabled. Generally, a disabled node is passed-through and ignored for transformations and when rendering the image. Disabling a node is useful when turning off portions of a rig, or comparing the output of a node.

Disable All 'FX'

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

nodes = scene.nodes                                          #Get the scene's node list. All nodes within the scene.
for node in nodes:

  try:                                                                            #There may not be a port at that index, instead, just request it and catch the error.
    if not node.ports_in.dynamic:                                                 #A basic assumption that a effect module cannot be dynamic. 
      if node.ports_in[0].type == "IMAGE" and node.ports_out[0].type == "IMAGE":  #An effect is a node with an image input and output. 
        print( "Disabling Node: %s"%(node.path) ) 
        node.enabled = False        

  except:
    pass                                                      

locked

bool OMC::Node::locked

readwrite

Get/set whether the node is locked.

A boolean property that defines whether the node is locked. Locked nodes will restrict certain kinds of interactions.

matte_port

OMC::Node::matte_port

Returns the matte port, if one exists.

Some node-types provide a matte-port (sometimes hidden) that provides specialized functionality for providing a matte while rendering. This property provides the matte-port as a OMC::InPort if one is available.

Attach a mask to a drawing

from PySide6 import QtWidgets
from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

proj.history.begin( "Attaching a Mask" )

drawing = scene.nodes["Top/Drawing"]
mask    = scene.nodes["Top/Mask"]

matte_port = drawing.matte_port                              #Get the drawing's matte port

if matte_port:
  matte_port.link( mask.ports_out[0] )                       #Link the matte port to the out-port (0th) on the mask node.
  # OR 
  matte_port.source = mask.ports_out[0]                      #This is equivalent ot the link command above, but the source is set as a property instead.   

proj.history.end()

metadata

OMC::Node::metadata

The metadata handler object to provide metadata information.

Metadata can be used to store generic information in the scene, and in nodes. This data is created and accessed through the object (OMC::MetaDataHandler) provided by this property.

Print all Metadata in the node.

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

node = scene.nodes["Top/Drawing"]                            #The node that is being checked for metadata.

if len(node.metadata) == 0:
  print( "Node has no Metadata" )

for metadata in node.metadata:
  print( "Key : %s"%(metadata.key) )
  print( "  Value : %s"%(metadata.value) )
  print( "  Type : %s"%(metadata.type) )

Create Some Metadata

import json
import time
from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

node = scene.nodes["Top/Drawing"]                            #The node that is being checked for metadata.

metadata = node.metadata                                     #The metadata handler.

production_data = {
                    "artist"   : "John Doe",
                    "scene_id" : "TB_001_0010",
                    "date"     : int(time.time())
                  }

metadata["production_data"] = json.dumps( production_data )
print( "Set Production Data" )

json_data = metadata["production_data"].value
retrieved_data = json.loads( json_data )
for x in retrieved_data:
  print( "%s : %s"%(x, retrieved_data[x]) )

#The metadata will be saved and available within the scene in subsequent instances of Harmony. This is useful for saving
#generic data related to scenes or nodes.

name

QString OMC::Node::name

readwrite

Get/set the name of the node.

The name of the node is the unique node name within a group. Given a node with "Top/Group/NodeName", the last section "NodeName" is the unique node-name within the group. This can also be used to rename the node in-place – in the event that the provided name is not unique, a new unique name will be generated.

Add a Prefix to All Selected Nodes

import random
from PySide6 import QtWidgets

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
selection = scene.selection                                  #Get the selected nodes.

sel_node_size = len(selection.nodes)                         #How many nodes are selected?
if sel_node_size > 0:
  nodestr = "Node"
  if sel_node_size > 1:
    nodestr = "Nodes"

  prefix, accept = QtWidgets.QInputDialog.getText( None, "Prefix", "Prefix %s %s"%(sel_node_size, nodestr) )      # Using PySide's built-in utilities to pop-up a string request.

  if accept and len(prefix)>0:
    for node in selection.nodes:
      if not node.name.startswith( prefix ):
        replacement_name = "%s%s"%(prefix, node.name)
        print( "Renaming %s to %s"%(node.name, replacement_name) )

        node.name = replacement_name                         #Renaming the node by setting its name.

path

QString OMC::Node::path

readwrite

Get the path of the node. The path of the node is the absolute location of a node within a scene, including its name. The node's path provides the absolute location and the name of the node and can be used to both move and rename the node as needed.

Rename the Node with the Path

import random
from PySide6 import QtWidgets

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
selection = scene.selection                                  #Get the selected nodes.

sellist = selection.nodes.list()                             #Create a static list, impervious to further node changes.
newgroup = scene.nodes.create( "GROUP", "NEW_GROUP" )

sel_node_size = len(sellist)                                 #How many nodes are selected?
if sel_node_size > 0:
  for selnode in sellist:                                    #For each node, move it into the new group, and name it based on its type.
    new_name = selnode.type.upper()
    new_path = [ newgroup.path, new_name ]

    selnode.path = "/".join(new_path)                        #Join the group's full path 'Top/NEW_GROUP' with the new name.
    print( "New Node Location : %s"%(selnode.path) )

ports_in

OMC::Node::ports_in

Provides the list of input ports belonging to the node.

Provides a dynamic list object (OMC::PortList) of input ports on the node. The portlist object is also used for generating new in-ports (OMC::InPort) on the node when the node-type supports dynamic port creation.
Ports are connected to one another for rigging-purposes – a node's in-ports must be connected to another node's out-ports.

Find First Node – Identify Port Count

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
nodes = scene.nodes                                          #Get the node list of the scene.

try:
  first_node = nodes[0]                                        #Just using the first node as an example.
except:
  first_node = False

if first_node:
  portsin_count = len( first_node.ports_in )
  print( "Node %s has %s input ports."%( first_node.path, portsin_count ) )
else:
  print( "Unable to find a node." )

ports_out

OMC::Node::ports_out

Provides the list of output ports belonging to the node.

Provides a dynamic list object (OMC::PortList) of output ports on the node. The portlist object is also used for generating new out-ports (OMC::OutPort) on the node when the node-type supports dynamic port creation.
Ports are connected to one another for rigging-purposes – a node's in-ports must be connected to another node's out-ports.

Find First Node – Identify Port Count

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.
nodes = scene.nodes                                          #Get the node list of the scene.

try:
  first_node = nodes[0]                                        #Just using the first node as an example.
except:
  first_node = False

if first_node:
  portsout_count = len( first_node.ports_out )
  print( "Node %s has %s output ports."%( first_node.path, portsout_count ) )
else:
  print( "Unable to find a node." )

position

OMC::Node::position

The position of the node in the node view.

Provides a modifiable OMC::Node_Coordinates object. This can be used to modify the position of a node within the node view. See OMC::Node_Coordinates for more information.

subselections

OMC::Node::subselections

A list of subselectable objects that belong to the node.

Provides a list of subselection objects, with IDs. These are used when selecting controllers on a given node and are best used in conjunction with the selection interface.

thumbnail_timeline

bool OMC::Node::thumbnail_timeline

readwrite

Get and set whether the node shows a thumbnail in the timeline.

Defines whether the thumbnail in the timeline view is enabled. When enabled, the node in the timeline will be expanded and a thumbnail will be visible. Generally, only image-type nodes (nodes with an image output port) support thumbnails in the timeline.

Identify the Image Nodes and Enable Thumbnails

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

proj.history.begin( "Enabling Timeline Thumbnails" )

nodes = scene.nodes
for node in nodes:
  try:                                                       #Not all nodes provide a 0th port, instead of looking for one, just do the work and catch the error.
    port = node.ports_out[0]
    if port.type == "IMAGE":
      print( "Enabling Timeline Thumbnail : %s"%(node.path) )
      node.thumbnail_timeline = True

  except:
    pass

proj.history.end()

type

QString OMC::Node::type

read

Get the type of the node.

All nodes have an underlying keyword node-type. This type value defines the type of the node and its utility in the scene. This is useful when looking for a specific node type in a scene.

Find all Nodes, Move them 10 Units Right

import random
from PySide6 import QtWidgets

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.

nodes = scene.nodes                                          #Get the scene's node list. All nodes within the scene.
for node in nodes:
  if node.type.upper() == "PEG":                             #Its generally good practice to compare strings in a case insensitive manner.
    #We found a peg, hurrah! 

    #Only pegs have the apply_translation method.
    node.apply_translation( [1, scene.frame_count], harmony.Vector3d(10.0, 0.0, 0.0 ) )  #Applies the translation to a range of frames.

valid

bool OMC::Node::valid

read

Whether the bool is currently valid and the node still exists in the scene.

The Document Object Model maintains links between the object in the DOM and the actual object in Harmony. Certain methods and actions within the GUI will devalidate the DOM objects, and in these cases the object is considered no longer valid. This can happen if the object is kept in memory in the DOM and other actions are performed in the GUI.
The valid property defines whether or not the object is still valid. If actions are performed on an object that is no longer valid, an error will be thrown and needs to be caught and dealt with appropriately. It is particularly important to catch errors and check for validity on nodes in longer-running/persistent scripts. Only a few methods will devalidate a node within the same script.

Checking for Valid Nodes

from ToonBoom import harmony                                 #Import the Harmony Module
sess = harmony.session()                                     #Get access to the Harmony session, this class.
proj = sess.project                                          #Get the active session's currently loaded project.
scene = proj.scene                                           #Get the top scene in the project.


first_node   = scene.nodes.create( "PEG", "PEG001" )
target_group = scene.nodes.create( "GROUP", "GROUP001") 

#These nodes are both valid.
print( "First Node: %s"%(first_node.valid) )                #Expectation: "First Node: True"
print( "Group Node: %s"%(target_group.valid) )              #Expectation: "Group Node: True"

# Moving a node to a group will result in the devalidation of the object -- since the move operation destroys the original node
# and recreates it in the target location.

resulting_node = target_group.nodes.move( first_node )

#The original node that was moved is no longer valid.
print( "First Node: %s"%(first_node.valid) )                #Expectation: "First Node: False"

try:
  print( "Bad Node Path: %s"%(first_node.path) )
except:
  print( "This was expected -- the original first_node is no longer valid due to move." )

#But the 'move' method was nice enough to provide the resulting moved node.
print( "Resulting Node: %s %s"%(resulting_node.valid, resulting_node.path) ) #Expectation: "Resulting Node: True Top/GROUP001/PEG001"

version

int OMC::Node::version

readwrite

Get and set the version of the node.

Certain nodes are versioned and these versions can change between versions releases and builds of the application. The version property identifies the current version of the node, which can be up to a maximum of the value provided by OMC::Node::version_max.

version_max

int OMC::Node::version_max

read

Get the max version of the node available.

Certain nodes are versioned and these versions can change between versions releases and builds of the application. The version_max property provides the max version number that the node supports. The version of the node can be changed with the OMC::Node::version property.

Inheritance diagram for OMC::Node:

Collaboration diagram for OMC::Node: