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}
- Copyright:
- 2017 - 2023 Nicolas Dufresne, RxLaboratory
- 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/.
- GPL-3.0
- See:
-
DuAETag
for low-level group management
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
Properties:
Name | Type | Description |
---|---|---|
HIDE |
Number
|
|
WIREFRAME |
Number
|
string
# static Group
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. |
Number
# static readonly IsolationMode
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 |
Number
# static readonly WarningFrameMode
Properties:
Name | Type | Description |
---|---|---|
NONE |
Number
|
No frame at all |
ABOVE |
Number
|
Above all layers |
BELOW |
Number
|
Below all layers |
Methods
# static addSelectedLayersToGroup(group, compopt)
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
group |
string
|
The group name | ||
comp |
CompItem
|
<optional> |
DuAEProject.getActiveComp | The composition to update. |
# static do(groups, callback, invertopt, compopt, notCallbackopt, andopt)
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. |
# static exitIsolation(compopt)
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
comp |
CompItem
|
<optional> |
DuAEProject.getActiveComp | The composition to update. |
# static inGroups(layer, groups, tagopt, andopt) → {Boolean}
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. |
Boolean
# static isolate(groups, invertopt, compopt, frameModeopt, isolationModeopt, compIsolationModeopt, lockHiddenLayersopt)
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. |
# static isolationMode(compopt) → {DuGR.IsolationMode}
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
comp |
CompItem
|
<optional> |
DuAEProject.getActiveComp | The composition to check. |
# static listGroups(compopt, selectedLayersopt) → {DuList}
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. |
# static removeGroup(group, compopt, selectedLayersopt)
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. |
# static renameGroup(previousName, newName, compopt)
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. |
# static select(groups, invertopt, compopt, andopt)
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. |
# static toggleAdjustment(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleCollapseTransformation(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleEffects(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleFrameBlending(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleGuide(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleLocked(groups, invertopt, compopt)
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. |
# static toggleMotionBlur(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleQuality(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleShy(groups, invertopt, compopt)
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. |
# static toggleSolo(groups, invertopt, compopt)
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. |
# static toggleSound(groups, invertopt, compopt)
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. |
# static toggleThreeD(groups, invertopt, compopt, allowLockedChangesopt)
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. |
# static toggleVisibility(groups, invertopt, compopt)
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. |
Type Definitions
# doCallBack(layer, returnValue) → {any}
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. |
This is useful if the function has to set a toogle on the first layer, and then re-use it, for example.
any