MochaImportPlusAPI.js

Summary
MochaImportPlusAPI.js
Using The MochaImport+ APIGetting started with the MochaImport+ API
MochaImportPlusdocumentation of all MochaImportPlus API functions available in the MochaImportPlus object
Variables
versionThe version number of MochaImport+
Functions
createMochaProjectCreates a mocha project for the given AV layer.
openProjectInMochaLaunches mocha and opens the given mocha project file in it.
setMochaVersionSets the version of mocha that should be used by the function openProjectInMocha.
getAllInstalledMochaVersionsReturns the name, file path and id for all versions of mocha that are installed on the system.
loadFromFileloads mocha tracking data from a file
loadFromClipboardloads mocha tracking data from the clipboard
cornerPincreates a corner pin effect on the given layer
stabilizeLayerapplies the stabilize function of MochaImport+ to the given layer.
stabilizedPrecompTurns the given layer into a stabilized precomp.
createMoveNullLayerCreates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data.
moveLayersCreates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it.
movePropertiesMoves the given 2d point properties, masks or shapes with the tracking data.
generateAETrackpointsGenerates After Effects trackpoints on the given layer based on the loaded mocha tracking data.
addKeyframesToPropertiesAdds a keyframe for each of the given properties at the specified time.
Miscellaneous
Exceptionserror handling in the MochaImport+ API
Undo Groupshow to use Undo Groups with the MochaImport+ API
LicensingTo use the MochaImport+ API, all you need is a normal license of MochaImport+.

Using The MochaImport+ API

Getting started with the MochaImport+ API

The entire API is encapsulated in the MochaImportPlus object.  This object offers functions to load tracking data, to create mocha projects and to apply the tracking data in various ways.

To use the API, you first need an instance of this object.  If you have the MochaImport+ user interface open in After Effects, an instance of this Object with name mochaImportPlus already exists ready to use.

// load tracking data from the clipboard into the MochaImport+ that is open in the user interface
mochaImportPlus.loadFromClipboard({silent:true});

If you want to write a script that runs independently, even if MochaImport+ is not open in After Effects, you need to create your own instance.  For this you need the file MochaImportPlusAPI.jsxbin which you can download at http://mochaimport-api.mamoworld.com/downloads/MochaImportPlusAPI.jsxbin.

The following example creates such a new instance, loads tracking data from the clipboard into it and creates a new null layer that moves with the tracking data.

// load the MochaImport+ API
// this assumes that MochaImportPlusAPI.jsxbin is located in the same folder as this script
var APIfolder = (new File($.fileName)).parent;
var APIfile = new File(APIfolder.fsName+"/MochaImportPlusAPI.jsxbin");
APIfile.open("r");
var APIstring =  APIfile.read();
APIfile.close();
eval(APIstring);

// create your own instance of a MochaImportPlus object
var myMochaImportPlus = new MochaImportPlus();

// load tracking data from the clipboard
myMochaImportPlus.loadFromClipboard({silent:true});

// create a null layer in the selected comp to move with the tracking data
var comp = app.project.activeItem;
myMochaImportPlus.createMoveNullLayer(comp);

MochaImportPlus

documentation of all MochaImportPlus API functions available in the MochaImportPlus object

Summary
Variables
versionThe version number of MochaImport+
Functions
createMochaProjectCreates a mocha project for the given AV layer.
openProjectInMochaLaunches mocha and opens the given mocha project file in it.
setMochaVersionSets the version of mocha that should be used by the function openProjectInMocha.
getAllInstalledMochaVersionsReturns the name, file path and id for all versions of mocha that are installed on the system.
loadFromFileloads mocha tracking data from a file
loadFromClipboardloads mocha tracking data from the clipboard
cornerPincreates a corner pin effect on the given layer
stabilizeLayerapplies the stabilize function of MochaImport+ to the given layer.
stabilizedPrecompTurns the given layer into a stabilized precomp.
createMoveNullLayerCreates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data.
moveLayersCreates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it.
movePropertiesMoves the given 2d point properties, masks or shapes with the tracking data.
generateAETrackpointsGenerates After Effects trackpoints on the given layer based on the loaded mocha tracking data.
addKeyframesToPropertiesAdds a keyframe for each of the given properties at the specified time.

Variables

version

this.version

The version number of MochaImport+

Examples

alert("I am using MochaImport+ version "+mochaImportPlus.version);

Functions

createMochaProject

this.createMochaProject = function(layer,
options)

Creates a mocha project for the given AV layer.  To also includes masks of this layer in the project, either don’t set options.silent (in which case the user will be prompted which masks should be send), or set options.maskToLayerMapping.

Parameters

layeran AV Layer for which a project should be created
optionsan optional object that may contain the following members:
options.silentdon’t show a dialog to check for existing projects or choose which mask goes on which mocha layer
options.projectFileFile object to which the project should be written (only considered if options.silent == true)
options.maskToLayerMappingArray or Arrays of mask indices; [[1],[2,3]] means place first mask on first mocha layer and second and third mask on second mocha layer (only considered if options.silent == true)
options.projectFormatVersion”v3” or “v4” (default = “v4”, only change this is you work with a very old version of mocha that does not accept v4 format)
options.colorDepth”auto”, “force8”, “force16”, or “force32” (don’t set this parameter unless you know what you do - not all codecs work with each color depth)
options.ProjectOutputDirectoryFolder Object or String where mocha should put its rendered files (default = same as mocha project location)
options.UseAbsoluteOutputDirectoryonly use this in combination with options.ProjectOutputDirectory Returns:

the File object for the created file throws the string “user canceled” when the user clicked cancel in one of the dialogs that may popup (the dialogs asking whether an existing project should be opened or which masks should go on which mocha layer).

Examples

// same as clicking the "send to mocha" button of MochaImport+ with the given layer selected
try {
    var myProjectFile = mochaImportPlus.createMochaProject(layer);
    mochaImportPlus.openProjectInMocha(myProjectFile);
}
catch(error){
    if(error != "user canceled"){
        throw error;  // must be some more serious error
    }
}
// write mocha project for the layer to the specified file and ignore any masks
mochaImportPlus.createMochaProject(layer, {silent:true, projectFile: new File('path/to/my/mochaProject.mocha')});
// write mocha project for the layer to the specified file and
// place the four masks of the layer all on the same mocha layer
// requires the layer to have at least 4 masks
mochaImportPlus.createMochaProject(layer, {silent:true, projectFile: new File('path/to/my/mochaProject.mocha'), maskToLayerMapping:[[1,2,3,4]]});
// write mocha project for the layer to the specified file and
// place the first three masks of the layer all to separate mocha layers
// requires the layer to have at least 3 masks
mochaImportPlus.createMochaProject(layer, {silent:true, projectFile: new File('path/to/my/mochaProject.mocha'), maskToLayerMapping:[[1][2][3]]});
// create mocha project with custom absolute output directory
mochaImportPlus.createMochaProject(layer,
   {  projectFile: new File('path/to/my/mochaProject.mocha'),
    ProjectOutputDirectory : new Folder("path/to/my/output/"),
    UseAbsoluteOutputDirectory : true
   }
// create mocha project with custom relative output directory (relative to footage path)
mochaImportPlus.createMochaProject(layer,
   {  projectFile: new File('path/to/my/mochaProject.mocha'),
    ProjectOutputDirectory : '../relative/path/',
    UseAbsoluteOutputDirectory : false
   }

openProjectInMocha

this.openProjectInMocha = function(projectFile)

Launches mocha and opens the given mocha project file in it.

Parameters

projectFilea File object for the mocha project file that should be opened in mocha.

Returns

nothing

Examples

 // creates a mocha project for the given layer and opens it in mocha
var myProjectFile = mochaImportPlus.createMochaProject(layer,{silent:true});
mochaImportPlus.openProjectInMocha(myProjectFile);

setMochaVersion

this.setMochaVersion = function(id)

Sets the version of mocha that should be used by the function openProjectInMocha.

Parameters

idid of the version of mocha that should be used.  Must be one of the ids returned by getAllInstalledMochaVersions or -1 to choose the system default program for .mocha files (which is the program that is used to open a .mocha file when you double-click on it in a file browser)

Returns

nothing

Examples

 // use system default program for .mocha files
mochaImportPlus.setMochaVersion(-1);
 // retrieve all versions of mocha available on this system and configure MochaImport+ to use the first one on this list
var myMochaPrograms = mochaImportPlus.getAllInstalledMochaVersions();
mochaImportPlus.setMochaVersion(myMochaPrograms[0].id);
alert("from now on, mochaImportPlus.openProjectInMocha will use the following version of mocha: "+myMochaPrograms[0].name);

getAllInstalledMochaVersions

this.getAllInstalledMochaVersions = function()

Returns the name, file path and id for all versions of mocha that are installed on the system.

Parameters

none

Returns

an Array of Objects of the form {name: String, file: File, id: number} each representing one version of mocha that is installed on the system.  Name is a human readable name for the variant of the program like “mocha AE CS6” or “mocha Pro” The file is the executable file of the mocha version or is null for mocha versions that are bundled with AE and cannot be launched independently. id is the id as needed by the function setMochaVersion.

Examples

 // retrieve all versions of mocha available on this system and configure MochaImport+ to use the first one on this list
var myMochaPrograms = mochaImportPlus.getAllInstalledMochaVersions();
mochaImportPlus.setMochaVersion(myMochaPrograms[0].id);
alert("from now on, mochaImportPlus.openProjectInMocha will use the following version of mocha: "+myMochaPrograms[0].name);

loadFromFile

this.loadFromFile = function(file,
options)

loads mocha tracking data from a file

Parameters

filea ExtendScript File object.
optionsan optional object that may contain the following members:
options.silentshow no dialog to interpret the keyframe data
options.fpsoverwrites the frames per second information from the tracking data file (only used if silent==true)
options.frameOffsetat which frame of the comp the tracking data starts (default = 0, only used if silent==true)

Returns

nothing

Examples

// loads tracking data and shows dialog to ask which layer was tracked
// (to figure out where tracking data starts and if fps is correct)
mochaImportPlus.loadFromFile(new File("/path/to/my/file.txt"),{silent:true});
// loads tracking data without prompting for details, tracking data starts at frame 0
mochaImportPlus.loadFromFile(new File("/path/to/my/file.txt"),{silent:true});
// loads tracking data without prompting for details, tracking data starts at frame 20
// framerate of tracking data file is ignored and replaced by 25fps
mochaImportPlus.loadFromFile(new File("/path/to/my/file.txt"),{silent:true, fps:25, frameOffset:20});

loadFromClipboard

this.loadFromClipboard = function(options)

loads mocha tracking data from the clipboard

Parameters

optionsan optional object that may contain the following members:
options.silentshow no dialog to interpret the keyframe data
options.fpsoverwrites the frames per second information from the tracking data file (only used if silent==true)
options.frameOffsetat which frame of the comp the tracking data starts (default = 0, only used if silent==true)

Returns

nothing

Examples

// loads tracking data and shows dialog to ask which layer was tracked
// (to figure out where tracking data starts and if fps is correct)
mochaImportPlus.loadFromClipboard({silent:true});
// loads tracking data without prompting for details, tracking data starts at frame 0
mochaImportPlus.loadFromClipboard({silent:true});
// loads tracking data without prompting for details, tracking data starts at frame 20
// framerate of tracking data file is ignored and replaced by 25fps
mochaImportPlus.loadFromClipboard({silent:true, fps:25, frameOffset:20});

cornerPin

this.cornerPin = function(layer,
options)

creates a corner pin effect on the given layer

Parameters

layerthe layer to which the effect should be applied
optionsan optional object that may contain the following members
options.silentshow no dialog for details like which corner pin effect to choose and whether the tracking data should be applied as expression or keyframes
options.cornerPinEffectmatchname of any supported corner pin effect (only used if silent==true) supported matchnames are “ADBE Corner Pin”, “CC Power Pin”, “ADBE BEZMESH”, “APC CardDanceCam”, “rg CornerPin”, “BCC3CornerPin”, “RE:Map Planar”, “S_WarpCornerPin”, “Mettle FreeForm Pro”
options.useExpressionInsteadOfKeyframescan be true or false.  It this is true, the trackingdata is represented with an expression instead of writing lots of keyframes.

Returns

the PropertyGroup of the created corner pin effect

Examples

// applies the default corner pin effect to the layer and stores it in the
// variable myCornerPinEffect
var myCornerPinEffect = mochaImportPlus.cornerPin(layer, {silent:true});
// applies the default corner pin effect to the layer but
// represents the tracking data with an expression instead of keyframes
mochaImportPlus.cornerPin(layer, {silent:true,useExpressionInsteadOfKeyframes:true});
// applies a bezier warp effect to the layer
mochaImportPlus.cornerPin(layer, {silent:true,cornerPinEffect:'ADBE BEZMESH'});

stabilizeLayer

this.stabilizeLayer = function(layer,
options)

applies the stabilize function of MochaImport+ to the given layer.  Depending on whether transform data or corner pin data is loaded, this function uses a different technique to stabilize.  With corner pin data, the corner pin region is “unstretched” like in a stabilized precomp.  For transform data, the movement can either be eliminated completely or only be smoothed.  Usually, you want to do a stabilize with transform data.

Parameters

layerthe layer that should be stabilized
optionsan optional object that may contain the following members
options.silentif this is NOT true, a dialog is shown that allows the user to choose all the other options below.
options.smoothMovementif this is true, the movement is not eliminated completely, but a rig is created that allows to smooth the movement (only used if transform data is loaded and silent==true)
options.cornerPinEffectmatchname of any supported corner pin effect (only used if corner pin data is loaded and silent==true) supported matchnames are “CC Power Pin”, “rg CornerPin”, “RE:Map Planar”
options.useExpressionInsteadOfKeyframescan be true or false.  It this is true, the trackingdata is represented with an expression instead of writing lots of keyframes.

Returns

nothing

Examples

// applies the default stabilization to the layer
//(works with both transform or corner pin data loaded)
mochaImportPlus.applyStabilize(layer, {silent:true});
// creates the stabilization rig that smoothes the movement
// (works only with transform data loaded)
mochaImportPlus.applyStabilize(layer, {silent:true,smoothMovement:true});

stabilizedPrecomp

this.stabilizedPrecomp = function(layer,
options)

Turns the given layer into a stabilized precomp.

Parameters

layerthe layer that should be stabilized
optionsan optional object that may contain the following members
options.silentif this is NOT true, a dialog is shown that allows the user to choose all the other options below.
options.cornerPinEffectmatchname of any supported corner pin effect (only used if corner pin data is loaded and silent==true) supported matchnames are “CC Power Pin”, “rg CornerPin”, “RE:Map Planar”
options.useExpressionInsteadOfKeyframescan be true or false.  It this is true, the trackingdata is represented with an expression instead of writing lots of keyframes (only used if corner pin data is loaded and silent==true)

Returns

the layer representing the stabilized precomp

Examples

// creates a stabilized precomp and stores both the precomp layer in the main comp
// and the precomp itself in some variables.
// works with both transform data and corner pin data
// if corner pin data is loaded, a dialog is shown to the user to choose all options
var precompLayerInMainComp = mochaImportPlus.stabilizedPrecomp(layer);
var precomp = precompLayerInMainComp.source;
// creates a stabilized precomp with the default options
//(works with both transform or corner pin data loaded)
mochaImportPlus.stabilizedPrecomp(layer, {silent:true});
// creates a stabilized precomp using the Red Giant Warp Plugin and
// with expressions instead of keyframes
//(works only with corner pin data loaded)
mochaImportPlus.stabilizedPrecomp(layer, {silent:true, cornerPinEffect:"rg CornerPin", useExpressionInsteadOfKeyframes:true});

createMoveNullLayer

this.createMoveNullLayer = function(comp)

Creates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data.  Requires mocha transform data to be loaded.

Parameters

compthe comp in which the null layer should be created

Returns

the created null layer

Examples

// works only if transform data is loaded
var nullLayer = mochaImportPlus.createMoveNullLayer(comp);

moveLayers

this.moveLayers = function(layerArray)

Creates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it.  As a result, all these layers move with the track.  Requires mocha transform data to be loaded.  All layers in the given array must belong to the same composition.

Parameters

layerArrayan array containing all the Layer objects of the layers that should be moved with the track.  All of these layers must belong to the same composition.

Returns

the created null layer

Examples

// moves the layer with name "my layer" with the tracking data
// works only if transform data is loaded
var nullLayer = mochaImportPlus.moveLayers([comp.layer("my layer")]);
// moves the first three layers of a comp with the tracking data
// works only if transform data is loaded
mochaImportPlus.moveLayers([comp.layer(1),comp.layer(2),comp.layer(3)]);

moveProperties

this.moveProperties = function(propertyArray,
options)

Moves the given 2d point properties, masks or shapes with the tracking data.  The current time is taken as the reference frame, i.e. at the current frame the property remains unchanged and at all other points in time the properties are moved relative to the current frame.  This function requires corner pin data (without motion blur) to be loaded.

Parameters

propertyArrayan array of properties that should be used.  Properties that are no spacial 2d properties and no shapes are ignored.  If a mask PropertyGroup is included in the array, the mask shape of this mask is moved.
optionsan optional object that may contain the following members
options.silentshow no dialog to ask whether the tracking data should be applied as expressions or keyframes (if all properties are masks, no dialog is shown anyway, since the expressions variant is only available for 2d point properties).
options.useExpressionInsteadOfKeyframescan be true or false.  It this is true, the trackingdata is represented with an expression instead of writing lots of keyframes.  This option only affects 2d point properties, since masks cannot be moved with expressions.  (is only considered if options.silent==true)

Returns

true if the properties have been moved and false otherwise (false may only occur if the user clicked cancel in the dialog which asks whether expressions or keyframes should be generated).

Examples

// moves all selected masks and 2d point properties of the layer
// and shows a dialog whether they should be moved based on keyframes or expressions
 mochaImportPlus.moveProperties(comp.selectedProperties);
// moves all selected masks and 2d point properties of the layer
// and represents the tracking data with keyframes
 mochaImportPlus.moveProperties(comp.selectedProperties,{silent:true});
// moves all selected masks and 2d point properties of the layer
// and represents the tracking data with expressions
 mochaImportPlus.moveProperties(comp.selectedProperties,{silent:true, useExpressionInsteadOfKeyframes:true});

generateAETrackpoints

this.generateAETrackpoints = function(layer)

Generates After Effects trackpoints on the given layer based on the loaded mocha tracking data.  For transform data one trackpoint is created, one trackpoint is created for each of the four corners.

Parameters

layerthe layer on which the trackpoints should be created

Returns

the tracker PropertyGroup containing the generated trackpoints

Examples

// this only works when transform data is loaded
var tracker = mochaImportPlus.generateAETrackpoints(layer)
var myTrackpoint = tracker.property('Mocha Point');
alert("my new trackpoint has "+ myTrackpoint.property("ADBE MTracker Pt Attach Pt").numKeys +" keyframes");
// this only works when cornerpin data is loaded
var tracker = mochaImportPlus.generateAETrackpoints(layer)
var firstCornerPoint = tracker.property('Corner Pin Point 0');
var secondCornerPoint = tracker.property('Corner Pin Point 1');
var thirdCornerPoint = tracker.property('Corner Pin Point 2');
var fourthCornerPoint = tracker.property('Corner Pin Point 3');
alert("my new trackpoint has "+ firstCornerPoint.property("ADBE MTracker Pt Attach Pt").numKeys +" keyframes");

addKeyframesToProperties

this.addKeyframesToProperties = function(propertyArray,
time)

Adds a keyframe for each of the given properties at the specified time.  Use this function to generate keyframes for expression-driven tracking data when you want to avoid that the track jumps to another position.

Parameters

propertyArrayan array of properties for which keyframes should be generated
timethe time at which a keyframe should be inserted

Miscellaneous

Summary
Exceptionserror handling in the MochaImport+ API
Undo Groupshow to use Undo Groups with the MochaImport+ API
LicensingTo use the MochaImport+ API, all you need is a normal license of MochaImport+.

Exceptions

error handling in the MochaImport+ API

all API calls may throw exceptions if something goes wrong.  Each exception has a member message that tells what went wrong.

Example

try {
   mochaImportPlus.loadFromClipboard();
   }
catch(e){
    alert("Could not load tracking data from clipboard: "+e.message);
}

Undo Groups

how to use Undo Groups with the MochaImport+ API

The API functions do not introduce any undo groups.

The reason for this is that exceptions would easily cause an undo group mismatch

If between the beginUndoGroup and corresponding endUndoGroup an exception occurs, the endUndoGroup would never be called.

We recommend to always create undo groups catching the exceptions like this

try {
    app.beginUndoGroup("My action");
    // my MochaImport+ API call(s) go here
    }
 catch(e){
     alert("An error occurred: "+e.message);
 }
 finally{
     app.endUndoGroup();
 }

Example

try {
    app.beginUndoGroup("create stabilized precomp");
    mochaImportPlus.stabilizedPrecomp(layer, {silent:true});
    }
 catch(e){
     alert("Could not create stabilized precomp: "+e.message);
 }
 finally{
     app.endUndoGroup();
 }

Licensing

To use the MochaImport+ API, all you need is a normal license of MochaImport+.  The API functions will work on any machine where a MochaImport+ license is installed.  If no license is installed, the API functions may throw an exception.

this.version
The version number of MochaImport+
this.createMochaProject = function(layer,
options)
Creates a mocha project for the given AV layer.
this.openProjectInMocha = function(projectFile)
Launches mocha and opens the given mocha project file in it.
this.setMochaVersion = function(id)
Sets the version of mocha that should be used by the function openProjectInMocha.
this.getAllInstalledMochaVersions = function()
Returns the name, file path and id for all versions of mocha that are installed on the system.
this.loadFromFile = function(file,
options)
loads mocha tracking data from a file
this.loadFromClipboard = function(options)
loads mocha tracking data from the clipboard
this.cornerPin = function(layer,
options)
creates a corner pin effect on the given layer
this.stabilizeLayer = function(layer,
options)
applies the stabilize function of MochaImport+ to the given layer.
this.stabilizedPrecomp = function(layer,
options)
Turns the given layer into a stabilized precomp.
this.createMoveNullLayer = function(comp)
Creates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data.
this.moveLayers = function(layerArray)
Creates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it.
this.moveProperties = function(propertyArray,
options)
Moves the given 2d point properties, masks or shapes with the tracking data.
this.generateAETrackpoints = function(layer)
Generates After Effects trackpoints on the given layer based on the loaded mocha tracking data.
this.addKeyframesToProperties = function(propertyArray,
time)
Adds a keyframe for each of the given properties at the specified time.
Close