LayerCollection object¶

app.project.item(index).layers

Description¶

The LayerCollection object represents a set of layers. The LayerCollection belonging to a CompItem object contains all the layer objects for layers in the composition. The methods of the collection object allow you to manipulate the layer list.

Info

LayerCollection is a subclass of Collection object. All methods and attributes of Collection, in addition to those listed below, are available when working with LayerCollection.

Example¶

Given that the first item in the project is a CompItem and the second item is an AVItem, this example shows the number of layers in the CompItem's layer collection, adds a new layer based on an AVItem in the project, then displays the new number of layers.

var firstComp = app.project.item(1);
var layerCollection = firstComp.layers;
alert("number of layers before is " + layerCollection.length);
var anAVItem = app.project.item(2);
layerCollection.add(anAVItem);
alert("number of layers after is " + layerCollection.length);

Methods¶

LayerCollection.add()¶

app.project.item(index).layers.add(item[, duration])

Description¶

Creates a new AVLayer object containing the specified item, and adds it to this collection. The new layer honors the "Create Layers at Composition Start Time" preference. This method generates an exception if the item cannot be added as a layer to this CompItem.

Parameters¶

Parameter	Type	Description
`item`	AVItem object	The item to be added.
`duration`	Floating-point value	Optional. The length of a still layer in seconds. Used only if the item contains a piece of still footage. Has no effect on movies, sequences or audio. If supplied, sets the duration value of the new layer. Otherwise, the duration value is set according to user preferences. By default, this is the same as the duration of the containing CompItem. To set another preferred value, open `Edit > Preferences > Import` (Windows) or `After Effects > Preferences > Import` (Mac OS), and specify options under Still Footage.

Returns¶

AVLayer object;

LayerCollection.addBoxText()¶

app.project.item(index).layers.addBoxText([width, height])

Description¶

Creates a new paragraph (box) text layer with TextDocument.lineOrientation set to LineOrientation.HORIZONTAL and adds the new TextLayer object to this collection. To create a point text layer, use the LayerCollection.addText() method.

Parameters¶

Parameter	Type	Description
`[width, height]`	Array of floating-point values	The dimensions of the new text box.

Returns¶

TextLayer object.

LayerCollection.addCamera()¶

app.project.item(index).layers.addCamera(name, centerPoint)

Description¶

Creates a new camera layer and adds the CameraLayer object to this collection. The new layer honors the "Create Layers at Composition Start Time" preference.

Parameters¶

Parameter	Type	Description
`name`	String	The name of the new layer.
`centerPoint`	Array of floating-point values, `[x, y]`	The initial X and Y values of the new camera's Point of Interest property. The z value is set to 0.

Returns¶

CameraLayer object.

LayerCollection.addLight()¶

app.project.item(index).layers.addLight(name, centerPoint)

Description¶

Creates a new light layer and adds the LightLayer object to this collection. The new layer honors the "Create Layers at Composition Start Time" preference.

Parameters¶

Parameter	Type	Description
`name`	String	The name of the new layer.
`centerPoint`	Array of floating-point values, `[x, y]`	The center of the new light

Returns¶

LightLayer object.

LayerCollection.addNull()¶

app.project.item(index).layers.addNull([duration])

Description¶

Creates a new null layer and adds the AVLayer object to this collection. This is the same as choosing Layer > New > Null Object.

Parameters¶

Parameter	Type	Description
`duration`	Floating-point value	Optional. The length of a still layer in seconds. If supplied, sets the `duration` value of the new layer. Otherwise, the `duration` value is set according to user preferences. By default, this is the same as the duration of the containing CompItem. To set another preferred value, open `Edit > Preferences > Import (Windows)` or `After Effects > Preferences > Import (Mac OS)`, and specify options under Still Footage.

Returns¶

AVLayer object.

LayerCollection.addShape()¶

app.project.item(index).layers.addShape()

Description¶

Creates a new ShapeLayer object for a new, empty Shape layer. Use the ShapeLayer object to add properties, such as shape, fill, stroke, and path filters. This is the same as using a shape tool in "Tool Creates Shape" mode. Tools automatically add a vector group that includes Fill and Stroke as specified in the tool options.

Parameters¶

None.

Returns¶

ShapeLayer object.

LayerCollection.addSolid()¶

app.project.item(index).layers.addSolid(color, name, width, height, pixelAspect[, duration])

Description¶

Creates a new SolidSource object, with values set as specified; sets the new SolidSource as the mainSource value of a new FootageItem object, and adds the FootageItem to the project. Creates a new AVLayer object, sets the new Footage Item as its source, and adds the layer to this collection.

Parameters¶

Parameter	Type	Description
`color`	Array of three floating-point values, `[R, G, B]`, in the range `[0.0..1.0]`	The color of the solid.
`name`	String	The name of the solid.
`width`	Integer, in the range `[4..30000]`	The width of the solid in pixels.
`height`	Integer, in the range `[4..30000]`	The height of the solid in pixels.
`pixelAspect`	Floating-point value in the range `[0.01..100.0]`	The pixel aspect ratio of the solid.
`duration`	Floating-point value	Optional. The length of a still layer in seconds. If supplied, sets the `duration` value of the new layer. Otherwise, the `duration` value is set according to user preferences. By default, this is the same as the duration of the containing CompItem. To set another preferred value, open `Edit > Preferences > Import` (Windows) or `After Effects > Preferences > Import` (MacOS), and specify options under Still Footage.

Returns¶

AVLayer object.

LayerCollection.addText()¶

app.project.item(index).layers.addText([sourceText])

Description¶

Creates a new point text layer with TextDocument.lineOrientation set to LineOrientation.HORIZONTAL and adds the new TextLayer object to this collection. To create a paragraph (box) text layer, use LayerCollection.addBoxText().

Parameters¶

Parameter	Type	Description
`sourceText`	String	Optional. The source text of the new layer, or a TextDocument object containing the source text of the new layer.

Returns¶

TextLayer object.

LayerCollection.addVerticalBoxText()¶

app.project.item(index).layers.addVerticalBoxText([width, height])

Note

This functionality was added in After Effects 24.2

Description¶

Creates a new paragraph (box) text layer with TextDocument.lineOrientation set to LineOrientation.VERTICAL_RIGHT_TO_LEFT and adds the new TextLayer object to this collection. To create a point text layer, use the LayerCollection.addText() or LayerCollection.addVerticalText() methods.

Parameters¶

Parameter	Type	Description
`[width, height]`	Array of floating-point values	The dimensions of the new text box.

Returns¶

TextLayer object.

LayerCollection.addVerticalText()¶

app.project.item(index).layers.addVerticalText([sourceText])

Note

This functionality was added in After Effects 24.2

Description¶

Creates a new point text layer with TextDocument.lineOrientation set to LineOrientation.VERTICAL_RIGHT_TO_LEFT and adds the new TextLayer object to this collection. To create a paragraph (box) text layer, use the LayerCollection.addBoxText() or LayerCollection.addVerticalBoxText() methods.

Parameters¶

Parameter	Type	Description
`sourceText`	String	Optional. The source text of the new layer, or a TextDocument object containing the source text of the new layer.

Returns¶

TextLayer object.

LayerCollection.byName()¶

app.project.item(index).layers.byName(name)

Description¶

Returns the first (topmost) layer found in this collection with the specified name, or null if no layer with the given name is found.

Parameters¶

| name | A string containing the name. |

Returns¶

Layer object or null.

LayerCollection.precompose()¶

app.project.item(index).layers.precompose(layerIndicies, name[, moveAllAttributes])

Description¶

Creates a new CompItem object and moves the specified layers into its layer collection. It removes the individual layers from this collection, and adds the new CompItem to this collection.

Parameters¶

Parameter	Type	Description
`layerIndices`	Array of integers	The position indexes of the layers to be collected.
`name`	String	The name of the new CompItem object.
`moveAllAttributes`	Boolean	Optional. When `true` (the default), retains all attributes in the new composition. This is the same as selecting the "Move all attributes into the new composition" option in the Pre-compose dialog box. You can only set this to `false` if there is just one index in the `layerIndices` array. This is the same as selecting the "Leave all attributes in" option in the Pre-compose dialog box.

Returns¶

CompItem object.