Ae Layer Properties

Layer Properties vs Layer Attributes

Layer properties are the parameters of a layer which are listed in the After Effects timeline panel and that can usually be keyframed. There are many other things that belong to a layer, like its name, motion blur setting, parent layer or in point, for example - and we call those attributes. This chapter is only about layer properties - the blocks to get or set a layer attribute are described in the section Layers.

Accessing Layer Properties

Whenever a block requires a layer property as argument, Automation Blocks represents the property as a text, which is similar to a file path. You can create those texts manually using a Text block, for example, but usually it is more convenient to use a Layer Property block, which will create the text for you.

A property path string is identical to a layer path string, except that you need to append the match name or name of the property and all its parent properties (i.e. groups that it is included in).

The position is inside the Transform group, for example, so the path for the position of the layer "White Solid 1" in "Comp 1" is

Comp 1::White Solid 1/Transform/Position

Note that this will only work in the English version of Ae, and in other language versions you have to use the translated terms for "Transform" and "Position". To be language independent, each property in Ae also has a match name. The match name for "Position" is "ADBE Position" and the one for "Transform" is "ADBE Transform Group". So you can also access the position as:

/Comp 1::White Solid 1/ADBE Transform Group/ADBE Position

However, the good news is that you rarely need to create these paths yourself. Usually, you use the Layer Property block instead.

Layer Property

This block will create the path strings for you, which you need to access a particular property. If you select the position property of the layer "White Solid 1" of the comp "Comp 1", for example, and then click the refresh icon of the block, it will create this path for you:

/Comp 1::White Solid 1/ADBE Transform Group/ADBE Position

which is exactly the path you need to access this property.

Property Value

If you want to set a property value or a keyframe, this value can be as simple as a single number (for the Opacticy property), or as complex as a shape or mask path. With this block you can store all kinds of property values as part of your script. Just select a property and click the refresh button of the block. It will read the property value and store it in the block as a string in JSON format. Now you can use it to set the value of a property using the block Set Attribute of Property for example.

Note that the block creates a string in JSON format. If you feel adventurous, you can copy and paste this data to a code editor of your choice and understand its structure. Then you can also create and manipulate these json texts with the blocks in the text category.

Only Selected Layer Property

Returns the (full path of) the only currently selected property of the given composition. If more than one property is selected, the block will stop with an error.

List of Layer Properties

This block creates a list (array) of all layer properties of the given layer(s) or composition(s). You can give this block either a single layer or comp or an entire list of layers or comps as argument and it will put the properties of all of them into the list.

You can choose to only include certain kinds of properties into the list. For a description of the available filter options, see the block For Each Layer Property, which has exactly the same options.

For Each Layer Property

This block is a loop which allows you to do something with all (or some of) the properties of the given layer(s) or comp(s). The blocks you plug into this block are executed many times - namely once for each of the considered properties. In the first row, you'll find various filter options to choose which properties should be considered.

my property variable

The block creates a variable my property and during each execution of the loop, the variable contains the property that is currently considered.

comp(s), layer(s) or group(s)

At this parameter, which is set to the active comp by default, you can either specify a single comp or layer or Layer Property Group or a list of layers or comps. For each given layer, all properties of that layer are considered - for each given composition, the properties of all layers in that comp are considered. If you give a property group (like the Transform group of a layer, for example) only the properties contained in that group are considered.

each

In the first dropdown list of the block you have the option to loop over each or each selected property.

property type filter

In the second dropdown list of the block you can limit the loop to different kinds of properties:

• property and property group loops over all properties, including the groups which contain other properties (example: the loop is not just executed for properties like the Position or Scale property inside the Transform group, but also for the Transform group itself).
• property loops over all properties except groups (example: the loop is executed for Position and Scale inside the Transform group, but not for the Transform group itself)
• Type Filter: For each property value type there is a separate entry in the dropdown which allows you to loop only over properties with that type (like for each color property or 2D spatial property, for example).
• keyframed property loops only over properties which currently have keyframes.
• keyframeable property loops only over properties which can be keyframed (whether they currently have keyframes or not).
• property with expression loops only over properties which have a (non-empty) expression
• property to which expressions can be applied loops only over properties to which expressions can be applied (whether they currently have an expression or not)

For Each Effect

Loops over all the effects of the given comp(s) or layer(s). You can either give the block a single comp or a single layer as argument or an entire list (array) of them. The property group of the effect is stored in the variable my effect when the nested blocks of the loop are executed.

Get Attribute of Property

Returns one of the attributes of the given layer property - most notably the property's value, but also other attributes like its expression, its name or number of keyframes. For a description of all available attributes see Set Attribute of Property.

Set Attribute of Property

Sets any of the available attributes of a property - like its value, expression, name or selected flag. After you choose an attribute, the inputs of the block change as needed for that attribute.

The available attributes of properties are listed below. If an attribute is marked as read-only, you can only get but not set this attribute.

can set enabled (read-only)

A logic value which is true, if you can set the enabled attribute value. Generally, this is true if the user interface displays an eyeball icon for this property;

can set expression (read-only)

A logic value which is true, if this property supports expressions.

can vary over time (read-only)

A logic value which is true, if that property can vary over time—that is, keyframe values or expressions can be written to this property.

If you want to know if the property is actually varying over time, use the attribute is time varying.

dimensions separated

A logic value true or false. When true, the property's dimensions are represented as separate properties. For example, if the layer's position is represented as X Position and Y Position properties in the Timeline panel, the Position property has this attribute set to true.

dropdown list entries (write only)

A list (array) of texts. This attribute can only be set for one property, namely the Dropdown Menu Control effect. It allows to set the labels for the dropdown options, in the same way as if you would click the Edit button of this effect.

To insert an separator in the list, add an empty string to the like (or alternatively the text (-). The | symbol is not allowed in label names and will be removed. If you try to set the dropdown list entries for other properties than the Dropdown Menu Control effect, a warning is printed on the console and the request is ignored.

Matchname Change

If you change the dropdown list entries, After Effects internally replaces the effect by a new one with a new match name. As a result, any variable pointing to the effect becomes invalid. If you need to do multiple things with the effect (say setting its list entries AND changing its name, adding keyframes,...) best change the list entries after the other operations. If this is not possible, you can also save the name of the

example

In this example we first create a dropdown list on the only selected layer. Then we set its dropdown list options, and after that change the name of the dropdown and choose the fourth of the new list options:

enabled

A logic value true or false. For a layer, this corresponds to the video switch state of the layer in the Timeline panel. For an effect and other properties, it corresponds to the setting of the eyeball icon, if there is one.

If you try to set this attribute for a property whose can set enabled attribute is false, Automation Blocks writes a warning to the console and ignores the request (but continues the script execution and does not stop with an error).

expression

The expression (as a text) which is applied to this property (or the empty text, if there is no expression).

If you set this value, the following happens:

• If the text contains a valid expression, expression enabled becomes true.
• If the text does not contain a valid expression, an error is generated, and expression enabled becomes false.
• If you set the attribute to the empty text, expression enabled becomes false but no error is generated.

If you try to set this attribute for a property whose can set expression attribute is false, Automation Blocks writes a warning to the console and ignores the request (but continues the script execution and does not stop with an error).

expression enabled

A logic value true or false which indicates whether the expression of this property is currently active or not.

expression error (read-only)

Contains the error message text, if any, generated by evaluation of the expression on this property. If the property has no expression, or if the expression evaluated without error, this contains the empty text.

has max value (read-only)

A logic value which is true if the property has a maximum value (i.e. its max value attribue is not null.

Note that when you attempt to set a value, Automation Blocks clips it to the min-max range of the property, if it has one. So, you usually don't need to worry about these.

has index (read-only)

A logic value true or false which determined whether this property is part of an "indexed group", i.e. if it can be moved up or down among its sibling properties. Effects have an index, for example (you can move an effect up or down in the effects stack), but the "Transform" group or the "Effects" groups, which contains all the effects, has a fixed place and cannot be moved, so they have no index.

If a property has an index, you can get or set it using the index attribute.

has min value (read-only)

A logic value which is analogous to the has max value attribute.

max value (read-only)

Some properties have a min-max range: The opacity of a layer cannot be smaller than 0 or bigger than 100. This attribute is null if this property has no maximum value. See also has max value.

min/max for array values

Also, some array values have minimal or maximal values. The size of a rectangle shape is a 2D value, for example, and has a minumum of 0. Note that the minimum is just a single number and applies to all components of the array, i.e. neither the width nor the height can be smaller than zero.

min value (read-only)

This attribute is analogous to the max value attribute.

index

The index of the property, which determines where the index is located among its siblings. The first property in a group has index 1.

You can set this value to a new number to move the property up and down. Setting the index of an effect to 1, for example, makes it the first effect on that layer, but you can also use it on masks or shape groups, for example.

positive number If you set the value to 8, it will become the 8th property of the group (unless the group has less than 8 layers: in that case it will become the last property). If you set the value to 0 the result is the same as if you set it to 1 - it will become the first property of the group.

negative number If you set this value to a negative number, the index is counted from the end of the group. Hence, if you set the value to -1, it will become the last property of the group and if you set it to -2, it will become the last but one.

not everything has an index

You can move an effect up and down, but you cannot move individual controls of an effect up and down (since those have a fixed order inside the effect). To check if a property can be moved, see the attribute has index. If you try to get the index of a property which has no index, the result will be null.

is time varying (read-only)

A logic value true or false. When true, the property is time varying — that is, it has keyframes or an enabled expression. When this attribute is true, the attribute can vary over time must also be true.

name

The name of the property. Note that not all names can be set. You can, for example, rename an effect that you applied to a layer, but you cannot rename the group Effects in which it is contained:

If you attempt to rename a property which cannot be renamed, Automation Blocks ignores the request, prints a warning to the console and continues with the execution of the script (and does not stop with an error).

name (unique match name) (read-only)

A special name for the property is used to build unique naming paths. The match name is not displayed, but you can refer to it in scripts. Every property has a unique match-name identifier. Match names are stable from version to version regardless of the display name (the name attribute value) or any changes to the application. Unlike the display name, it is not localized. An indexed group may not have a name value, but always has a matchName value.

num keys (read-only)

The number of keyframes of this property (0 if the property is not keyframed).

num properties (read-only)

If this property is a group, this is the number of properties that are contained within it. For the property ::1/ADBE Effect Parade (which is the Effects group of the first layer of the active comp), it returns the number of effects on that layer. If the property is no group, the value is 0.

property value type (read-only)

A text describing the kind of value, which this property has. This text can have the following values:

• NO_VALUE: (groups, like the "Transform Group", for example)
• ThreeD_SPATIAL: a list (array) of three numbers representing a point in 3D space (the position of a layer, for example)
• ThreeD: a list (array) of three numbers (the scale of a layer, for example)
• TwoD_SPATIAL a list (array) of two numbers representing a point in 2D space(the Point property of the Point Control effect, for example)
• TwoD: a list (array) of two numbers (the Size of Rectangle Path of a Shape Layer, for example)
• OneD: a single number, (like the Opacity or Rotation of a layer, for example)
• COLOR: a list (array) of 4 floating-point numbers. You can set color values in various formats, see Ae Color.
• CUSTOM_VALUE these values cannot be read or set by scripts (the Histogram property of the Levels effect, for example).
• MARKER: an index number refering to a marker on the same layer as the property itself (starting with 1 for the first marker).
• LAYER_INDEX: The index of a layer in the same comp. If you want to set this value, you can also specify the layer in other ways, and Automation Blocks will convert it to an index for you.
• MASK_INDEX: The index of a mask on the same layer (1 for the first mask on that layer).
• SHAPE: A shape path as a json text.
• TEXT_DOCUMENT: A text.

spatial vs non-spatial

One difference between spatial and non-spatial values is that spatial values are usually visualized as points in the Composition panel (you can click and drag a point control in the comp viewer, for example). But the most important difference is that the interpolation between keyframes is very different for spatial and non-spatial properties. Non-spatial properties only have temporal interpolation - they are interpolated exactly as if they where two (or three) independent 1D properties. By contrast, spatial properties have a spatial interpolation, which defines the path along which the value travels from keyframe to keyframe. Temporal interpolation thus is not performed for each dimension individually, but only once, along the path.

You can see the difference when you separate the dimensions of the position property, because this effectively switches from spatial interpolation to non-spatial interpolation:

more 3D than you can see

Note that After Effects sometimes hides part of a value from the user interface. Layer positions are always 3D spatial values, for example, even if the layer is a 2D layer. The third component is hidden (and ignored) in that case, but still present. The same is also the case for the scale property.

selected

A logic value which is true, if the property is selected.

value

The value of the property. If the property has keyframes, the value at the current time is returned if you get the value and a keyframe is created at the current time if you set the value.

See the Property Value Type to figure out what kind of value a property has. If you want to set the value of a property, you can create this value with the Property Value block.

If you want to keyframe a value, see the block Add Keyframes

Delete Property

Deletes the given property (or list (array) of properties). If the property is a group, all child properties are removed as well. Note that not all properties can be deleted - you can delete an effect, for example, but you cannot delete an individual parameter of an effect or the transform group.

Rebase Property

This block allows you to replace the comp or layer of a layer property string. In other words, it returns the same property, but on a different layer or on the same layer in a different comp.

If you access a property with the Layer Property block, for example, it contains the full path for the property, like

comp 1::my text layer/transform/position

for the position property of the layer "my text layer" in the composition "comp 1". If you want to access the position of another layer, you can take this path and replace the layer, which will effectively replace the comp 1::my text layer part of the path with the respective path from the new layer.

After you have used the Rebase Property block, you'll often want to check if the property exists, because not all layers have the same properties.

Property Exists

This block returns a logic value which is true if the given property exists. You can always assume that a video layer has a position property, for example, but if you want to access a property of an effect, which may or may not be applied to the layer, you should check if the property actually exists before you try to get an attribute from it, for example.

See also the Project Item Exists block.

Check if layer exists

Since layers are also properties, you can also use the Property Exists block to check if a particular layer exists.