Detailed Description

The Position3D attribute wrapper.

This object wraps a Position3D Attribute, which provides the 3D positional information.

Public Member Functions
virtual OMC::Point3d *	localvalue ()
	Get the attribute's localvalue as a OMC::Point3d value. More...

virtual OMC::Point3d *	value (int frame)
	Get the attribute's value as a OMC::Point3d value at a given frame. More...

virtual void	set_localvalue (OMC::Point3d *value)
	Sets the attribute's local value as a OMC::Point3d value. More...

virtual void	set_value (int frame, OMC::Point3d *, bool adjustLastKeyframe=false)
	Set the attribute's value as a OMC::Point3d value at a given frame. More...

virtual void	offset_value (const QVariant &frameOrRange, OMC::Point3d *)
	Offsets the attribute's value at a given frame or frame range. More...

virtual void	reset_localvalue ()
	Reset the attribute's localvalue to the default value. More...

virtual void	reset_value (int frame)
	Reset the attribute to the default value. More...

OMC::Node *	node () const
	The node that owns this attributes. More...

virtual bool	unlink ()
	Unlinks a column from the attribute. More...

virtual bool	link (const QVariant &column)
	Links a column to the attribute, making it animate over time. More...

bool	set_text_value (int atFrame, const QString &value)
	Modify an attribute with a text value at a given frame. Change an attribute with a text value applied at a specific frame. This provides similar utility as the Javascript libraries available for the application. More...

QString	get_text_value (int atFrame) const
	Get a text value at a given frame. Retrieve the text value of an attribute at a specific frame. This provides similar utility as the Javascript libraries available for the application. More...

Public Attributes
OMC::Point3d *	default
	Get the default value of the attribute. More...

OMC::Column *	column
	Get and set the column object attached to the the attribute, if it is supported. More...

QString	column_name
	Get and set the column name attached to the the attribute. More...

QString	keyword
	Get the keyword of the attribute. More...

QString	display_name
	Get the display name of the attribute. More...

QString	type_name
	Get the display name of the attribute. More...

QString	full_keyword
	Return the full keyword of the Attribute. More...

bool	dynamic
	Identifies if the attribute is dynamic. More...

bool	linkable
	Identifies if the attribute is linkable and can have a column linked to it. More...

AttributeList *	subattributes
	Get the list of subattributes belonging to the attribute. More...

Member Function Documentation

◆ get_text_value()

QString OMC::Attribute::get_text_value ( int atFrame ) const

inherited

Get a text value at a given frame. Retrieve the text value of an attribute at a specific frame. This provides similar utility as the Javascript libraries available for the application.

Parameters

atFrame - The frame at which to set the attribute.

Returns: Returns the text value of the string at the given frame.

◆ link()

virtual bool OMC::Attribute::link ( const QVariant & column )

virtualinherited

Links a column to the attribute, making it animate over time.

Returns: Returns whether the column has been successfully linked to the attribute.

Links a column to the attribute, if the column is compatible with the attribute type. Also see setting OMC::Column::column with a Column object property.

◆ localvalue()

virtual OMC::Point3d* OMC::Position3DAttribute::localvalue ( )

virtual

Get the attribute's localvalue as a OMC::Point3d value.

Provides the localvalue as a OMC::Point3d value. The local value is the non-animateable value of an attribute when no column is present. If the attribute can be linked and has a column linked to it, the value at a frame is provided by the column and the local value is ignored.

Note: Its generally better to reference the value over the localvalue. When no column is present, the value will also provide the localvalue – this is not true in reverse, if a column is present, the localvalue will still reference the ignored localvalue. Non-animateable attributes that cannot be linked will only provide the localvalue.

Retrieve a OMC::Point3d Localvalue

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/Peg"]                                #Find the peg, as it contains a 3D position attribute.
point3d_attribute_keyword = "POSITION"                       #The path to a OMC::Point3d attribute
attribute = node.attributes[point3d_attribute_keyword]       #Get the attribute by name
if attribute:
  current_value = attribute.localvalue()                     #Get the attribute's localvalue.
  #Show the localvalue of the attribute.
  print( "LOCALVALUE: %s %s %s"%( current_value.x, current_value.y, current_value.z ) )
else:
  print( "Unable to find attribute by keyword: %s"%(point3d_attribute_keyword) )

◆ node()

OMC::Node* OMC::Attribute::node ( ) const

inherited

The node that owns this attributes.

Retrieves the Node that owns this attribute.

Returns: Returns the owning OMC::Node object related to this attribute.

◆ offset_value()

virtual void OMC::Position3DAttribute::offset_value	(	const QVariant &	frameOrRange,
		OMC::Point3d *
	)

virtual

Offsets the attribute's value at a given frame or frame range.

Provided a OMC::Point3d object, will offset the existing value (either the animated value, or local value if none exists) by the color argument's value.

Parameters

frameOrRange	- A frame range provided by a list in form [startFrame, endFrame]
value	- The OMC::Colour object to by which the attribute is offset.

Offset a Point3d Attribute

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/Peg"]                                #Find the peg, as it contains a 3D position attribute.
point3d_attribute_keyword = "POSITION"                       #The path to a OMC::Point3d attribute
attribute = node.attributes[point3d_attribute_keyword]       #Get the attribute by name
if attribute:
  at_frame = 1
  current_value = attribute.value( at_frame )                #Get the attribute's value.
  #Show the current localvalue of the attribute.
  print( "CURRENT VALUE AT %s : %s"%( at_frame, current_value ) )
  new_value = harmony.Point3d( random.uniform( -20.0, 20.0 ), random.uniform( -20.0, 20.0 ), random.uniform( -20.0, 20.0 ) )
  range = [ at_frame, scene.frame_count ]                    #The range will be from at_frame, to the last frame of the scene.
  attribute.offset_value( range, new_value )                 #Offset the attribute's value by the provided value
  new_value = attribute.value( at_frame )                    #Get the attribute's new localvalue, to check it for debug/example purposes
  print( "NEW VALUE AT %s : %s"%( at_frame, new_value ) )
else:
  print( "Unable to find attribute by keyword: %s"%(point3d_attribute_keyword) )

◆ reset_localvalue()

virtual void OMC::Position3DAttribute::reset_localvalue ( )

virtual

Reset the attribute's localvalue to the default value.

The value of an attribute has a default value when the node is initially created. This method will reset the localvalue to its initial default value.

◆ reset_value()

virtual void OMC::Position3DAttribute::reset_value ( int frame )

virtual

Reset the attribute to the default value.

The value of an attribute has a default value when the node is initially created. This method will reset the value to its initial default value at the provided frame.

Parameters

frame - the frame at which the attribute is reset.

◆ set_localvalue()

virtual void OMC::Position3DAttribute::set_localvalue ( OMC::Point3d * value )

virtual

Sets the attribute's local value as a OMC::Point3d value.

Sets the local value of the attribute to the provided OMC::Point3d value. The local value is the non-animateable value of an attribute when no column is present. If the attribute can be linked and has a column linked to it, the value at a frame is provided by the column and the local value is ignored.

Note: Its generally better to reference the value over the localvalue. When no column is present, the value will also provide the localvalue – this is not true in reverse, if a column is present, the localvalue will still reference the ignored localvalue. Non-animateable attributes that cannot be linked will only provide the localvalue.

Parameters

value - the OMC::Point3d value to which the attribute should be set.

Set a OMC::Color Localvalue

from ToonBoom import harmony                                 #Import the Harmony Module
import random
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/Peg"]                                #Find the peg, as it contains a 3D position attribute.
point3d_attribute_keyword = "POSITION"                       #The path to a OMC::Point3d attribute
attribute = node.attributes[point3d_attribute_keyword]       #Get the attribute by name
if attribute:
  current_value = attribute.localvalue()                     #Get the attribute's localvalue.
  #Show the current localvalue of the attribute.
  print( "CURRENT LOCALVALUE: %s"%( current_value ) )
  new_value = harmony.Point3d( random.uniform( -20.0, 20.0 ), random.uniform( -20.0, 20.0 ), random.uniform( -20.0, 20.0 ) )
  attribute.set_localvalue( new_value )                      #Set the attribute's local value to the new value
  new_value = attribute.localvalue()                         #Get the attribute's new localvalue, to check it for debug/example purposes
  print( "NEW LOCALVALUE: %s %s %s"%( new_value.x, new_value.y, new_value.z ) )
else:
  print( "Unable to find attribute by keyword: %s"%(point3d_attribute_keyword) )

◆ set_text_value()

bool OMC::Attribute::set_text_value	(	int	atFrame,
		const QString &	value
	)

inherited

Modify an attribute with a text value at a given frame. Change an attribute with a text value applied at a specific frame. This provides similar utility as the Javascript libraries available for the application.

Parameters

atFrame	- The frame at which to set the attribute.
value	- The new value of the attribute.

Returns: Returns whether the attribute has been successfully changed.

◆ set_value()

virtual void OMC::Position3DAttribute::set_value	(	int	frame,
		OMC::Point3d *	,
		bool	adjustLastKeyframe = `false`
	)

virtual

Set the attribute's value as a OMC::Point3d value at a given frame.

Sets the value of the attribute to the provided OMC::Point3d value at the given frame. If the attribute can be linked and has a column linked to it, the value is set on the column – otherwise, it is set on the localvalue of the attribute.

Note: If no column is present, setting an animateable column's value on the attribute will result in the creation of a new column.

Parameters

frame	- the frame at which the attribute is set.
value	- the OMC::Point3d value to which the attribute should be set.

Set a OMC::Point3d Value at a Frame

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.
node = scene.nodes["Top/Peg"]                                #Find the peg, as it contains a 3D position attribute.
point3d_attribute_keyword = "POSITION"                       #The path to a OMC::Point3d attribute
attribute = node.attributes[point3d_attribute_keyword]       #Get the attribute by name
if attribute:
  at_frame = 1
  current_value = attribute.value( at_frame )                #Get the attribute's value.
  #Show the current localvalue of the attribute.
  print( "CURRENT VALUE AT %s : %s"%( at_frame, current_value ) )
  new_value = harmony.Point3d( random.uniform( -20.0, 20.0 ), random.uniform( -20.0, 20.0 ), random.uniform( -20.0, 20.0 ) )
  attribute.set_value( at_frame, new_value )                                                      #Set the attribute's local value to the new value
  new_value = attribute.value( at_frame )                                                         #Get the attribute's new localvalue, to check it for debug/example purposes
  print( "NEW VALUE AT %s : %s"%( at_frame, new_value ) )
else:
  print( "Unable to find attribute by keyword: %s"%(point3d_attribute_keyword) )

◆ unlink()

virtual bool OMC::Attribute::unlink ( )

virtualinherited

Unlinks a column from the attribute.

Returns: Returns whether the column has been successfully removed from the attribute.

Unlinks any column from the attribute.
Also see OMC::Column::column with property None.

node.attribute["attrbKeyword"].unlink()
#Same as:
node.attribute["attrbKeyword"].column = None

◆ value()

virtual OMC::Point3d* OMC::Position3DAttribute::value ( int frame )

virtual

Get the attribute's value as a OMC::Point3d value at a given frame.

Provides the value as a OMC::Point3d value. If the attribute can be linked and has a column linked to it, the value at a frame is provided by the column and the local value is ignored.

Retrieve a OMC::Point3d Value

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/Peg"]                                #Find the peg, as it contains a 3D position attribute.
point3d_attribute_keyword = "POSITION"                       #The path to a OMC::Point3d attribute
attribute = node.attributes[point3d_attribute_keyword]       #Get the attribute by name
if attribute:
  at_frame = 1
  current_value = attribute.value(at_frame)                       #Get the attribute's value at frame 1
  #Show the value of the attribute.
  print( "VALUE AT FRAME %s : %s %s %s"%( at_frame, current_value.x, current_value.y, current_value.z ) )
else:
  print( "Unable to find attribute by keyword: %s"%(point3d_attribute_keyword) )

Member Data Documentation

◆ column

OMC::Attribute::column

inherited

Get and set the column object attached to the the attribute, if it is supported.

Attributes that are animateable will support columns that provide values per frame. Different attribute-types support different column types. The OMC::Attribute::column provides access to getting and setting the Column object associated with this attribute.

Note: Setting a column will override any other column associated with the attribute. Setting the column to none will unlink the column (similar to ONC::Attribute::unlink)

Get the Column Associated with the Attribute:

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_path = "Top/Node"
node = scene.nodes[ node_path ]
if node:
  for attrbs in node.attributes:
    if attrbs.column:
      print( "%s has column %s"%(attrbs.full_keyword, attrbs.column.name) )
else:
  print( "Unable to find node: %s"%(node_path) )

Set the Column on the Attribute

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_path = "Top/Node"
node = scene.nodes[ node_path ]
type_map = {                                                 #Different attrb types support different column types, create a lookup map.
             "PATH_3D"         : "3D_PATH",
             "QUATERNION_PATH" : "QUATERNION_PATH",
             "TIMING"          : "TIMING",
             "DOUBLE"          : "BEZIER",
             "DOUBLEVB"        : "BEZIER",
             "INT"             : "BEZIER"
            }
if node:
  idx = 0
  
  #Create a recursive function to apply columns to even the subattributes.
  def create_new_columns( nodelist, type_map ):
    global idx
    for attrb in nodelist:
      if attrb.linkable:                                                                                #The attribute is linkable, so it will support a columm.
          if attrb.type.upper() in type_map:                                                            #Ensure our lookup map supports the attrb type.
            
            while True:
              try:                                                                                      #Iterate until a new column is available with the provided name.
                newcol = scene.columns.create( type_map[attrb.type.upper()], "NEW_COLUMN_%03d"%(idx) )  #Create a new column for this attribute.
                break
              except:
                idx = idx + 1
    
            print( "Linking %s to %s"%(newcol.name, attrb.full_keyword) )
            attrb.column = newcol                                                                       #Set the newly created column to the attribute.
            
            idx = idx + 1
          else:
            print( "Unsupported Attrb type : %s"%(attrb.type) )
      elif attrb.subattributes:
         create_new_columns( attrb.subattributes, type_map )
  
  #Use the recursive function to set a new column on every attribute.
  create_new_columns( node.attributes, type_map )  

◆ column_name

QString OMC::Attribute::column_name

readwriteinherited

Get and set the column name attached to the the attribute.

A utility to allow references to the column by name, instead of by Column object (OMC::Column). This would be similar to the following:

node.attribute["attrbKeyword"].column_name = column_object.name
#Same as:
node.attribute["attrbKeyword"].column = column

◆ default

OMC::Position3DAttribute::default

Get the default value of the attribute.

Provides the default value of the attribute – this is the value that the attribute will use when it is reset.

◆ display_name

QString OMC::Attribute::display_name

readinherited

Get the display name of the attribute.

Provides the display name of the attribute. The display name is read only, and is the name of the attribute provided within the GUI to the user.

◆ dynamic

bool OMC::Attribute::dynamic

readinherited

Identifies if the attribute is dynamic.

Dynamic attributes are those that are created with scripted access to an attribute and are created dynamically and uniquely for that node. These dynamic attributes are not necessarily standard for the node-type, and can be added or removed from the node on-demand.
See OMC::AttributeList::create_dynamic_attr for more information.

Create a new Double Dynamic Attribute

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_path = "Top/Node"
node = scene.nodes[ node_path ]
if node:
  attrbs = node.attributes
  created_attribute = attrbs.create_dynamic_attr( "DOUBLE", "DYNAMIC_NAME", "DYNAMIC_DISPLAY", True )
  if created_attribute:
    if created_attribute.dynamic:                            #Expected to be true, since we just created it.
      print( "Created Dynamic Attribute: %s"%(created_attribute.full_keyword) )
      created_attribute.set_value(1, 10, False)
  else:
    print( "Failed to create attribute." )
else:
  print( "Node does not exist: %s"%(node_path) )

◆ full_keyword

QString OMC::Attribute::full_keyword

readinherited

Return the full keyword of the Attribute.

All columns can be referenced by their full keyword as this provides the full path to the given attribute on a Node.

Note: The full_keyword is useful when referencing an attribute from a node, even if that attribute is a subattribute of another. Notice in the example below, that only the full keyword is printed, which provides the path to the attribute from the base of the node's attribute list (see OMC::AttributeList::operator[ QString& keyword ]).

Get the Keyword of All Attributes on a 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_path = "Top/Node"
node = scene.nodes[ node_path ]
def attrb_keywords( attrblist, depth ):
  for attrb in attrblist:
    print( "%s %s"%( "  "*depth, attrb.full_keyword ) )      #Only printing the keyword of the attribute. Note, subattributes will only print their basename, and not their parent's in a path.
    if attrb.subattributes:
      attrb_keywords( attrb.subattributes, depth+1 )         #If we hit something with subattributes, print those too!
if node:
  attrb_keywords( node.attributes, 0 )
else:
  print( "Unable to find node: %s"%(node_path) )

◆ keyword

QString OMC::Attribute::keyword

readinherited

Get the keyword of the attribute.

All columns are referenced by their keyword when relative to a given parent object. Otherwise, they are referenced by their full_keyword (OMC::Column::full_keyword) property – which contains the full path to that attribute on a given Node.

Note: The keyword is useful when relative to a given parent, but the full_keyword will provide the absolute path of the attribute. Notice in the example below, that only the relative keyword is printed.

Get the Keyword of All Attributes on a 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_path = "Top/Node"
node = scene.nodes[ node_path ]
def attrb_keywords( attrblist, depth ):
  for attrb in attrblist:
    print( "%s %s"%( "  "*depth, attrb.keyword ) )           #Only printing the keyword of the attribute. Note, subattributes will only print their basename, and not their parent's in a path.
    
    if attrb.subattributes: 
      attrb_keywords( attrb.subattributes, depth+1 )         #If we hit something with subattributes, print those too!
if node:
  attrb_keywords( node.attributes, 0 )
 
else:
  print( "Unable to find node: %s"%(node_path) )

◆ linkable

bool OMC::Attribute::linkable

readinherited

Identifies if the attribute is linkable and can have a column linked to it.

Only some attributes are animateable and accept a column. If a column is set on a non-linkable attribute, an error is thrown.
See OMC::Attribute::column for an example.

◆ subattributes

OMC::Attribute::subattributes

inherited

Get the list of subattributes belonging to the attribute.

Provides the subattribute list (OMC::AttributeList) for this attribute, if one is available. Only certain attribute-types are considered complex, and contain subattributes.

Identify if an Attribute has Subattributes

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_path = "Top/Node"
node = scene.nodes[ node_path ]
if node:
  for attrbs in node.attributes:
    if attrbs.subattributes:
      print( "Attrb %s has %s subattributes."%(attrbs.full_keyword, len(attrbs.subattributes) ) )
    else:
      print( "Attrb %s has no subattributes."%(attrbs.full_keyword) )
else:
  print( "Unable to find node: %s"%(node_path) )

See OMC::Attribute::column for more examples.

◆ type_name

OMC::Attribute::type_name

inherited

Get the display name of the attribute.

Provides the type-name of the attribute. Different attribute-types provide different information to the node and also require different column-types when linked (if linkable).

Note: Different subclasses of the OMC::Attribute object are provided for different attribute types. These different subclasses provode specific utilties for that attribute-type. See OMC::BoolAttribute, OMC::ColourAttribute, OMC::DoubleAttribute, OMC::DrawingAttribute, OMC::ElementAttribute, OMC::EnumAttribute, OMC::IntAttribute, OMC::Position2DAttribute, OMC::Position3DAttribute, OMC::TextAttribute and OMC::TimingAttribute.

See OMC::Attribute::column for an example.

Inheritance diagram for OMC::Position3DAttribute:

[legend]

Collaboration diagram for OMC::Position3DAttribute:

[legend]

Detailed Description

Public Member Functions

Public Attributes

Member Function Documentation

◆ get_text_value()

◆ link()

◆ localvalue()

◆ node()

◆ offset_value()

◆ reset_localvalue()

◆ reset_value()

◆ set_localvalue()

◆ set_text_value()

◆ set_value()

◆ unlink()

◆ value()

Member Data Documentation

◆ column

◆ column_name

◆ default

◆ display_name

◆ dynamic

◆ full_keyword

◆ keyword

◆ linkable

◆ subattributes

◆ type_name