OMC::PegNode Class Reference

Detailed Description

Represents and provides the methods for a Peg node.

The Peg node is an animateable, transformable node that provides its transformation to other connected nodes attached to its OutPort.

Public Member Functions
OMC::Matrix *	matrix (int frame) const
	Get the matrix for a peg at a specific frame. More...
void	set_matrix (int frame, OMC::Matrix *matrix, bool lastKey=false) const
	Set the matrix of a peg at a specific frame. More...
void	apply_matrix (const QVariant &frameOrRange, OMC::Matrix *matrix) const
	Apply the matrix of a peg at a specific frame or range. This results in the matrix being appended to the existing transformation. More...
OMC::Vector3d *	translation (int frame) const
	Get the translation for a peg at a specific frame. More...
void	set_translation (int frame, OMC::Vector3d *position, bool lastKey) const
	Set the translation of a peg at a specific frame. Sets the translation of a peg to match the vector (OMC::Vector3d) translation at a given frame. More...
void	apply_translation (const QVariant &frameOrRange, OMC::Vector3d *position) const
	Apply the translation of a peg at a specific frame or range. This results in the translation being appended to the existing transformation. More...
OMC::Vector3d *	scale (int frame) const
	Get the scale for a peg at a specific frame. More...
void	set_scale (int frame, OMC::Vector3d *scale, bool lastKey=false))
	Set the scale of a peg at a specific frame. More...
void	apply_scale (const QVariant &frameOrRange, OMC::Vector3d *scale) const
	Apply the scale of a peg at a specific frame or range. This results in the scale being appended to the existing transformation. More...
OMC::Vector3d *	rotation (int frame) const
	Get the rotation for a peg at a specific frame. More...
void	set_rotation (int frame, const QVariant &rotation, bool lastKey=false) const
	Set the rotation of a peg at a specific frame. More...
void	apply_rotation (const QVariant &frameOrRange, OMC::Vector3d *rotation) const
	Apply the rotation of a peg at a specific frame or range. This results in the rotation being appended to the existing transformation. More...
double	skew (int frame) const
	Get the skew for a peg at a specific frame. More...
void	set_skew (int frame, double skewValue, bool lastKey=false) const
	Set the skew of a peg at a specific frame. More...
void	apply_skew (const QVariant &frameOrRange, double skewValue) const
	Apply the skew of a peg at a specific frame or range. This results in the skew being appended to the existing transformation. More...
OMC::Vector3d *	pivot (int frame, bool apply_element_pivots=false) const
	Get the pivot at the given frame. More...
void	set_pivot (int frame, OMC::Vector3d *position, bool compensate_for_elements=true) const
	Set the pivot of a peg at a specific frame. More...
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

apply_matrix()

void OMC::PegNode::apply_matrix	(	const QVariant &	frameOrRange,
		OMC::Matrix *	matrix
	)		const

Apply the matrix of a peg at a specific frame or range. This results in the matrix being appended to the existing transformation.

The peg will apply the matrix to the existing transformation already supplied by the peg.

Note

The original transformation of this peg is not discarded and the matrix will applied onto the existing peg's transformation.

Parameters

matrix	- the matrix to set on the peg.
range	- supplied as a list in the form [startFrame, endFrame]

Apply a Matrix to All Frames

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.

peg = scene.nodes["Top/Peg"]                                 #Find the peg node.

matrix_to_apply = harmony.Matrix( )                          #Create a matrix to apply.
matrix_to_apply.scale( 2.0, 1.0, 1.0 )                       #Scale the matrix horizontally by 2.0

peg.apply_matrix( [1, scene.frame_count], matrix_to_apply )  #Apply the matrix to all valid frames in the scene.

apply_rotation()

void OMC::PegNode::apply_rotation	(	const QVariant &	frameOrRange,
		OMC::Vector3d *	rotation
	)		const

Apply the rotation of a peg at a specific frame or range. This results in the rotation being appended to the existing transformation.

Applies a vector's (OMC::Vector3d) rotation to the existing rotation of the peg.

Parameters

range

- Supplied as a list in the form [startFrame, endFrame]

rotation

- The OMC::Vector3d to apply to the peg. Apply Rotation 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. peg = scene.nodes["Top/Peg"] #Find the peg node. vector_to_apply = harmony.Vector3d( 0.0, 0.0, 4.0 ) #Create a vector to apply. range = [1, scene.frame_count] #The range to apply, all frames in scene. peg.apply_rotation( range, vector_to_apply ) #Apply the vector as a rotation to all valid frames in the scene.

apply_scale()

void OMC::PegNode::apply_scale	(	const QVariant &	frameOrRange,
		OMC::Vector3d *	scale
	)		const

Apply the scale of a peg at a specific frame or range. This results in the scale being appended to the existing transformation.

Applies a vector's (OMC::Vector3d) scale to the existing scale of the peg. This will apply directly to the peg's scale and does not consider its global transformation.

Note

The scale is set as a local translation on the peg. If a global translation is preferred, the incoming matrix and camera matrix should be considered.

Parameters

range	- supplied as a list in the form [startFrame, endFrame]
scale	- the OMC::Vector3d to apply to the peg.

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.

peg = scene.nodes["Top/Peg"]                                     #Find the peg node.

vector_to_apply = harmony.Vector3d( 2.0, 1.0, 1.0 )              #Create a vector to apply.

range = [1, scene.frame_count]                                   #The range to apply, all frames in scene.
peg.applyScale( range, vector_to_apply )                         #Apply the vector as a scale to all valid frames in the scene.

apply_skew()

void OMC::PegNode::apply_skew	(	const QVariant &	frameOrRange,
		double	skewValue
	)		const

Apply the skew of a peg at a specific frame or range. This results in the skew being appended to the existing transformation.

Applies a skew to the transformation over the frame range provided. The original skew is kept and the new value is applied onto that.

Parameters

range

- Supplied as a list in the form [startFrame, endFrame]

skew

- The OMC::Vector3d to apply to the peg. Apply Skew 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. peg = scene.nodes["Top/Peg"] #Find the peg node. range = [1, scene.frame_count] #The range to apply, all frames in scene. peg.apply_skew( range, 45 ) #Apply the skew to all valid frames in the scene.

apply_translation()

void OMC::PegNode::apply_translation	(	const QVariant &	frameOrRange,
		OMC::Vector3d *	position
	)		const

Apply the translation of a peg at a specific frame or range. This results in the translation being appended to the existing transformation.

Applies a vector's (OMC::Vector3d) translation to the existing translation of the peg. This will apply directly to the peg's position and does not consider its global transformation.

Note

The translation is set as a local translation on the peg. If a global translation is preferred, the incoming matrix and camera matrix should be considered.

Parameters

range	- supplied as a list in the form [startFrame, endFrame]
position	- the OMC::Vector3d to apply to the peg.

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.
                                                                 
peg = scene.nodes["Top/Peg"]                                     #Find the peg node.
                                                                 
vector_to_apply = harmony.Vector3d( 2.0, 0.0, 0.0 )              #Create a vector to apply.

range = [1, scene.frame_count]                                   #The range to apply, all frames in scene.
peg.apply_translation( range, vector_to_apply )                  #Apply the vector to all valid frames in the scene.

matrix()

OMC::Matrix* OMC::PegNode::matrix

(

int

frame

)

const

Get the matrix for a peg at a specific frame.

Provides the output transformation matrix of the peg node. Note, this is not the local transformation of the peg, but the accumulated transformation of the peg and all of its applied parents.
The transformation is a standard OMC::Matrix

Returns

OMC::Matrix that represents the applied transformation of the peg.

Detail a Peg Transformation

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.

peg = scene.nodes["Top/Peg"]                              #Find the peg node.
matrix = peg.matrix( 1 )

matrix_values = matrix.extract_parameters_3d( harmony.Point3d() )

print( "Translation : %s"%(matrix_values[0]) )
print( "Scale       : %s"%(matrix_values[1]) )
print( "Rotation    : %s"%(matrix_values[2]) )

move_to() [1/2]

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

inherited

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  )

inherited

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

inherited

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

inherited

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"

pivot()

OMC::Vector3d* OMC::PegNode::pivot	(	int	frame,
		bool	apply_element_pivots = false
	)		const

Get the pivot at the given frame.

Provides the pivot of a PegNode as a Vector3d object. The pivot is generally static on Peg, but can change from frame to frame when the peg (or drawing) is set to different pivot modes.

Parameters

frame	- The frame at which the matrix is retrieved.
apply_element_pivots	- Whether to consider the attached element's influence on the peg's pviot [true] or not.

Get a Peg's Pivot

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.

peg = scene.nodes["Top/Peg"]                                     #Find the peg node.

frame = 1
pivot = peg.pivot( frame, False )
print( "Pivot at frame %s : %s %s %s"%(frame, pivot.x, pivot.y, pivot.z) )

rotation()

OMC::Vector3d* OMC::PegNode::rotation

(

int

frame

)

const

Get the rotation for a peg at a specific frame.

The rotation is provided by a vector (OMC::Vector3d) that provides the rotation of the peg on each available axis in 3D.

scale()

OMC::Vector3d* OMC::PegNode::scale

(

int

frame

)

const

Get the scale for a peg at a specific frame.

The scale of the peg is provided as a OMC::Vector3d object.

set_matrix()

void OMC::PegNode::set_matrix	(	int	frame,
		OMC::Matrix *	matrix,
		bool	lastKey = false
	)		const

Set the matrix of a peg at a specific frame.

The peg will set its transformation values to match the transformation that is applied by the matrix (OMC::Matrix).

Note

The original transformation of this peg will be discarded and the matrix will be set instead. To apply a matrix value, use OMC::PegNode::apply_matrix.

Parameters

frame	- The frame at which the matrix is set.
matrix	- The matrix to set on the peg.
lastKey	- Whether this is set on the last available key relative to the frame [true], or at the given frame [false]

Setting a Transformation

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.

peg = scene.nodes["Top/Peg"]                                 #Find the peg node.

matrix_to_apply = harmony.Matrix( )                          #Create a matrix to apply.
matrix_to_apply.scale( 2.0, 1.0, 1.0 )                       #Scale the matrix horizontally by 2.0

peg.set_matrix(1.0, matrix_to_apply, False)

set_pivot()

void OMC::PegNode::set_pivot	(	int	frame,
		OMC::Vector3d *	position,
		bool	compensate_for_elements = true
	)		const

Set the pivot of a peg at a specific frame.

Sets the pivot on a peg at a given frame. Generally, a peg does not provide an animateable pivot– but the pivot may need to compensate for the elements at a given frame.

Parameters

frame	- The frame at which the matrix is set.
position	- The pivot position to which the peg will be set; provided as a OMC::Vector3d object.
compensate_for_elements	- Bool defining whether the pivot should be set in a way that compensates for the attached elements and their pivot modes.

Set a Peg's Pivot

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.

peg = scene.nodes["Top/Peg"]                                     #Find the peg node.

frame = 1
old_pivot = peg.pivot( frame, False )
print( "Pivot at frame %s : %s %s %s"%(frame, pivot.x, pivot.y, pivot.z) )

new_pivot_to_set = harmony.Vector3d( 1.0, 2.0, 0.0 )             #The new pivot object we'll use...

try:
  peg.set_pivot( frame, new_pivot_to_set, False )                  #Set the pivot at frame 1
  new_pivot = peg.pivot( frame, False )                            #Get the new_pivot, for demo . . . unnecessary, as an error would have been throw if failed.
  
  #Print it for demo-purposes.
  print( "New Pivot at frame %s : %s %s %s"%(frame, new_pivot.x, new_pivot.y, new_pivot.z) )

except:
  print( "Failed to set the Pivot." )

set_rotation()

void OMC::PegNode::set_rotation	(	int	frame,
		const QVariant &	rotation,
		bool	lastKey = false
	)		const

Set the rotation of a peg at a specific frame.

Sets the rotation of a peg to match the vector (OMC::Vector3d) rotation at a given frame, provided as a vector of degrees for each angle on the axis.

Parameters

frame	- The frame at which the translation will be set.
rotation	- The OMC::Vector3d to apply to the peg.
lastKey	- Whether this is set on the last available key relative to the frame [true], or at the given frame [false]

<Sets the Rotation at a Given Frame

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.

peg = scene.nodes["Top/Peg"]                                 #Find the peg node.

vector_to_set = harmony.Vector3d( 0.0, 0.0, 45.0 )           #Create a vector to set.

peg.set_rotation( 1, vector_to_set, False )                  #Set the vector translation on the first frame.

set_scale()

void OMC::PegNode::set_scale	(	int	frame,
		OMC::Vector3d *	scale,
		bool	lastKey = false
	)

Set the scale of a peg at a specific frame.

Sets the scale of a peg to match the vector (OMC::Vector3d) scale at a given frame.

Parameters

frame	- The frame at which the translation will be set.
scale	- The OMC::Vector3d to apply to the peg.
lastKey	- Whether this is set on the last available key relative to the frame [true], or at the given frame [false]

<Sets the Scale at a Given Frame

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.

peg = scene.nodes["Top/Peg"]                                 #Find the peg node.

vector_to_set = harmony.Vector3d( 2.0, 1.0, 1.0 )            #Create a vector to set.

peg.set_scale( 1, vector_to_set, False )                     #Set the vector translation on the first frame.

set_skew()

void OMC::PegNode::set_skew	(	int	frame,
		double	skewValue,
		bool	lastKey = false
	)		const

Set the skew of a peg at a specific frame.

Sets the local skew applied by the peg for a given frame.

Parameters

frame	- The frame at which the translation will be set.
skewValue	- The skew to apply to the peg.
lastKey	- Whether this is set on the last available key relative to the frame [true], or at the given frame [false] <Sets the Skew at a Given Frame 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. peg = scene.nodes["Top/Peg"] #Find the peg node. peg.set_skew( 1, 45, False ) #Set the skew on the first frame.

set_translation()

void OMC::PegNode::set_translation	(	int	frame,
		OMC::Vector3d *	position,
		bool	lastKey
	)		const

Set the translation of a peg at a specific frame. Sets the translation of a peg to match the vector (OMC::Vector3d) translation at a given frame.

Note

The translation is set as a local translation on the peg. If a global translation is preferred, the incoming matrix and camera matrix should be considered.

Parameters

frame	- The frame at which the translation will be set.
position	- The OMC::Vector3d to apply to the peg.
lastKey	- Whether this is set on the last available key relative to the frame [true], or at the given frame [false]

<Sets the Translation at a Given Frame

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.

peg = scene.nodes["Top/Peg"]                                 #Find the peg node.

vector_to_set = harmony.Vector3d( 2.0, 0.0, 0.0 )            #Create a vector to set.

peg.set_translation( 1, vector_to_set, False )               #Set the vector translation on the first frame.

skew()

double OMC::PegNode::skew

(

int

frame

)

const

Get the skew for a peg at a specific frame.

Provides the skew applied by the peg at a given frame. The skew is provided as a number value in degrees on the skewed axis.

translation()

OMC::Vector3d* OMC::PegNode::translation

(

int

frame

)

const

Get the translation for a peg at a specific frame.

The translation of the peg is provided as a OMC::Vector3d object.

Member Data Documentation

attributes

OMC::Node::attributes

inherited

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

readinherited

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

readwriteinherited

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

inherited

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

inherited

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

readwriteinherited

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

readwriteinherited

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

inherited

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

inherited

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

readwriteinherited

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

readwriteinherited

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

inherited

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

inherited

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

inherited

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

inherited

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

readwriteinherited

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

readinherited

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

readinherited

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

readwriteinherited

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

readinherited

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

Collaboration diagram for OMC::PegNode: