MochaImportPlusAPI.js | |
OUTDATED! | Note that this API documentation is for MochaImport+ V5. |
Using The MochaImport+ API | Getting started with the MochaImport+ API |
MochaImportPlus | documentation of all MochaImportPlus API functions available in the MochaImportPlus object |
Variables | |
version | The version number of MochaImport+ |
Functions | |
createMochaProject | Creates a mocha project for the given AV layer. |
openProjectInMocha | Launches mocha and opens the given mocha project file in it. |
setMochaVersion | Sets the version of mocha that should be used by the function openProjectInMocha. |
getAllInstalledMochaVersions | Returns the name, file path and id for all versions of mocha that are installed on the system. |
loadFromFile | loads mocha tracking data from a file |
loadFromClipboard | loads mocha tracking data from the clipboard |
cornerPin | creates a corner pin effect on the given layer |
stabilizeLayer | applies the stabilize function of MochaImport+ to the given layer. |
stabilizedPrecomp | Turns the given layer into a stabilized precomp. |
createMoveNullLayer | Creates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data. |
moveLayers | Creates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it. |
moveProperties | Moves the given 2d point properties, masks or shapes with the tracking data. |
generateAETrackpoints | Generates After Effects trackpoints on the given layer based on the loaded mocha tracking data. |
addKeyframesToProperties | Adds a keyframe for each of the given properties at the specified time. |
Miscellaneous | |
Exceptions | error handling in the MochaImport+ API |
Undo Groups | how to use Undo Groups with the MochaImport+ API |
Licensing | To use the MochaImport+ API, all you need is a normal license of MochaImport+. |
Note that this API documentation is for MochaImport+ V5. For MochaImport+ V6 see https://mamoworld.com
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
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);
documentation of all MochaImportPlus API functions available in the MochaImportPlus object
Variables | |
version | The version number of MochaImport+ |
Functions | |
createMochaProject | Creates a mocha project for the given AV layer. |
openProjectInMocha | Launches mocha and opens the given mocha project file in it. |
setMochaVersion | Sets the version of mocha that should be used by the function openProjectInMocha. |
getAllInstalledMochaVersions | Returns the name, file path and id for all versions of mocha that are installed on the system. |
loadFromFile | loads mocha tracking data from a file |
loadFromClipboard | loads mocha tracking data from the clipboard |
cornerPin | creates a corner pin effect on the given layer |
stabilizeLayer | applies the stabilize function of MochaImport+ to the given layer. |
stabilizedPrecomp | Turns the given layer into a stabilized precomp. |
createMoveNullLayer | Creates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data. |
moveLayers | Creates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it. |
moveProperties | Moves the given 2d point properties, masks or shapes with the tracking data. |
generateAETrackpoints | Generates After Effects trackpoints on the given layer based on the loaded mocha tracking data. |
addKeyframesToProperties | Adds a keyframe for each of the given properties at the specified time. |
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.
layer | an AV Layer for which a project should be created |
options | an optional object that may contain the following members: |
options.silent | don’t show a dialog to check for existing projects or choose which mask goes on which mocha layer |
options.projectFile | File object to which the project should be written (only considered if options.silent == true) |
options.maskToLayerMapping | Array 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.ProjectOutputDirectory | Folder Object or String where mocha should put its rendered files (default = same as mocha project location) |
options.UseAbsoluteOutputDirectory | only 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).
// 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 }
this.openProjectInMocha = function( projectFile )
Launches mocha and opens the given mocha project file in it.
projectFile | a File object for the mocha project file that should be opened in mocha. |
nothing
// creates a mocha project for the given layer and opens it in mocha var myProjectFile = mochaImportPlus.createMochaProject(layer,{silent:true}); mochaImportPlus.openProjectInMocha(myProjectFile);
this.setMochaVersion = function( id )
Sets the version of mocha that should be used by the function openProjectInMocha.
id | id 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) |
nothing
// 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);
this.getAllInstalledMochaVersions = function()
Returns the name, file path and id for all versions of mocha that are installed on the system.
none
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.
// 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);
this.loadFromFile = function( file, options )
loads mocha tracking data from a file
file | a ExtendScript File object. |
options | an optional object that may contain the following members: |
options.silent | show no dialog to interpret the keyframe data |
options.fps | overwrites the frames per second information from the tracking data file (only used if silent==true) |
options.frameOffset | at which frame of the comp the tracking data starts (default = 0, only used if silent==true) |
nothing
// 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});
this.loadFromClipboard = function( options )
loads mocha tracking data from the clipboard
options | an optional object that may contain the following members: |
options.silent | show no dialog to interpret the keyframe data |
options.fps | overwrites the frames per second information from the tracking data file (only used if silent==true) |
options.frameOffset | at which frame of the comp the tracking data starts (default = 0, only used if silent==true) |
nothing
// 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});
this.cornerPin = function( layer, options )
creates a corner pin effect on the given layer
layer | the layer to which the effect should be applied |
options | an optional object that may contain the following members |
options.silent | show no dialog for details like which corner pin effect to choose and whether the tracking data should be applied as expression or keyframes |
options.cornerPinEffect | matchname 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.useExpressionInsteadOfKeyframes | can be true or false. It this is true, the trackingdata is represented with an expression instead of writing lots of keyframes. |
the PropertyGroup of the created corner pin effect
// 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'});
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.
layer | the layer that should be stabilized |
options | an optional object that may contain the following members |
options.silent | if this is NOT true, a dialog is shown that allows the user to choose all the other options below. |
options.smoothMovement | if 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.cornerPinEffect | matchname 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.useExpressionInsteadOfKeyframes | can be true or false. It this is true, the trackingdata is represented with an expression instead of writing lots of keyframes. |
nothing
// 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});
this.stabilizedPrecomp = function( layer, options )
Turns the given layer into a stabilized precomp.
layer | the layer that should be stabilized |
options | an optional object that may contain the following members |
options.silent | if this is NOT true, a dialog is shown that allows the user to choose all the other options below. |
options.cornerPinEffect | matchname 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.useExpressionInsteadOfKeyframes | can 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) |
the layer representing the stabilized precomp
// 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});
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.
comp | the comp in which the null layer should be created |
the created null layer
// works only if transform data is loaded var nullLayer = mochaImportPlus.createMoveNullLayer(comp);
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.
layerArray | an 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. |
the created null layer
// 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)]);
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.
propertyArray | an 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. |
options | an optional object that may contain the following members |
options.silent | show 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.useExpressionInsteadOfKeyframes | can 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) |
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).
// 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});
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.
layer | the layer on which the trackpoints should be created |
the tracker PropertyGroup containing the generated trackpoints
// 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");
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.
propertyArray | an array of properties for which keyframes should be generated |
time | the time at which a keyframe should be inserted |
Exceptions | error handling in the MochaImport+ API |
Undo Groups | how to use Undo Groups with the MochaImport+ API |
Licensing | To use the MochaImport+ API, all you need is a normal license of MochaImport+. |
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.
try { mochaImportPlus.loadFromClipboard(); } catch(e){ alert("Could not load tracking data from clipboard: "+e.message); }
how to use Undo Groups with the MochaImport+ API
The API functions do not introduce any undo groups.
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(); }
try { app.beginUndoGroup("create stabilized precomp"); mochaImportPlus.stabilizedPrecomp(layer, {silent:true}); } catch(e){ alert("Could not create stabilized precomp: "+e.message); } finally{ app.endUndoGroup(); }
The version number of MochaImport+
this.version
Creates a mocha project for the given AV layer.
this.createMochaProject = function( layer, options )
Launches mocha and opens the given mocha project file in it.
this.openProjectInMocha = function( projectFile )
Sets the version of mocha that should be used by the function openProjectInMocha.
this.setMochaVersion = function( id )
Returns the name, file path and id for all versions of mocha that are installed on the system.
this.getAllInstalledMochaVersions = function()
loads mocha tracking data from a file
this.loadFromFile = function( file, options )
loads mocha tracking data from the clipboard
this.loadFromClipboard = function( options )
creates a corner pin effect on the given layer
this.cornerPin = function( layer, options )
applies the stabilize function of MochaImport+ to the given layer.
this.stabilizeLayer = function( layer, options )
Turns the given layer into a stabilized precomp.
this.stabilizedPrecomp = function( layer, options )
Creates a new null layer and sets its position, scale and rotation to the loaded mocha tracking data.
this.createMoveNullLayer = function( comp )
Creates a new null layer for the tracking data (like createMoveNullLayer) and parents all given layers to it.
this.moveLayers = function( layerArray )
Moves the given 2d point properties, masks or shapes with the tracking data.
this.moveProperties = function( propertyArray, options )
Generates After Effects trackpoints on the given layer based on the loaded mocha tracking data.
this.generateAETrackpoints = function( layer )
Adds a keyframe for each of the given properties at the specified time.
this.addKeyframesToProperties = function( propertyArray, time )