Class: oScene

$. oScene

The base Class to access all the contents of the scene, and add elements.
This is the main class to do exporting operations as well as column/element/palette creation.

new $.oScene()

openHarmony/openHarmony_scene.js, line 73
The constructor for $.oScene.
Example
// Access to the direct dom object. Available and automatically instantiated as $.getScene, $.scene, $.scn, $.s
var doc = $.getScene ;
var doc = $.scn ;
ver doc = $.s ;         // all these are equivalents

// To grab the scene from a QWidget Dialog callback, store the $ object in a local variable to access all the fonctions from the library.
function myCallBackFunction(){
  var this.$ = $;

  var doc = this.$.scn;
}

Members

activeDrawing$.oDrawing

The currently active drawing in the harmony UI.

aspectRatioXdouble

The horizontal aspect ratio of Field units.

aspectRatioYdouble

The vertical aspect ratio of Field units.

center$.oPoint

The center coordinates of the scene.

readonlycolumnsArray.<$.oColumn>

Contains the list of columns present in the scene.
TODO
  • add attribute finding to get complete column objects

currentFrameint

The current frame of the scene.

readonlycurrentTimeline$.oTimeline

The current timeline using the default Display.

defaultDisplayoNode

The default Display of the scene.

defaultResolutionXint

The default horizontal resolution in pixels.

defaultResolutionYint

The default vertical resolution in pixels.

readonlyelementsArray.<$.oElement>

Contains the list of elements present in the scene. Element ids can appear more than once if they are used by more than one Drawing column

readonlyenvironnementstring

The name of the scene.

readonlyfieldVectorResolutionXdouble

The amount of drawing units represented by 1 field on the horizontal axis.

readonlyfieldVectorResolutionYdouble

The amount of drawing units represented by 1 field on the vertical axis.

fovdouble

The field of view of the scene.

frameratefloat

The frame rate of the scene.

readonlyjobstring

The name of the scene.

lengthint

The length of the scene.

readonlynamestring

The name of the scene.

readonlynodesArray.<$.oNode>

Contains the list of all the nodes present in the scene.

readonlyonlinebool

Wether the scene is hosted on a Toonboom database.

readonlypaletteFolder$.oFolder

The folder that contains this scene.

readonlypalettesArray.<$.oPalette>

Contains the list of scene palettes present in the scene.

readonlypath$.oFolder

The folder that contains this scene.

readonlyresolutionXint

The horizontal resolution in pixels (for rendering).

resolutionYint

The vertical resolution in pixels (for rendering).

readonlyroot$.oGroupNode

The root group of the scene.

readonlysceneNamestring

The sceneName file of the scene.
Deprecated
  • Yes

selectedContoursArray.<$.oContour>

The selected strokes on the currently active Drawing

selectedFramesArray.<int>

Retrieve and change the selected frames. This is an array with two values, one for the start and one for the end of the selection (not included).

selectedNodesArray.<$.oNode>

Retrieve and change the selection of nodes.

selectedPalette$.oPalette

Retrieve and set the selected palette from the scene palette list.

selectedShapesArray.<$.oStroke>

The selected strokes on the currently active Drawing

selectedStrokesArray.<$.oStroke>

The selected strokes on the currently active Drawing

readonlystage$.oFile

The stage file of the scene.

startPreviewint

The startframe to the playback of the scene.

stopPreviewint

The stopFrame to the playback of the scene.

readonlytempFolder$.oFolder

The temporary folder where files are created before being saved. If the folder doesn't exist yet, it will be created.

unitsAspectRatiodouble

The Field unit aspect ratio as a coefficient (width/height).

unitsXdouble

The horizontal Field unit count.

unitsYdouble

The vertical Field unit count.

unitsZdouble

The depth Field unit count.

readonlyunsavedbool

Whether the scene contains unsaved changes.

readonlyversionstring

The name of the scene.

Methods

$column(uniqueName, oAttributeObject){$.oColumn}

openHarmony/openHarmony_scene.js, line 2386
Gets a column by the name.
Name Type Description
uniqueName string The unique name of the column as a string.
oAttributeObject $.oAttribute The oAttribute object the column is linked to.
Returns:
Type Description
$.oColumn The node found given the query.

$node(fullPath){$.oNode}

openHarmony/openHarmony_scene.js, line 2375
Gets a node by the path.
Name Type Description
fullPath string The path of the node in question.
Returns:
Type Description
$.oNode The node found given the query.

$palette(name){$.oPalette}

openHarmony/openHarmony_scene.js, line 2397
Gets a palette by its name.
Name Type Description
name string The name of the palette.
Returns:
Type Description
$.oPalette The node found given the query.

addBackdrop(groupPath, title, body, color, x, y, width, height){$.oBackdrop}

openHarmony/openHarmony_scene.js, line 2130
Adds a backdrop to a group in a specific position.
Name Type Description
groupPath string The group in which this backdrop is created.
title string The title of the backdrop.
body string The body text of the backdrop.
color $.oColorValue The oColorValue of the node.
x float The X position of the backdrop, an offset value if nodes are specified.
y float The Y position of the backdrop, an offset value if nodes are specified.
width float The Width of the backdrop, a padding value if nodes are specified.
height float The Height of the backdrop, a padding value if nodes are specified.
Deprecated
  • Yes
Returns:
Type Description
$.oBackdrop The created backdrop.

addBackdropToNodes(groupPath, nodes, title, body, color, x, y, width, height){$.oBackdrop}

openHarmony/openHarmony_scene.js, line 2159
Adds a backdrop to a group around specified nodes
Name Type Description
groupPath string The group in which this backdrop is created.
nodes Array.<$.oNode> The nodes that the backdrop encompasses.
title string The title of the backdrop.
body string The body text of the backdrop.
color $.oColorValue The oColorValue of the node.
x float The X position of the backdrop, an offset value if nodes are specified.
y float The Y position of the backdrop, an offset value if nodes are specified.
width float The Width of the backdrop, a padding value if nodes are specified.
height float The Height of the backdrop, a padding value if nodes are specified.
Deprecated
  • Yes
Returns:
Type Description
$.oBackdrop The created backdrop.

addColumn(type, name, oElementObject){$.oColumn}

openHarmony/openHarmony_scene.js, line 1234
Adds a column to the scene.
Name Type Description
type string The type of the column.
name string The name of the column.
oElementObject $.oElement For Drawing column, the element that will be represented by the column.
Returns:
Type Description
$.oColumn The created column

addDrawingNode(name, group, nodePosition, element, drawingColumn, options){$.oDrawingNode}

openHarmony/openHarmony_scene.js, line 1314
Adds a drawing layer to the scene, with a drawing column and element linked. Possible to specify the column and element to use.
Name Type Description
name string The name of the newly created node.
group string The group in which the node is added.
nodePosition $.oPoint The position for the node to be placed in the network.
element $.object The element to attach to the column.
drawingColumn object The column to attach to the drawing module.
options object The creation options, nothing available at this point.
Deprecated
  • Use oGroupNode.addDrawingNode instead
    Returns:
    Type Description
    $.oDrawingNode The created node.

    addElement(name, imageFormat, fieldGuide, scanType){$.oElement}

    openHarmony/openHarmony_scene.js, line 1281
    Adds an element to the scene.
    Name Type Default Description
    name string The name of the element
    imageFormat string "TVG" optional The image format in capital letters (ex: "TVG", "PNG"...)
    fieldGuide int 12 optional The field guide .
    scanType string "COLOR" optional can have the values "COLOR", "GRAY_SCALE" or "BW".
    Returns:
    Type Description
    $.oElement The created element

    addGroup(name, includeNodes, addComposite, addPeg, group, nodePosition){$.oGroupNode}

    openHarmony/openHarmony_scene.js, line 1339
    Adds a group to the scene.
    Name Type Description
    name string The name of the newly created group.
    includeNodes string The nodes to add to the group.
    addComposite $.oPoint Whether to add a composite.
    addPeg bool Whether to add a peg.
    group string The group in which the node is added.
    nodePosition $.oPoint The position for the node to be placed in the network.
    Deprecated
    • Use oGroupNode.addGroup instead
      Returns:
      Type Description
      $.oGroupNode The created node.

      addNode(type, name, group, nodePosition){$.oNode}

      openHarmony/openHarmony_scene.js, line 1211
      Adds a node to the scene.
      Name Type Description
      type string The type-name of the node to add.
      name string The name of the newly created node.
      group string The groupname to add the node.
      nodePosition $.oPoint The position for the node to be placed in the network.
      Deprecated
      • use AddNode directly in the destination group by calling it on the oGroupNode
        Returns:
        Type Description
        $.oNode The created node

        addPalette(name, index, paletteStorage, storeInElement){$.oPalette}

        openHarmony/openHarmony_scene.js, line 1413
        Add a palette object to the scene palette list and into the specified location.
        Name Type Description
        name string The name for the palette.
        index string Index at which to insert the palette.
        paletteStorage string Storage type: environment, job, scene, element, external.
        storeInElement $.oElement The element to store the palette in. If paletteStorage is set to "external", provide a destination folder for the palette here.
        Returns:
        Type Description
        $.oPalette newly created oPalette with provided name.

        close(exit)

        openHarmony/openHarmony_scene.js, line 2309
        Closes the scene.
        Name Type Description
        exit bool optional Whether it should exit after closing.

        createPaletteFromNodes(nodes, paletteName, colorName){Array.<$.oLink>}

        openHarmony/openHarmony_scene.js, line 1517
        Creates a single palette containing all the individual colors used by an ensemble of nodes.
        Name Type Description
        nodes Array.<$.oNode> The nodes to look at.
        paletteName string optional A custom name for the created palette.
        colorName string optional A custom name to give to the gathered colors.
        Returns:
        Type Description
        Array.<$.oLink> An array of unique links existing between the nodes.

        exportLayoutImage(path, includedNodes, exportFrame, exportCameraFrame, exportBackground, frameScale)

        openHarmony/openHarmony_scene.js, line 1886
        Exports a png of the selected node/frame. if no node is given, all layers will be visible.
        Name Type Default Description
        path $.oFile The path in which to save the image. Image will be outputted as PNG.
        includedNodes $.oNode optional The nodes to include in the rendering. If no node is specified, all layers will be visible.
        exportFrame int optional The frame at which to create the image. By default, the timeline current Frame.
        exportCameraFrame bool false optional Whether to export the camera frames
        exportBackground bool false optional Whether to add a white background.
        frameScale float 1 optional A factor by which to scale the frame. ex: 1.05 will add a 10% margin (5% on both sides)

        exportPSD(path, margin, layersDescription)

        openHarmony/openHarmony_scene.js, line 1941
        Export the scene as a single PSD file, with layers described by the layerDescription array. This function is not supported in batch mode.
        Name Type Description
        path $.oFile
        margin float a factor by which to increase the rendering area. for example, 1.05 creates a 10% margin. (5% on each side)
        layersDescription Array.<Object> must be an array of objects {layer: $.oNode, frame: int} which describe all the images to export. By default, will include all visible layers of the timeline.

        exportQT(path, display, scale, exportSound, exportPreviewArea, createThumbnail){bool}

        openHarmony/openHarmony_scene.js, line 2072
        Exports a QT of the scene
        Name Type Description
        path string The path to export the quicktime file to.
        display string The name of the display to use to export.
        scale double The scale of the export compared to the scene resolution.
        exportSound bool Whether to include the sound in the export.
        exportPreviewArea bool Whether to only export the preview area of the timeline.
        createThumbnail bool Whether to create a thumbnail at the first frame.
        Returns:
        Type Description
        bool The success of the export

        exportTemplate(nodes, exportPath, exportPalettesMode, renameUsedColors=, copyOptions){bool}

        openHarmony/openHarmony_scene.js, line 1746
        export a template from the specified nodes.
        Name Type Default Description
        nodes Array.<$.oNodes> The list of nodes included in the template.
        exportPath bool optional The path of the TPL file to export.
        exportPalettesMode string 'usedOnly' optional can have the values : "usedOnly", "all", "createPalette"
        renameUsedColors= string optional if creating a palette, optionally set here the name for the colors (they will have a number added to each)
        copyOptions copyOptions optional An object containing paste options as per Harmony's standard paste options.
        TODO
        • turn exportPalettesMode into an enum?
        Returns:
        Type Description
        bool The success of the export.
        Example
        // how to export a clean palette with no extra drawings and everything renamed by frame, and only the necessary colors gathered in one palette:

$.beginUndo();

var doc = $.scn;
var nodes = doc.getSelectedNodes();

for (var i in nodes){
  if (nodes[i].type != "READ") continue;

  var myColumn = nodes[i].element.column;      // we grab the column directly from the element of the node
  myColumn.removeUnexposedDrawings();          // remove extra unused drawings
  myColumn.renameAllByFrame();                 // rename all drawings by frame
}

doc.exportTemplate(nodes, "C:/templateExample.tpl", "createPalette"); // "createPalette" value will create one palette for all colors

$.endUndo();

        getCameraMatrix(){Matrix4x4}

        openHarmony/openHarmony_scene.js, line 2324
        Gets the current camera matrix.
        Returns:
        Type Description
        Matrix4x4 The matrix of the camera.

        getColumnByName(uniqueName, oAttributeObject){$.oColumn}

        openHarmony/openHarmony_scene.js, line 847
        Gets a column by the name.
        Name Type Description
        uniqueName string The unique name of the column as a string.
        oAttributeObject $.oAttribute The oAttributeObject owning the column.
        TODO
        • cache and find attribute if it is missing
        Returns:
        Type Description
        $.oColumn The column found given the query.

        getElementById(id, oColumnObject){$.oElement}

        openHarmony/openHarmony_scene.js, line 868
        Gets an element by Id.
        Name Type Description
        id string The unique name of the column as a string.
        oColumnObject $.oColumn optional The oColumn object linked to the element in case of duplicate.
        Returns:
        Type Description
        $.oElement The element found given the query. In case of an element linked to several column, only the first one will be returned, unless the column is specified

        getMetadata(){$.oMetadata}

        openHarmony/openHarmony_scene.js, line 2362
        Gets the current scene's metadata.
        See:
        Returns:
        Type Description
        $.oMetadata The metadata of the scene.

        getNodeByPath(fullPath){$.oNode}

        openHarmony/openHarmony_scene.js, line 787
        Gets a node by the path.
        Name Type Description
        fullPath string The path of the node in question.
        Returns:
        Type Description
        $.oNode The node found given the query.

        getNodesByType(typeName){Array.<$.oNode>}

        openHarmony/openHarmony_scene.js, line 821
        Returns the nodes of a certain type in the entire scene.
        Name Type Description
        typeName string The name of the node.
        Returns:
        Type Description
        Array.<$.oNode> The nodes found.
        openHarmony/openHarmony_scene.js, line 1550
        Returns all the links existing between an ensemble of nodes.
        Name Type Description
        nodes Array.<$.oNode> The nodes to look at.
        Returns:
        Type Description
        Array.<$.oLink> An array of unique links existing between the nodes.

        getPaletteByName(name){$.oPalette}

        openHarmony/openHarmony_scene.js, line 1369
        Gets a scene palette by the name.
        Name Type Description
        name string The palette name to query and find.
        Returns:
        Type Description
        $.oPalette The oPalette found given the query.

        getPaletteByPath(path){$.oPalette}

        openHarmony/openHarmony_scene.js, line 1382
        Gets a scene palette by the path of the plt file.
        Name Type Description
        path string The palette path to find.
        Returns:
        Type Description
        $.oPalette The oPalette or null if not found.

        getProjectionMatrix(){Matrix4x4}

        openHarmony/openHarmony_scene.js, line 2333
        Gets the current projection matrix.
        Returns:
        Type Description
        Matrix4x4 The projection matrix of the camera/scene.

        getSelectedNodes(recurse){Array.<$.oNode>}

        openHarmony/openHarmony_scene.js, line 885
        Gets the selected Nodes.
        Name Type Description
        recurse bool Whether to recurse into groups.
        Returns:
        Type Description
        Array.<$.oNode> The selected nodes.

        getSelectedNodesOfType(types, recuse){Array.<$.oNode>}

        openHarmony/openHarmony_scene.js, line 832
        Returns the selected nodes of a certain type in the entire scene.
        Name Type Description
        types Array.<string> The types of nodes that will be returned (if only one is provided, doesn't need to be an array)
        recuse bool Wether to include nodes inside selected groups in selection.
        Returns:
        Type Description
        Array.<$.oNode> The nodes found.

        getSelectedPalette(){$.oPalette}

        openHarmony/openHarmony_scene.js, line 1396
        Grabs the selected palette.
        Deprecated
        • Yes
        Returns:
        Type Description
        $.oPalette oPalette with provided name.

        getTimeline(display){$.oTimeline}

        openHarmony/openHarmony_scene.js, line 1358
        Grabs the timeline object for a specific display.
        Name Type Description
        display string optional The display node to build the timeline for.
        Returns:
        Type Description
        $.oTimeline The timelne object given the display.

        importPalette(path, name, index, paletteStorage, storeInElement){$.oPalette}

        openHarmony/openHarmony_scene.js, line 1450
        Imports a palette to the scene palette list and into the specified storage location.
        Name Type Description
        path string The palette file to import.
        name string The name for the palette.
        index string Index at which to insert the palette.
        paletteStorage string Storage type: environment, job, scene, element, external.
        storeInElement $.oElement The element to store the palette in. If paletteStorage is set to "external", provide a destination folder for the palette here.
        Returns:
        Type Description
        $.oPalette oPalette with provided name.

        importPSD(path, group, nodePosition, separateLayers, addPeg, addComposite, alignment){Array.<$.oNode>}

        openHarmony/openHarmony_scene.js, line 2006
        Imports a PSD to the scene.
        Name Type Description
        path string The palette file to import.
        group string optional The path of the existing group to import the PSD into.
        nodePosition $.oPoint optional The position for the node to be placed in the network.
        separateLayers bool optional Separate the layers of the PSD.
        addPeg bool optional Whether to add a peg.
        addComposite bool optional Whether to add a composite.
        alignment string optional Alignment type.
        Deprecated
        • use oGroupNode.importPSD instead
          Returns:
          Type Description
          Array.<$.oNode> The nodes being created as part of the PSD import.

          importQT(path, group, importSound, nodePosition, extendScene, alignment, convertToTvg){$.oNode}

          openHarmony/openHarmony_scene.js, line 2102
          Imports a QT into the scene
          Name Type Description
          path string The quicktime file to import.
          group string The group to import the QT into.
          importSound bool Whether to import the sound
          nodePosition $.oPoint The position for the node to be placed in the network.
          extendScene bool Whether to extend the scene to the duration of the QT.
          alignment string Alignment type.
          convertToTvg bool Convert movie frames to TVG format.
          Deprecated
          • Yes
          Returns:
          Type Description
          $.oNode The imported Quicktime Node.

          importSound(path, layerName){$.oNode}

          openHarmony/openHarmony_scene.js, line 2049
          Imports a sound into the scene
          Name Type Description
          path string The sound file to import.
          layerName string The name to give the layer created.
          Returns:
          Type Description
          $.oNode The imported sound column.

          importTemplate(tplPath, group, destinationNodes, extendScene, nodePosition, pasteOptions){Array.<$.oNode>}

          openHarmony/openHarmony_scene.js, line 1863
          Imports the specified template into the scene.
          Name Type Description
          tplPath string The path of the TPL file to import.
          group string optional The path of the existing target group to which the TPL is imported.
          destinationNodes Array.<$.oNode> optional The nodes affected by the template.
          extendScene bool optional Whether to extend the exposures of the content imported.
          nodePosition $.oPoint optional The position to offset imported new nodes.
          pasteOptions object optional An object containing paste options as per Harmony's standard paste options.
          Deprecated
          • Yes
          Returns:
          Type Description
          Array.<$.oNode> The resulting pasted nodes.

          mergeNodes(nodes, resultName, deleteMerged){$.oNode}

          openHarmony/openHarmony_scene.js, line 1601
          Merges Drawing nodes into a single node.
          Name Type Description
          nodes Array.<$.oNode> The Drawing nodes to merge.
          resultName string The Node name for the resulting node of the merged content.
          deleteMerged bool Whether the original nodes be deleted.
          Returns:
          Type Description
          $.oNode The resulting drawing node from the merge.

          nodeSearch(query){Array.<$.oNode>}

          openHarmony/openHarmony_scene.js, line 918
          Searches for a node based on the query.
          Name Type Description
          query string The query for finding the node[s].
          Returns:
          Type Description
          Array.<$.oNode> The node[s] found given the query.

          renderWriteNodes(renderInBackground, startFrame, endFrame, resX, resY, preRenderScript, postRenderScript){$.oProcess}

          openHarmony/openHarmony_scene.js, line 2219
          Renders the write nodes of the scene. This action saves the scene.
          Name Type Default Description
          renderInBackground bool true optional Whether to do the render on the main thread and block script execution
          startFrame int 1 optional The first frame to render
          endFrame int oScene.length optional The end of the render (non included)
          resX int optional The horizontal resolution of the render. Uses the scene resolution by default.
          resY int optional The vertical resolution of the render. Uses the scene resolution by default.
          preRenderScript string optional The path to the script to execute on the scene before doing the render
          postRenderScript string optional The path to the script to execute on the scene after the render is finished
          Returns:
          Type Description
          $.oProcess In case of using renderInBackground, will return the oProcess object doing the render

          save()

          openHarmony/openHarmony_scene.js, line 2176
          Saves the scene.

          saveAs(newPath)

          openHarmony/openHarmony_scene.js, line 2185
          Saves the scene in a different location (only available on offline scenes).
          Name Type Description
          newPath string the new location for the scene (must be a folder path and not a .xstage)

          saveNewVersion(newVersionName, markAsDefault)

          openHarmony/openHarmony_scene.js, line 2201
          Saves the scene as new version.
          Name Type Description
          newVersionName string The name for the new version
          markAsDefault bool Wether to make this new version the default version that will be opened from the database.

          updatePSD(path, separateLayers){Array.<$.oNode>}

          openHarmony/openHarmony_scene.js, line 2028
          Updates a previously imported PSD by matching layer names.
          Name Type Description
          path string The PSD file to update.
          separateLayers bool optional Whether the PSD was imported as separate layers.
          Deprecated
          • Yes
          Returns:
          Type Description
          Array.<$.oNode> The nodes affected by the update