Namespace

DuGR

DuGR

Duduf Groups

Group After Effects layers by tags, and run batch methods on them.
DuGR is the high-level interface to the layer groups,
and it relies on DuAETag, a lower-level interface which adds tags on layers,
and stores data in these tags.

A group is created using DuGR.addSelectedLayersToGroup() or DuAETag.addGroup().
Groups can be renamed with DuGR.renameGroup(),
They can be removed with DuGR.removeGroup().
You can run a method on all layers belonging to a set of groups with DuGR.do().

DuGR.Group contains predefined groups to sort layers by type or attribute and use DuGR.do() on them.

You can use DuGR.isolate() to isolate layers in the timeline, the comp panel, or both,
use DuGR.exitIsolation() to get out of isolation mode.

DuGR requires DuAEF, the Duduf After Effects Framework. Two builds of the DuGR API are available:

  • DuGR_api.jsxinc does not include DuAEF, and can be used to compine multiple Duduf APIs with a single copy of DuAEF.
    Be careful to grab the right version of DuAEF in this case.
  • DuAEF_DuGR_api.jsxinc includes all dependencies, with DuAEF, and is easier to include in your scripts.

Version:
  • {dugrVersion}
Author:
  • Nicolas Dufresne and contributors
License:
  • GPL-3.0
    DuGR is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    DuGR is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with DuGR. If not, see http://www.gnu.org/licenses/.
See:
  • DuAETag for low-level group management

View Source api.jsxinc, line 124

Examples

// Encapsulate everything to avoid global variables!
// The parameter is either undefined (stand alone script) or the panel containing the ui (ScriptUI)
(function(thisObj)
{
     // If you only need DuGR, just include DuAEF_DuGR_api
     #include "DuAEF_DuGR_api.jsxinc";
     
     // Running the init() method of DuAEF is required to setup everything properly.
     DuAEF.init( "YourScriptName", "1.0.0", "YourCompanyName" );
     
     // These info can be used by the framework to improve UX, but they're optional
     DuESF.chatURL = 'http://chat.rxlab.info'; // A link to a live-chat server like Discord or Slack...
     DuESF.bugReportURL = 'https://github.com/RxLaboratory/DuAEF_Dugr/issues/new/choose'; // A link to a bug report form
     DuESF.featureRequestURL = 'https://github.com/RxLaboratory/DuAEF_Dugr/issues/new/choose'; // A link to a feature request form
     DuESF.aboutURL = 'http://rxlaboratory.org/tools/dugr'; // A link to the webpage about your script
     DuESF.docURL = 'http://dugr.rxlab.guide'; // A link to the documentation of the script
     DuESF.scriptAbout = 'Duduf Groups: group After Effects layers!'; // A short string describing your script
     DuESF.companyURL = 'https://rxlaboratory.org'; // A link to your company's website
     DuESF.rxVersionURL = 'http://version.rxlab.io' // A link to an RxVersion server to check for updates
     
     // Build your UI here, declare your methods, etc.

     // This will be our main panel
     var ui = DuScriptUI.scriptPanel( thisObj, true, true, new File($.fileName) );
     ui.addCommonSettings(); // Automatically adds the language settings, location of the settings file, etc

     DuScriptUI.staticText( ui.settingsGroup, "Hello world of settings!" ); // Adds a static text to the settings panel
     DuScriptUI.staticText( ui.mainGroup, "Hello worlds!" ); // Adds a static text to the main panel
     
     // When you're ready to display everything
     DuScriptUI.showUI(ui);

     // Note that if you don't have a UI or if you don't use DuScriptUI to show it,
     // you HAVE TO run this method before running any other function:
     // DuAEF.enterRunTime();
 
})(this);
// Encapsulate everything to avoid global variables!
// The parameter is either undefined (stand alone script) or the panel containing the ui (ScriptUI)
(function(thisObj)
{
     // If you need to combine DuGR and other APIs like DuIO or DuIK
     // Include DuAEF first, and then stand-alone APIs
     #include "DuAEF.jsxinc";
     #include "DuGR_api.jsxinc";
     #include "DuIK_api.jsxinc";
     #include "DuIO_api.jsxinc";
     
     // Running the init() method of DuAEF is required to setup everything properly.
     DuAEF.init( "YourScriptName", "1.0.0", "YourCompanyName" );
     
     // These info can be used by the framework to improve UX, but they're optional
     DuESF.chatURL = 'http://chat.rxlab.info'; // A link to a live-chat server like Discord or Slack...
     DuESF.bugReportURL = 'https://github.com/RxLaboratory/DuAEF_Dugr/issues/new/choose'; // A link to a bug report form
     DuESF.featureRequestURL = 'https://github.com/RxLaboratory/DuAEF_Dugr/issues/new/choose'; // A link to a feature request form
     DuESF.aboutURL = 'http://rxlaboratory.org/tools/dugr'; // A link to the webpage about your script
     DuESF.docURL = 'http://dugr.rxlab.guide'; // A link to the documentation of the script
     DuESF.scriptAbout = 'Duduf Groups: group After Effects layers!'; // A short string describing your script
     DuESF.companyURL = 'https://rxlaboratory.org'; // A link to your company's website
     DuESF.rxVersionURL = 'http://version.rxlab.io' // A link to an RxVersion server to check for updates
     
     // Build your UI here, declare your methods, etc.

     // This will be our main panel
     var ui = DuScriptUI.scriptPanel( thisObj, true, true, new File($.fileName) );
     ui.addCommonSettings(); // Automatically adds the language settings, location of the settings file, etc

     DuScriptUI.staticText( ui.settingsGroup, "Hello world of settings!" ); // Adds a static text to the settings panel
     DuScriptUI.staticText( ui.mainGroup, "Hello worlds!" ); // Adds a static text to the main panel
     
     // When you're ready to display everything
     DuScriptUI.showUI(ui);

     // Note that if you don't have a UI or if you don't use DuScriptUI to show it,
     // you HAVE TO run this method before running any other function:
     // DuAEF.enterRunTime();
 
})(this);

Requires

  • module:DuAEF>=1.0.0

Members

Number

# static readonly CompIsolationMode

How to isolate layers in the comp panel
Properties:
Name Type Description
HIDE Number
WIREFRAME Number

View Source api.jsxinc, line 362

string

# static Group

Predefined and automatic groups
Properties:
Name Type Description
ALL string All layers in the composition
SELECTED string Selected layers
GROUPED string Layers included in a custom group
COMP string Precompositions
NULL string Null objects
SOLID string Solids
SHAPE string Shape layers
TEXT string Text layers
ADJUSTMENT string Adjustement layers
LIGHT string 3D Light layers
CAMERA string Camera layers
THREED_MODEL string 3D Model layers
VISIBLE string Visible layers
SOUND string Audio layers
SOLO string Solo layers
LOCKED string Locked layers
SHY string Shy layers
EFFECTS string Effects enabled
MB string Motion Blur enabled
THREE_D string 3D layers
GUIDE string Guide layers
ORPHAN string The layer does not have any parent
HAS_CHILD string The layer has at least one child
IGNORED string This is a special group: all layers in there will always be ignored by all methods.
LAYER_STYLES string Layer styles are enabled.
STYLE_DROP_SHADOW string Layer style: Drop shadow is enabled.
STYLE_INNER_SHADOW string Layer style: Inner shadow is enabled.
STYLE_OUTER_GLOW string Layer style: Outer glow is enabled..
STYLE_INNER_GLOW string Layer style: Inner glow is enabled.
STYLE_BEVEL string Layer style: Bevel is enabled.
STYLE_SATIN string Layer style: Satin is enabled.
STYLE_COLOR string Layer style: Color overlay is enabled.
STYLE_GRADIENT string Layer style: Gradient Overlay is enabled.
STYLE_STROKE string Layer style: Stroke is enabled.
AT_TIME string Animation: at current time.
IN_TIME_RANGE string Animation: in the current time range.
HAS_KEYFRAMES string Animation: has keyframes.
HAS_EXPRESSIONS string Animation: has expressions.
HAS_MASK string Matte: has at least one mask.
HAS_MATTE string Matte: has track matte.
IS_MATTE string Matte: is used as a track matte.
PRESERVE_TRANSPARENCY string Matte: Preserve transparency is enabled.
NORMAL_BLENDING string Matte: The blending mode is normal.
OTHER_BLENDING string Matte: The blending mode is not normal.
OTHER_BLENDING string Attribute: has effects.

View Source api.jsxinc, line 130

Number

# static readonly IsolationMode

The way layers are isolated
Properties:
Name Type Description
NONE Number No isolation
BOTH Number Both the timeline and the comp panel
TIMELINE Number Only in the timeline
COMP_PANEL Number Only in the comp panel

View Source api.jsxinc, line 338

Number

# static readonly WarningFrameMode

The way the warning frame can be displayed
Properties:
Name Type Description
NONE Number No frame at all
ABOVE Number Above all layers
BELOW Number Below all layers

View Source api.jsxinc, line 318

Methods

# static addSelectedLayersToGroup(group, compopt)

Adds the selected layers to a (new) group
Parameters:
Name Type Attributes Default Description
group string The group name
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 1187

# static do(groups, callback, invertopt, compopt, notCallbackopt, andopt)

Runs a function for each layer in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
callback DuGR~doCallBack The function to run on each layer.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
notCallback DuGR~doNotCallBack <optional>
The function to run on each layer IF it is NOT in the groups.
and Boolean <optional>
false If false, runs the function on the layers contained in at least one of the groups, otherwise in all the groups.

View Source api.jsxinc, line 523

# static exitIsolation(compopt)

Exits the isolation mode.
Parameters:
Name Type Attributes Default Description
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 1156

# static inGroups(layer, groups, tagopt, andopt) → {Boolean}

Checks if a layer is included in the given groups
Parameters:
Name Type Attributes Default Description
layer Layer The layer to test
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
tag MarkerValue <optional>
If you have the tag as returned by DuAETag.get or DuAETag.set, providing it here improves performance.
and Boolean <optional>
false If false, the layer must be contained in at least one of the groups, otherwise in all the groups.

View Source api.jsxinc, line 433

true if the layer belongs to at least one of the given groups
Boolean

# static isolate(groups, invertopt, compopt, frameModeopt, isolationModeopt, compIsolationModeopt, lockHiddenLayersopt)

Activates the isolation mode.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to isolate.
frameMode DuGR.WarningFrameMode <optional>
DuGR.WarningFrameMode.BELOW How the warning frame must be shown
isolationMode DuGR.IsolationMode <optional>
DuGR.IsolationMode.BOTH What needs to be hidden.
compIsolationMode DuGR.CompIsolationMode <optional>
DuGR.CompIsolationMode.HIDE How to hide the layers
lockHiddenLayers Boolean <optional>
true whether to lock the layers being hidden.

View Source api.jsxinc, line 988

# static isolationMode(compopt) → {DuGR.IsolationMode}

Checks the isolation mode of the comp.
Parameters:
Name Type Attributes Default Description
comp CompItem <optional>
DuAEProject.getActiveComp The composition to check.

View Source api.jsxinc, line 964

The isolation mode.

# static listGroups(compopt, selectedLayersopt) → {DuList}

Gets the list of all groups
Parameters:
Name Type Attributes Default Description
comp CompItem <optional>
DuAEProject.getActiveComp The composition to read.
selectedLayers Boolean <optional>
false When true, only from selected layers.

View Source api.jsxinc, line 1207

The list of groups
DuList

# static removeGroup(group, compopt, selectedLayersopt)

Removes a group from the composition
Parameters:
Name Type Attributes Default Description
group string The group to remove
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
selectedLayers Boolean <optional>
false When true, only from selected layers.

View Source api.jsxinc, line 1255

# static renameGroup(previousName, newName, compopt)

Renames an existing group (in the comp only)
Parameters:
Name Type Attributes Default Description
previousName string The current name
newName string The new name
comp CompItem <optional>
DuAEProject.getActiveComp The composition to read.

View Source api.jsxinc, line 1237

# static select(groups, invertopt, compopt, andopt)

Selects the layers.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
and Boolean <optional>
false If false, selects the layers contained in at least one of the groups, otherwise in all the groups.

View Source api.jsxinc, line 876

# static toggleAdjustment(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the adjustment layer mode for all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 824

# static toggleCollapseTransformation(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the collapse transformation/continuous rasterization mode of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 651

# static toggleEffects(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the the effects of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 736

# static toggleFrameBlending(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the effects of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 762

# static toggleGuide(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the guide mode of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 678

# static toggleLocked(groups, invertopt, compopt)

Toggles the lock of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 614

# static toggleMotionBlur(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the motion blur of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 798

# static toggleQuality(groups, invertopt, compopt, allowLockedChangesopt)

Changes the render quality of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 704

# static toggleShy(groups, invertopt, compopt)

Toggles the shy mode of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 632

# static toggleSolo(groups, invertopt, compopt)

Toggles the solo mode of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 596

# static toggleSound(groups, invertopt, compopt)

Toggles the audio of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 578

# static toggleThreeD(groups, invertopt, compopt, allowLockedChangesopt)

Toggles the 3D mode for all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.
allowLockedChanges Boolean <optional>
true If set to false, locked layers won't be changed.

View Source api.jsxinc, line 850

# static toggleVisibility(groups, invertopt, compopt)

Toggles the visibility of all layers in the groups.
Parameters:
Name Type Attributes Default Description
groups Array.<string> The list of group names. It can include custom groups, or predefined names taken from DuGR.Group.
invert Boolean <optional>
false When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
comp CompItem <optional>
DuAEProject.getActiveComp The composition to update.

View Source api.jsxinc, line 559

Type Definitions

# doCallBack(layer, returnValue) → {any}

A function passed to Dugr.do.
Parameters:
Name Type Description
layer Layer The layer on which the function operates.
returnValue any The return value of the previous iteration. Undefined during the first iteration.

View Source api.jsxinc, line 543

What the function returns will be automatically passed as a second argument on the next iteration.
This is useful if the function has to set a toogle on the first layer, and then re-use it, for example.
any