redefinery

Masks

This section describes how to work with masks applied to a specific layer. The following topics are covered:


Checking if a layer can have masks applied

Some types of layers, such as cameras and lights, do not use masks. Before you can retrieve masks from a layer, first check that the layer can accept masks. Although you can check the layer’s type for supported layers, a more future-proof way is checking if the layer has an Masks property group (PropertyGroup object).

The following code shows how to check a layer for a Masks property group.

// given:
// layer = Layer object
//
var masksGroup = layer("Masks");                 // Get the PropertyGroup for the masks
// This PropertyGroup can also be retrieved by using 
// layer.property("Masks") or layer.property("ADBE Mask Parade")
if (masksGroup !== null)                         // Filter out layers that cannot use masks
{
    // The layer can have masks
}

Applying a mask to a layer

To apply (add) a mask to a layer, you need to create a Shape object that describes the form of the mask, and then assign it as the value of the mask’s Mask Shape property.

A Shape object contains attributes for setting the vertices (an array of arrays of x,y floating point values representing coordinates in the composition, with 0,0 at the upper left corner of the composition), incoming and outgoing tangent vectors for each vertex (array of arrays of x,y floating point values representing relative coordinates for the tangent handles), and whether the mask is opened or closed.

The following code shows how to apply an open mask.

// given:
// masksGroup = PropertyGroup associated with the layer's masks
//
var mask = masksGroup.addProperty("Mask");       // Create a new mask
if (mask !== null)
{
    var s = new Shape();
    if (s !== null)
    {
        s.vertices = [ [0,0], [0,100], [100,100], [100,0] ];
        s.closed = false;                        // The close attribute defaults to true
        
        maskShape = mask.property("maskShape");  // Get the Mask Shape property for the mask
        maskShape.setValue(s);                   // Change the mask shape (not keyframed)
    }
}

Retrieving all masks on a layer

The masks applied to a layer are the properties of the layer’s Masks PropertyGroup.

The following code shows how to iterate over the properties of a layer’s Masks PropertyGroup and store them in an array for retrieval or use elsewhere in your code.

// given:
// layer = Layer object, and the layer can have masks applied
//
var masksGroup = layer("Masks");
var masksOnLayer = new Array();                  // Store masks in an array; starts as empty
if (masksGroup !== null)
{
                                                 // Iterate through properties of masksGroup
                                                 // Append mask to the array
    for (var i = 1; i <= masksGroup.numProperties; i++)
        masksOnLayer[masksOnLayer.length] = masksGroup.property(i);
}
// The masksOnLayer array now contains the list of masks
// The number of masks is masksOnLayer.length

Retrieving the selected masks on a layer

If your script needs to operate on the selected masks on a layer, you need to check if the selected attribute for the mask (Property) is true.

The following code shows how to iterate over the properties of a layer’s Masks PropertyGroup, and store only the properties whose selected attribute is true in an array for retrieval or use elsewhere in your code. This code is very similar to the code for retrieving the masks on a layer, with the extra check for the selected attribute value.

// given:
// layer = Layer object, and the layer can have masks applied
//
var masksGroup = layer("Masks");
var selectedMasks = new Array();                 // Store masks in an array; starts as empty
if (masksGroup !== null)
{
                                                 // Iterate through properties of masksGroup
                                                 // Append selected mask to the array
    for (var i = 1; i <= masksGroup.numProperties; i++)
        if (masksGroup.property(i).selected)
            selectedMasks[selectedMasks.length] = masksGroup.property(i);
}
// The selectedMasks array now contains the list of selected masks 
// in top-to-bottom order

Selecting or deselecting a mask

Selecting or deselecting a mask is as simple as changing the Boolean value of the selected attribute for the mask’s PropertyBase.

Note: Changing the selection of a mask does not affect the selection state of other masks.

The following code shows how to select and deselect a mask.


// given:
// mask = PropertyBase associated with the layer mask to select or deselect
//
mask.selected = true;                            // Select the mask

mask.selected = false;                           // Deselect the mask

Rearranging a mask on a layer

Reordering a mask within the stack of masks (as listed in the Timeline window) applied to a layer is as simple as specifying the intended position in the stack with the moveTo() method for the mask (PropertyBase). Use a value of 1 to move a mask to the top of the stack, or a value equal to the number of masks on the layer to move a mask to the bottom.

The following code shows how to move a specific mask to the top and bottom of the stack.

// given:
// mask = PropertyBase associated with the layer mask to rearrange
// masksGroup = PropertyGroup associated with the layer's masks
//
mask.moveTo(1);                                  // Move to the top (1 = top of stack)

mask.moveTo(masksGroup.numProperties);           // Move to the bottom

Removing a mask from a layer

Removing a mask from the stack of masks on a layer is as simple as calling the remove() method for the mask (PropertyBase).

Note: If you want to remove all masks from a layer, index the mask’s PropertyGroup in reverse. Otherwise, incrementing through the PropertyBase’s properties will cause your script to access indices that no longer exist as masks are deleted.

The following code shows how to remove a single mask, as well as all masks on a layer.

// given:
// layer = Layer object, and the layer can have masks applied
// masksGroup = PropertyGroup associated with the layer's masks
// mask = PropertyBase associated with the layer mask to remove
//
mask.remove();                                   // Removes a specific mask

                                                 // Remove all masks on the layer
for (var i = masksGroup.numProperties; i >= 1; i--)
    masksGroup.property(i).remove();
// ... or ...
while (masksGroup.numProperties > 0)             // Continually remove masks until no more
    masksGroup.property(masksGroup.numProperties).remove();