Namespace: 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.3

Author:

Nicolas Dufresne and contributors

Copyright:

2017 - 2022 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/.

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

static,readonlyDuGR.CompIsolationModestring

How to isolate layers in the comp panel

Properties:

Name	Type	Default	Description
`HIDE`	string	0
`WIREFRAME`	string	1

staticDuGR.Groupstring

Predefined and automatic groups

Properties:

Name	Type	Default	Description
`ALL`	string	DuGR.all	All layers in the composition
`SELECTED`	string	DuGR.selected	Selected layers
`GROUPED`	string	DuGR.grouped	Layers included in a custom group
`COMP`	string	DuGR.type.comp	Precompositions
`NULL`	string	DuGR.type.null	Null objects
`SOLID`	string	DuGR.type.solid	Solids
`SHAPE`	string	DuGR.type.shape	Shape layers
`TEXT`	string	DuGR.type.text	Text layers
`ADJUSTMENT`	string	DuGR.type.adjustment	Adjustement layers
`LIGHT`	string	DuGR.type.light	3D Light layers
`CAMERA`	string	DuGR.type.camera	Camera layers
`VISIBLE`	string	DuGR.attr.visible	Visible layers
`SOUND`	string	DuGR.attr.sound	Audio layers
`SOLO`	string	DuGR.attr.solo	Solo layers
`LOCKED`	string	DuGR.attr.locked	Locked layers
`SHY`	string	DuGR.attr.shy	Shy layers
`EFFECTS`	string	DuGR.attr.effects	Effects enabled
`MB`	string	DuGR.attr.mb	Motion Blur enabled
`THREE_D`	string	DuGR.attr.three_d	3D layers
`GUIDE`	string	DuGR.attr.guide	Guide layers
`ORPHAN`	string	DuGR.hierarchy.orphan	The layer does not have any parent
`HAS_CHILD`	string	DuGR.hierarchy.hasChildren	The layer has at least one child
`IGNORED`	string	::Ignored::	This is a special group: all layers in there will always be ignored by all methods.

static,readonlyDuGR.IsolationModeint

The way layers are isolated

Properties:

Name	Type	Default	Description
`NONE`	int	0	No isolation
`BOTH`	int	1	Both the timeline and the comp panel
`TIMELINE`	int	2	Only in the timeline
`COMP_PANEL`	int	3	Only in the comp panel

static,readonlyDuGR.WarningFrameModeint

The way the warning frame can be displayed

Properties:

Name	Type	Default	Description
`NONE`	int	0	No frame at all
`ABOVE`	int	1	Above all layers
`BELOW`	int	2	Below all layers

Methods

staticDuGR.addSelectedLayersToGroup(group, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29540

Adds the selected layers to a (new) group

Name	Type	Default	Description
`group`	string		The group name
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to update.

staticDuGR.do(groups, callback, invert, comp, notCallback) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28878

Runs a function for each layer in the groups.

Name	Type	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	false	optional When true, the list of groups is a blacklist and the layer must not be contained in any one of them.
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to update.
`notCallback`	DuGR~doNotCallBack		optional The function to run on each layer IF it is NOT in the groups.

staticDuGR.exitIsolation(comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29509

Exits the isolation mode.

Name	Type	Default	Description
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to update.

staticDuGR.inGroups(layer, groups, tag){Boolean} D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28808

Checks if a layer is included in the given groups

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

Returns:

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

staticDuGR.isolate(groups, invert, comp, frameMode, isolationMode, compIsolationMode, lockHiddenLayers) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29341

Activates the isolation mode.

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

staticDuGR.isolationMode(comp){DuGR.IsolationMode} D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29317

Checks the isolation mode of the comp.

Name	Type	Default	Description
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to check.

Returns:

Type	Description
DuGR.IsolationMode	The isolation mode.

staticDuGR.listGroups(comp, selectedLayers){DuList} D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29560

Gets the list of all groups

Name	Type	Default	Description
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to read.
`selectedLayers`	Boolean	false	optional When true, only from selected layers.

Returns:

Type	Description
DuList	The list of groups

staticDuGR.removeGroup(group, comp, selectedLayers) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29608

Removes a group from the composition

Name	Type	Default	Description
`group`	string		The group to remove
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to update.
`selectedLayers`	Boolean	false	optional When true, only from selected layers.

staticDuGR.renameGroup(previousName, newName, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29590

Renames an existing group (in the comp only)

Name	Type	Default	Description
`previousName`	string		The current name
`newName`	string		The new name
`comp`	CompItem	DuAEProject.getActiveComp	optional The composition to read.

staticDuGR.select(groups, invert, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29229

Selects the layers.

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

staticDuGR.toggleAdjustment(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29178

Toggles the adjustment layer mode for all layers in the groups.

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

staticDuGR.toggleCollapseTransformation(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29006

Toggles the collapse transformation/continuous rasterization mode of all layers in the groups.

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

staticDuGR.toggleEffects(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29090

Toggles the the effects of all layers in the groups.

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

staticDuGR.toggleFrameBlending(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29116

Toggles the effects of all layers in the groups.

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

staticDuGR.toggleGuide(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29032

Toggles the guide mode of all layers in the groups.

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

staticDuGR.toggleLocked(groups, invert, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28969

Toggles the lock of all layers in the groups.

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

staticDuGR.toggleMotionBlur(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29152

Toggles the motion blur of all layers in the groups.

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

staticDuGR.toggleQuality(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29058

Changes the render quality of all layers in the groups.

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

staticDuGR.toggleShy(groups, invert, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28987

Toggles the shy mode of all layers in the groups.

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

staticDuGR.toggleSolo(groups, invert, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28951

Toggles the solo mode of all layers in the groups.

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

staticDuGR.toggleSound(groups, invert, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28933

Toggles the audio of all layers in the groups.

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

staticDuGR.toggleThreeD(groups, invert, comp, allowLockedChanges) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 29204

Toggles the 3D mode for all layers in the groups.

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

staticDuGR.toggleVisibility(groups, invert, comp) D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28914

Toggles the visibility of all layers in the groups.

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

Type Definitions

DuGR.doCallBack(layer, returnValue){any} D:/RxLab/src/RxOT/DuAEF/Duik/Duik_API/DuAEF_Duik_api.jsxinc, line 28898

A function passed to Dugr.do.

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.

Returns:

Type	Description
any	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.