redefinery

Layers

This section describes how to work with layers in a composition. The following topics are covered:


Checking if a layer is of a specific type

When you need to operate on a specific type of layer, you need to know how to identify the layer’s type. Unfortunately, there is no consistent way to identify all of the different types of layers (audio/video, text, light, camera, etc.).

The following code shows how to check for different types of layers, at least in After Effects 6.5.

// given:
// layer = Layer object
//

// Checking for an audio/video (AV) layer, such as:
// video and/or audio footage, placeholder, adjustment, null, or pre-composition (pre-comp)
if (layer instanceof AVLayer)
{
    if (layer.property("sourceText") === null)   // (For AE 6.5) Text layers are AVLayer, so filter out
    {
        // Layer is an AV layer

        if (!layer.hasAudio)
        {
            // AV Layer has only video (no audio)
        }

        if (!layer.hasVideo)
        {
            // AV Layer has only audio (no video)
        }

        if (layer.source instanceof FootageItem)
        {
            if (layer.source.mainSource instanceof PlaceholderSource)
            {
                // AV Layer is placeholder
            }
            if (layer.source.mainSource instanceof SolidSource)
            {
                // AV Layer is a solid
            }
        }

        if (layer.adjustmentLayer)
        {
            // AV Layer is an adjustment layer or any layer with the Adjustment switch enabled
            // (other layer types can also have the Adjustment switch enabled for them)
        }

        if (layer.nullLayer)
        {
            // AV Layer is a null layer (originally created as a null layer)
        }

        if (layer.source instanceof CompItem)
        {
            // AV Layer is a pre-composition layer
        }
    }

    if (layer.threeDLayer)                       // for 2D, check: !layer.threeDLayer
    {
        // AV Layer is a 3D layer
    }

    if (layer.guideLayer)
    {
        // AV Layer is a guide layer
    }
}

// Checking for a text layer
if (layer.property("sourceText") !== null)       // Or "Source Text", "text", or "Text"
{
    // Layer is a text layer
}


// Checking for a light layer
if (layer.property("intensity") !== null)        // Or "Intensity", "color", or "Color"
{
    // Layer is a light layer
}

// Checking for a camera layer
if (layer.property("zoom") !== null)             // Or "Zoom" or other values
{
    // Layer is a camera layer
}

In After Effects 7.0, text, light, and camera layers can be detected as TextLayer, LightLayer, and CameraLayer objects, as follows.

Note: In After Effects 6.5, text layers used to be detectable as AVLayer objects, and light and camera layers as Layer objects.

// given:
// layer = Layer object
//

// Checking for a text layer (as of After Effects 7.0)
if (layer instanceof TextLayer)
{
    // Layer is a text layer
}


// Checking for a light layer (as of After Effects 7.0)
if (layer instanceof LightLayer)
{
    // Layer is a light layer
}

// Checking for a camera layer (as of After Effects 7.0)
if (layer instanceof CameraLayer)
{
    // Layer is a camera layer
}

For more information, read about AE 7.0 Scripting Compatibility.

In After Effects CS3, per-character 3D text layers can be detected by using the threeDPerChar attribute, and shape layers as ShapeLayer objects, as follows.

// given:
// layer = Layer object
//

// Checking for a per-character 3D text layer (as of After Effects CS3)
if (layer.threeDPerChar)
{
    // Layer is a per-character 3D text layer
    // (as a result, also a TextLayer object)
}


// Checking for a shape layer (as of After Effects CS3)
if (layer instanceof ShapeLayer)
{
    // Layer is a shape layer
}

For more information, read about AE CS3 Scripting Compatibility.


Retrieving all layers of a specific type

With the ability to check for layers of a specific type, you can retrieve all layers of that type for use in operations that require such layers.

The following code shows how to iterate over the layers in a composition and store those matching a particular type in an array for retrieval or use elsewhere in your code. For this example, text layers are retrieved.

// given:
// comp = CompItem object representing the composition containing layers (Layer objects)
//
var layers = comp.layers;                        // Retrieve the composition's layers
var matchingLayers = new Array();                // Store matching layers in an array
var layer;

for (var i = 1; i <= layers.length; i++)
{
    layer = layers[i];

    // Check for the particular layer type here:
    if (layer.property("sourceText") !== null)   // In this example, get text layers
        matchingLayers[matchingLayers.length] = layer;
}
// The matchingLayers array now contains the layers needed
// The number of matching layers is matchingLayers.length

Retrieving the selected layers of a specific type

If your script needs to operate on the selected layers of a given type, you need to check the layers in the composition’s selectedLayers array of Layer objects for those matching the specific type.

The following code shows how to iterate over the layers in the CompItem object’s selectedLayers array, and store only the Layer objects matching a particular type. For this example, selected text layers are retrieved.

Note: The layers in the selectedLayers array are listed in selected order, so if you need them listed in top-to-bottom order, you will need to sort the layers by their index attribute value, also shown in the following code.

// given:
// comp = CompItem object representing the composition containing layers (Layer objects)
//
var selectedLayers = comp.selectedLayers;        // Start with the selected layers
var matchingLayers = new Array();                // Store matching selected layers in an array
var layer;

for (var i = 0; i < selectedLayers.length; i++)
{
    layer = layers[i];

    // Check for the particular layer type here:
    if (layer.property("sourceText") !== null)   // In this example, get text layers
        matchingLayers[matchingLayers.length] = layer;
}
// The matchingLayers array now contains the selected layers needed
// The number of matching selected layers is matchingLayers.length in top-to-bottom order


// If you need the selected layers in top-to-bottom listed order, sort the layers
// using a sort function that compares layers based on their index values

// This custom sort function for the Array.sort() function takes two Layer objects
// as arguments, comparing the layer's index attribute values, returning: a negative number
// if the index of a is less than that of b, a positive number if it's greater,
// or 0 if they're the same
//
function sortLayersByIndex(a, b)
{
    return a.index - b.index;
}

matchingLayers.sort(sortLayersByIndex);          // Sort the layers by index (top-to-bottom)