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:
  • 4.0.4
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 DuAEF_Duik_api.jsxinc, line 29067

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

string

# static readonly CompIsolationMode

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

View Source DuAEF_Duik_api.jsxinc, line 29216

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

View Source DuAEF_Duik_api.jsxinc, line 29072

int

# static readonly IsolationMode

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

View Source DuAEF_Duik_api.jsxinc, line 29192

int

# static readonly WarningFrameMode

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

View Source DuAEF_Duik_api.jsxinc, line 29172

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 DuAEF_Duik_api.jsxinc, line 30018

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

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.

View Source DuAEF_Duik_api.jsxinc, line 29356

# static exitIsolation(compopt)

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

View Source DuAEF_Duik_api.jsxinc, line 29987

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

Checks if a layer is included in the given groups
Parameters:
Name Type Attributes 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.

View Source DuAEF_Duik_api.jsxinc, line 29286

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.WIREFRAME How to hide the layers
lockHiddenLayers Boolean <optional>
true whether to lock the layers being hidden.

View Source DuAEF_Duik_api.jsxinc, line 29819

# 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 DuAEF_Duik_api.jsxinc, line 29795

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 DuAEF_Duik_api.jsxinc, line 30038

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 DuAEF_Duik_api.jsxinc, line 30086

# 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 DuAEF_Duik_api.jsxinc, line 30068

# static select(groups, invertopt, compopt)

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.

View Source DuAEF_Duik_api.jsxinc, line 29707

# 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 DuAEF_Duik_api.jsxinc, line 29656

# 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 DuAEF_Duik_api.jsxinc, line 29484

# 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 DuAEF_Duik_api.jsxinc, line 29568

# 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 DuAEF_Duik_api.jsxinc, line 29594

# 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 DuAEF_Duik_api.jsxinc, line 29510

# 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 DuAEF_Duik_api.jsxinc, line 29447

# 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 DuAEF_Duik_api.jsxinc, line 29630

# 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 DuAEF_Duik_api.jsxinc, line 29536

# 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 DuAEF_Duik_api.jsxinc, line 29465

# 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 DuAEF_Duik_api.jsxinc, line 29429

# 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 DuAEF_Duik_api.jsxinc, line 29411

# 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 DuAEF_Duik_api.jsxinc, line 29682

# 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 DuAEF_Duik_api.jsxinc, line 29392

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 DuAEF_Duik_api.jsxinc, line 29376

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