Detailed Description

A scene within a loaded project.

The scene provides access to functions and properties related to a specific scene within a project. The scene is composed of scene specific settings, nodes and column values.

Public Member Functions
bool	frame_insert (int atFrame, int nbFrames, OMC::FrameOptions options=FrameOptions())
	Inserts frames at the selected frame number. More...

bool	frame_remove (int atFrame, int nbFrames, OMC::FrameOptions options=FrameOptions())
	Deletes frames starting from the selected frame number. More...

Public Attributes
OMH::Selection *	selection
	Provides the selection handler for the current project. More...

OMH::Clipboard *	clipboard
	Provides the clipboard access for the current project. More...

uint	processing_bit_depth
	Provides the processing bit-depth of the scene at render. More...

int	frame_current
	Get/set the scene's current frame, only available when used within Harmony's GUI (and not in Batch or External mode). More...

OMC::SceneAspect *	aspect
	Get the aspect ratio of the scene. More...

OMC::SceneUnits *	units
	Get the number of units of the scene. More...

OMC::SceneCenter *	center
	Get the center coordinates of the scene. More...

QString	name
	Get/set the scene's name.

double	framerate
	Get/set the framerate of the scene. More...

double	vector_texture_pixel_density
	Get/set the default texture pixel density for new Vector Drawings. More...

double	bitmap_texture_pixel_density
	Get/set the default texture pixel density for new bitmap Drawings. More...

int	frame_count
	Get/set the frame count of the scene. More...

int	frame_start
	Get/set the start-frame of the scene. More...

int	frame_stop
	Get/set the stop-frame of the scene. More...

QString	colorspace
	Get/set the colorspace of the scene. More...

QStringList	colorspaces
	Get list of available colorspace names. More...

OMC::CameraNode *	camera
	Get/set the camera node object for the scene. More...

QString	camera_path
	Get/set the camera's name being used in the scene. More...

OMC::SceneUnitConverter *	unit_converter
	The tool used for converting between OGL and scene spaces. More...

OMC::MetaDataHandler *	metadata
	The metadata handler object to provide metadata information. More...

std::vector< OMC::Sound * >	sounds
	The list of sound objects in the scene. More...

OMC::NodeList *	top
	The top group in the scene. More...

OMC::NodeList *	nodes
	The list of all nodes in the scene. More...

OMC::CompositionList *	compositions
	The list of all compositions in the scene (based on available displays).

OMC::ColumnList *	columns
	The list of all columns in the scene. More...

OMC::DisplayNode *	display
	Provides and sets the display node of the current display. More...

QString	display_name
	Provides and sets the display node of the current display. More...

QList< OMC::Node * >	displays
	Provides a list of the display nodes available in the scene. More...

QStringList	display_names
	Provides a list of the display names available in the scene. More...

Member Function Documentation

◆ frame_insert()

bool OMC::Scene::frame_insert	(	int	atFrame,
		int	nbFrames,
		OMC::FrameOptions	options = `FrameOptions()`
	)

inherited

Inserts frames at the selected frame number.

atFrame = 0 -> insert before first frame.
atFrame = n -> insert after frame n.
atFrame = scene_object.frame_count.

Parameters

atFrame	- The frame number at which the frames will be inserted. Frames are inserted after the frame indicated. Use 0 to insert frames before the first frame.
nbFrames	- The number of frames to insert
options	- This optional parameter should be an object with the desired behaviours for when the frames are inserted. See OMC::FrameOptions for further information on options.

Add 10 Frames at the start of 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.
scene.frame_insert( 0, 10, harmony.FrameOptions(True, True) )  #Insert the frames, with FrameOptions( ripple_markers = True, extend_exposure = True)
#Content will now be pushed out 10 frames from before the starting frame of the scene.

Returns: True if the number of frames given is valid.

◆ frame_remove()

bool OMC::Scene::frame_remove	(	int	atFrame,
		int	nbFrames,
		OMC::FrameOptions	options = `FrameOptions()`
	)

inherited

Deletes frames starting from the selected frame number.

atFrame = 0 -> delete at the beginning atFrame = n -> delete frames following the nth frame atFrame = Application.frame.nbFrames() -> won't delete anything

Parameters

atFrame	The frame number at which the frames will be removed. Frames are removed after the frame indicated. Use 0 to remove frames before the first frame.
nbFrames	The number of frames to remove
options	This optional parameter should be an object with the desired behaviours for when the frames are removed. See OMC::FrameOptions for further information on options.

Remove 10 Frames at the start of 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.
scene.frame_remove( 1, 10, harmony.FrameOptions(True, True) )  #Remove the frames, with FrameOptions( ripple_markers = True, extend_exposure = True)
#Content will now be pulled back10 frames from before the starting frame of the scene.

Member Data Documentation

◆ aspect

OMC::Scene::aspect

inherited

Get the aspect ratio of the scene.

The aspect ratio is provided as an object (OMC::SceneAspect) that provides properties related to the aspect ratio of the scene.

◆ bitmap_texture_pixel_density

double OMC::Scene::bitmap_texture_pixel_density

readwriteinherited

Get/set the default texture pixel density for new bitmap Drawings.

The bitmap texture pixel density is the ratio used for pixel density in bitmap layers.

◆ camera

OMC::Scene::camera

inherited

Get/set the camera node object for the scene.

Provides the OMC::CameraNode object that represents the currently active camera in the scene.

Identify the Camera 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.
camera = scene.camera
if not camera:
  print( "No camera is currently set." )
else:
  print( "Current Camera: %s"%(camera.path) )

Set the Camera Node to the first identified camera:

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.
for node in scene.nodes:
  if( node.type.upper() == "CAMERA" ):
    scene.camera = node
    print( "Set the Camera: %s"%(node.path) )
    break

◆ camera_path

OMC::Scene::camera_path

inherited

Get/set the camera's name being used in the scene.

Similar to OMC::Scene::camera – but provides the string representing the path to the camera node of 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.
print( "Current Camera: %s"%(scene.camera_path) )            #Print the camera path.

◆ center

OMC::Scene::center

inherited

Get the center coordinates of the scene.

The center coordinates of the scene, provided as a read/write object (OMC::SceneCenter).

◆ clipboard

OMH::HarmonyScene::clipboard

Provides the clipboard access for the current project.

The clipboard object (OMH::Clipboard) is used for saving and recalling content as objects in memory. It is also used for generating templates.

Copying Content

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.
clipboard = scene.clipboard                                  #The clipboard object.
selection_handler = scene.selection                          #The selection handler.
selection_handler.nodes.select_all()                         #Select all nodes in the scene.
copy_object = clipboard.copy( selection_handler.nodes.list() )    #Create a copy_object in memory from the selection.
selection_handler.select_none()
new_nodes = clipboard.paste_new_nodes( copy_object, scene.top )   #Paste duplicate nodes into the top-group of the scene.
for node in new_nodes:
  print( "Pasted: %s"%(node.path) )                               #Announce the new node's path
  if node.parent_group().path == scene.top.path:
    node.position.y = node.position.y + 300                         #Move it up, to avoid overlap with existing content

◆ colorspace

QString OMC::Scene::colorspace

readwriteinherited

Get/set the colorspace of the scene.

The colorspace name is provided and can be set as a value. In order to get available colorspaces, see OMC::Scene::colorspaces.

Change the colorspace:

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.
print( "Color Space: %s"%(scene.colorspace) )                #Print the current colorspace.
scene.colorspace = "Rec.709"
print( "Color Space: %s"%(scene.colorspace) )                #Expected result: "Color Space: Rec.709"

◆ colorspaces

QStringList OMC::Scene::colorspaces

readinherited

Get list of available colorspace names.

The available colorspaces in the application. These colorspaces are extended and defined in a resource file.

Print available colorspaces:

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.
for colorspace in scene.colorspaces:
  print( "Colour Space Name: %s"%(colorspace) )              #Print the colorspace names.

◆ columns

OMC::Scene::columns

inherited

The list of all columns in the scene.

Columns are the time-based objects that provide values to animateable attributes on nodes. The scene's column list (OMC::ColumnList) is a list containing all columns in the scene and can be used to create, modify and remove columns as needed.

List All Columns:

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.
columns = scene.columns                                      #The overall node list of the scene.
for col in columns:
  print( "Column: %s (%s)"%(col.name, col.type) )

◆ display

OMC::Scene::display

inherited

Provides and sets the display node of the current display.

Provides the OMC::DisplayNode that represents the display node set as the current global display in the scene. This value can be set as needed to different display nodes.

Find and Set a Display 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                                          #The overall node list of the scene.
for node in nodes:
  if node.type.upper() == "DISPLAY":
    scene.display = node
    print( "Set the Display Node to : %s"%(node.path) )
    break

◆ display_name

OMC::Scene::display_name

inherited

Provides and sets the display node of the current display.

Similar to OMC::Scene::display – provides the name of the OMC::DisplayNode as a string to the current display.

Print the Current Display Name

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.
print( "Current Display: %s"%(scene.display_name) )
scene.display_name = None                                    #Set the Display to the generic "Display All" display. 

◆ display_names

QStringList OMC::Scene::display_names

readinherited

Provides a list of the display names available in the scene.

Similar to OMC::Scene::displays, but instead of providing the node object (OMC::Node), provides the display names as strings.
Print the Display Name List

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.
display_names = scene.display_names                          #Get the display_name list.
for display_name in display_names:
  print( "Display: %s"%(display_name) )

◆ displays

OMC::Scene::displays

inherited

Provides a list of the display nodes available in the scene.

Instead of searching for diplay nodes in the scene, OMC::Scene::displays provides a list of Display nodes available within the scene directly. This list cannot be modified directly. Print the Display List

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.
displays = scene.displays                                        
for display in displays:
  print( "Display: %s"%(display.name) )

◆ frame_count

int OMC::Scene::frame_count

readwriteinherited

Get/set the frame count of the scene.

The number of frames in a scene. This value can be changed – frames changes will be applied at the end of the scene. Frames can be added or removed more specifically with OMC::Scene::frame_insert and OMC::Scene::frame_remove.

Change the Scene's frame length

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.
scene.frame_count = 10                                       #Change the frame count to 10.

◆ frame_current

int OMH::HarmonyScene::frame_current

readwrite

Get/set the scene's current frame, only available when used within Harmony's GUI (and not in Batch or External mode).

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
#Advance the current frame of the given scene.
scene.frame_current = scene.frame_current + 1

◆ frame_start

int OMC::Scene::frame_start

readwriteinherited

Get/set the start-frame of the scene.

The frame start is the temporary frame start (in) position of the scene and will be where the playhead starts and restarts at loop.

Change the frame_start to 10:

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.
scene.frame_start = 10

◆ frame_stop

int OMC::Scene::frame_stop

readwriteinherited

Get/set the stop-frame of the scene.

The frame stop is the temporary frame stop (out) position of the scene and will be where the playhead stops and where it will loop when enabled.

Change the frame_stop to 10:

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.
scene.frame_stop = 15

◆ framerate

double OMC::Scene::framerate

readwriteinherited

Get/set the framerate of the scene.

Change the Scene's framerate

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.
scene.framerate = 24000.0/1001.0                             #Set the framerate to 24P NTSC

◆ metadata

OMC::Scene::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.

Note: Some metadata is used internally in the scene, and is not accessible in the DOM scripting.

Print all Metadata 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.
for metadata in scene.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.
metadata = scene.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.

◆ nodes

OMC::Scene::nodes

inherited

The list of all nodes in the scene.

The scene's nodelist provides the list of all the nodes in the scene, regardless of the group hierarchy. This means that all nodes in the scene, inlcuding those in subgroups, should be in this list. It can also be used to create and remove nodes from the scene as needed.

Print path of all Nodes 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                                          #The overall node list of the scene.
for node in nodes:
  print( "Node: %s (%s)"%(node.path, node.type) )

◆ processing_bit_depth

uint OMH::HarmonyScene::processing_bit_depth

readwrite

Provides the processing bit-depth of the scene at render.

The processing bit-depth defines how the Harmony handles the softrendering in the scene. Harmony supports both processing in 16-bit clamped values, and 32-bit floating point values. When using floating-point values, the values are unclamped and allow for values beyond 0 and 1. At 16-bit, the processing is limited to values within the 16-bit range (0 - 32767).

Changing Processing Bit-Depth

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.
print( "Current bit-depth: %s"%(scene.processing_bit_depth) )
scene.processing_bit_depth = 32

◆ selection

OMH::HarmonyScene::selection

Provides the selection handler for the current project.

The selection handler (OMH::Selection) allows for read and write access to the current selection within the scene. This allows for nodes and columns to be referenced by selection, or selected as needed.
Deselecting Undesired 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.
history = proj.history
history.begin( "Deselection unwanted nodes." )               #Selection can add undos (if undoable selection set in preferences)
selection_handler = scene.selection                          #The selection handler.
deselect_bad_nodes = []                                      #We'll iterate the list, find the nodes we want to deselect.
for node in selection_handler.nodes:
  if not node.type.upper() == "PEG":                         #Lets deselect all nodes that ARE NOT pegs.
    deselect_bad_nodes.append( node )                        #We collect them here, to avoid deselecting them while iterating in the for loop; which could be complicated.
if deselect_bad_nodes:
  selection_handler.remove( deselect_bad_nodes )               #Remove non-peg nodes from the selection, leaving ONLY pegs.
  
history.end()

◆ sounds

OMC::Scene::sounds

inherited

The list of sound objects in the scene.

Sounds and sound lists will be implemented in future DOM versions.

◆ top

OMC::Scene::top

inherited

The top group in the scene.

Every scene has an initial 'group' that contains the nodes of the scene. This group is transparent, in that it is not represented by any node in the node view – but it represents the outer-most layer in which nodes can be placed. Every scene starts with this group, named 'Top', and all subsequent nodes are placed within this container.

Identify All Nodes in the 'Top' group of the scene.

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.
nodes = scene.top.nodes                                      #The node list of the nodes contained within the 'Top' group.
for node in nodes:
  print( "Node: %s (%s)"%(node.path, node.type) )
#Note -- this list will identify all nodes directly within the group, and does not consider the contents recursively.
#The node list will not show nodes contained within other groups interior to itself; to do this, a recursive approach should be considered.  
print( "\nNow -- Recursively . . ." )
#Here is a recursive approach, a function that will do the work for us. . .
def recursively_detail_group(group, depth):
  for node in group.nodes:                                         #Look through all if this group's contents.
    print( "%sNode: %s (%s)"%("   "*depth, node.path, node.type) ) #Print Information
    if node.type.upper() == "GROUP":                               #If its a group type, we recursive even further.
      recursively_detail_group( node, depth+1 )                    #Calling this same function will dive deeper into the next group.
recursively_detail_group(scene.top, 0)                             #Start diving into the groups!

◆ unit_converter

OMC::Scene::unit_converter

inherited

The tool used for converting between OGL and scene spaces.

Scenes within Harmony use field units, but most graphical operations use OpenGL units. Depending on the function and the context, conversion between these units are necessary and are done with the unit_converter. This converter (OMC::SceneUnitConverter) will use the scene's metric information to convert between the units.

Conversion from OGL to Field Units

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.
unit_converter = scene.unit_converter                        #The unit converter for this scene.
open_gl_point = harmony.Point3d( 1.0, 1.0, 1.0 )             #A Point3D object in 'OpenGL' units.
field_point   = unit_converter.to_field( open_gl_point )     #Convert it.
#Print the converted field units.
print( "Field Units: %s %s %s"%(field_point.x, field_point.y, field_point.z) )

◆ units

OMC::Scene::units

inherited

Get the number of units of the scene.

The units are provided as an object (OMC::SceneUnits) that provides properties related to the units of the scene.

◆ vector_texture_pixel_density

double OMC::Scene::vector_texture_pixel_density

readwriteinherited

Get/set the default texture pixel density for new Vector Drawings.

The vector texture pixel density is the ratio used for pixel density in textures being applied to vector shapes.

Inheritance diagram for OMH::HarmonyScene:

[legend]

Collaboration diagram for OMH::HarmonyScene:

[legend]

Detailed Description

Public Member Functions

Public Attributes

Member Function Documentation

◆ frame_insert()

◆ frame_remove()

Member Data Documentation

◆ aspect

◆ bitmap_texture_pixel_density

◆ camera

◆ camera_path

◆ center

◆ clipboard

◆ colorspace

◆ colorspaces

◆ columns

◆ display

◆ display_name

◆ display_names

◆ displays

◆ frame_count

◆ frame_current

◆ frame_start

◆ frame_stop

◆ framerate

◆ metadata

◆ nodes

◆ processing_bit_depth

◆ selection

◆ sounds

◆ top

◆ unit_converter

◆ units

◆ vector_texture_pixel_density