# 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

#### activeDrawingin$.oDrawing

  The current drawing of the scene.

#### aspectRatioXdouble

  The horizontal aspect ratio.

#### aspectRatioYdouble

  The vertical aspect ratio.

#### 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.

#### defaultDisplayoNode

  The default Display of the scene.

#### defaultResolutionXint

  The default horizontal resolution.

#### defaultResolutionYint

  The default vertical resolution.

#### 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.

#### 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.

#### resolutionYint

  The vertical resolution.

#### readonlyroot$.oGroupNode

  The root group of the scene.

#### readonlysceneNamestring

  The sceneName file of the scene.
  Deprecated
    - Yes

#### 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 selected frames. This is an array with the start frame and the end frame (non included)

#### 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.

#### unitsXdouble

  The horizontal unit count.

#### unitsYdouble

  The vertical unit count.

#### unitsZdouble

  The depth 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 2192
  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 2181
  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 2203
  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 1950
  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 1979
  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 1090
  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){$.oNode}

openHarmony/openHarmony_scene.js, line 1167
  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
  --- | ---
  $.oNode | The created node, or bool as false.

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

openHarmony/openHarmony_scene.js, line 1137
  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){$.oGroupNode}

openHarmony/openHarmony_scene.js, line 1192
  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.
  `$.` | oPoint | nodePosition The position for the node to be placed in the network.

  Deprecated
    - Use oGroupNode.addGroup instead

  ##### Returns:

  Type | Description
  --- | ---
  $.oGroupNode | The created node, or bool as false.

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

openHarmony/openHarmony_scene.js, line 1067
  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 1255
  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 2115
  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 1360
  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 1712
  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 1767
  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){$.oNode}

openHarmony/openHarmony_scene.js, line 1895
  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.

  ##### Returns:

  Type | Description
  --- | ---
  $.oNode | The imported Quicktime Node.

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

openHarmony/openHarmony_scene.js, line 1566
  export a template from the specified nodes.

  Name | Type | Description
  --- | --- | ---
  `nodes` | Array.<$.oNodes> | The path of the TPL file to import.
  `exportPath` | bool | optional Whether to extend the exposures of the content imported.
  `exportPalettesMode` | string | 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 2130
  Gets the current camera matrix.

  ##### Returns:

  Type | Description
  --- | ---
  Matrix4x4 | The matrix of the camera.

#### getColumnByName(uniqueName, oAttributeObject){$.oColumn}

openHarmony/openHarmony_scene.js, line 703
  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 724
  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 2168
  Gets the current scene's metadata.
  See:
    - $.oMetadata

  ##### Returns:

  Type | Description
  --- | ---
  $.oMetadata | The metadata of the scene.

#### getNodeByPath(fullPath){$.oNode}

openHarmony/openHarmony_scene.js, line 665
  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.

#### getNodesLinks(nodes){Array.<$.oLink>}

openHarmony/openHarmony_scene.js, line 1408
  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 1223
  Gets a 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.

#### getProjectionMatrix(){Matrix4x4}

openHarmony/openHarmony_scene.js, line 2139
  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 741
  Gets the selected Nodes.

  Name | Type | Description
  --- | --- | ---
  `recurse` | bool | Whether to recurse into groups.

  ##### Returns:

  Type | Description
  --- | ---
  Array.<$.oNode> | The selected nodes.

#### getSelectedPalette(){$.oPalette}

openHarmony/openHarmony_scene.js, line 1238
  Grabs the selected palette.
  Deprecated
    - Yes

  ##### Returns:

  Type | Description
  --- | ---
  $.oPalette | oPalette with provided name.

#### getTimeline(display){$.oTimeline}

openHarmony/openHarmony_scene.js, line 1211
  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 1292
  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 1832
  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, nodePosition, extendScene, alignment){$.oNode}

openHarmony/openHarmony_scene.js, line 1922
  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.
  `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.

  Deprecated
    - Yes

  ##### Returns:

  Type | Description
  --- | ---
  $.oNode | The imported Quicktime Node.

#### importSound(path, layerName){$.oNode}

openHarmony/openHarmony_scene.js, line 1873
  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 Quicktime Node.

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

openHarmony/openHarmony_scene.js, line 1689
  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 1459
  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 774
  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)

openHarmony/openHarmony_scene.js, line 2038
  Renders the write nodes of 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

#### save()

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

#### saveAs(newPath)

openHarmony/openHarmony_scene.js, line 2005
  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 2021
  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)

openHarmony/openHarmony_scene.js, line 1852
  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