45 |
--------------------------------------------------------------------------------
/docs/_global/readme.md:
--------------------------------------------------------------------------------
1 | # docsforadobe.dev MkDocs Config
2 |
3 | This repo holds the common components shared between this org's hosted MkDocs documentation projects.
4 |
5 | The idea is that this repo will be kept up-to-date with global config, and each child repo will use the provided script to download the latest commit from this repo, and have its "local" MkDocs config point to the downloaded files from this repo.
6 |
7 | In all cases, each child repo will be able to *override* config items here as needed.
8 |
9 | ## Updating This Repo
10 |
11 | See [Modifying Common Components](https://docsforadobe.dev/contributing/common-components/modifying-common-components/) in the org contribution guide for info on how this repo works, and best practices for modifying it.
12 |
--------------------------------------------------------------------------------
/docs/_global/requirements.txt:
--------------------------------------------------------------------------------
1 | markdown_grid_tables
2 | mkdocs
3 | mkdocs-git-revision-date-localized-plugin
4 | mkdocs-material
5 | mkdocs-print-site-plugin
6 |
--------------------------------------------------------------------------------
/docs/_global/scripts/update-common-components.py:
--------------------------------------------------------------------------------
1 | import os
2 | import shutil
3 | import tarfile
4 | import tempfile
5 | import urllib.request
6 |
7 | org_name = "docsforadobe"
8 | repo_name = "docsforadobe-mkdocs-config"
9 | destination_dir = "./docs/_global"
10 |
11 | def download_github_repo(org_name, repo_name, destination_dir):
12 | tar_url = f"https://api.github.com/repos/{org_name}/{repo_name}/tarball/main"
13 |
14 | response = urllib.request.urlopen(tar_url)
15 |
16 | if (response):
17 | with tempfile.TemporaryDirectory() as temp_dir:
18 | tar = tarfile.open(fileobj=response, mode="r|gz")
19 | tar_extraction_path = os.path.join(temp_dir, tar.firstmember.name)
20 |
21 | tar.extractall(path=temp_dir)
22 |
23 | # If already exist, remove first
24 | if (os.path.isdir(destination_dir)):
25 | shutil.rmtree(destination_dir)
26 |
27 | # Move from temp folder to destination folder
28 | shutil.move(tar_extraction_path, destination_dir)
29 |
30 | download_github_repo(org_name, repo_name, destination_dir)
31 |
--------------------------------------------------------------------------------
/docs/_static/extra.css:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/docsforadobe/after-effects-expression-reference/0cdf30d6c9a3edcad456c6dc4430392149efa808/docs/_static/extra.css
--------------------------------------------------------------------------------
/docs/general/color-conversion.md:
--------------------------------------------------------------------------------
1 | # Color Conversion
2 |
3 | These methods are all around converting colours from one format to another. Think converting a hex code to RGB, so you can use your client's brand colours in an expression in the project, or converting a value to HSL so you can adjust the lightness or saturation procedurally.
4 |
5 | ---
6 |
7 | ## Methods
8 |
9 | ### rgbToHsl()
10 |
11 | `rgbToHsl(rgbaArray)`
12 |
13 | #### Description
14 |
15 | Converts a color in RGBA space to HSLA space.
16 |
17 | The input is an Array of normalized red, green, blue, and alpha channel values, all in the range of `0.0` to `1.0`.
18 |
19 | The resulting value is an Array of hue, saturation, lightness, and alpha channel values, also in the range of `0.0` to `1.0`.
20 |
21 | #### Parameters
22 |
23 | | Parameter | Type | Description |
24 | | ----------- | -------------------------------- | -------------------------------------- |
25 | | `rgbaArray` | Array of numbers (4-dimensional) | RGBA values, in the range `[0.0..1.0]` |
26 |
27 | #### Returns
28 |
29 | HSLA Array (4-dimensional)
30 |
31 | #### Example:
32 |
33 | ```js
34 | rgbToHsl.effect("Change Color")("Color To Change")
35 | ```
36 |
37 | ---
38 |
39 | ### hslToRgb()
40 |
41 | `hslToRgb(hslaArray)`
42 |
43 | #### Description
44 |
45 | Converts a color in HSLA space to RGBA space.
46 |
47 | This conversion is the opposite of the conversion performed by the [rgbToHsl()](#rgbtohsl) method.
48 |
49 | #### Parameters
50 |
51 | | Parameter | Type | Description |
52 | | ----------- | -------------------------------- | -------------------------------------- |
53 | | `hslaArray` | Array of numbers (4-dimensional) | HSLA values, in the range `[0.0..1.0]` |
54 |
55 | #### Returns
56 |
57 | RGBA Array (4-dimensional)
58 |
59 | ---
60 |
61 | ### hexToRgb()
62 |
63 | `hexToRgb(hexString)`
64 |
65 | !!! note
66 | This functionality was added in After Effects 16.0.
67 |
68 | #### Description
69 |
70 | Converts a color in hex triplet space to RGB space, or in hex quartet space to RGBA space.
71 |
72 | For hex triplets, the alpha channel defaults to 1.0.
73 |
74 | #### Parameters
75 |
76 | +-------------------------------------------------------------------------------------------------------+--------+------------------------------------------------------------------------------------------------------------------------------------+
77 | | Parameter | Type | Description |
78 | +=======================================================================================================+========+====================================================================================================================================+
79 | | `hexString` | String | Hex triplet (6 digits, no alpha channel) or quartet (8 digits, includes alpha channel) containing only numerals or characters A–F. |
80 | | | | |
81 | | Optional leading characters 0x, 0X, or # will be ignored. Characters beyond 8 digits will be ignored. | | |
82 | +-------------------------------------------------------------------------------------------------------+--------+------------------------------------------------------------------------------------------------------------------------------------+
83 |
84 | #### Returns
85 |
86 | Array (4-dimensional)
87 |
88 | #### Examples
89 |
90 | Any of the following will return `[1.0, 0.0, 1.0, 1.0]`:
91 |
92 | - `hexToRgb("FF00FF")`
93 | - `hexToRgb("#FF00FF")`
94 | - `hexToRgb("0xFF00FF")`
95 | - `hexToRgb("0XFF00FFFF")`
96 | - **Note:** This inputs an 8-digit hex quartet; the last two digits set alpha channel to 1.0.
97 |
--------------------------------------------------------------------------------
/docs/general/general.md:
--------------------------------------------------------------------------------
1 | # General
2 |
3 | The methods and attributes in this category apply to–and can be used by–nearly *every* expression in After Effects.
4 |
5 | These global, top-level elements have been grouped into several categories for the sake of organization.
6 |
7 | Those categories are:
8 |
9 | - [Global](./global.md) is for broad, commonly-used elements such as the current comp or property; the current comp time, and so on.
10 | - [Time Conversion](./time-conversion.md) holds various methods for converting time to and from various other methods.
11 | - [Vector Math](./vector-math.md) provides a suite of methods for working with vectors and arrays.
12 | - [Random Numbers](./random-numbers.md) is for generating randomness within your expression.
13 | - [Interpolation](./interpolation.md) is for converting values from one set to another, or using one set of values to drive another set of values.
14 | - [Color Conversion](./color-conversion.md) is for changing between colour modes (such as converting RGB values to HSL, or Hex values to RGB)
15 | - [Other Math](./other-math.md) is for all other assorted math– namely, converting between degrees and radians for rotation values.
16 |
--------------------------------------------------------------------------------
/docs/general/global.md:
--------------------------------------------------------------------------------
1 | # Global
2 |
3 | These attributes and methods are global, top-level elements accessible from any expression across your project. They're among the most commonly-used expression elements.
4 |
5 | ---
6 |
7 | ## Attributes
8 |
9 | ### colorDepth
10 |
11 | `colorDepth`
12 |
13 | #### Description
14 |
15 | Type the project color depth value.
16 |
17 | For example, `colorDepth` returns `16` when the project color depth is 16 bits per channel.
18 |
19 | #### Type
20 |
21 | Number
22 |
23 | ---
24 |
25 | ### thisComp
26 |
27 | `thisComp`
28 |
29 | #### Description
30 |
31 | Represents the composition containing the expression.
32 |
33 | #### Type
34 |
35 | [Comp](../objects/comp.md)
36 |
37 | ---
38 |
39 | ### thisLayer
40 |
41 | `thisLayer`
42 |
43 | #### Description
44 |
45 | Represents the layer containing the expression.
46 |
47 | Because `thisLayer` is the default object, its use is optional.
48 |
49 | For example, you can start an expression with `thisLayer.width` or `width` and get the same result.
50 |
51 | #### Type
52 |
53 | [Layer](../layer/layer.md), [Light](../objects/light.md), or [Camera](../objects/camera.md) object
54 |
55 | ---
56 |
57 | ### thisProject
58 |
59 | `thisProject`
60 |
61 | #### Description
62 |
63 | Represents the project which contains the expression.
64 |
65 | #### Type
66 |
67 | [Project](../objects/project.md)
68 |
69 | ---
70 |
71 | ### thisProperty
72 |
73 | `thisProperty`
74 |
75 | #### Description
76 |
77 | Represents the property containing the expression.
78 |
79 | For example, if you write an expression on the Rotation property, you can start an expression with `thisProperty` to refer to the Rotation property.
80 |
81 | #### Type
82 |
83 | [Property](../objects/property.md)
84 |
85 | ---
86 |
87 | ### time
88 |
89 | `time`
90 |
91 | #### Description
92 |
93 | Represents the composition time, in seconds, at which the expression is being evaluated.
94 |
95 | #### Type
96 |
97 | Number
98 |
99 | ---
100 |
101 | ### value
102 |
103 | `value`
104 |
105 | #### Description
106 |
107 | Represents the value at the current time for the property containing the expression.
108 |
109 | #### Type
110 |
111 | A value of the same property type as the property being refrenced.
112 |
113 | ---
114 |
115 | ## Methods
116 |
117 | ### comp()
118 |
119 | `comp(name)`
120 |
121 | #### Description
122 |
123 | Retrieves another composition by name.
124 |
125 | #### Parameters
126 |
127 | | Parameter | Type | Description |
128 | | --------- | ------ | ---------------------------------- |
129 | | `name` | String | The name of the composition to get |
130 |
131 | #### Returns
132 |
133 | [Comp](../objects/comp.md)
134 |
135 | ---
136 |
137 | ### footage()
138 |
139 | `footage(name)`
140 |
141 | #### Description
142 |
143 | Retrieves a footage item by name.
144 |
145 | #### Parameters
146 |
147 | | Parameter | Type | Description |
148 | | --------- | ------ | ----------------------------------- |
149 | | `name` | String | The name of the footage item to get |
150 |
151 | #### Returns
152 |
153 | [Footage](../objects/footage.md)
154 |
155 | ---
156 |
157 | ### posterizeTime()
158 |
159 | `posterizeTime(updatesPerSecond)`
160 |
161 | #### Description
162 |
163 | This expression allows you to set the frame rate for a property to be lower than the frame rate of the composition.
164 |
165 | #### Parameters
166 |
167 | | Parameter | Type | Description |
168 | | ------------------ | ------ | --------------------------------------------------------------- |
169 | | `updatesPerSecond` | Number | The *number of times per second* the expression should evaluate |
170 |
171 | #### Returns
172 |
173 | Number
174 |
175 | #### Example
176 |
177 | To change a property to a random value 1 time per second:
178 |
179 | ```js
180 | posterizeTime(1);
181 |
182 | random()
183 | ```
184 |
185 | To change a 2d property (such as Position or Scale) to a random value 3 times per second:
186 |
187 | ```js
188 | posterizeTime(3);
189 |
190 | const newValue = random(0, 100);
191 | [newValue, newValue];
192 | ```
193 |
194 | To change a property to a random value within a specified range, every 12 frames:
195 |
196 | ```js
197 | const holdFrames = 12;
198 | const minValue = 50;
199 | const maxValue = 100;
200 |
201 | posterizeTime(1 / framesToTime(holdFrames));
202 |
203 | const newValue = random(minValue, maxValue);
204 | newValue;
205 | ```
206 |
--------------------------------------------------------------------------------
/docs/general/interpolation.md:
--------------------------------------------------------------------------------
1 | # Interpolation
2 |
3 | For all the Interpolation methods, the argument `t` is often `time` or `value`, though it can have other values, instead. If `t` is `time`, the interpolation between values happens over a duration. If `t` is `value`, then the expression maps one range of values to a new range of values.
4 |
5 | All the Interpolation methods can also be used to convert from one range of values to another.
6 |
7 | Chris and Trish Meyer provide additional information and examples for these methods in an article on the [ProVideo Coalition website](http://provideocoalition.com/index.php/cmg_keyframes/story/deeper_modes_of_expression_part_2_interpolation_methods/).
8 |
9 | Ian Haigh provides a script on [After Effects Scripts website](http://aescripts.com/ease-and-wizz/) that you can use to easily apply advanced interpolation method expressions—such as bounces—to properties.
10 |
11 | ---
12 |
13 | ## Methods
14 |
15 | ### linear(t, tMin, tMax, value1, value2)
16 |
17 | `linear(t, tMin, tMax, value1, value2)`
18 |
19 | #### Description
20 |
21 | Returns `value1` when `t <= tMin`. Returns `value2` when `t >= tMax`. Returns a linear interpolation between `value1` and `value2` when `tMin < t < tMax`.
22 |
23 | #### Parameters
24 |
25 | | Parameter | Type | Description |
26 | | --------- | --------------- | ------------------------- |
27 | | `t` | Number | Interpolation Driver |
28 | | `tMin` | Number | Minimum driver value |
29 | | `tMax` | Number | Maximum driver value |
30 | | `value1` | Number or Array | Value to interpolate from |
31 | | `value2` | Number or Array | Value to interpolate to |
32 |
33 | #### Returns
34 |
35 | Number or Array
36 |
37 | #### Example
38 |
39 | This expression on the Opacity property causes Opacity values to ramp linearly from `20%` to `80%` over the time from `0` seconds to `6` seconds:
40 |
41 | ```js
42 | linear(time, 0, 6, 20, 80)
43 | ```
44 |
45 | This expression on the Opacity property converts the Opacity values from the range `0%`-`100%` to the range `20%`-`80%`:
46 |
47 | ```js
48 | linear(value, 0, 100, 20, 80)
49 | ```
50 |
51 | ---
52 |
53 | ### linear(t, value1, value2)
54 |
55 | `linear(t, value1, value2)`
56 |
57 | #### Description
58 |
59 | Returns a value that linearly interpolates from `value1` to `value2` as `t` ranges from `0` to `1`. Returns `value1` when `t <= 0`. Returns `value2` when `t >= 1`.
60 |
61 | #### Parameters
62 |
63 | | Parameter | Type | Description |
64 | | --------- | --------------- | ------------------------- |
65 | | `t` | Number | Interpolation Driver |
66 | | `value1` | Number or Array | Value to interpolate from |
67 | | `value2` | Number or Array | Value to interpolate to |
68 |
69 | #### Returns
70 |
71 | Number or Array
72 |
73 | ---
74 |
75 | ### ease(t, tMin, tMax, value1, value2)
76 |
77 | `ease(t, tMin, tMax, value1, value2)`
78 |
79 | #### Description
80 |
81 | Similar to linear with the same arguments, except that the interpolation eases in and out so that the velocity is `0` at the start and end points. This method results in a smooth animation.
82 |
83 | #### Parameters
84 |
85 | | Parameter | Type | Description |
86 | | --------- | --------------- | ------------------------- |
87 | | `t` | Number | Interpolation Driver |
88 | | `tMin` | Number | Minimum driver value |
89 | | `tMax` | Number | Maximum driver value |
90 | | `value1` | Number or Array | Value to interpolate from |
91 | | `value2` | Number or Array | Value to interpolate to |
92 |
93 | #### Returns
94 |
95 | Number or Array
96 |
97 | ---
98 |
99 | ### ease(t, value1, value2)
100 |
101 | `ease(t, value1, value2)`
102 |
103 | #### Description
104 |
105 | Similar to linear with the same arguments, except that the interpolation eases in and out so that the velocity is `0` at the start and end points. This method results in a smooth animation.
106 |
107 | #### Parameters
108 |
109 | | Parameter | Type | Description |
110 | | --------- | --------------- | ------------------------- |
111 | | `t` | Number | Interpolation Driver |
112 | | `value1` | Number or Array | Value to interpolate from |
113 | | `value2` | Number or Array | Value to interpolate to |
114 |
115 | #### Returns
116 |
117 | Number or Array
118 |
119 | ---
120 |
121 | ### easeIn(t, tMin, tMax, value1, value2)
122 |
123 | `easeIn(t, tMin, tMax, value1, value2)`
124 |
125 | #### Description
126 |
127 | Similar to ease, except that the tangent is `0` only on the `tMin` side and interpolation is `linear` on the `tMax` side.
128 |
129 | #### Parameters
130 |
131 | | Parameter | Type | Description |
132 | | --------- | --------------- | ------------------------- |
133 | | `t` | Number | Interpolation Driver |
134 | | `tMin` | Number | Minimum driver value |
135 | | `tMax` | Number | Maximum driver value |
136 | | `value1` | Number or Array | Value to interpolate from |
137 | | `value2` | Number or Array | Value to interpolate to |
138 |
139 | #### Returns
140 |
141 | Number or Array
142 |
143 | ---
144 |
145 | ### easeIn(t, value1, value2)
146 |
147 | `easeIn(t, value1, value2)`
148 |
149 | #### Description
150 |
151 | Similar to ease, except that the tangent is `0` only on the `value1` side and interpolation is `linear` on the `value2` side.
152 |
153 | #### Parameters
154 |
155 | | Parameter | Type | Description |
156 | | --------- | --------------- | ------------------------- |
157 | | `t` | Number | Interpolation Driver |
158 | | `value1` | Number or Array | Value to interpolate from |
159 | | `value2` | Number or Array | Value to interpolate to |
160 |
161 | #### Returns
162 |
163 | Number or Array
164 |
165 | ---
166 |
167 | ### easeOut(t, tMin, tMax, value1, value2)
168 |
169 | `easeOut(t, tMin, tMax, value1, value2)`
170 |
171 | #### Description
172 |
173 | Similar to ease, except that the tangent is `0` only on the `tMax` side and interpolation is `linear` on the `tMin` side.
174 |
175 | #### Parameters
176 |
177 | | Parameter | Type | Description |
178 | | --------- | --------------- | ------------------------- |
179 | | `t` | Number | Interpolation Driver |
180 | | `tMin` | Number | Minimum driver value |
181 | | `tMax` | Number | Maximum driver value |
182 | | `value1` | Number or Array | Value to interpolate from |
183 | | `value2` | Number or Array | Value to interpolate to |
184 |
185 | #### Returns
186 |
187 | Number or Array
188 |
189 | ---
190 |
191 | ### easeOut(t, value1, value2)
192 |
193 | `easeOut(t, value1, value2)`
194 |
195 | #### Description
196 |
197 | Similar to ease, except that the tangent is `0` only on the `value2` side and interpolation is `linear` on the `value1` side.
198 |
199 | #### Parameters
200 |
201 | | Parameter | Type | Description |
202 | | --------- | --------------- | ------------------------- |
203 | | `t` | Number | Interpolation Driver |
204 | | `value1` | Number or Array | Value to interpolate from |
205 | | `value2` | Number or Array | Value to interpolate to |
206 |
207 | #### Returns
208 |
209 | Number or Array
210 |
--------------------------------------------------------------------------------
/docs/general/other-math.md:
--------------------------------------------------------------------------------
1 | # Other Math
2 |
3 | This category holds other math functions not otherwise covered.
4 |
5 | ---
6 |
7 | ## Methods
8 |
9 | ### degreesToRadians()
10 |
11 | `degreesToRadians(degrees)`
12 |
13 | #### Description
14 |
15 | Converts degrees to radians.
16 |
17 | #### Parameters
18 |
19 | | Parameter | Type | Description |
20 | | --------- | ------ | -------------------------------------------- |
21 | | `degrees` | Number | The value (in degrees) to convert to radians |
22 |
23 | #### Returns
24 |
25 | Number
26 |
27 | ---
28 |
29 | ### radiansToDegrees()
30 |
31 | `radiansToDegrees(radians)`
32 |
33 | #### Description
34 |
35 | Converts radians to degrees.
36 |
37 | #### Parameters
38 |
39 | | Parameter | Type | Description |
40 | | --------- | ------ | -------------------------------------------- |
41 | | `radians` | Number | The value (in radians) to convert to degrees |
42 |
43 | #### Returns
44 |
45 | Number
46 |
--------------------------------------------------------------------------------
/docs/general/random-numbers.md:
--------------------------------------------------------------------------------
1 | # Random Numbers
2 |
3 | These items deal with randomness in expressions.
4 |
5 | !!! note
6 | The [wiggle()](../objects/property.md#wiggle) method—which is used to randomly vary a property value—is in the [Property](../objects/property.md) attributes and methods category.
7 |
8 | ---
9 |
10 | ## Methods
11 |
12 | ### gaussRandom()
13 |
14 | `gaussRandom([maxValOrArray=1])`
15 |
16 | #### Description
17 |
18 | When `maxValOrArray` is a Number, this method returns a random number. Approximately `90%` of the results are in the `0` to `maxValOrArray` range, and the remaining `10%` are outside this range.
19 |
20 | When `maxValOrArray` is an Array, this method returns an Array of random values, with the same dimension as `maxValOrArray`. `90%` of the values are in the range from `0` to `maxValOrArray`, and the remaining `10%` are outside this range.
21 |
22 | The results have a Gaussian (bell-shaped) distribution.
23 |
24 | #### Parameters
25 |
26 | | Parameter | Type | Description |
27 | | --------------- | --------------- | --------------------------------------------------------------------------------------------- |
28 | | `maxValOrArray` | Number or Array | Optional. The max value (or array) to generate a random number to, from `0`. Defaults to `1`. |
29 |
30 | #### Returns
31 |
32 | Number or Array
33 |
34 | ---
35 |
36 | ### gaussRandom(minValOrArray, maxValOrArray)
37 |
38 | `gaussRandom(minValOrArray, maxValOrArray)`
39 |
40 | #### Description
41 |
42 | If `minValOrArray` and `maxValOrArray` are Numbers, this method returns a random number. Approximately `90%` of the results are in the range from `minValOrArray` to `maxValOrArray`, and the remaining `10%` are outside this range.
43 |
44 | If the arguments are Arrays, this method returns an Array of random numbers with the same dimension as the argument with the greater dimension. For each component, approximately 90% of the results are in the range from the corresponding component of `minValOrArray` to the corresponding component of `maxValOrArray`, and the remaining `10%` are outside this range.
45 |
46 | The results have a Gaussian (bell-shaped) distribution.
47 |
48 | #### Parameters
49 |
50 | | Parameter | Type | Description |
51 | | --------------- | --------------- | ---------------------------------------------------------- |
52 | | `minValOrArray` | Number or Array | The min value (or array) to generate a random number from. |
53 | | `maxValOrArray` | Number or Array | The max value (or array) to generate a random number to. |
54 |
55 | #### Returns
56 |
57 | Number or Array
58 |
59 | ---
60 |
61 | ### noise(valOrArray)
62 |
63 | `noise(valOrArray)`
64 |
65 | #### Description
66 |
67 | Returns a number in the range from `-1` to `1`.
68 |
69 | The noise is not actually random; it is based on Perlin noise, which means that the return values for two input values that are near one another tend to be near one another.
70 |
71 | This type of noise is useful when you want a sequence of seemingly random numbers that don't vary wildly from one to the other—as is usually the case when animating any apparently random natural motion.
72 |
73 | #### Parameters
74 |
75 | | Parameter | Type | Description |
76 | | ------------ | ---------------------------------------- | ---------------------------------------------------------------- |
77 | | `valOrArray` | Number or an Array (2- or 3-dimensional) | The input value (or array) to use to generate the random number. |
78 |
79 | #### Returns
80 |
81 | Number
82 |
83 | #### Example
84 |
85 | ```js
86 | rotation + 360*noise(time)
87 | ```
88 |
89 | ---
90 |
91 | ### random()
92 |
93 | `random([maxValOrArray=1])`
94 |
95 | #### Description
96 |
97 | If `maxValOrArray` is a Number, this method returns a number in the range from `0` to `maxValOrArray`.
98 |
99 | If `maxValOrArray` is an Array, this method returns an Array with the same dimension as `maxValOrArray`, with each component ranging from `0` to the corresponding component of `maxValOrArray`.
100 |
101 | !!! note
102 | In After Effects CC and CS6, the behavior of random() is changed to be more random when layer IDs are close together. The wiggle() expression is not affected.
103 |
104 | #### Parameters
105 |
106 | | Parameter | Type | Description |
107 | | --------------- | --------------- | --------------------------------------------------------------------------------------------- |
108 | | `maxValOrArray` | Number or Array | Optional. The max value (or array) to generate a random number to, from `0`. Defaults to `1`. |
109 |
110 | #### Returns
111 |
112 | Number or Array
113 |
114 | ---
115 |
116 | ### random(minValOrArray, maxValOrArray)
117 |
118 | `random(minValOrArray, maxValOrArray)`
119 |
120 | #### Description
121 |
122 | If `minValOrArray` and `maxValOrArray` are Numbers, this method returns a number in the range from `minValOrArray` to `maxValOrArray`.
123 |
124 | If the arguments are Arrays, this method returns an Array with the same dimension as the argument with the greater dimension, with each component in the range from the corresponding component of `minValOrArray` to the corresponding component of `maxValOrArray`.
125 |
126 | For example, the expression `random([100, 200], [300, 400])` returns an Array whose first value is in the range `100–300` and whose second value is in the range `200–400`. If the dimensions of the two input Arrays don't match, higher-dimension values of the shorter Array are filled out with zeros.
127 |
128 | #### Parameters
129 |
130 | | Parameter | Type | Description |
131 | | --------------- | --------------- | ---------------------------------------------------------- |
132 | | `minValOrArray` | Number or Array | The min value (or array) to generate a random number from. |
133 | | `maxValOrArray` | Number or Array | The max value (or array) to generate a random number to. |
134 |
135 | #### Returns
136 |
137 | Number or Array
138 |
139 | ---
140 |
141 | ### seedRandom()
142 |
143 | `seedRandom(offset[, timeless=false])`
144 |
145 | #### Description
146 |
147 | The `random()` and `gaussRandom()` methods use a seed value that controls the sequence of numbers.
148 |
149 | By default, the seed is computed as a function of a unique layer identifier, the property within the layer, the current time, and an offset value of `0`.
150 |
151 | Call `seedRandom()` to set the offset to something other than 0 to create a different random sequence.
152 |
153 | The multiplication by `100` in this example converts the value in the range `0–1` returned by the random method into a Number in the range `0–100`; this range is more typically useful for the Opacity property, which has values from `0%` to `100%`.
154 |
155 | #### Parameters
156 |
157 | | Parameter | Type | Description |
158 | | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
159 | | `offset` | Number | The value with which to offset the seed. This is also used to control the initial value of the [`wiggle()`](../objects/property.md#wiggle) function. |
160 | | `timeless` | Boolean | Optional. Use `true` for the timeless argument to not use the current time as input to the random seed. This allows you to generate a random number that doesn't vary depending on the time of evaluation. Defaults to `false`. |
161 |
162 | #### Returns
163 |
164 | None
165 |
166 | #### Example
167 |
168 | This expression on the Opacity property sets the Opacity value to a random value that does not vary with time:
169 |
170 | ```js
171 | seedRandom(123456, true);
172 | random()*100
173 | ```
174 |
--------------------------------------------------------------------------------
/docs/general/time-conversion.md:
--------------------------------------------------------------------------------
1 | # Time Conversion
2 |
3 | These methods are all about converting between various time formats.
4 |
5 | !!! tip
6 | If you want more control over the look of timecode in your footage, use the `timeToCurrentFormat()` method or other `timeTo` methods to generate the timecode instead of using the Timecode or Numbers effect.
7 |
8 | #### Example
9 |
10 | You can easily format and animate the timecode text by creating a text layer, applying whatever text styling you'd like, and adding this expression to the Source Text property:
11 |
12 | ```js
13 | timeToCurrentFormat();
14 | ```
15 |
16 | ---
17 |
18 | ## Methods
19 |
20 | ### framesToTime()
21 |
22 | `framesToTime(frames[, fps=1.0 / thisComp.frameDuration])`
23 |
24 | #### Description
25 |
26 | Returns the time corresponding to the frames argument. It doesn't have to be an integer.
27 |
28 | The inverse of [`timeToFrames()`](#timetoframes).
29 |
30 | #### Parameters
31 |
32 | | Parameter | Type | Description |
33 | | --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
34 | | `frames` | Number | The amount of frames to convert. |
35 | | `fps` | Number | Optional. The number of frames per second to use to convert. Defaults to `1.0 / thisComp.frameDuration` (the frame rate of the current composition). |
36 |
37 | #### Returns
38 |
39 | Number
40 |
41 | ---
42 |
43 | ### timeToCurrentFormat()
44 |
45 | `timeToCurrentFormat([t=time + thisComp.displayStartTime][, fps=1.0 / thisComp.frameDuration][, isDuration=false][, ntscDropFrame=thisComp.ntscDropFrame])`
46 |
47 | #### Description
48 |
49 | Converts the value of `t` to a String representing time in the current Project Settings display format.
50 |
51 | #### Parameters
52 |
53 | | Parameter | Type | Description |
54 | | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55 | | `t` | Number | Optional. The time (in seconds) to convert. Defaults to `time + thisComp.displayStartTime`. |
56 | | `fps` | Number | Optional. Defaults to `1.0 / thisComp.frameDuration` (the frame rate of the current composition). |
57 | | `isDuration` | Boolean | Optional. Whether `t` represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to `false`. |
58 | | `ntscDropFrame` | Boolean | Optional. If `false`, the result is NTSC non-drop-frame timecode. If `true`, the result is NTSC drop-frame timecode. Defaults to `thisComp.ntscDropFrame`. |
59 |
60 | !!! note
61 | The `ntscDropFrame` argument was added in After Effects CS5.5.
62 |
63 | #### Returns
64 |
65 | String
66 |
67 | ---
68 |
69 | ### timeToFeetAndFrames()
70 |
71 | `timeToFeetAndFrames([t=time + thisComp.displayStartTime][, fps=1.0 / thisComp.frameDuration][, framesPerFoot=16][, isDuration=false])`
72 |
73 | #### Description
74 |
75 | Converts the value of `t` to a String representing feet of film and frames.
76 |
77 | #### Parameters
78 |
79 | | Parameter | Type | Description |
80 | | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
81 | | `t` | Number | Optional. The time (in seconds) to convert. Defaults to `time + thisComp.displayStartTime`. |
82 | | `framesPerFoot` | Number | Optional. Specifies the number of frames in one foot of film. Defaults to `16` (the most common rate for 35mm footage). |
83 | | `isDuration` | Boolean | Optional. Whether `t` represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to `false`. |
84 |
85 | #### Returns
86 |
87 | String
88 |
89 | ---
90 |
91 | ### timeToFrames()
92 |
93 | `timeToFrames([t=time + thisComp.displayStartTime][, fps=1.0 / thisComp.frameDuration][, isDuration=false])`
94 |
95 | #### Description
96 |
97 | Converts the value of `t` (some amount of time, in seconds) to an integer number of frames.
98 |
99 | #### Parameters
100 |
101 | | Parameter | Type | Description |
102 | | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
103 | | `t` | Number | Optional. The time (in seconds) to convert. Defaults to `time + thisComp.displayStartTime`. |
104 | | `fps` | Number | Optional. The number of frames per second to use to convert. Defaults to `1.0 / thisComp.frameDuration` (the frame rate of the current composition). |
105 | | `isDuration` | Boolean | Optional. Whether `t` represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to `false`. |
106 |
107 | #### Returns
108 |
109 | Number
110 |
111 | ---
112 |
113 | ### timeToNTSCTimecode()
114 |
115 | `timeToNTSCTimecode([t=time + thisComp.displayStartTime][, ntscDropFrame=false][, isDuration=false])`
116 |
117 | #### Description
118 |
119 | Converts `t` to a String representing NTSC timecode.
120 |
121 | #### Parameters
122 |
123 | | Parameter | Type | Description |
124 | | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125 | | `t` | Number | Optional. The time (in seconds) to convert. Defaults to `time + thisComp.displayStartTime`. |
126 | | `ntscDropFrame` | Boolean | Optional. If `false`, the result is NTSC non-drop-frame timecode. If `true`, the result is NTSC drop-frame timecode. Defaults to `false`. |
127 | | `isDuration` | Boolean | Optional. Whether `t` represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to `false`. |
128 |
129 | #### Returns
130 |
131 | String
132 |
133 | ---
134 |
135 | ### timeToTimecode()
136 |
137 | `timeToTimecode([t=time + thisComp.displayStartTime][, timecodeBase=30][, isDuration=false])`
138 |
139 | #### Description
140 |
141 | Converts the value of `t` to a String representing timecode.
142 |
143 | #### Parameters
144 |
145 | | Parameter | Type | Description |
146 | | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
147 | | `t` | Number | Optional. The time (in seconds) to convert. Defaults to `time + thisComp.displayStartTime`. |
148 | | `timecodeBase` | Number | Optional. Specifies the number of frames in one second. Defaults to `30`. |
149 | | `isDuration` | Boolean | Optional. Whether `t` represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to `false`. |
150 |
151 | #### Returns
152 |
153 | String
154 |
--------------------------------------------------------------------------------
/docs/general/vector-math.md:
--------------------------------------------------------------------------------
1 | # Vector Math
2 |
3 | Vector Math functions are global methods that perform operations on arrays, treating them as mathematical vectors.
4 |
5 | Unless otherwise specified, Vector Math methods are lenient about dimensions and return a value that is the dimension of the largest input Array object, filling in missing elements with zeros.
6 |
7 | Unlike built-in JavaScript methods, such as `Math.sin`, these methods are not used with the `Math` prefix.
8 |
9 | #### Example
10 |
11 | This expression returns `[11, 22, 3]`:
12 |
13 | ```js
14 | add([10, 20], [1, 2, 3])
15 | ```
16 |
17 | ---
18 |
19 | ## Methods
20 |
21 | ### add()
22 |
23 | `add(vec1, vec2)`
24 |
25 | #### Description
26 |
27 | Adds two vectors.
28 |
29 | #### Parameters
30 |
31 | | Parameter | Type | Description |
32 | | --------- | ----- | --------------------- |
33 | | `vec1` | Array | First vector to add. |
34 | | `vec2` | Array | Second vector to add. |
35 |
36 | #### Returns
37 |
38 | Array
39 |
40 | ---
41 |
42 | ### clamp()
43 |
44 | `clamp(value, limit1, limit2)`
45 |
46 | #### Description
47 |
48 | The value of each component of `value` is constrained to fall between the values of the corresponding values of `limit1` and `limit2`.
49 |
50 | #### Parameters
51 |
52 | | Parameter | Type | Description |
53 | | --------- | --------------- | ----------------------------------- |
54 | | `value` | Number or Array | Value to clamp. |
55 | | `limit1` | Number or Array | Minimum amount to clamp `value` to. |
56 | | `limit2` | Number or Array | Maximum amount to clamp `value` to. |
57 |
58 | #### Returns
59 |
60 | Number or Array
61 |
62 | #### Example
63 |
64 | Ensure that a wiggled amount never exceeds the 0-100 range:
65 |
66 | ```js
67 | const wiggled = wiggle(0.5, 500);
68 | clamp(wiggled, 0, 500);
69 | ```
70 |
71 | ---
72 |
73 | ### cross()
74 |
75 | `cross(vec1, vec2)`
76 |
77 | #### Description
78 |
79 | Returns the vector cross product of `vec1` and `vec2`.
80 |
81 | Refer to a math reference or JavaScript guide for more information.
82 |
83 | #### Parameters
84 |
85 | | Parameter | Type | Description |
86 | | --------- | --------------------------- | -------------------------------------------- |
87 | | `vec1` | Array (2- or 3-dimensional) | First vector to calculate cross product of. |
88 | | `vec2` | Array (2- or 3-dimensional) | Second vector to calculate cross product of. |
89 |
90 | #### Returns
91 |
92 | Array (2- or 3-dimensional)
93 |
94 | ---
95 |
96 | ### div()
97 |
98 | `div(vec, amount)`
99 |
100 | #### Description
101 |
102 | Divides every element of the vector by the amount.
103 |
104 | #### Parameters
105 |
106 | | Parameter | Type | Description |
107 | | --------- | ------ | ----------------------- |
108 | | `vec` | Array | The vector to divide |
109 | | `amount` | Number | The amount to divide by |
110 |
111 | #### Returns
112 |
113 | Array
114 |
115 | ---
116 |
117 | ### dot()
118 |
119 | `dot(vec1, vec2)`
120 |
121 | #### Description
122 |
123 | Returns the dot (inner) product of the vector arguments.
124 |
125 | #### Parameters
126 |
127 | | Parameter | Type | Description |
128 | | --------- | ----- | ------------------------------------------ |
129 | | `vec1` | Array | First vector to calculate dot product of. |
130 | | `vec2` | Array | Second vector to calculate dot product of. |
131 |
132 | #### Returns
133 |
134 | Number
135 |
136 | ---
137 |
138 | ### length()
139 |
140 | `length(vec[, point2])`
141 |
142 | #### Description
143 |
144 | Returns the length of vector `vec`.
145 |
146 | If a second argument is provided, instead treats the first argument as a point and returns the distance between the two points.
147 |
148 | !!! tip
149 | Using `length()` with two arguments is the same as `length(sub(vec, point2))`.
150 |
151 | #### Parameters
152 |
153 | | Parameter | Type | Description |
154 | | --------- | ----- | ------------------------------------------------------------ |
155 | | `vec` | Array | The vector to normalize, or the first point to measure from. |
156 | | `point2` | Array | Optional. The second point to measure to. |
157 |
158 | #### Returns
159 |
160 | Number
161 |
162 | #### Example
163 |
164 | For example, add this expression to the Focus Distance property of a camera to lock the focal plane to the camera's point of interest so that the point of interest is in focus:
165 |
166 | ```js
167 | length(position, pointOfInterest)
168 | ```
169 |
170 | ---
171 |
172 | ### lookAt()
173 |
174 | `lookAt(fromPoint, atPoint)`
175 |
176 | #### Description
177 |
178 | Orients a layer to look at a given point, from a given point.
179 |
180 | The return value can be used as an expression for the Orientation property, making the z-axis of the layer point at atPoint.
181 |
182 | This method is especially useful for cameras and lights.
183 |
184 | !!! tip
185 | If you use this expression on a camera, turn off auto-orientation.
186 |
187 | #### Parameters
188 |
189 | | Parameter | Type | Description |
190 | | ----------- | --------------------- | ---------------------------------------------------------- |
191 | | `fromPoint` | Array (3-dimensional) | The location (in world space) of the layer to orient. |
192 | | `atPoint` | Array (3-dimensional) | The point (in world space) you want to point the layer at. |
193 |
194 | #### Returns
195 |
196 | Array (3-dimensional)
197 |
198 | #### Example
199 |
200 | This expression on the Orientation property of a spot light makes the light point at the anchor point of layer number 1 in the same composition:
201 |
202 | ```js
203 | lookAt(position, thisComp.layer(1).position)
204 | ```
205 |
206 | ---
207 |
208 | ### mul()
209 |
210 | `mul(vec, amount)`
211 |
212 | #### Description
213 |
214 | Multiplies every element of the vector by the amount.
215 |
216 | #### Parameters
217 |
218 | | Parameter | Type | Description |
219 | | --------- | ------ | ------------------------- |
220 | | `vec` | Array | The vector to multiply |
221 | | `amount` | Number | The amount to multiply by |
222 |
223 | #### Returns
224 |
225 | Array
226 |
227 | ---
228 |
229 | ### normalize()
230 |
231 | `normalize(vec)`
232 |
233 | #### Description
234 |
235 | Normalizes the vector so that its length is `1.0`.
236 |
237 | Using the normalize method is a short way of performing the operation `div(vec, length(vec))`.
238 |
239 | #### Parameters
240 |
241 | | Parameter | Type | Description |
242 | | --------- | ----- | ----------------------- |
243 | | `vec` | Array | The vector to normalize |
244 |
245 | #### Returns
246 |
247 | Array
248 |
249 | ---
250 |
251 | ### sub()
252 |
253 | `sub(vec1, vec2)`
254 |
255 | #### Description
256 |
257 | Subtracts two vectors.
258 |
259 | #### Parameters
260 |
261 | | Parameter | Type | Description |
262 | | --------- | ----- | ----------------- |
263 | | `vec1` | Array | The first vector |
264 | | `vec2` | Array | The second vector |
265 |
266 | #### Returns
267 |
268 | Array
269 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | Use the After Effects expression elements along with standard JavaScript elements to write your expressions. You can use the Expression Language menu at any time to insert methods and attributes into an expression, and you can use the pick whip at any time to insert properties.
4 |
5 | - For resources on how to get started with expressions, see [Resources](./introduction/resources.md).
6 | - For some broad examples, see [Examples](./introduction/examples.md).
7 | - For info on changes to the expression engine over the years, see [Changelog](./introduction/changelog.md).
8 |
9 | ---
10 |
11 | ## Navigating the docs
12 |
13 | Within each page, you'll see categories for each logical group of pages, and then specific pages within each category.
14 |
15 | When you open a page, you'll be presented with:
16 |
17 | - A brief introduction to that topic ("This is what the page is about")
18 | - Headers for **Attributes** and **Methods**
19 | - **Attributes** are accessible bits of information:
20 | - `thisComp.name` gets the name of the comp!
21 | - `text.sourceText.fontSize` gets the font size of the text
22 | - **Methods** are functions that you run, to either get some other info or generate a result:
23 | - `thisComp.layer("Banana")` retrieves a layer called Banana, or
24 | - `text.sourceText.setFontSize(123)` will set the font size to 123
25 | - A list of each expression method or attribute alphabetically sorted under its header, which includes:
26 | - The name of the item
27 | - At least one way of how to access it from an expression (ie if you want to use the "TextStyle.font" item, you access it via `text.sourceText.style.font`)
28 | - A brief description on what the item does & how it works
29 | - The **type** of info an attribute provides, or the type of info a method **returns**(1)
30 | { .annotate }
31 | 1. Some return-value descriptions include a number in square brackets—this number specifies the dimension of the returned property or Array.
32 |
33 | If a specific dimension is not included, the dimension of the returned Array depends on the dimension of the input.
34 |
35 | - *(Methods only)* A list of all arguments/parameters needed to call the method, including optional arguments/parameters(1)
36 | { .annotate }
37 | 1. If an argument description contains an equal sign (`=`) and a value (such as `t=time` or `width=.2`), then the argument uses the included default value if you don't specify a different value.
38 |
39 | Some argument descriptions include a number in square brackets—this number indicates the dimension of the expected property or Array.
40 |
41 | - And, sometimes, an example showing how to use that item
42 |
43 | !!! tip
44 | The docs also include notes (where applicable) indicating any other warnings, bugs, issues, or tips that may apply to a given item. We've also tried to provide info on when an item was added into After Effects, so that you can ensure it'll work for your project.
45 |
46 | ---
47 |
48 | ## A Note on Sources
49 |
50 | Please note that the majority of this document is community-supported and community-generated by **volunteers** just trying to help out!
51 |
52 | While we're lucky enough to have some Adobe staff keeping these docs up-to-date with each version of After Effects, their time and energy is *also* being donated in a volunteer capacity.
53 |
54 | If you have any questions, comments, or concerns about anything in these docs – or if you'd like to contribute (no code experience necessary!), propose suggestions, or anything else – please reach out to the admins at [hi@docsforadobe.dev](mailto:hi@docsforadobe.dev).
55 |
--------------------------------------------------------------------------------
/docs/introduction/changelog.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | What's new and changed for expressions?
4 |
5 | ---
6 |
7 | ## [After Effects 25.0](https://helpx.adobe.com/after-effects/using/whats-new/2025.html) (October 2024)
8 |
9 | Added many new text style properties and methods for both characters and paragraphs, as well as the ability to control per-character styling through expressions.
10 |
11 | - New attributes of .sourceText:
12 | - Added: [SourceText.isPointText](../text/sourcetext.md#sourcetextispointtext)
13 | - Added: [SourceText.isParagraphText](../text/sourcetext.md#sourcetextisparagraphtext)
14 | - Added: [SourceText.isHorizontalText](../text/sourcetext.md#sourcetextishorizontaltext)
15 | - Added: [SourceText.isVerticalText](../text/sourcetext.md#sourcetextisverticaltext)
16 | - New per-character style properties and methods:
17 | - Added: [TextStyle.replaceText()](../text/style.md#textstylereplacetext)
18 | - Added: [TextStyle.baselineDirection](../text/style.md#textstylebaselinedirection)
19 | - Added: [TextStyle.setBaselineDirection()](../text/style.md#textstylesetbaselinedirection)
20 | - Added: [TextStyle.baselineOption](../text/style.md#textstylebaselineoption)
21 | - Added: [TextStyle.setBaselineOption()](../text/style.md#textstylesetbaselineoption)
22 | - Added: [TextStyle.digitSet](../text/style.md#textstyledigitset)
23 | - Added: [TextStyle.setDigitSet()](../text/style.md#textstylesetdigitset)
24 | - Added: [TextStyle.isLigature](../text/style.md#textstyleisligature)
25 | - Added: [TextStyle.setLigature()](../text/style.md#textstylesetligature)
26 | - Added: [TextStyle.tsume](../text/style.md#textstyletsume)
27 | - Added: [TextStyle.setTsume()](../text/style.md#textstylesettsume)
28 | - Added: [TextStyle.verticalScaling](../text/style.md#textstyleverticalscaling)
29 | - Added: [TextStyle.setVerticalScaling()](../text/style.md#textstylesetverticalscaling)
30 | - Added: [TextStyle.horizontalScaling](../text/style.md#textstylehorizontalscaling)
31 | - Added: [TextStyle.setHorizontalScaling()](../text/style.md#textstylesethorizontalscaling)
32 | - Added: [TextStyle.lineJoin](../text/style.md#textstylelinejoin)
33 | - Added: [TextStyle.setLineJoin()](../text/style.md#textstylesetlinejoin)
34 | - New paragraph style properties and methods:
35 | - Added: [TextStyle.direction](../text/style.md#textstyledirection)
36 | - Added: [TextStyle.setDirection()](../text/style.md#textstylesetdirection)
37 | - Added: [TextStyle.isEveryLineComposer](../text/style.md#textstyleiseverylinecomposer)
38 | - Added: [TextStyle.setEveryLineComposer()](../text/style.md#textstyleseteverylinecomposer)
39 | - Added: [TextStyle.firstLineIndent](../text/style.md#textstylefirstlineindent)
40 | - Added: [TextStyle.setFirstLineIndent()](../text/style.md#textstylesetfirstlineindent)
41 | - Added: [TextStyle.isHangingRoman](../text/style.md#textstyleishangingroman)
42 | - Added: [TextStyle.setHangingRoman()](../text/style.md#textstylesethangingroman)
43 | - Added: [TextStyle.justification](../text/style.md#textstylejustification)
44 | - Added: [TextStyle.setJustification()](../text/style.md#textstylesetjustification)
45 | - Added: [TextStyle.leadingType](../text/style.md#textstyleleadingtype)
46 | - Added: [TextStyle.setLeadingType()](../text/style.md#textstylesetleadingtype)
47 | - Added: [TextStyle.leftMargin](../text/style.md#textstyleleftmargin)
48 | - Added: [TextStyle.setLeftMargin()](../text/style.md#textstylesetleftmargin)
49 | - Added: [TextStyle.rightMargin](../text/style.md#textstylerightmargin)
50 | - Added: [TextStyle.setRightMargin()](../text/style.md#textstylesetrightmargin)
51 | - Added: [TextStyle.spaceAfter](../text/style.md#textstylespaceafter)
52 | - Added: [TextStyle.setSpaceAfter()](../text/style.md#textstylesetspaceafter)
53 | - Added: [TextStyle.spaceBefore](../text/style.md#textstylespacebefore)
54 | - Added: [TextStyle.setSpaceBefore()](../text/style.md#textstylesetspacebefore)
55 | - Existing style methods updated to allow per-character styles:
56 | - Changed: [TextStyle.setFontSize()](../text/style.md#textstylesetfontsize)
57 | - Changed: [TextStyle.setFont()](../text/style.md#textstylesetfont)
58 | - Changed: [TextStyle.setFauxBold()](../text/style.md#textstylesetfauxbold)
59 | - Changed: [TextStyle.setFauxItalic()](../text/style.md#textstylesetfauxitalic)
60 | - Changed: [TextStyle.setAllCaps()](../text/style.md#textstylesetallcaps)
61 | - Changed: [TextStyle.setSmallCaps()](../text/style.md#textstylesetsmallcaps)
62 | - Changed: [TextStyle.setTracking()](../text/style.md#textstylesettracking)
63 | - Changed: [TextStyle.setLeading()](../text/style.md#textstylesetleading)
64 | - Changed: [TextStyle.setAutoLeading()](../text/style.md#textstylesetautoleading)
65 | - Changed: [TextStyle.setBaselineShift()](../text/style.md#textstylesetbaselineshift)
66 | - Changed: [TextStyle.setApplyFill()](../text/style.md#textstylesetapplyfill)
67 | - Changed: [TextStyle.setFillColor()](../text/style.md#textstylesetfillcolor)
68 | - Changed: [TextStyle.setApplyStroke()](../text/style.md#textstylesetapplystroke)
69 | - Changed: [TextStyle.setStrokeColor()](../text/style.md#textstylesetstrokecolor)
70 | - Changed: [TextStyle.setStrokeWidth()](../text/style.md#textstylesetstrokewidth)
71 |
72 | ---
73 |
74 | ## [After Effects 17.7](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheFebruary2021releaseversion177) (Feb 2021)
75 |
76 | - Fixed: An issue where expression edits made in the Graph Editor were not applied consistently.
77 |
78 | ---
79 |
80 | ## [After Effects 17.6](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheJanuary2021releaseversion176) (Jan 2021)
81 |
82 | - Fixed: An issue that could cause an expression to be replaced instead of appending when using expression or property pick-whip.
83 |
84 | ---
85 |
86 | ## [After Effects 17.1.2](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheJuly2020releaseversion1712) (Jul 2020)
87 |
88 | - Fixed: An issue where Markers could not be referenced by name in the JavaScript Expressions Engine.
89 |
90 | ---
91 |
92 | ## [After Effects 17.1](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheMay2020releaseversion171) (May 19 2020)
93 |
94 | - Fixed: An issue with Expression editor to auto-complete 'timeToFrames' function.
95 |
96 | ---
97 |
98 | ## [After Effects 17.0.5](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheMarch2020releaseversion1705) (Mar 2020)
99 |
100 | - Fixed: An issue where the Link Focus to Layer command produced an expression that did not work with the JavaScript expression engine.
101 |
102 | ---
103 |
104 | ## [After Effects 17.0.2](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheJanuary2020releaseversion1702) (Jan 2020)
105 |
106 | - Fixed: An issue where wrong line numbers would be displayed related to errors in JavaScript expressions.
107 |
108 | ---
109 |
110 | ## [After Effects 17.0](https://helpx.adobe.com/after-effects/using/whats-new/2020.html) (Jan 24 2020)
111 |
112 | - Implemented Dropdown Menu Expression Control
113 | - Expression Editor improvements:
114 | - You can now use the new scrolling functionality to prevent the scroll from adjusting incorrectly when the box is resized by typing the return character.
115 | - Prevent numbers from matching in an autocomplete list if the variable begins with a number. Smarter autocomplete prevents from overriding closing brackets and quotes.
116 | - You can now scale font size for Hi-DPI displays.
117 | - Graph editor now commits changes in preferences for all the open graph editors.
118 | - If you enable syntax highlight, the folding icon buttons in the UI now respect the default and background color, or the line numbers color and background color.
119 | - Expression performance improvements:
120 | - After Effects now attempts to detect an expression that does not change throughout a comp and calculates the expression only once. Load your favorite expression-filled comp and experience the improved performance.
121 | - Any expression using [posterizeTime()](../general/global.md#posterizetime) now calculates only once for the entire comp, not on every frame.
122 | - Added: Extended expressions access to Text properties.
123 | - Added: [Text.Font...](../text/text.md#textfont)
124 | - Added: [Source Text](../text/sourcetext.md)
125 | - Added: [Text Style](../text/style.md)
126 |
127 | ---
128 |
129 | ## [After Effects 16.1.3](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheearlierversionsofAfterEffects) (Sep 2019)
130 |
131 | - Fixed: Indentation of curly braces on new lines could be incorrect in the Expressions editor.
132 |
133 | ---
134 |
135 | ## [After Effects 16.1.2](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheearlierversionsofAfterEffects) (June 2019)
136 |
137 | - Fixed: After Effects crashes when you close a project that has an expression containing an error.
138 | - Fixed: Expression error messages could be truncated in the error ribbon if there were multiple lines of error text to show.
139 | - Fixed: The property, this_Layer had stopped working when using the Legacy ExtendScript expression engine.
140 | - Fixed: Crash when switching the project level expression engine from JavaScript to Legacy ExtendScript.
141 | - Fixed: Crash with expressions that contain calls to Date.toLocaleString().
142 | - Fixed: Crash when editing expressions in the Graph Editor expression field when AutoComplete is disabled.
143 |
144 | ---
145 |
146 | ## [After Effects 16.1 (CC 19)](https://helpx.adobe.com/after-effects/kb/fixed-issues.html#BugsfixedintheearlierversionsofAfterEffects) (Apr 2 2019)
147 |
148 | - Implemented new expression editor
149 | - Fixed: The JavaScript expressions engine does not generate the same random number results as the Legacy ExtendScript engine.
150 | - Fixed: When an expression references the name of a layer in a string or in a Source Text property, the name of the layer is not returned. Instead, it returns [Object].
151 | - Fixed: The [sampleImage()](../layer/general.md#layersampleimage) expression method returns the wrong value if the post-expression value of the property is read by a ScriptUI panel.
152 | - Fixed: Applying the [createPath()](../objects/path-property.md#pathpropertycreatepath) expression via the Expression Language menu autofills the (is_Closed) parameter as deprecated snake case instead of camel caseisClosed.
153 | - Fixed: Renaming an effect that is referenced by an expression causes the expression to incorrectly update references to that effect properties when those properties have the same name as the effect.
154 | - Fixed: The Link Focus Distance to Layer, Link Focus Distance to Point of Interest, Create Stereo 3D Rig, and Create Orbit Null commands create expressions that are incompatible with the JavaScript expression engine.
155 | - Fixed: Specific complex, multi-composition expressions cause fast flickering of the expression error warning banner and icons. Note that to fix this, there is a small slowdown in expression evaluation speed for these expressions.
156 |
157 | ---
158 |
159 | ## [After Effects 16.0 (CC 19)](https://helpx.adobe.com/after-effects/using/whats-new/2019.html) (Oct 15 2018)
160 |
161 | - Implemented new Javascript engine
162 | - Added: [hexToRgb](../general/color-conversion.md#hextorgb)
163 | - Added: [marker protectedRegion](../objects/markerkey.md#markerkeyprotectedregion) property
164 |
165 | ---
166 |
167 | ## [After Effects 15.1.2](https://helpx.adobe.com/after-effects/kb/bug-fixes-in-after-effects-cc.html) (Jul 16 2018)
168 |
169 | - Fixed: If your project contains multiple master properties by the same name, the expressions that refer to the master properties evaluate incorrectly.
170 | - Fixed: The Property Link pick whip incorrectly writes a self-referential expression for the other selected properties.
171 |
172 | ---
173 |
174 | ## [After Effects 15.1](https://helpx.adobe.com/after-effects/using/whats-new/2018.html#AfterEffectsCCApril2018version151release) (Apr 3 2018)
175 |
176 | - Added: Property Link pick whip
177 | - Added: Support for custom expression function libraries
178 | - Added: Expression access to [Project](../objects/project.md)
179 | - Added: [Project.fullPath](../objects/project.md#projectfullpath)
180 | - Added: [Project.bitsPerChannel](../objects/project.md#projectbitsperchannel)
181 | - Added: [Project.linearBlending](../objects/project.md#projectlinearblending)
182 |
183 | ---
184 |
185 | ## [After Effects 15.0 (CC)](https://community.adobe.com/t5/after-effects/expression-and-scripting-improvements-in-after-effects-october-2017-pdf/td-p/4787866) (Oct 18 2017)
186 |
187 | - Added: Expression access to data in JSON files
188 | - Added: [footage sourceText](../objects/footage.md#footagesourcetext) attribute
189 | - Added: [footage sourceData](../objects/footage.md#footagesourcedata) attribute
190 | - Added: [footage dataValue](../objects/footage.md#footagedatavalue) method
191 | - Added: [footage dataKeyCount](../objects/footage.md#footagedatakeycount) method
192 | - Added: [footage dataKeyTimes](../objects/footage.md#footagedatakeytimes) method
193 | - Added: [footage dataKeyValues](../objects/footage.md#footagedatakeyvalues) method
194 | - Added: Expression access to path points on masks, Bezier shapes, and brush strokes
195 | - Added: [path points](../objects/path-property.md#pathpropertypoints) method
196 | - Added: [path inTangents](../objects/path-property.md#pathpropertyintangents) method
197 | - Added: [path outTangents](../objects/path-property.md#pathpropertyouttangents) method
198 | - Added: [path isClosed](../objects/path-property.md#pathpropertyisclosed) method
199 | - Added: [path pointOnPath](../objects/path-property.md#pathpropertypointonpath) method
200 | - Added: [path tangentOnPath](../objects/path-property.md#pathpropertytangentonpath) method
201 | - Added: [path normalOnPath](../objects/path-property.md#pathpropertynormalonpath) method
202 | - Added: [path createPath](../objects/path-property.md#pathpropertycreatepath) method
203 |
204 | ---
205 |
206 | ## [After Effects 13.6 (CC 2015)](https://helpx.adobe.com/after-effects/kb/ae-13-6.html) (Nov 30 2015)
207 |
208 | - Improved performance of expressions on time-remapped layers. This also reduces rendering time for audio on time-remapped layers with expressions.
209 | - Fixed: Changing the source text of a text layer no longer causes expressions to fail when the name of the text layer was referenced.
210 | - Fixed: After Effects no longer crashes when the graph editor is displayed while processing an time remapping expression.
211 |
212 | ---
213 |
214 | ## [After Effects 13.5 (CC 2015)](https://helpx.adobe.com/after-effects/kb/what-s-new-and-changed-in-after-effects-cc-2015--13-5-.html) (Jun 15 2015)
215 |
216 | - More efficient expression evaluation
217 | - Added: Expression warning banner
218 |
219 | ---
220 |
221 | ## [After Effects 13.2 (CC 2014.2)](https://helpx.adobe.com/ca/after-effects/using/whats-new-2014.html) (Dec 16 2014)
222 |
223 | - Added: [sourceRectAtTime()](../layer/sub-objects.md#layersourcerectattime) method
224 | - Fixed: [sampleImage()](../layer/general.md#layersampleimage) in an expression no longer disables multiprocessing
225 |
226 | ---
227 |
228 | ## [After Effects 12.1 (CC)](https://helpx.adobe.com/after-effects/using/whats-new-12-1.html/) (Sep 8 2013)
229 |
230 | - Added iris and highlight properties for camera layers to the expression language menu
231 | - - Added: [Camera.irisShape](../objects/camera.md#camerairisshape)
232 | - Added: [Camera.irisRotation](../objects/camera.md#camerairisrotation)
233 | - Added: [Camera.irisRoundness](../objects/camera.md#camerairisroundness)
234 | - Added: [Camera.irisAspectRatio](../objects/camera.md#camerairisaspectratio)
235 | - Added: [Camera.irisDiffractionFringe](../objects/camera.md#camerairisdiffractionfringe)
236 | - Added: [Camera.highlightGain](../objects/camera.md#camerahighlightgain)
237 | - Added: [Camera.highlightThreshold](../objects/camera.md#camerahighlightthreshold)
238 | - Added: [Camera.highlightSaturation](../objects/camera.md#camerahighlightsaturation)
239 |
240 | ---
241 |
242 | ## [After Effects 10.5 (CS5.5)](https://helpx.adobe.com/ro/after-effects/user-guide.html/ro/after-effects/using/expression-language-reference.ug.html/) (Apr 11 2011)
243 |
244 | - Added: [Footage.ntscDropFrame](../objects/footage.md#footagentscdropframe)
245 | - Added: ntscDropFrame argument to [timeToCurrentFormat()](../general/time-conversion.md#timetocurrentformat)
246 | - Added: [Layer.sourceTime()](../layer/sub-objects.md#layersourcetime)
247 |
248 | ---
249 |
250 | ## [After Effects 5.5](https://en.wikipedia.org/wiki/Adobe_After_Effects#History/) (Jan 7 2002)
251 |
252 | - Added: Looping via expressions
253 | - Added: Expression controllers
254 |
255 | ---
256 |
257 | ## [After Effects 5.0](https://en.wikipedia.org/wiki/Adobe_After_Effects#History/) (Apr 2001)
258 |
259 | - Expressions first added
260 |
--------------------------------------------------------------------------------
/docs/introduction/examples.md:
--------------------------------------------------------------------------------
1 | # Examples
2 |
3 | !!! note
4 | Many of the examples in this section are based on expressions provided by Dan Ebberts.
5 |
6 | ---
7 |
8 | ## Get this project's AEP name (AE 15.1+ only)
9 |
10 | While there is no method to directly access your AEP's name, you CAN get the full path to the AEP.
11 |
12 | With some string manipulation, you can derive the aep name from this:
13 |
14 | ```js
15 | var aepName = thisProject.fullPath.split($.os.indexOf("Windows") > -1 ? "\\" : "/").pop();
16 | ```
17 |
18 | If you wanted to write "Unsaved" in that case, you can use the following expression:
19 |
20 | ```js
21 | var aepName = thisProject.fullPath.split($.os.indexOf("Windows") > -1 ? "\\" : "/").pop();
22 | aepName = aepName === "" ? "Unsaved" : aepName;
23 | ```
24 |
25 | ---
26 |
27 | ## Make a layer revolve in a circle
28 |
29 | You can create an expression without using properties from other layers. For example, you can make a layer revolve in a perfect circle.
30 |
31 | 1. Select a layer, press P to reveal its Position property in the Timeline panel, and Alt-click (Windows) or Option-click (Mac OS) the stopwatch to the left of the property name.
32 | 2. Enter the following in the expression field:
33 | ```js
34 | [(thisComp.width/2), (thisComp.height/2)] + [Math.sin(time)*50, -Math.cos(time)*50]
35 | ```
36 |
37 | ---
38 |
39 | ## Rotate the hands of a clock
40 |
41 | You can use the pick whip to link rotation values between layers to animate the hands on a clock—as the hour hand moves from hour to hour, the minute hand rotates the full circumference of the clock face. This type of animation would take a long time to create if you had to set each keyframe for both hand layers, but with the pick whip, you can do it in a matter of minutes.
42 |
43 | 1. Import or create two long, narrow solid-color layers: an hour hand and a minute hand.
44 | 2. Set the anchor points at the ends of the layers.
45 | 3. Move the layers so that the anchor points are at the center of the composition.
46 | 4. Set Rotation keyframes for the hour hand.
47 | 5. Select the Rotation property for the minute hand and choose `Animation > Add Expression.`
48 | 6. Drag the pick whip to the Rotation property for the hour hand. The following expression appears:
49 | ```js
50 | thisComp.layer("hour hand").rotation
51 | ```
52 | 7. To make the minute hand rotate 12 times as fast as the hour hand, add `* 12` at the end of the expression as follows:
53 | ```js
54 | thisComp.layer("hour hand").rotation * 12
55 | ```
56 |
57 | ---
58 |
59 | ## Position one layer between two others
60 |
61 | This example expression positions and maintains one layer at a balanced distance between two other layers.
62 |
63 | 1. Start with three layers.
64 | 2. Animate the positions of the first two layers in the Timeline panel.
65 | 3. Select the third layer, press P to reveal the Position property, and Alt-click (Windows) or Option-click (Mac OS) the stopwatch button to the left of the property name.
66 | 4. Enter the following in the expression field:
67 | ```js
68 | (thisComp.layer(1).position + thisComp.layer(2).position)/2
69 | ```
70 |
71 | ---
72 |
73 | ## Create a trail of images
74 |
75 | This example expression instructs a layer to be at the same position as the next higher layer in the Timeline panel, but delayed by a specified amount of time (in this case, 0.5 seconds). You can set similar expressions for the other geometric properties.
76 |
77 | 1. Start with two solid-color layers that are scaled to approximately 30% of the composition size. (See Solid-color layers and solid-color footage items.)
78 | 2. Animate the position of the first layer.
79 | 3. Select the second layer, press P to reveal the Position property, and Alt-click (Windows) or Option-click (Mac OS) the stopwatch button to the left of the property name.
80 | 4. Enter the following in the expression field:
81 | ```js
82 | thisComp.layer(thisLayer, -1).position.valueAtTime(time - .5)
83 | ```
84 | 5. Duplicate the last layer five times by selecting it and pressing Ctrl+D (Windows) or Command+D (Mac OS) five times.
85 |
86 | All layers follow the same path, and each is delayed 0.5 seconds from the previous.
87 |
88 | !!! note
89 | Dan Ebberts provides more examples and techniques for creating trails of images on his [MotionScript](http://www.motionscript.com/mastering-expressions/follow-the-leader.html).
90 |
91 | ---
92 |
93 | ## Create a bulge between two layers
94 |
95 | This example expression synchronizes the Bulge Center argument of the Bulge effect in one layer with the position of another layer. For example, you can create an effect that looks like a magnifying glass moving over a layer, with the contents under the magnifying glass bulging as the lens (that is, the overlying layer) moves. This expression uses the fromWorld method, which makes the expression work correctly regardless of whether you move the magnifying glass layer or the underlying layer. You can rotate or scale the underlying layer, and the expression stays intact.
96 |
97 | You can also use other effects, such as Ripple, with this expression.
98 |
99 | 1. Start with two layers. Make one layer a magnifying glass or similar object with a hole in the middle and name it Magnifier. (See Creating layers.)
100 | 2. Animate the position of the magnifying glass layer. (See Motion paths.)
101 | 3. Apply the Bulge effect to the other layer. (See Apply an effect or animation preset.)
102 | 4. Select the Bulge Center property of the Bulge effect in the Timeline panel and choose Animation > Add Expression, or Alt-click (Windows) or Option-click (Mac OS) the stopwatch button for the property.
103 | 5. Select the default expression text and type the following:
104 | ```js
105 | fromWorld(thisComp.layer("Magnifier").position)
106 | ```
107 |
108 | ---
109 |
110 | ## Fade opacity of a 3D layer based on distance from camera
111 |
112 | Apply the following expression to the Opacity property of a 3D layer:
113 |
114 | ```js
115 | startFade = 500; // Start fade 500 pixels from camera.
116 | endFade = 1500; // End fade 1500 pixels from camera.
117 |
118 | try { // Check whether there's a camera
119 | C = thisComp.activeCamera.toWorld([0,0,0]);
120 | } catch (err) { // No camera, so assume 50mm
121 | w = thisComp.width * thisComp.pixelAspect;
122 | z = (w/2)/Math.tan(degreesToRadians(19.799));
123 | C = [0,0,-z];
124 | }
125 |
126 | P = toWorld(anchorPoint);
127 | d = length(C,P);
128 |
129 | linear(d,startFade,endFade,100,0)
130 | ```
131 |
132 | The fade starts at a distance of `500` pixels from the camera and is complete at `1500` pixels from the camera. The linear interpolation method is used to map distance values to opacity values.
133 |
134 | ---
135 |
136 | ## Make a 3D layer invisible if facing away from camera
137 |
138 | Apply the following expression to the Opacity property of a 3D layer:
139 |
140 | ```js
141 | if (toCompVec([0, 0, 1])[2] > 0 ) value else 0
142 | ```
143 |
144 | !!! note
145 | Dan Ebberts explains this expression on his [site](http://www.adobe.com/go/learn_ae_motionscriptinvisiblelayer).
146 |
147 | ---
148 |
149 | ## Flip layer horizontally if facing away from camera
150 |
151 | Apply the following expression to the Scale property of a 3D layer:
152 |
153 | ```js
154 | if (toCompVec([0, 0, 1])[2] > 0 ) value else [-value[0], value[1], value[2]]
155 | ```
156 |
157 | ---
158 |
159 | ## Animate scale at each layer marker
160 |
161 | Apply the following expression to a Scale property to make a layer wobble at each marker:
162 |
163 | ```js
164 | n = 0;
165 | t = 0;
166 |
167 | if (marker.numKeys > 0){
168 | n = marker.nearestKey(time).index;
169 | if (marker.key(n).time > time) n--;
170 | }
171 |
172 | if (n > 0) t = time - marker.key(n).time;
173 |
174 | amp = 15;
175 | freq = 5;
176 | decay = 3.0;
177 |
178 | angle = freq * 2 * Math.PI * t;
179 | scaleFact = (100 + amp * Math.sin(angle) / Math.exp(decay * t)) / 100;
180 | [value[0] * scaleFact, value[1] / scaleFact];
181 | ```
182 |
183 | ---
184 |
185 | ## Start or stop wiggle at specific time
186 |
187 | You can use any expression in place of the wiggle expression used here, to begin and end the influence of any expression at a specific time.
188 |
189 | Apply the following expression to a property to wiggle it beginning at time 2 seconds:
190 |
191 | ```js
192 | timeToStart = 2;
193 | if (time > timeToStart) {
194 | wiggle(3,25);
195 | } else {
196 | value;
197 | }
198 | ```
199 |
200 | Apply the following expression to a property to stop wiggling it at time 4 seconds:
201 |
202 | ```js
203 | timeToStop = 4;
204 |
205 | if (time > timeToStop) {
206 | value;
207 | } else {
208 | wiggle(3,25);
209 | }
210 | ```
211 |
212 | Apply the following expression to a property to start wiggling it at time 2 seconds and stop wiggling it at time 4 seconds:
213 |
214 | ```js
215 | timeToStart = 2;
216 | timeToStop = 4;
217 |
218 | if ((time > timeToStart) && (time < timeToStop)) {
219 | wiggle(3,25);
220 | } else {
221 | value;
222 | }
223 | ```
224 |
225 | ---
226 |
227 | ## Match camera focal plane to another layer
228 |
229 | Apply the following expression to the Focus Distance property of a camera layer to have its focus distance match the distance to the anchor point of a layer named "target":
230 |
231 | ```js
232 | target = thisComp.layer("target");
233 | V1 = target.toWorld(target.anchorPoint) - toWorld([0,0,0]);
234 | V2 = toWorldVec([0,0,1]);
235 | dot(V1,V2);
236 | ```
237 |
238 | !!! note
239 | Dan Ebberts explains this expression example in detail on his [website](http://motionscript.com/design-guide/auto-focus.html).
240 |
--------------------------------------------------------------------------------
/docs/introduction/resources.md:
--------------------------------------------------------------------------------
1 | # Resources
2 |
3 | !!! note
4 | Have suggestions for new resources to add here? Please [reach out](mailto:hi@docsforadobe.dev)! Happy to add your site, book, training channel, etc.
5 |
6 | Dan Ebberts provides example expressions and tutorials for learning how to work with expressions on his [MotionScript website](https://www.motionscript.com). For example, Dan provides an excellent [page about collision detection](http://www.motionscript.com/design-guide/collision.html).
7 |
8 | The AE Enhancers forum provides many examples and much useful information about expressions, as well as scripts and animation presets. In [this post on the AE Enhancers forum](https://aenhancers.com/viewtopic.php?t=630), Paul Tuersley provides a tutorial and example project that show how to use expressions to animate several layers in a swarm.
9 |
10 | Rick Gerard provides an example on [Rick's site](https://hottek.net/2007/11/square-wheels.html) that demonstrates rolling a square object along a floor so that the sides stay in contact with the floor plane.
11 |
12 | Chris Zwar provides an example project on [chriszwar.com](http://chriszwar.com/wordpress/2008/11/imagegrids/) for automatically arranging still images or videos into a grid (like a video wall). You can easily adjust position and spacing with sliders that are connected to a system of expressions. There are three compositions in the project—one for stills, one for videos, and one to create an auto-storyboard in which a video is sampled at user-defined intervals and aligned into a grid.
13 |
14 | [JJ Gifford's website](http://www.jjgifford.com/expressions/) provides several example projects that demonstrate how to use expressions.
15 |
--------------------------------------------------------------------------------
/docs/layer/general.md:
--------------------------------------------------------------------------------
1 | # Layer General
2 |
3 | `thisLayer`
4 |
5 | !!! info
6 | On this page, we're going to use `thisLayer` as a sample on how to call these items, however note that any method that returns a [Layer](./layer.md) will work.
7 |
8 | ---
9 |
10 | ## Attributes
11 |
12 | ### Layer.active
13 |
14 | `thisLayer.active`
15 |
16 | #### Description
17 |
18 | Returns `true` if the Video switch is on for the layer and the current time is in the range from the In point of the layer to the Out point of the layer; `false` otherwise.
19 |
20 | #### Type
21 |
22 | Boolean
23 |
24 | ---
25 |
26 | ### Layer.audioActive
27 |
28 | `thisLayer.audioActive`
29 |
30 | #### Description
31 |
32 | Returns `true` if the Audio switch is on for the layer and the current time is in the range from the In point of the layer to the Out point of the layer; `false` otherwise.
33 |
34 | #### Type
35 |
36 | Boolean
37 |
38 | ---
39 |
40 | ### Layer.enabled
41 |
42 | `thisLayer.enabled`
43 |
44 | #### Description
45 |
46 | Whether the layer is enabled.
47 |
48 | #### Type
49 |
50 | Boolean. `true` if the Video switch is on for the layer; `false` otherwise.
51 |
52 | ---
53 |
54 | ### Layer.hasAudio
55 |
56 | `thisLayer.hasAudio`
57 |
58 | #### Description
59 |
60 | Whether the layer has audio.
61 |
62 | #### Type
63 |
64 | Boolean. `true` if the layer has audio or `false` if it doesn't.
65 |
66 | ---
67 |
68 | ### Layer.hasParent
69 |
70 | `thisLayer.hasParent`
71 |
72 | #### Description
73 |
74 | Use the `hasParent` attribute to determine if a layer has a parent layer. You can use this attribute even if the layer has no parent layer at present.
75 |
76 | #### Type
77 |
78 | Boolean. `true` if the layer has a parent, `false` if it doesn't.
79 |
80 | #### Example
81 |
82 | The following expression indicates that the layer to which you apply it wiggles based on the position of the parent. If the layer has no parent, then it wiggles based on its own position.
83 |
84 | If the layer is given a parent later, then the behavior of the layer changes accordingly:
85 |
86 | ```js
87 | idx = index;
88 | if (hasParent) {
89 | idx = parent.index;
90 | }
91 | thisComp.layer(idx).position.wiggle(5,20)
92 | ```
93 |
94 | ---
95 |
96 | ### Layer.hasVideo
97 |
98 | `thisLayer.hasVideo`
99 |
100 | #### Description
101 |
102 | Whether the layer has video.
103 |
104 | #### Type
105 |
106 | Boolean. `true` if the layer has audio or `false` if it doesn't.
107 |
108 | ---
109 |
110 | ### Layer.height
111 |
112 | `thisLayer.height`
113 |
114 | #### Description
115 |
116 | Returns the height of the layer, in pixels.
117 |
118 | If the layer has a [source](./sub-objects.md#layersource), this is the same as either the source [comp height](../objects/comp.md#compheight) or the source [footage height](../objects/footage.md#footageheight) (as applicable).
119 |
120 | #### Type
121 |
122 | Number
123 |
124 | ---
125 |
126 | ### Layer.index
127 |
128 | `thisLayer.index`
129 |
130 | #### Description
131 |
132 | Returns the index number of the layer in the composition.
133 |
134 | #### Type
135 |
136 | Number
137 |
138 | ---
139 |
140 | ### Layer.inPoint
141 |
142 | `thisLayer.inPoint`
143 |
144 | #### Description
145 |
146 | Returns the In point of the layer, in seconds.
147 |
148 | !!! note
149 | In general, the value of outPoint is greater than the value of inPoint. However, if a layer is reversed in time, the value of inPoint is greater than the value of outPoint. Similarly, the value of startTime can be greater than the value of inPoint.
150 |
151 | #### Type
152 |
153 | Number
154 |
155 | ---
156 |
157 | ### Layer.outPoint
158 |
159 | `thisLayer.outPoint`
160 |
161 | #### Description
162 |
163 | Returns the Out point of the layer, in seconds.
164 |
165 | #### Type
166 |
167 | Number
168 |
169 | ---
170 |
171 | ### Layer.parent
172 |
173 | `thisLayer.parent`
174 |
175 | #### Description
176 |
177 | Returns the parent Layer object of the layer, if it has one.
178 |
179 | You can check whether a layer has a parent with the [`Layer.hasParent`](#layerhasparent) attribute.
180 |
181 | #### Type
182 |
183 | [Layer](../layer/layer.md), [Light](../objects/light.md), or [Camera](../objects/camera.md) object
184 |
185 | #### Example
186 |
187 | ```js
188 | position[0] + parent.width
189 | ```
190 |
191 | ---
192 |
193 | ### Layer.startTime
194 |
195 | `thisLayer.startTime`
196 |
197 | #### Description
198 |
199 | Returns the start time of the layer, in seconds.
200 |
201 | #### Type
202 |
203 | Number
204 |
205 | ---
206 |
207 | ### Layer.width
208 |
209 | `thisLayer.width`
210 |
211 | #### Description
212 |
213 | Returns the width of the layer, in pixels.
214 |
215 | If the layer has a [source](./sub-objects.md#layersource), this is the same as either the source [comp width](../objects/comp.md#compwidth) or the source [footage width](../objects/footage.md#footagewidth) (as applicable).
216 |
217 | #### Type
218 |
219 | Number
220 |
221 | ---
222 |
223 | ## Methods
224 |
225 | ### Layer.sampleImage()
226 |
227 | `thisLayer.sampleImage(point[, radius=[0.5, 0.5]][, postEffect=true][, t=time])`
228 |
229 | #### Description
230 |
231 | Samples the color and alpha channel values of a layer and returns the average alpha-weighted value of the pixels within the specified distance of the point as an array: `[red, green, blue, alpha]`.
232 |
233 | !!! note
234 | Using `sampleImage()` in an expression no longer disables multiprocessing.
235 |
236 | #### Parameters
237 |
238 | | Parameter | Type | Description |
239 | | ------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
240 | | `point` | 2-dimensional Number array | Required. The point at which to sample, im layer space. The point `[0, 0]` is the center of the upper-left pixel in the layer. |
241 | | `radius` | 2-dimensional Number array | Optional. Specifies the horizontal and vertical distance from the sample center to the edges of the sampled rectangle. The default value samples one pixel. Defaults to `[0.5, 0.5]`. |
242 | | `postEffect` | Boolean | Optional. If `true`, to sample the values *after* layer masks and effects **directly applied to the layer** have been rendered. If `false`, sample values *before* layer masks and effects. Defaults to `true`. |
243 | | `t` | Number | Optional. Defaults to `time`. |
244 |
245 |
246 | #### Type
247 |
248 | Array (4-dimensional)
249 |
250 | #### Examples
251 |
252 | This samples a rectangle 4 pixels wide and 3 pixels high, centered around a point 100 pixels down and to the right of the upper-left corner of the layer:
253 |
254 | ```js
255 | thisComp.layer(1).sampleImage([100, 100], [2, 1.5])
256 | ```
257 |
--------------------------------------------------------------------------------
/docs/layer/layer-space-transforms.md:
--------------------------------------------------------------------------------
1 | # Layer Space Transforms
2 |
3 | `thisLayer`
4 |
5 | Use layer space transform methods to transform values from one space to another, such as from layer space to world space.
6 |
7 | Composition (comp) and world space are the same for 2D layers. For 3D layers, however, composition space is relative to the active camera, and world space is independent of the camera.
8 |
9 | !!! info
10 | On this page, we're going to use `thisLayer` as a sample on how to call these items, however note that any method that returns a [Layer](./layer.md) will work.
11 |
12 | #### "From" & "To" Methods
13 |
14 | The `from` methods transform values from the named space (composition or world) to the layer space.
15 |
16 | The `to` methods transform values from the layer space to the named space (composition or world). Each transform method takes an optional argument to determine the time at which the transform is computed; however, you can almost always use the current (default) time.
17 |
18 | #### "Vec" Methods
19 |
20 | Use `Vec` transform methods when transforming a direction vector, such as the difference between two position values.
21 |
22 | Use the plain (non-`Vec`) transform methods when transforming a point, such as position.
23 |
24 | ---
25 |
26 | ## Methods
27 |
28 | ### toComp()
29 |
30 | `thisLayer.toComp(point[, t=time])`
31 |
32 | #### Description
33 |
34 | Transforms a point from layer space to composition space.
35 |
36 | #### Parameters
37 |
38 | | Parameter | Type | Description |
39 | | --------- | --------------------------- | ----------------------------------------------------------------------- |
40 | | `point` | Array (2- or 3-dimensional) | The point to convert |
41 | | `t` | Number | Optional. The time at which to sample the point at. Defaults to `time`. |
42 |
43 | #### Type
44 |
45 | Array (2- or 3-dimensional)
46 |
47 | ---
48 |
49 | ### fromComp()
50 |
51 | `thisLayer.fromComp(point[, t=time])`
52 |
53 | #### Description
54 |
55 | Transforms a point from composition space to layer space. The resulting point in a 3D layer may have a nonzero value even though it is in layer space.
56 |
57 | #### Parameters
58 |
59 | | Parameter | Type | Description |
60 | | --------- | --------------------------- | ----------------------------------------------------------------------- |
61 | | `point` | Array (2- or 3-dimensional) | The point to convert |
62 | | `t` | Number | Optional. The time at which to sample the point at. Defaults to `time`. |
63 |
64 | #### Type
65 |
66 | Array (2- or 3-dimensional)
67 |
68 | #### Example
69 |
70 | ```js
71 | fromComp(thisComp.layer(2).position)
72 | ```
73 |
74 | ---
75 |
76 | ### toWorld()
77 |
78 | `thisLayer.toWorld(point[, t=time])`
79 |
80 | #### Description
81 |
82 | Transforms a point from layer space to view-independent world space.
83 |
84 | !!! tip
85 | Dan Ebberts provides an expression on his [MotionScript website](http://www.motionscript.com/design-guide/auto-orient-y-only.html) that uses the `toWorld` method to auto-orient a layer along only one axis. This is useful, for example, for having characters turn from side to side to follow the camera while remaining upright.
86 |
87 | !!! tip
88 | Rich Young provides a set of expressions on his [AE Portal website](http://aeportal.blogspot.com/2010/02/fly-around-cc-sphered-layer-in-after.html) that use the toWorld method link a camera and light to a layer with the CC Sphere effect.
89 |
90 | #### Parameters
91 |
92 | | Parameter | Type | Description |
93 | | --------- | --------------------------- | ----------------------------------------------------------------------- |
94 | | `point` | Array (2- or 3-dimensional) | The point to convert |
95 | | `t` | Number | Optional. The time at which to sample the point at. Defaults to `time`. |
96 |
97 | #### Type
98 |
99 | Array (2- or 3-dimensional)
100 |
101 | #### Example
102 |
103 | ```js
104 | toWorld.effect("Bulge")("Bulge Center")
105 | ```
106 |
107 | ---
108 |
109 | ### fromWorld()
110 |
111 | `thisLayer.fromWorld(point[, t=time])`
112 |
113 | #### Description
114 |
115 | Transforms a point from world space to layer space.
116 |
117 | #### Parameters
118 |
119 | | Parameter | Type | Description |
120 | | --------- | --------------------------- | ----------------------------------------------------------------------- |
121 | | `point` | Array (2- or 3-dimensional) | The point to convert |
122 | | `t` | Number | Optional. The time at which to sample the point at. Defaults to `time`. |
123 |
124 | #### Type
125 |
126 | Array (2- or 3-dimensional)
127 |
128 | #### Example
129 |
130 | ```js
131 | fromWorld(thisComp.layer(2).position)
132 | ```
133 |
134 | ---
135 |
136 | ### toCompVec()
137 |
138 | `thisLayer.toCompVec(vec[, t=time])`
139 |
140 | #### Description
141 |
142 | Transforms a vector from layer space to composition space.
143 |
144 | #### Parameters
145 |
146 | | Parameter | Type | Description |
147 | | --------- | --------------------------- | ----------- |
148 | | `vec` | Array (2- or 3-dimensional) | |
149 | | `t` | Number | |
150 |
151 | #### Type
152 |
153 | Array (2- or 3-dimensional)
154 |
155 | #### Example
156 |
157 | ```js
158 | toCompVec([1, 0])
159 | ```
160 |
161 | ---
162 |
163 | ### fromCompVec()
164 |
165 | `thisLayer.fromCompVec(vec[, t=time])`
166 |
167 | #### Description
168 |
169 | Transforms a vector from composition space to layer space.
170 |
171 | #### Parameters
172 |
173 | | Parameter | Type | Description |
174 | | --------- | --------------------------- | ----------- |
175 | | `vec` | Array (2- or 3-dimensional) | |
176 | | `t` | Number | |
177 |
178 | #### Type
179 |
180 | Array (2- or 3-dimensional)
181 |
182 | #### Example:
183 |
184 | For a 2D layer:
185 |
186 | ```js
187 | const dir = sub(position, thisComp.layer(2).position);
188 | fromCompVec(dir)
189 | ```
190 |
191 | ---
192 |
193 | ### toWorldVec()
194 |
195 | `thisLayer.toWorldVec(vec[, t=time])`
196 |
197 | #### Description
198 |
199 | Transforms a vector from layer space to world space.
200 |
201 | #### Parameters
202 |
203 | | Parameter | Type | Description |
204 | | --------- | --------------------------- | ----------- |
205 | | `vec` | Array (2- or 3-dimensional) | |
206 | | `t` | Number | |
207 |
208 | #### Type
209 |
210 | Array (2- or 3-dimensional)
211 |
212 | #### Example
213 |
214 | Transform two different "Bulge Center" properties from the *layer space* of the layer the effect is applied to, to the *world space* of the comp the layers live in:
215 |
216 | ```js
217 | const p1 = effect("Eye Bulge 1")("Bulge Center");
218 | const p2 = effect("Eye Bulge 2")("Bulge Center");
219 |
220 | toWorld(sub(p1, p2))
221 | ```
222 |
223 | ---
224 |
225 | ### fromWorldVec()
226 |
227 | `thisLayer.fromWorldVec(vec[, t=time])`
228 |
229 | #### Description
230 |
231 | Transforms a vector from world space to layer space.
232 |
233 | #### Parameters
234 |
235 | | Parameter | Type | Description |
236 | | --------- | --------------------------- | ----------- |
237 | | `vec` | Array (2- or 3-dimensional) | |
238 | | `t` | Number | |
239 |
240 | #### Type
241 |
242 | Array (2- or 3-dimensional)
243 |
244 | #### Example
245 |
246 | Convert layer #2's position from world space to *this layer's* space:
247 |
248 | ```js
249 | fromWorld(thisComp.layer(2).position)
250 | ```
251 |
252 | ---
253 |
254 | ### fromCompToSurface()
255 |
256 | `thisLayer.fromCompToSurface(point[, t=time])`
257 |
258 | #### Description
259 |
260 | Projects a point located in composition space to a point on the surface of the layer (zero z-value) at the location where it appears when viewed from the active camera. This method is useful for setting effect control points.
261 |
262 | !!! note
263 | Use with 3D layers only.
264 |
265 | #### Parameters
266 |
267 | | Parameter | Type | Description |
268 | | --------- | --------------------------- | ----------------------------------------------------------------------- |
269 | | `point` | Array (2- or 3-dimensional) | The point to convert |
270 | | `t` | Number | Optional. The time at which to sample the point at. Defaults to `time`. |
271 |
272 | #### Type
273 |
274 | Array (2-dimensional)
275 |
--------------------------------------------------------------------------------
/docs/layer/layer.md:
--------------------------------------------------------------------------------
1 | # Layer
2 |
3 | As Layers are the foundation of most things in After Effects, this category is large and has been split into smaller pages for various focuses.
4 |
5 | These pages reflect the organization of the Expression fly-out menu within After Effects.
6 |
7 | !!! info
8 | Layer is the base class for [Camera](../objects/camera.md) and [Light](../objects/light.md), so Layer attributes and methods are available when working with those layer types (except when noted).
9 |
10 | Layer is also a subclass of [PropertyGroup](../objects/propertygroup.md), so all methods of PropertyGroup, in addition to those listed in the below pages, are available when working with Layer.
11 |
12 | Those categories are:
13 |
14 | - [Layer Sub-objects](./sub-objects.md) is for items that give you *other objects* based on the current layer; things like the source (for precomps or footage), effects, masks, sourceRect, etc.
15 | - [Layer General](./general.md) holds general info about the layer; width and height, whether the layer has audio or video, the layer's start and end points, etc. With few exceptions, typically *don't change* over the duration of the comp.
16 | - [Layer Properties](./properties.md) is generally for more dynamic properties; the layer's transform data (position, scale, rotation, etc), its audio or time remap, info about markers, and so on.
17 | - [Layer Space Transforms](./layer-space-transforms.md) contains info on how to convert values from one "space" to another, such as from layer space to world space.
18 | - [Layer 3D](./threed.md) is all about the 3d properties of layers. 3d rotation values, material properties, and more live here.
19 |
--------------------------------------------------------------------------------
/docs/layer/properties.md:
--------------------------------------------------------------------------------
1 | # Layer Properties
2 |
3 | `thisLayer`
4 |
5 | When you add masks, effects, paint, or text to a layer, After Effects adds new properties to the Timeline panel. There are too many of these properties to list here, so use the pick whip to learn the syntax for referring to them in your expressions.
6 |
7 | !!! info
8 | On this page, we're going to use `thisLayer` as a sample on how to call these items, however note that any method that returns a [Layer](./layer.md) will work.
9 |
10 | ---
11 |
12 | ## Attributes
13 |
14 | ### Layer.anchorPoint
15 |
16 | `thisLayer.anchorPoint`
17 |
18 | #### Description
19 |
20 | Returns the anchor point value of the layer in the coordinate system of the layer (layer space).
21 |
22 | #### Type
23 |
24 | Array of Numbers (2- or 3-dimensional)
25 |
26 | ---
27 |
28 | ### Layer.audioLevels
29 |
30 | `thisLayer.audioLevels`
31 |
32 | #### Description
33 |
34 | Returns the value of the Audio Levels property of the layer, in decibels. This value is a 2D value; the first value represents the left audio channel, and the second value represents the right. The value is not the amplitude of the audio track of the source material. Instead, it is the value of the Audio Levels property, which may be affected by keyframes.
35 |
36 | #### Type
37 |
38 | Array of Numbers (2-dimensional)
39 |
40 | ---
41 |
42 | ### Layer.marker
43 |
44 | `thisLayer.marker`
45 |
46 | #### Description
47 |
48 | Returns a given layer's [Marker](../objects/marker-property.md) property.
49 |
50 | #### Type
51 |
52 | [Marker Property](../objects/marker-property.md)
53 |
54 | ---
55 |
56 | ### Layer.name
57 |
58 | `thisLayer.name`
59 |
60 | #### Description
61 |
62 | Returns the name of the layer.
63 |
64 | #### Type
65 |
66 | String
67 |
68 | ---
69 |
70 | ### Layer.opacity
71 |
72 | `thisLayer.opacity`
73 |
74 | #### Description
75 |
76 | Returns the opacity value for the layer, expressed as a percentage.
77 |
78 | #### Type
79 |
80 | Number
81 |
82 | ---
83 |
84 | ### Layer.position
85 |
86 | `thisLayer.position`
87 |
88 | #### Description
89 |
90 | Returns the position value of the layer, in world space if the layer has no parent. If the layer has a parent, it returns the position value of the layer in the coordinate system of the parent layer (in the layer space of the parent layer).
91 |
92 | #### Type
93 |
94 | Array of Numbers (2- or 3-dimensional)
95 |
96 | ---
97 |
98 | ### Layer.rotation
99 |
100 | `thisLayer.rotation`
101 |
102 | #### Description
103 |
104 | Returns the rotation value of the layer in degrees. For a 3D layer, it returns the z rotation value in degrees.
105 |
106 | #### Type
107 |
108 | Number
109 |
110 | ---
111 |
112 | ### Layer.scale
113 |
114 | `thisLayer.scale`
115 |
116 | #### Description
117 |
118 | Returns the scale value of the layer, expressed as a percentage.
119 |
120 | #### Type
121 |
122 | Array of Numbers (2- or 3-dimensional)
123 |
124 | ---
125 |
126 | ---
127 |
128 | ### Layer.timeRemap
129 |
130 | `thisLayer.timeRemap`
131 |
132 | #### Description
133 |
134 | Returns the value of the Time Remap property, in seconds, if Time Remap is enabled.
135 |
136 | #### Type
137 |
138 | Number
139 |
--------------------------------------------------------------------------------
/docs/layer/sub-objects.md:
--------------------------------------------------------------------------------
1 | # Layer Sub-objects
2 |
3 | `thisLayer`
4 |
5 | This category describes items that give you *other objects* based on the current layer; things like the source (for precomps or footage), effects, masks, sourceRect, etc.
6 |
7 | !!! info
8 | On this page, we're going to use `thisLayer` as a sample on how to call these items, however note that any method that returns a [Layer](./layer.md) will work.
9 |
10 | !!! note
11 | For After Effects CC and CS6, the Expression language menu, the "Layer Sub-objects", "Layer General", "Layer Properties", "Layer 3D", and "Layer Space Transforms" have been arranged into a "Layer" submenu.
12 |
13 | ---
14 |
15 | ## Attributes
16 |
17 | ### Layer.source
18 |
19 | `thisLayer.source`
20 |
21 | #### Description
22 |
23 | Returns the source [Comp](../objects/comp.md) or [Footage](../objects/footage.md) object for the layer.
24 |
25 | Default time is adjusted to the time in the source.
26 |
27 | Example:
28 |
29 | ```js
30 | source.layer(1).position
31 | ```
32 |
33 | #### Type
34 |
35 | [Comp](../objects/comp.md) or [Footage](../objects/footage.md)
36 |
37 | ---
38 |
39 | ## Methods
40 |
41 | ### Layer.effect()
42 |
43 | `thisLayer.effect(name)`
44 |
45 | `thisLayer.effect(index)`
46 |
47 | #### Description
48 |
49 | The `name` value will have After Effects find the effect by its name in the Effect Controls panel. The name can be the default name or a user-defined name. If multiple effects have the same name, the effect closest to the top of the Effect Controls panel is used.
50 |
51 | The `index` value will have After Effects finds the effect by its index in the Effect Controls panel, starting at `1` and counting from the top.
52 |
53 | #### Parameters
54 |
55 | +-----------+--------+------------------------------+
56 | | Parameter | Type | Description |
57 | +===========+========+==============================+
58 | | `name` | String | Effect name or index to get. |
59 | | | | |
60 | | `index` | Number | |
61 | +-----------+--------+------------------------------+
62 |
63 | #### Returns
64 |
65 | [Effect](../objects/effect.md)
66 |
67 | #### Example
68 |
69 | Get the "Blurriness" effect by name:
70 |
71 | ```js
72 | thisLayer.effect("Fast Blur")
73 | ```
74 |
75 | Get the first effect on the layer:
76 |
77 | ```js
78 | thisLayer.effect(1)
79 | ```
80 |
81 | ---
82 |
83 | ### Layer.mask()
84 |
85 | `thisLayer.mask(name)`
86 |
87 | `thisLayer.mask(index)`
88 |
89 | #### Description
90 |
91 | The `name` value can be the default name or a user-defined name. If multiple masks have the same name, the first (topmost) mask is used.
92 |
93 | The `index` value will have After Effects finds the mask by its index in the Timeline panel, starting at `1` and counting from the top.
94 |
95 | #### Parameters
96 |
97 | +-----------+--------+------------------------------+
98 | | Parameter | Type | Description |
99 | +===========+========+==============================+
100 | | `name` | String | Effect name or index to get. |
101 | | | | |
102 | | `index` | Number | |
103 | +-----------+--------+------------------------------+
104 |
105 | #### Returns
106 |
107 | [Effect](../objects/effect.md)
108 |
109 | #### Example
110 |
111 | Get the mask "Mask 1" by name:
112 |
113 | ```js
114 | thisLayer.mask("Mask 1")
115 | ```
116 |
117 | Get the first mask on the layer:
118 |
119 | ```js
120 | thisLayer.mask(1)
121 | ```
122 |
123 | ---
124 |
125 | ### Layer.sourceRectAtTime()
126 |
127 | `thisLayer.sourceRectAtTime(t = time, includeExtents = false)`
128 |
129 | !!! note
130 | This functionality was added in After Effects 13.2
131 | Paragraph text extents was added in After Effects 15.1.
132 |
133 | #### Description
134 |
135 | Returns the bounding box of the layer (or the layer's source).
136 |
137 | #### Parameters
138 |
139 | +------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------+
140 | | Parameter | Type | Description |
141 | +==================+=========+==========================================================================================================================================+
142 | | `t` | Number | Optional. The specified time (in comp seconds) to apply the smoothing filter to. Defaults to `time` (the current comp time, in seconds). |
143 | +------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------+
144 | | `includeExtents` | Boolean | Optional. Only applies to shape layers and paragraph text layers. Defaults to `false`. |
145 | | | | |
146 | | | | - For shape layers: Increases the size of the layer bounds as necessary. |
147 | | | | - For paragraph text layers: Returns the bounds of the paragraph box |
148 | +------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------+
149 |
150 | #### Returns
151 |
152 | An object with four attributes: `{top, left, width, height}`
153 |
154 | #### Example
155 |
156 | ```js
157 | myTextLayer.sourceRectAtTime().width
158 | ```
159 |
160 | ---
161 |
162 | ### Layer.sourceTime()
163 |
164 | `thisLayer.sourceTime([t=time])`
165 |
166 |
167 | !!! note
168 | This functionality was added in After Effects CS5.5
169 |
170 | #### Description
171 |
172 | Returns the layer source corresponding to time `t`.
173 |
174 | #### Parameters
175 |
176 | | Parameter | Type | Description |
177 | | --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
178 | | `t` | Number | Optional. The specified time (in comp seconds) to apply the smoothing filter to. Defaults to `time` (the current comp time, in seconds). |
179 |
180 | #### Returns
181 |
182 | Number
183 |
--------------------------------------------------------------------------------
/docs/layer/threed.md:
--------------------------------------------------------------------------------
1 | # Layer 3D
2 |
3 | `thisLayer`
4 |
5 | These attributes are related to the 3d properties of layers.
6 |
7 | !!! info
8 | On this page, we're going to use `thisLayer` as a sample on how to call these items, however note that any method that returns a [Layer](./layer.md) will work.
9 |
10 | ---
11 |
12 | ## Attributes
13 |
14 | ### Layer.acceptsLights
15 |
16 | `thisLayer.acceptsLights`
17 |
18 | #### Description
19 |
20 | Returns a value of `1` if the layer accepts lights.
21 |
22 | #### Type
23 |
24 | Boolean Number
25 |
26 | ---
27 |
28 | ### Layer.acceptsShadows
29 |
30 | `thisLayer.acceptsShadows`
31 |
32 | #### Description
33 |
34 | Returns a value of `1` if the layer accepts shadows and `2` if the property is set to `Only`.
35 |
36 | #### Type
37 |
38 | Number
39 |
40 | ---
41 |
42 | ### Layer.ambient
43 |
44 | `thisLayer.ambient`
45 |
46 | #### Description
47 |
48 | Returns the ambient component value as a percentage.
49 |
50 | #### Type
51 |
52 | Number
53 |
54 | ---
55 |
56 | ### Layer.castsShadows
57 |
58 | `thisLayer.castsShadows`
59 |
60 | #### Description
61 |
62 | Returns a value of `1.0` if the layer casts shadows and `2` if the property is set to `Only`.
63 |
64 | #### Type
65 |
66 | Number
67 |
68 | ---
69 |
70 | ### Layer.diffuse
71 |
72 | `thisLayer.diffuse`
73 |
74 | #### Description
75 |
76 | Returns the diffuse component value as a percentage.
77 |
78 | #### Type
79 |
80 | Number
81 |
82 | ---
83 |
84 | ### Layer.lightTransmission
85 |
86 | `thisLayer.lightTransmission`
87 |
88 | #### Description
89 |
90 | Returns the value of the Light Transmission property for a 3D layer.
91 |
92 | #### Type
93 |
94 | Number
95 |
96 | ---
97 |
98 | ### Layer.metal
99 |
100 | `thisLayer.metal`
101 |
102 | #### Description
103 |
104 | Returns the metal component value as a percentage.
105 |
106 | #### Type
107 |
108 | Number
109 |
110 | ---
111 |
112 | ### Layer.orientation
113 |
114 | `thisLayer.orientation`
115 |
116 | #### Description
117 |
118 | Returns the 3D orientation value, in degrees, for a 3D layer.
119 |
120 | #### Type
121 |
122 | Array (3-dimensional)
123 |
124 | ---
125 |
126 | ### Layer.rotationX
127 |
128 | `thisLayer.rotationX`
129 |
130 | #### Description
131 |
132 | Returns the x rotation value, in degrees, for a 3D layer.
133 |
134 | #### Type
135 |
136 | Number
137 |
138 | ---
139 |
140 | ### Layer.rotationY
141 |
142 | `thisLayer.rotationY`
143 |
144 | #### Description
145 |
146 | Returns the y rotation value, in degrees, for a 3D layer.
147 |
148 | #### Type
149 |
150 | Number
151 |
152 | ---
153 |
154 | ### Layer.rotationZ
155 |
156 | `thisLayer.rotationZ`
157 |
158 | #### Description
159 |
160 | Returns the z rotation value, in degrees, for a 3D layer.
161 |
162 | #### Type
163 |
164 | Number
165 |
166 | ---
167 |
168 | ### Layer.shininess
169 |
170 | `thisLayer.shininess`
171 |
172 | #### Description
173 |
174 | Returns the shininess component value as a percentage.
175 |
176 | #### Type
177 |
178 | Number
179 |
180 | ---
181 |
182 | ### Layer.specular
183 |
184 | `thisLayer.specular`
185 |
186 | #### Description
187 |
188 | Returns the specular component value as a percentage.
189 |
190 | #### Type
191 |
192 | Number
193 |
--------------------------------------------------------------------------------
/docs/objects/camera.md:
--------------------------------------------------------------------------------
1 | # Camera
2 |
3 | `thisLayer.cameraOption`
4 |
5 | This category is for items specific to Camera Layers.
6 |
7 | !!! info
8 | Camera is a subclass of the [Layer object](../layer/layer.md). All methods and attributes of Layer are available when working with Camera, except:
9 |
10 | - `source`
11 | - `effect`
12 | - `mask`
13 | - `width`
14 | - `height`
15 | - `anchorPoint`
16 | - `scale`
17 | - `opacity`
18 | - `audioLevels`
19 | - `timeRemap`
20 | - all the 3d material properties
21 |
22 | ---
23 |
24 | ## Attributes
25 |
26 | ### Camera.active
27 |
28 | `thisLayer.cameraOption.active`
29 |
30 | #### Description
31 |
32 | Returns `true` if:
33 |
34 | 1. The camera is the active camera for the composition at the current time: the *video switch* for the camera layer is on,
35 | 2. the current time is in the range from the *in point* of the camera layer to the *out point* of the camera layer, **and**
36 | 3. The camera is the first (topmost) such camera layer listed in the *timeline panel*
37 |
38 | Returns `false` otherwise.
39 |
40 | #### Type
41 |
42 | Boolean
43 |
44 | ---
45 |
46 | ### Camera.aperture
47 |
48 | `thisLayer.cameraOption.aperture`
49 |
50 | #### Description
51 |
52 | Returns the aperture value of a camera, in pixels.
53 |
54 | #### Type
55 |
56 | Number
57 |
58 | ---
59 |
60 | ### Camera.blurLevel
61 |
62 | `thisLayer.cameraOption.blurLevel`
63 |
64 | #### Description
65 |
66 | Returns the blur level value of a camera as a percentage.
67 |
68 | #### Type
69 |
70 | Number
71 |
72 | ---
73 |
74 | ### Camera.depthOfField
75 |
76 | `thisLayer.cameraOption.depthOfField`
77 |
78 | #### Description
79 |
80 | Returns `1` if the Depth Of Field property of a camera is on, or returns `0` if the Depth Of Field property is off.
81 |
82 | #### Type
83 |
84 | Boolean Number
85 |
86 | ---
87 |
88 | ### Camera.focusDistance
89 |
90 | `thisLayer.cameraOption.focusDistance`
91 |
92 | #### Description
93 |
94 | Returns the focus distance value of a camera, in pixels.
95 |
96 | #### Type
97 |
98 | Number
99 |
100 | ---
101 |
102 | ### Camera.highlightGain
103 |
104 | `thisLayer.cameraOption.highlightGain`
105 |
106 | #### Description
107 |
108 | Returns the camera highlight gain, from 1 to 100.
109 |
110 | #### Type
111 |
112 | Number
113 |
114 | ---
115 |
116 | ### Camera.highlightSaturation
117 |
118 | `thisLayer.cameraOption.highlightSaturation`
119 |
120 | #### Description
121 |
122 | Returns the camera highlight saturation, from `1` to `100`.
123 |
124 | #### Type
125 |
126 | Number
127 |
128 | ---
129 |
130 | ### Camera.highlightThreshold
131 |
132 | `thisLayer.cameraOption.highlightThreshold`
133 |
134 | #### Description
135 |
136 | Returns the camera highlight threshhold.
137 |
138 | - In an 8-bit comp, this value ranges from `0` to `100`
139 | - In a 16-bit comp, this value ranges from `0` to `32768`
140 | - In a 32-bit comp, this value ranges from `0` to `1.0`
141 |
142 | #### Type
143 |
144 | Number
145 |
146 | ---
147 |
148 | ### Camera.irisAspectRatio
149 |
150 | `thisLayer.cameraOption.irisAspectRatio`
151 |
152 | #### Description
153 |
154 | Returns the camera iris aspect ratio, from 1 to 100.
155 |
156 | #### Type
157 |
158 | Number
159 |
160 | ---
161 |
162 | ### Camera.irisDiffractionFringe
163 |
164 | `thisLayer.cameraOption.irisDiffractionFringe`
165 |
166 | #### Description
167 |
168 | Returns the camera iris diffraction fringe, from 1 to 100.
169 |
170 | #### Type
171 |
172 | Number
173 |
174 | ---
175 |
176 | ### Camera.irisRotation
177 |
178 | `thisLayer.cameraOption.irisRotation`
179 |
180 | #### Description
181 |
182 | Returns the iris rotation value, in degrees.
183 |
184 | #### Type
185 |
186 | Number
187 |
188 | ---
189 |
190 | ### Camera.irisRoundness
191 |
192 | `thisLayer.cameraOption.irisRoundness`
193 |
194 | #### Description
195 |
196 | Returns the camera iris roundness value as a percentage.
197 |
198 | #### Type
199 |
200 | Number
201 |
202 | ---
203 |
204 | ### Camera.irisShape
205 |
206 | `thisLayer.cameraOption.irisShape`
207 |
208 | #### Description
209 |
210 | Returns the iris shape value from 1-10, corresponding to the selected dropdown value.
211 |
212 | !!! note
213 | Value `2` is reserved for the divider.
214 |
215 | #### Type
216 |
217 | Number
218 |
219 | ---
220 |
221 | ### Camera.pointOfInterest
222 |
223 | `thisLayer.cameraOption.pointOfInterest`
224 |
225 | #### Description
226 |
227 | Returns the point of interest values of a camera in world space.
228 |
229 | #### Type
230 |
231 | Array (3 dimensional)
232 |
233 | ---
234 |
235 | ### Camera.zoom
236 |
237 | `thisLayer.cameraOption.zoom`
238 |
239 | #### Description
240 |
241 | Returns the zoom values of a camera in pixels.
242 |
243 | #### Type
244 |
245 | Number
246 |
247 | #### Example
248 |
249 | Here's an expression for the Scale property of a layer that maintains the relative size of the layer in frame while changing the z position (depth) of a layer or the Zoom value of a camera:
250 |
251 | ```js
252 | cam = thisComp.activeCamera;
253 | distance = length(sub(position, cam.position));
254 | scale * distance / cam.zoom;
255 | ```
256 |
--------------------------------------------------------------------------------
/docs/objects/comp.md:
--------------------------------------------------------------------------------
1 | # Comp
2 |
3 | `thisComp`
4 |
5 | `comp("CompName")`
6 |
7 | `layer("layerName").source`
8 |
9 | These attributes and methods can be called on Comp objects.
10 |
11 | These are typically accessed in a few ways, most commonly:
12 |
13 | - `thisComp` to get the Comp object of the active comp the expression is written in,
14 | - `comp("CompName")` to get a specific comp by name,
15 | - `layer("layerName").source`, **if referring to a precomp layer**, to get the targeted precomp layer's source comp
16 |
17 | !!! info
18 | On this page, we're going to use `thisComp` as a sample on how to call these items, however note that any method that returns a [Comp](#) will work.
19 |
20 | ---
21 |
22 | ## Attributes
23 |
24 | ### Comp.activeCamera
25 |
26 | `thisComp.activeCamera`
27 |
28 | #### Description
29 |
30 | Returns the [Camera object](./camera.md) for the camera through which the composition is rendered at the current frame.
31 |
32 | This camera is not necessarily the camera through which you are looking in the Composition panel.
33 |
34 | #### Type
35 |
36 | [Camera](./camera.md)
37 |
38 | ---
39 |
40 | ### Comp.bgColor
41 |
42 | `thisComp.bgColor`
43 |
44 | #### Description
45 |
46 | Returns the background color of the composition.
47 |
48 | #### Type
49 |
50 | Array (4-dimensional)
51 |
52 | ---
53 |
54 | ### Comp.displayStartTime
55 |
56 | `thisComp.displayStartTime`
57 |
58 | #### Description
59 |
60 | Returns the composition start time, in seconds.
61 |
62 | #### Type
63 |
64 | Number
65 |
66 | ---
67 |
68 | ### Comp.duration
69 |
70 | `thisComp.duration`
71 |
72 | #### Description
73 |
74 | Returns the composition duration, in seconds.
75 |
76 | #### Type
77 |
78 | Number
79 |
80 | ---
81 |
82 | ### Comp.frameDuration
83 |
84 | `thisComp.frameDuration`
85 |
86 | #### Description
87 |
88 | Returns the duration of a frame, in seconds.
89 |
90 | #### Type
91 |
92 | Number
93 |
94 | ---
95 |
96 | ### Comp.height
97 |
98 | `thisComp.height`
99 |
100 | #### Description
101 |
102 | Returns the composition height, in pixels.
103 |
104 | #### Type
105 |
106 | Number
107 |
108 | ---
109 |
110 | ### Comp.marker
111 |
112 | `thisComp.marker`
113 |
114 | #### Description
115 |
116 | Returns a given composition's [Marker](./marker-property.md) property.
117 |
118 | !!! note
119 | You can no longer access a composition marker by marker number.
120 |
121 | If you have a project created in a previous version of After Effects that uses composition marker numbers in expressions, you must change those calls to use `marker.key(name)` instead. Because the default name of a composition marker is a number, converting the reference to use the name is often just a matter of surrounding the number with quotation marks.
122 |
123 | #### Type
124 |
125 | [Marker Property](./marker-property.md)
126 |
127 | ---
128 |
129 | ### Comp.name
130 |
131 | `thisComp.name`
132 |
133 | #### Description
134 |
135 | Returns the name of the composition.
136 |
137 | #### Type
138 |
139 | String
140 |
141 | ---
142 |
143 | ### Comp.ntscDropFrame
144 |
145 | `thisComp.ntscDropFrame`
146 |
147 | !!! note
148 | This functionality was added in After Effects CS5.5
149 |
150 | #### Description
151 |
152 | Returns `true` if the timecode is in drop-frame format.
153 |
154 | #### Type
155 |
156 | Boolean
157 |
158 | ---
159 |
160 | ### Comp.numLayers
161 |
162 | `thisComp.numLayers`
163 |
164 | #### Description
165 |
166 | Returns the number of layers in the composition.
167 |
168 | #### Type
169 |
170 | Number
171 |
172 | ---
173 |
174 | ### Comp.pixelAspect
175 |
176 | `thisComp.pixelAspect`
177 |
178 | #### Description
179 |
180 | Returns the pixel aspect ratio of the composition.
181 |
182 | #### Type
183 |
184 | Number
185 |
186 | ---
187 |
188 | ### Comp.shutterAngle
189 |
190 | `thisComp.shutterAngle`
191 |
192 | #### Description
193 |
194 | Returns the shutter-angle value of the composition, in degrees.
195 |
196 | #### Type
197 |
198 | Number
199 |
200 | ---
201 |
202 | ### Comp.shutterPhase
203 |
204 | `thisComp.shutterPhase`
205 |
206 | #### Description
207 |
208 | Returns the shutter phase of the composition, in degrees.
209 |
210 | #### Type
211 |
212 | Number
213 |
214 | ---
215 |
216 | ### Comp.width
217 |
218 | `thisComp.width`
219 |
220 | #### Description
221 |
222 | Returns the composition width, in pixels.
223 |
224 | #### Type
225 |
226 | Number
227 |
228 | #### Example
229 |
230 | Apply the following expression to the Position property of a layer to center the layer in the composition frame:
231 |
232 | ```js
233 | [thisComp.width / 2, thisComp.height / 2];
234 | ```
235 |
236 | ---
237 |
238 | ## Methods
239 |
240 | ### Comp.layer()
241 |
242 | `thisComp.layer(index)`
243 |
244 | `thisComp.layer(name)`
245 |
246 | `thisComp.layer(otherLayer, relIndex)`
247 |
248 | #### Description
249 |
250 | Return the [Layer](../layer/layer.md) object with the specified `index` or `name`.
251 |
252 | The `index` value refers to the layer order in the Timeline panel.
253 |
254 | The `name` value refers to the user-specified layer name, or the layer source name if there is no layer name.
255 |
256 | If duplicate names exist, After Effects uses the first (topmost) one in the Timeline panel.
257 |
258 | If using the `otherLayer, relIndex` call, this retrieves the layer that is `relIndex` layers above or below `otherLayer`.
259 |
260 | #### Parameters
261 |
262 | +--------------+----------------------------+--------------------------------------------------------------+
263 | | Parameter | Type | Description |
264 | +==============+============================+==============================================================+
265 | | `index` | Number | Layer name or index to get. |
266 | | | | |
267 | | `name` | String | |
268 | +--------------+----------------------------+--------------------------------------------------------------+
269 | | `otherLayer` | [Layer](../layer/layer.md) | The "other" layer to start getting layers relative to |
270 | +--------------+----------------------------+--------------------------------------------------------------+
271 | | `relIndex` | Number | The number of layers to move above or below the `otherLayer` |
272 | +--------------+----------------------------+--------------------------------------------------------------+
273 |
274 | #### Returns
275 |
276 | [Layer](../layer/layer.md), [Light](./light.md), or [Camera](./camera.md) object
277 |
278 | #### Example
279 |
280 | Get the 3rd layer in the current comp:
281 |
282 | ```js
283 | thisComp.layer(3)
284 | ```
285 |
286 | Get the layer named "Solid 1" from the current comp:
287 |
288 | ```js
289 | thisComp.layer("Solid 1")
290 | ```
291 |
292 | Check whether the next layer down in the Timeline panel is active:
293 |
294 | ```js
295 | const nextLayer = thisComp.layer(thisLayer, 1);
296 | nextLayer.active;
297 | ```
298 |
299 | ---
300 |
301 | ### Comp.layerByComment()
302 |
303 | `thisComp.layerByComment(comment)`
304 |
305 | #### Description
306 |
307 | Retrieves a layer by matching the comment parameter to the value in the layer's Comment column.
308 |
309 | The matches are simple text matches. They will match partial words, and are case sensitive. Matching does not appear to use regular expressions or wildcards. If duplicate comments exist, After Effects uses the first (topmost) one in the Timeline panel.
310 |
311 | #### Parameters
312 |
313 | | Parameter | Type | Description |
314 | | --------- | ------ | -------------------------------- |
315 | | `comment` | String | The comment to find a layer from |
316 |
317 | #### Returns
318 |
319 | [Layer](../layer/layer.md), [Light](./light.md), or [Camera](./camera.md) object
320 |
321 | #### Example
322 |
323 | ```js
324 | // note this will match a layer with a comment "Controller" or "Motion Control"
325 | thisComp.layerByComment("Control");
326 | ```
327 |
--------------------------------------------------------------------------------
/docs/objects/effect.md:
--------------------------------------------------------------------------------
1 | # Effect
2 |
3 | `thisLayer.effect("Bulge")`
4 |
5 | This category contains information relating to Effects.
6 |
7 | !!! info
8 | On this page, we're going to use `thisLayer.effect("Bulge")` as a sample on how to call these items, however note that any method that returns an [Effect](#) will work.
9 |
10 | ---
11 |
12 | ## Attributes
13 |
14 | ### Effect.active
15 |
16 | `thisLayer.effect("Bulge").active`
17 |
18 | #### Description
19 |
20 | Returns `true` if the effect is turned on (the *effect switch* is selected).
21 |
22 | #### Type
23 |
24 | Boolean
25 |
26 | ---
27 |
28 | ## Methods
29 |
30 | ### Effect.param()
31 |
32 | `thisLayer.effect("Bulge").param(name)`
33 |
34 | `thisLayer.effect("Bulge").param(index)`
35 |
36 | #### Description
37 |
38 | Returns a property within an effect. Effect control points are always in layer space.
39 |
40 | This method can be called using *either* the property's `name` or its `index`.
41 |
42 | #### Parameters
43 |
44 | +-----------+--------+-----------------------------------------------+
45 | | Parameter | Type | Description |
46 | +===========+========+===============================================+
47 | | `name` | String | Property name or index to access property by. |
48 | | | | |
49 | | `index` | Number | |
50 | +-----------+--------+-----------------------------------------------+
51 |
52 | #### Returns
53 |
54 | [Property object](./property.md)
55 |
56 | #### Example
57 |
58 | To return the "Bulge Height" property from the "Bulge" effect by name:
59 |
60 | ```js
61 | thisLayer.effect("Bulge").param("Bulge Height");
62 | ```
63 |
64 | To return the "Bulge Height" property from the "Bulge" effect by index:
65 |
66 | ```js
67 | thisLayer.effect("Bulge").param(4);
68 | ```
69 |
--------------------------------------------------------------------------------
/docs/objects/footage.md:
--------------------------------------------------------------------------------
1 | # Footage
2 |
3 | `footage("myFile")`
4 |
5 | To use a footage item from the Project panel as an object in an expression, use the global footage method, as in `footage("myFile")`.
6 |
7 | You can also access a footage object using the source attribute on a layer whose source is a footage item (i.e. `thisLayer.source`)
8 |
9 | !!! info
10 | On this page, we're going to use `footage("myFile")` as a sample on how to call these items, however note that any method that returns a [Footage object](#) will work.
11 |
12 | ---
13 |
14 | ## Attributes
15 |
16 | ### Footage.duration
17 |
18 | `footage("myFile").duration`
19 |
20 | #### Description
21 |
22 | Returns the duration of the footage item, in seconds.
23 |
24 | #### Type
25 |
26 | Number
27 |
28 | ---
29 |
30 | ### Footage.frameDuration
31 |
32 | `footage("myFile").frameDuration`
33 |
34 | #### Description
35 |
36 | Returns the duration of a frame in the footage item, in seconds.
37 |
38 | #### Type
39 |
40 | Number
41 |
42 | ---
43 |
44 | ### Footage.height
45 |
46 | `footage("myFile").height`
47 |
48 | #### Description
49 |
50 | Returns the height of the footage item, in pixels.
51 |
52 | #### Type
53 |
54 | Number
55 |
56 | ---
57 |
58 | ### Footage.name
59 |
60 | `footage("myFile").name`
61 |
62 | #### Description
63 |
64 | Returns the name of the footage item as shown in the Project panel.
65 |
66 | #### Type
67 |
68 | String
69 |
70 | ---
71 |
72 | ### Footage.ntscDropFrame
73 |
74 | `footage("myFile").ntscDropFrame`
75 |
76 | !!! note
77 | This functionality was added in After Effects CS5.5
78 |
79 | #### Description
80 |
81 | Returns `true` if the timecode is in drop-frame format.
82 |
83 | #### Type
84 |
85 | Boolean
86 |
87 | ---
88 |
89 | ### Footage.pixelAspect
90 |
91 | `footage("myFile").pixelAspect`
92 |
93 | #### Description
94 |
95 | Returns the pixel aspect ratio of the footage item.
96 |
97 | #### Type
98 |
99 | Number
100 |
101 | ---
102 |
103 | ### Footage.sourceData
104 |
105 | `footage("myFile").sourceData`
106 |
107 | #### Description
108 |
109 | Returns the data of a JSON file as an array of `sourceData` objects.
110 |
111 | The structure of the JSON file will determine the size and complexity of the array.
112 |
113 | Individual data streams can be referenced as hierarchal attributes of the data.
114 |
115 | #### Type
116 |
117 | An array of `sourceData` objects; read-only.
118 |
119 | #### Example
120 |
121 | Given a data stream named "Color", the following will return the value of "Color" from the first data object:
122 |
123 | ```js
124 | footage("sample.json").sourceData[0].Color
125 | ```
126 |
127 | Typical use is to assign a JSON file's `sourceData` to a variable, and then reference the desired data stream. For example:
128 |
129 | ```js
130 | const myData = footage("sample.json").sourceData;
131 | myData[0].Color;
132 | ```
133 |
134 | ---
135 |
136 | ### Footage.sourceText
137 |
138 | `footage("myFile").sourceText`
139 |
140 | #### Description
141 |
142 | Returns the contents of a JSON file as a string.
143 |
144 | The `eval()` method can be used to convert the string to an array of sourceData objects, identical to the results of the [Footage.sourceData](#footagesourcedata) attribute, from which the individual data streams can be referenced as hierarchal attributes of the data.
145 |
146 | #### Type
147 |
148 | String, the contents of the JSON file; read-only.
149 |
150 | #### Example
151 |
152 | ```js
153 | const myData = eval(footage("sample.json").sourceText);
154 | myData.sampleValue;
155 | ```
156 |
157 | ---
158 |
159 | ### Footage.width
160 |
161 | `footage("myFile").width`
162 |
163 | #### Description
164 |
165 | Returns the width of the footage item, in pixels.
166 |
167 | #### Type
168 |
169 | Number
170 |
171 | ---
172 |
173 | ## Methods
174 |
175 | ### Footage.dataKeyCount()
176 |
177 | `footage("myFile").dataKeyCount(dataPath)`
178 |
179 | #### Description
180 |
181 | Returns the number of samples in a specificed dynamic data stream in a MGJSON file.
182 |
183 | Accepts a single array value to define the path in the hierarchy to the desired dynamic data stream.
184 |
185 | #### Parameters
186 |
187 | | Parameter | Type | Description |
188 | | ---------- | ----- | ----------------------------------------------------------------------- |
189 | | `dataPath` | Array | Required. The path in the hierarchy to a static or dynamic data stream. |
190 |
191 | #### Returns
192 |
193 | The number of samples in the dynamic data stream.
194 |
195 | #### Example
196 |
197 | To return the count of samples for the first child:
198 |
199 | ```js
200 | footage("sample.mgjson").dataKeyCount([0])
201 | ```
202 |
203 | To return the count of samples for the second group:
204 |
205 | ```js
206 | footage("sample.mgjson").dataKeyCount([1][0])
207 | ```
208 |
209 | ---
210 |
211 | ### Footage.dataKeyTimes()
212 |
213 | `footage("myFile").dataKeyTimes(dataPath[, t0=startTime][, t1=endTime])`
214 |
215 | #### Description
216 |
217 | Returns the time in seconds for the samples of a specificed dynamic data stream in a MGJSON file.
218 |
219 | Optionally specify the time span from which to return samples. By default the time for all samples between `startTime` and `endTime` in the dynamicdata stream are returned, as defined by the data stream's `samplesTemporalExtent` property in the MGJSON file.
220 |
221 | Accepts a single array value to define the path in the hierarchy to the desired dynamic data stream.
222 |
223 | #### Parameters
224 |
225 | | Parameter | Type | Description |
226 | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- |
227 | | `dataPath` | Array | Required. The path in the hierarchy to a static or dynamic data stream. |
228 | | `t0` | Number | Optional. The start time, in seconds, of the span from which to return samples. Defaults to `startTime`. |
229 | | `t1` | Number | Optional. The end time, in seconds, of the span from which to return samples. Defaults to `endTime`. |
230 |
231 | #### Returns
232 |
233 | Array of numbers representing the sample times.
234 |
235 | #### Example
236 |
237 | Return the times of samples between 1 second and 3 seconds for the first child:
238 |
239 | ```js
240 | footage("sample.mgjson").dataKeyTimes([0], 1, 3)
241 | ```
242 |
243 | ---
244 |
245 | ### Footage.dataKeyValues()
246 |
247 | `footage("myFile").dataKeyValues(dataPath[, t0=startTime][, t1=endTime])`
248 |
249 | #### Description
250 |
251 | Returns the values for the samples of a specificed dynamic data stream in a MGJSON file.
252 |
253 | Optionally specify the time span from which to return samples. By default the time for all samples between startTime and endTime in the dynamicdata stream are returned, as defined by the data stream's `samplesTemporalExtent` property in the MGJSON file.
254 |
255 | Accepts a single array value to define the path in the hierarchy to the desired dynamic data stream.
256 |
257 | #### Parameters
258 |
259 | | Parameter | Type | Description |
260 | | ---------- | ------ | -------------------------------------------------------------------------------------------------------- |
261 | | `dataPath` | Array | Required. The path in the hierarchy to a static or dynamic data stream. |
262 | | `t0` | Number | Optional. The start time, in seconds, of the span from which to return samples. Defaults to `startTime`. |
263 | | `t1` | Number | Optional. The end time, in seconds, of the span from which to return samples. Defaults to `endTime`. |
264 |
265 | #### Returns
266 |
267 | Array of numbers representing the sample values.
268 |
269 | #### Example
270 |
271 | Return the values of samples between 1 second and 3 seconds for the first child:
272 |
273 | ```js
274 | footage("sample.mgjson").dataKeyValues([0], 1, 3)
275 | ```
276 |
277 | ---
278 |
279 | ### Footage.dataValue()
280 |
281 | `footage("myFile").dataValue(dataPath)`
282 |
283 | #### Description
284 |
285 | Returns the value of specificed static or dynamic data stream in a MGJSON file.
286 |
287 | Accepts a single array value to define the path in the hierarchy to the desired data stream.
288 |
289 | #### Parameters
290 |
291 | | Parameter | Type | Description |
292 | | ---------- | ----- | ----------------------------------------------------------------------- |
293 | | `dataPath` | Array | Required. The path in the hierarchy to a static or dynamic data stream. |
294 |
295 | #### Returns
296 |
297 | The value of the data stream.
298 |
299 | #### Example
300 |
301 | To return data of the first child:
302 |
303 | ```js
304 | footage("sample.mgjson").dataValue([0])
305 | ```
306 |
307 | To return data of the first child in the second group:
308 |
309 | ```js
310 | footage("sample.mgjson").dataValue([1][0])
311 | ```
312 |
--------------------------------------------------------------------------------
/docs/objects/key.md:
--------------------------------------------------------------------------------
1 | # Key
2 |
3 | `thisProperty.key(1)`
4 |
5 | When you access a Key object, you can get `time`, `index`, and `value` properties from it.
6 |
7 | !!! tip
8 | In expressions, "Key" refers to Keyframes.
9 |
10 |
11 | !!! info
12 | On this page, we're going to use `thisProperty.key(1)` as a sample on how to call these items, however note that any method that returns a [Key](#) will work.
13 |
14 | ---
15 |
16 | ## Attributes
17 |
18 | ### Key.index
19 |
20 | `thisProperty.key(1).index`
21 |
22 | #### Description
23 |
24 | Returns the index of the keyframe.
25 |
26 | #### Type
27 |
28 | Number
29 |
30 | ---
31 |
32 | ### Key.time
33 |
34 | `thisProperty.key(1).time`
35 |
36 | #### Description
37 |
38 | Returns the time of the keyframe.
39 |
40 | #### Type
41 |
42 | Number
43 |
44 | ---
45 |
46 | ### Key.value
47 |
48 | `thisProperty.key(1).value`
49 |
50 | #### Description
51 |
52 | Returns the value of the keyframe.
53 |
54 | #### Type
55 |
56 | A value of the same property type as the property being refrenced.
57 |
58 | ---
59 |
60 | ## Example
61 |
62 | The following expression, when written on an Opacity property with keyframes, ignores the keyframe values and uses only the placement of the keyframes in time to determine where a flash should occur:
63 |
64 | ```js
65 | const d = Math.abs(time - nearestKey(time).time);
66 | easeOut(d, 0, .1, 100, 0)
67 | ```
68 |
69 | The following expression gives you the value of the third Position keyframe:
70 |
71 | ```js
72 | position.key(3).value;
73 | ```
74 |
--------------------------------------------------------------------------------
/docs/objects/light.md:
--------------------------------------------------------------------------------
1 | # Light
2 |
3 | `thisLayer.lightOption`
4 |
5 | This category is for items specific to Light Layers.
6 |
7 | !!! info
8 | Light is a subclass of the [Layer object](../layer/layer.md). All methods and attributes of Layer are available when working with Light, except:
9 |
10 | - `source`
11 | - `effect`
12 | - `mask`
13 | - `width`
14 | - `height`
15 | - `anchorPoint`
16 | - `scale`
17 | - `opacity`
18 | - `audioLevels`
19 | - `timeRemap`
20 | - all the material properties
21 |
22 | !!! note
23 | David Van Brink provides an instructional article and sample project on his [omino pixel blog](http://www.adobe.com/go/learn_ae_ominoflashing) that shows how to use expressions with lights.
24 |
25 | ---
26 |
27 | ## Attributes
28 |
29 | ### Light.castsShadows
30 |
31 | `thisLayer.lightOption.castsShadows`
32 |
33 | #### Description
34 |
35 | Returns whether the light casts shadows.
36 |
37 | #### Type
38 |
39 | Boolean
40 |
41 | ---
42 |
43 | ### Light.color
44 |
45 | `thisLayer.lightOption.color`
46 |
47 | #### Description
48 |
49 | Returns the color value of a light.
50 |
51 | #### Type
52 |
53 | Array (4-dimensional)
54 |
55 | ---
56 |
57 | ### Light.coneAngle
58 |
59 | `thisLayer.lightOption.coneAngle`
60 |
61 | #### Description
62 |
63 | Returns the cone angle of a light, in degrees.
64 |
65 | #### Type
66 |
67 | Number
68 |
69 | ---
70 |
71 | ### Light.coneFeather
72 |
73 | `thisLayer.lightOption.coneFeather`
74 |
75 | #### Description
76 |
77 | Returns the cone feather value of a light as a percentage.
78 |
79 | #### Type
80 |
81 | Number
82 |
83 | ---
84 |
85 | ### Light.falloff
86 |
87 | `thisLayer.lightOption.falloff`
88 |
89 | #### Description
90 |
91 | Returns the cone falloff dropdown option.
92 |
93 | #### Type
94 |
95 | Number
96 |
97 | ---
98 |
99 | ### Light.falloffDistance
100 |
101 | `thisLayer.lightOption.falloffDistance`
102 |
103 | #### Description
104 |
105 | Returns the falloff distance of a light.
106 |
107 | #### Type
108 |
109 | Number
110 |
111 | ---
112 |
113 | ### Light.intensity
114 |
115 | `thisLayer.lightOption.intensity`
116 |
117 | #### Description
118 |
119 | Returns the intensity values of a light as a percentage.
120 |
121 | #### Type
122 |
123 | Number
124 |
125 | ---
126 |
127 | ### Light.pointOfInterest
128 |
129 | `thisLayer.lightOption.pointOfInterest`
130 |
131 | #### Description
132 |
133 | Returns the point of interest values for a light in world space.
134 |
135 | #### Type
136 |
137 | Array (3-dimensional)
138 |
139 | ---
140 |
141 | ### Light.radius
142 |
143 | `thisLayer.lightOption.radius`
144 |
145 | #### Description
146 |
147 | Returns the radius values of a light.
148 |
149 | #### Type
150 |
151 | Number
152 |
153 | ---
154 |
155 | ### Light.shadowDarkness
156 |
157 | `thisLayer.lightOption.shadowDarkness`
158 |
159 | #### Description
160 |
161 | Returns the shadow darkness value of a light as a percentage.
162 |
163 | #### Type
164 |
165 | Number
166 |
167 | ---
168 |
169 | ### Light.shadowDiffusion
170 |
171 | `thisLayer.lightOption.shadowDiffusion`
172 |
173 | #### Description
174 |
175 | Returns the shadow diffusion value of a light, in pixels.
176 |
177 | #### Type
178 |
179 | Number
180 |
--------------------------------------------------------------------------------
/docs/objects/marker-property.md:
--------------------------------------------------------------------------------
1 | # Marker Property
2 |
3 | `thisComp.marker`
4 |
5 | `comp("CompName").marker`
6 |
7 | `layer("precompName").source.marker`
8 |
9 | `thisLayer.marker`
10 |
11 | The Marker Property is a special version of the [Property](./property.md) object *specifically* for composition & layer markers.
12 |
13 | It contains a special version of some of the same attributes and methods as the standard Property object, however most elements are not applicable here.
14 |
15 | !!! info
16 | On this page, we're going to use `thisComp.marker` as a sample on how to call these items, however note that any method that returns a [Marker Property](#) will work.
17 |
18 | ---
19 |
20 | ## Attributes
21 |
22 | ### Marker.numKeys
23 |
24 | `thisComp.marker.numKeys`
25 |
26 | #### Description
27 |
28 | Returns the total number of markers in this composition or layer.
29 |
30 | #### Type
31 |
32 | Number
33 |
34 | ---
35 |
36 | ## Methods
37 |
38 | ### Marker.key(index)
39 |
40 | `thisComp.marker.key(index)`
41 |
42 | `thisComp.marker.key(name)`
43 |
44 | #### Description
45 |
46 | Returns the [MarkerKey](./markerkey.md) object of the marker with the specified `index` or `name`.
47 |
48 | The `index` refers to the order of the marker in composition time, not to the numbered name of the marker.
49 |
50 | The `name` value is the name of the marker, as typed in the comment field in the marker dialog box. For example, `marker.key("1")`.
51 |
52 | If more than one marker has the same name, this method returns the marker that occurs first in time (in composition or layer time, depending on whether this is a composition or layer marker).
53 |
54 | #### Parameters
55 |
56 | +-----------+--------+-------------------------------------------+
57 | | Parameter | Type | Description |
58 | +===========+========+===========================================+
59 | | `index` | Number | The marker index to get |
60 | +-----------+--------+-------------------------------------------+
61 | | `name` | String | Marker name or index to access marker by. |
62 | | | | |
63 | | `index` | Number | |
64 | +-----------+--------+-------------------------------------------+
65 |
66 | #### Type
67 |
68 | [MarkerKey](./markerkey.md)
69 |
70 | #### Example
71 |
72 | Return the time of the first composition marker:
73 |
74 | ```js
75 | thisComp.marker.key(1).time;
76 | ```
77 |
78 | Return the time of the layer marker with the name "0":
79 |
80 | ```js
81 | thisLayer.marker.key("0").time;
82 | ```
83 |
84 | On a layer, ramp the value of the property from `0` to `100` between two markers identified by name:
85 |
86 | ```js
87 | const m1 = thisLayr.marker.key("Start").time;
88 | const m2 = thisLayr.marker.key("End").time;
89 | linear(time, m1, m2, 0, 100);
90 | ```
91 |
92 | ---
93 |
94 | ### Marker.nearestKey()
95 |
96 | `thisComp.marker.nearestKey(t)`
97 |
98 | #### Description
99 |
100 | Returns the marker that is nearest in comp or layer time to the provided time `t`.
101 |
102 | #### Parameters
103 |
104 | | Parameter | Type | Description |
105 | | --------- | ------ | ---------------------------------------- |
106 | | `t` | Number | The time to find the nearest marker from |
107 |
108 | #### Returns
109 |
110 | [MarkerKey](./markerkey.md)
111 |
112 | #### Example
113 |
114 | Return the time of the composition marker nearest to the time of 1 second:
115 |
116 | ```js
117 | thisComp.marker.nearestKey(1).time;
118 | ```
119 |
120 | This expression returns the time of the layer marker nearest to the current comp time:
121 |
122 | ```js
123 | thisLayer.marker.nearestKey(time).time;
124 | ```
125 |
--------------------------------------------------------------------------------
/docs/objects/markerkey.md:
--------------------------------------------------------------------------------
1 | # MarkerKey
2 |
3 | `thisComp.marker.key(1)`
4 |
5 | You can access values for composition markers and layer markers using the same methods. Access layer markers through the thisLayer.marker object; access composition markers through the [Marker Property](./marker-property.md) object.
6 |
7 | For the purpose of expressions, markers are a special type of [Key](./key.md) object, so you can use methods such as [`nearestKey(time)`](./property.md#nearestkey) to access markers, and markers also have `time` and `index` attributes. The `index` attribute is not the number (name) of the marker; it is the keyframe *index* number, representing the order of the marker in the time ruler.
8 |
9 | Expressions have access to all the values for a marker that you can set in the Composition Marker or Layer Marker dialog box.
10 |
11 | Because the XMP metadata in a footage item can be converted into layer markers for a layer based on that item, expressions can interact with XMP metadata. For information, see [XMP metadata in After Effects](https://helpx.adobe.com/after-effects/using/xmp-metadata.html#xmp_metadata_in_after_effects).
12 |
13 | Dan Ebberts provides a tutorial on the [After Effects Developer Center](http://www.adobe.com/devnet/aftereffects/) that includes an example of using XMP metadata with expressions.
14 |
15 | !!! info
16 | On this page, we're going to use `thisComp.marker.key(1)` as a sample on how to call these items, however note that any method that returns a [MarkerKey](#) will work.
17 |
18 | ---
19 |
20 | ## Attributes
21 |
22 | ### MarkerKey.chapter
23 |
24 | `thisComp.marker.key(1).chapter`
25 |
26 | #### Description
27 |
28 | Contents of Chapter field in marker dialog box.
29 |
30 | #### Type
31 |
32 | String
33 |
34 | ---
35 |
36 | ### MarkerKey.comment
37 |
38 | `thisComp.marker.key(1).comment`
39 |
40 | #### Description
41 |
42 | Contents of Comment field in marker dialog box.
43 |
44 | #### Type
45 |
46 | String
47 |
48 | ---
49 |
50 | ### MarkerKey.cuePointName
51 |
52 | `thisComp.marker.key(1).cuePointName`
53 |
54 | #### Description
55 |
56 | Contents of cue point Name field in marker dialog box.
57 |
58 | #### Type
59 |
60 | String
61 |
62 | ---
63 |
64 | ### MarkerKey.duration
65 |
66 | `thisComp.marker.key(1).duration`
67 |
68 | #### Description
69 |
70 | Duration, in seconds, of marker.
71 |
72 | #### Type
73 |
74 | Number
75 |
76 | ---
77 |
78 | ### MarkerKey.eventCuePoint
79 |
80 | `thisComp.marker.key(1).eventCuePoint`
81 |
82 | #### Description
83 |
84 | Setting for cue point type in marker dialog box.
85 |
86 | `true` for Event; `false` for Navigation.
87 |
88 | #### Type
89 |
90 | Boolean
91 |
92 | ---
93 |
94 | ### MarkerKey.frameTarget
95 |
96 | `thisComp.marker.key(1).frameTarget`
97 |
98 | #### Description
99 |
100 | Contents of Frame Target field in marker dialog box.
101 |
102 | #### Type
103 |
104 | String
105 |
106 | ---
107 |
108 | ### MarkerKey.parameters
109 |
110 | `thisComp.marker.key(1).parameters`
111 |
112 | #### Description
113 |
114 | Contents of Parameter Name and Parameter Value fields in marker dialog box.
115 |
116 | #### Type
117 |
118 | Associative array of String values
119 |
120 | #### Example
121 |
122 | If you have a parameter named "background color", then you can use the following expression to access its value at the nearest marker:
123 |
124 | ```js
125 | thisComp.marker.nearestKey(time).parameters["background color"];
126 | ```
127 |
128 | ---
129 |
130 | ### MarkerKey.protectedRegion
131 |
132 | `thisComp.marker.key(1).protectedRegion`
133 |
134 | !!! note
135 | This functionality was added in After Effects 16.0
136 |
137 | #### Description
138 |
139 | State of the Protected Region option in the Composition Marker dialog box.
140 |
141 | When `true`, the composition marker behaves as a protected region.
142 |
143 | Will also return `true` for protected region markers on nested composition layers, but is otherwise not applicable to layer markers.
144 |
145 | #### Type
146 |
147 | Boolean
148 |
149 | ---
150 |
151 | ### MarkerKey.url
152 |
153 | `thisComp.marker.key(1).url`
154 |
155 | #### Description
156 |
157 | Contents of URL field in marker dialog box.
158 |
159 | #### Type
160 |
161 | String
162 |
163 | ---
164 |
165 | ## Example
166 |
167 | This expression on the Source Text property of a text layer displays the time, duration, index, comment (name), chapter, URL, frame target, and cue point name for the layer marker nearest the current time, and whether the marker is for an event cue point:
168 |
169 | ```js
170 | const m = thisLayer.marker.nearestKey(time);
171 | const s = [
172 | "time:" + timeToCurrentFormat(m.time),
173 | "duration: " + m.duration,
174 | "key index: " + m.index,
175 | "comment:" + m.comment,
176 | "chapter:" + m.chapter,
177 | "URL:" + m.url,
178 | "frame target: " + m.frameTarget,
179 | "cue point name: " + m.cuePointName,
180 | "Event cue point? " + m.eventCuePoint,
181 | ""
182 | ];
183 |
184 | for (let param in m.parameters){
185 | s.push("parameter: " + param + " value: " + m.parameters[param]);
186 | }
187 |
188 | s.join("\n");
189 | ```
190 |
--------------------------------------------------------------------------------
/docs/objects/mask.md:
--------------------------------------------------------------------------------
1 | # Mask
2 |
3 | `thisLayer.mask("Mask 1")`
4 |
5 | This category contains information relating to mask objects. To manipulate the actual mask *path*, see [Mask Path](#maskmaskpath).
6 |
7 | !!! note
8 | You can link Mask Path properties to other path properties (paths in a shape layer and brush strokes), but the properties are not accessible for direct numerical manipulation through expressions.
9 |
10 | !!! info
11 | On this page, we're going to use `thisLayer.mask("Mask 1")` as a sample on how to call these items, however note that any method that returns a [Mask](#) will work.
12 |
13 | ---
14 |
15 | ## Attributes
16 |
17 | ### Mask.invert
18 |
19 | `thisLayer.mask("Mask 1").invert`
20 |
21 | #### Description
22 |
23 | Returns `true` if the mask is inverted or `false` if it is not.
24 |
25 | #### Type
26 |
27 | Boolean
28 |
29 | ---
30 |
31 | ### Mask.maskExpansion
32 |
33 | `thisLayer.mask("Mask 1").maskExpansion`
34 |
35 | #### Description
36 |
37 | Returns the expansion value of a mask, in pixels.
38 |
39 | #### Type
40 |
41 | Number
42 |
43 | ---
44 |
45 | ### Mask.maskFeather
46 |
47 | `thisLayer.mask("Mask 1").maskFeather`
48 |
49 | #### Description
50 |
51 | Returns the feather value of a mask, in pixels.
52 |
53 | #### Type
54 |
55 | Number
56 |
57 | ---
58 |
59 | ### Mask.maskOpacity
60 |
61 | `thisLayer.mask("Mask 1").maskOpacity`
62 |
63 | #### Description
64 |
65 | Returns the opacity value of a mask as a percentage.
66 |
67 | #### Type
68 |
69 | Number
70 |
71 | ---
72 |
73 | ### Mask.maskPath
74 |
75 | `thisLayer.mask("Mask 1").maskPath`
76 |
77 | #### Description
78 |
79 | Returns the actual mask [Path](./path-property.md).
80 |
81 | #### Type
82 |
83 | [Path object](./path-property.md)
84 |
--------------------------------------------------------------------------------
/docs/objects/path-property.md:
--------------------------------------------------------------------------------
1 | # Path Property
2 |
3 | `thisLayer.mask("Mask 1").maskPath`
4 |
5 | `thisLayer.content("Shape 1").content("Path 1").path;`
6 |
7 | !!! note
8 | This functionality was added in After Effects 15.0 (CC)
9 |
10 | This category contains information relating to mask & shape *paths*.
11 |
12 | !!! info
13 | On this page, we're going to use `thisLayer.mask("Mask 1").maskPath` as a sample on how to call these items, however note that any method that returns a [Path](#) will work.
14 |
15 | ---
16 |
17 | ## Attributes
18 |
19 | ### name
20 |
21 | `thisLayer.mask("Mask 1").maskPath.name`
22 |
23 | #### Description
24 |
25 | Returns the name of the property.
26 |
27 | #### Type
28 |
29 | String
30 |
31 | ---
32 |
33 | ## Methods
34 |
35 | ### PathProperty.createPath()
36 |
37 | `thisLayer.mask("Mask 1").maskPath.createPath(points=[[0,0], [100,0], [100,100], [0,100]], inTangents=[], outTangents=[], is_closed=true)`
38 |
39 | #### Description
40 |
41 | Creates a path object from a set of points and tangents.
42 |
43 | The [`points()`](#pathpropertypoints), [`inTangents()`](#pathpropertyintangents), [`outTangents()`](#pathpropertyouttangents), and [`isClosed()`](#pathpropertyisclosed) methods of a path can be passed into the `points`, `inTangents`, `outTangents`, and `is_closed` parameters to duplicate a path.
44 |
45 | The points and tangents of the same path can be passed into `createPath()` with modifications to generate a different result.
46 |
47 | #### Parameters
48 |
49 | +---------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
50 | | Parameter | Type | Description |
51 | +===============+=============================+=============================================================================================================================================================================================================================+
52 | | `points` | Array of number pair arrays | Optional. An array of number pair arrays representing the `[x, y]` coordinates of the points. The array must contain at least 1 item, and can be of any greater length. Defaults to `[[0,0], [100,0], [100,100], [0,100]]`. |
53 | +---------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
54 | | `inTangents` | Array of number pair arrays | Optional. An array of number pair arrays representing their `[x, y]` *offset* coordinates. The length of this array must be exactly the same as the `points` parameter. Defaults to `[]`. |
55 | | | | |
56 | | | | Coordinate values are offset relative to the parent point's coordinates. i.e. The value `[0, 0]` creates no curvature at the incoming tangent. |
57 | +---------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
58 | | `outTangents` | Array of number pair arrays | Optional. See `inTangents`. Defaults to `[]`. |
59 | | `is_closed` | Boolean | Optional. Defaults to `true`. |
60 | +---------------+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
61 |
62 | #### Returns
63 |
64 | [Path](#)
65 |
66 | #### Example
67 |
68 | For example, the following expression will remove curves from Mask 1 by not passing the inTangents or outTangents parameters:
69 |
70 | ```js
71 | const myMask = mask("Mask 1").path;
72 | myMask.createPath(myMask.points());
73 | ```
74 |
75 | The following example passes the points and tangents of Mask 1 and converts it to an open path by setting `is_closed` to `false`:
76 |
77 | ```js
78 | const myMask = mask("Mask 1").path;
79 | myMask.createPath(myMask.points(), myMask.inTangents(), myMask.outTangents(), false);
80 | ```
81 |
82 | ---
83 |
84 | ### PathProperty.inTangents()
85 |
86 | `thisLayer.mask("Mask 1").maskPath.inTangents([t=time])`
87 |
88 | #### Description
89 |
90 | Get the `[x, y]` coordinates of the incoming tangent handle for all points on a path.
91 |
92 | Tangent coordinate values are offset relative to the parent point's coordinates (i.e. the value `[0, 0]` creates no curvature at the incoming tangent).
93 |
94 | This method can be passed into the [`createPath()`](#pathpropertycreatepath) method for the `inTangents` parameter when duplicating a path.
95 |
96 |
97 | #### Parameters
98 |
99 | | Parameter | Type | Description |
100 | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
101 | | `t` | Number | Optional. The specified time (in comp seconds) to sample the tangents. Defaults to `time` (the current comp time, in seconds). |
102 |
103 | #### Returns
104 |
105 | Array of number pair arrays, rounded to the fourth decimal place
106 |
107 | ---
108 |
109 | ### PathProperty.isClosed()
110 |
111 | `thisLayer.mask("Mask 1").maskPath.isClosed()`
112 |
113 | #### Description
114 |
115 | Determines if the path is open or closed. Returns `true` if the path is closed, `false` if the path is open.
116 |
117 | This method can be passed into the [`createPath()`](#pathpropertycreatepath) method for the `is_closed` parameter when duplicating a path.
118 |
119 | #### Returns
120 |
121 | Boolean
122 |
123 | ---
124 |
125 | ### PathProperty.normalOnPath()
126 |
127 | `thisLayer.mask("Mask 1").maskPath.normalOnPath(percentage=0.5, t=time)`
128 |
129 | #### Description
130 |
131 | Get the calculated `[x, y]` coordinates of the normal for an arbitrary point along a path.
132 |
133 | Coordinate values of normals are offset relative to the parent point's coordinates (i.e. the value `[0, 0]` is the same as the parent point).
134 |
135 | The normal's parent point is expressed as a percentage of the arc-length of the path. Read the description of the [`pointOnPath()`](#pathpropertypointonpath) method for details about arc-length percentage.
136 |
137 | The linear distance between the parent point's coordinates and `normalOnPath()` coordinates will always be `1`.
138 |
139 | #### Parameters
140 |
141 | | Parameter | Type | Description |
142 | | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
143 | | `percentage` | Number | Optional. The percentage along the path at which to sample the normal. Defaults to `0.5` (50%). |
144 | | `t` | Number | Optional. The specified time (in comp seconds) to sample the path. Defaults to `time` (the current comp time, in seconds). |
145 |
146 | #### Returns
147 |
148 | A number pair array
149 |
150 | #### Example
151 |
152 | **Sample a normal and make it longer:**
153 |
154 | ```js
155 | myPath.normalOnPath() * 100
156 | ```
157 |
158 | ---
159 |
160 | ### PathProperty.outTangents()
161 |
162 | `thisLayer.mask("Mask 1").maskPath.outTangents([t=time])`
163 |
164 | #### Description
165 |
166 | Get the `[x, y]` coordinates of the outgoing tangent handle for all points on a path.
167 |
168 | Tangent coordinate values are offset relative to the parent point's coordinates (i.e. the value `[0, 0]` creates no curvature at the outgoing tangent).
169 |
170 | This method can be passed into the [`createPath()`](#pathpropertycreatepath) method for the `outTangents` parameter when duplicating a path.
171 |
172 | #### Parameters
173 |
174 | | Parameter | Type | Description |
175 | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
176 | | `t` | Number | Optional. The specified time (in comp seconds) to sample the tangents. Defaults to `time` (the current comp time, in seconds). |
177 |
178 | #### Returns
179 |
180 | Array of number pair arrays, rounded to the fourth decimal place
181 |
182 | ---
183 |
184 | ### PathProperty.pointOnPath()
185 |
186 | `thisLayer.mask("Mask 1").maskPath.pointOnPath([percentage=0.5][, t=time])`
187 |
188 | #### Description
189 |
190 | Get the `[x, y]` coordinates of an arbitrary point along a path.
191 |
192 | The point is expressed as a percentage of the arc-length of the path. `0.0` (0%) is the first point and `1.0` (100%) is the last point. When the path is closed, 0% and 100% will return the same coordinates.
193 |
194 | !!! info
195 | Percentage of arc-length is used to ensure uniform speed along the path.
196 |
197 | Other than 0% and 100%, percentages do not necessarily correlate with the Bezier points on the path. (i.e., For a path with three points, the second point will not necessarily be at 50%.)
198 |
199 | This also means that for an open path and closed path with identical points, the percentage along the open path will not return the same coordinates as the closed path due to the additional length of the closed path.
200 |
201 | | Parameter | Type | Description |
202 | | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
203 | | `percentage` | Number | Optional. The percentage along the path at which to sample the point. Defaults to `0.5` (50%). |
204 | | `t` | Number | Optional. The specified time (in comp seconds) to sample the path. Defaults to `time` (the current comp time, in seconds). |
205 |
206 | #### Returns
207 |
208 | A number pair array
209 |
210 | ---
211 |
212 | ### PathProperty.points()
213 |
214 | `thisLayer.mask("Mask 1").maskPath.points([t=time])`
215 |
216 | #### Description
217 |
218 | Get the x,y coordinates of all points on a path.
219 |
220 | The returned values are relative, depending on the context:
221 | - Coordinates for **layer mask path points** are relative to the layer's origin in its upper-left hand corner.
222 | - Coordinates for **Bezier shape path points** are are relative to the anchor point of the path's shape group
223 | - (ex., "Transform: Shape 1 > Anchor Point").
224 | - Coordinates for **brush stroke path points** are relative to the **start of the stroke**; the first point is `[0,0]`.
225 | - This method can be passed into the [`createPath()`](#pathpropertycreatepath) method for the points parameter when duplicating a path.
226 |
227 | #### Parameters
228 |
229 | | Parameter | Type | Description |
230 | | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
231 | | `t` | Number | Optional. The specified time (in comp seconds) to sample the path. Defaults to `time` (the current comp time, in seconds). |
232 |
233 | #### Returns
234 |
235 | Array of number pair arrays, rounded to the fourth decimal place
236 |
237 | #### Example
238 |
239 | **Read the coordinates of the first vertex of Mask 1 on Dark Gray Solid 1 and converts them to composition coordinates.**
240 |
241 | Apply this to a 2D point control of an effect, such as Write-on or CC Particle Systems II, to make the effect trace or track the first point of an animated mask.
242 |
243 | Duplicate the effect and change the path points index value ([0]) to trace or track the other points of the mask.
244 |
245 | ```js
246 | const myLayer = thisComp.layer("Dark Gray Solid 1");
247 | myLayer.toComp(myLayer.mask("Mask 1").maskPath.points()[0]);
248 | ```
249 |
250 | ---
251 |
252 | ### PathProperty.tangentOnPath()
253 |
254 | `thisLayer.mask("Mask 1").maskPath.tangentOnPath([percentage=0.5][, t=time])`
255 |
256 | #### Description
257 |
258 | Get the calculated `[x, y]` coordinates of the outgoing tangent handle for an arbitrary point along a path.
259 |
260 | Tangent coordinate values are offset relative to the parent point's coordinates (i.e. the value [0, 0] creates no curvature at the outgoing tangent). Values will differ from those returned by `outTangents()` if a user-defined point also exists at that arc-length pecentage.
261 |
262 | The incoming tangent handle is the inverse of this value (multiply the `[x, y]` coordinates by `-1`).
263 |
264 | The tangent's parent point is expressed as a percentage of the arc-length of the path. Read the description of the [`pointOnPath()`](#pathpropertypointonpath) method for details about arc-length percentage.
265 |
266 | The linear distance between the parent point's coordinates and `tangentOnPath()` coordinates will always be `1`.
267 |
268 | #### Parameters
269 |
270 |
271 | | Parameter | Type | Description |
272 | | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
273 | | `percentage` | Number | Optional. The percentage along the path at which to sample the tangent. Defaults to `0.5` (50%). |
274 | | `t` | Number | Optional. The specified time (in comp seconds) to sample the path. Defaults to `time` (the current comp time, in seconds). |
275 |
276 | #### Returns
277 |
278 | A number pair array
279 |
280 | #### Example
281 |
282 | **Sample a tangent and make it longer:**
283 |
284 | ```js
285 | myPath.tangentOnPath() * 100
286 | ```
287 |
288 | ---
289 |
290 | ## Example
291 |
292 | Writes the list of point and tangent coordinates from Path 1 of Shape 1 on layer Shape Layer 1, at `time=0`, into a string.
293 |
294 | Apply this to the source text property of a text layer for a readout of the coordinates and incoming and outgoing tangents of the shape.
295 |
296 | ```js
297 | let pointsList = "";
298 | const sampleTime = 0;
299 | const myShape = thisComp.layer("Shape Layer 1").content("Shape 1").content("Path 1").path;
300 |
301 | for (i = 0; i < myShape.points(sampleTime).length; i++) {
302 | pointsList += "c: " + myShape.points(sampleTime)[i].toString() + " i: " + myShape.inTangents(sampleTime)[i].toString() + " o: " + myShape.outTangents(sampleTime)[i].toString() + "\n";
303 | }
304 |
305 | pointsList;
306 | ```
307 |
--------------------------------------------------------------------------------
/docs/objects/project.md:
--------------------------------------------------------------------------------
1 | # Project
2 |
3 | `thisProject`
4 |
5 | This category holds info related to your current *project* as a whole -- that is, the current AEP. Thus, changing the corresponding project settings will also update the values that these expressions return.
6 |
7 | ---
8 |
9 | ## Attributes
10 |
11 | ### Project.bitsPerChannel
12 |
13 | `thisProject.bitsPerChannel`
14 |
15 | #### Description
16 |
17 | The color depth of the project in bits per channel (bpc), as set in *Project Settings > Color Management*
18 |
19 | They are one of 8, 16, or 32. Equivalent to the scripting project attribute [`app.project.bitsPerChannel`](https://ae-scripting.docsforadobe.dev/general/project/#projectbitsperchannel).
20 |
21 | #### Type
22 |
23 | Number
24 |
25 | #### Example
26 |
27 | ```js
28 | thisProject.bitsPerChannel
29 | ```
30 |
31 | ---
32 |
33 | ### Project.fullPath
34 |
35 | `thisProject.fullPath`
36 |
37 | #### Description
38 |
39 | The platform-specific absolute file path, including the project file name. If the project has not been saved, it returns an empty string.
40 |
41 | #### Type
42 |
43 | String
44 |
45 | #### Example
46 |
47 | ```js
48 | thisProject.fullPath
49 | ```
50 |
51 | ---
52 |
53 | ### Project.linearBlending
54 |
55 | `thisProject.linearBlending`
56 |
57 | #### Description
58 |
59 | The state of the Blend Colors Using 1.0 Gamma option in *Project Settings > Color Management*.
60 |
61 | Equivalent to the scripting project attribute [`app.project.linearBlending`](https://ae-scripting.docsforadobe.dev/general/project/#projectlinearblending).
62 |
63 | #### Type
64 |
65 | Boolean
66 |
67 | #### Example
68 |
69 | ```js
70 | thisProject.linearBlending
71 | ```
72 |
--------------------------------------------------------------------------------
/docs/objects/property.md:
--------------------------------------------------------------------------------
1 | # Property
2 |
3 | This category holds generic entries relating to generic *properties*.
4 |
5 | In expressions, a Property is *typically* anything that exists in the timeline (even if it can't be keyframed, or hold an expression).
6 |
7 | ??? example "Examples of Properties"
8 |
9 | All of the following AE items are actually "Properties" for the use of expressions, along with *some* ways to access those properties by code:
10 |
11 | - Position (`thisLayer.transform.position`, `layer.position`)
12 | - Scale (`thisLayer.transform.scale`, `layer.scale`)
13 | - A slider effect's *actual slider* (`effect("Slider Control")("Slider")`, `effect("Slider Control")(1)`)
14 | - A text layer's [Text](../text/text.md) property (`thisLayer.text`)
15 | - *Note that in this case, Text also has its own special items, found in the above link.*
16 |
17 | !!! info
18 | On this page, we're going to use `thisLayer.position` as a sample on how to call these items, however note that any method that returns a [Property](#) will work.
19 |
20 | ---
21 |
22 | ## Attributes
23 |
24 | ### name
25 |
26 | `thisLayer.position.name`
27 |
28 | #### Description
29 |
30 | Returns the name of the property or property group.
31 |
32 | #### Type
33 |
34 | String
35 |
36 | ---
37 |
38 | ### numKeys
39 |
40 | `thisLayer.position.numKeys`
41 |
42 | #### Description
43 |
44 | Returns the number of keyframes on a property, or the number of markers on a marker property.
45 |
46 | !!! note
47 | If you use the **Separate Dimensions** command to separate the dimensions of the Position property into individual components, the number of keyframes changes, so the value returned by this method changes.
48 |
49 | #### Type
50 |
51 | Number
52 |
53 | ---
54 |
55 | ### propertyIndex
56 |
57 | `thisLayer.position.propertyIndex`
58 |
59 | #### Description
60 |
61 | Returns the index of a property relative to other properties in its property group, including property groups within masks, effects, text animators, selectors, shapes, trackers, and track points.
62 |
63 | #### Type
64 |
65 | Number
66 |
67 | ---
68 |
69 | ### speed
70 |
71 | `thisLayer.position.speed`
72 |
73 | #### Description
74 |
75 | Returns a 1-dimensional, positive speed value equal to the speed at which the property is changing at the default time.
76 |
77 | !!! note
78 | This can be used only for spatial properties.
79 |
80 | #### Type
81 |
82 | Number
83 |
84 | ---
85 |
86 | ### value
87 |
88 | `thisLayer.position.value`
89 |
90 | #### Description
91 |
92 | Returns the value of a property at the current time.
93 |
94 | #### Type
95 |
96 | Number, Array, or String
97 |
98 | ---
99 |
100 | ### velocity
101 |
102 | `thisLayer.position.velocity`
103 |
104 | #### Description
105 |
106 | Returns the temporal velocity value at the current time. For spatial properties, such as Position, it returns the tangent vector value. The result is the same dimension as the property.
107 |
108 | #### Type
109 |
110 | Number or Array
111 |
112 | ---
113 |
114 | ## Methods
115 |
116 | ### key()
117 |
118 | `thisLayer.position.key(index)`
119 |
120 | #### Description
121 |
122 | Returns the Key or MarkerKey object by index number.
123 |
124 | #### Parameters
125 |
126 | | Parameter | Type | Description |
127 | | --------- | ------ | ----------------------------------- |
128 | | `index` | Number | The key (or MarkerKey) index number |
129 |
130 | #### Returns
131 |
132 | Key or MarkerKey
133 |
134 | #### Example
135 |
136 | To retrieve the first keyframe on a property:
137 |
138 | ```js
139 | thisLayer.scale.key(1);
140 | ```
141 |
142 | To retrieve the *last* keyframe on a property:
143 |
144 | ```js
145 | thisLayer.rotation.key(thisLayer.rotation.numKeys);
146 | ```
147 |
148 | ---
149 |
150 | ### key()
151 |
152 | `thisLayer.position.key(markerName)`
153 |
154 | #### Description
155 |
156 | Returns the MarkerKey object with this name.
157 |
158 | !!! note
159 | This can be used only on marker properties.
160 |
161 | #### Parameters
162 |
163 | | Parameter | Type | Description |
164 | | ------------ | ------ | ----------------------------------------------------- |
165 | | `markerName` | String | The name of the marker to return the matching key of. |
166 |
167 | #### Returns
168 |
169 | MarkerKey
170 |
171 | ---
172 |
173 | ### loopIn()
174 |
175 | `thisLayer.position.loopIn([type="cycle"][, numKeyframes=0])`
176 |
177 | #### Description
178 |
179 | Loops a segment of time that is measured from the first keyframe on the layer forward toward the Out point of the layer. The loop plays from the In point of the layer.
180 |
181 | You can use keyframe-looping methods to repeat a series of keyframes. You can use these methods on most properties. Exceptions include:
182 | - properties that can't be expressed by simple numeric values in the Timeline panel, such as:
183 | - the Source Text property,
184 | - path shape properties, and
185 | - the Histogram property for the Levels effect.
186 |
187 | Keyframes or duration values that are too large are clipped to the maximum allowable value. Values that are too small result in a constant loop.
188 |
189 | #### Parameters
190 |
191 | | Parameter | Type | Description |
192 | | -------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
193 | | `type` | Predefined string as defined in [Loop Types](#loop-types) | Optional. The loop type to use. Defaults to `"cycle"` |
194 | | `numKeyframes` | Number | Optional. The segment to loop, from keyframe #1 to keyframe #`numKeyframes + 1`. If unspecified (or `0`), all keyframes loop. Defaults to `0`. |
195 |
196 | #### Returns
197 |
198 | A looped value of the same property type as this current property.
199 |
200 | #### Example
201 |
202 | **To loop the segment bounded by the first and fourth keyframes:**
203 |
204 | ```js
205 | loopIn("cycle", 3);
206 | ```
207 |
208 | **To loop forward and backward indefinitely from your current keyframes:**
209 |
210 | ```js
211 | loopIn("continue") + loopOut("continue") - value;
212 | ```
213 |
214 | Note that we need to subtract `value`, because both `loopIn()` and `loopOut()` include the current value; by adding them, we have two copies of the current value, and need to remove one (the ` - value`) to get back to the proper keyframe value.
215 |
216 | ---
217 |
218 | ### loopInDuration()
219 |
220 | `thisLayer.position.loopInDuration([type="cycle"][, duration=0])`
221 |
222 | #### Description
223 |
224 | Loops a segment of time that is measured from the first keyframe on the layer forward toward the Out point of the layer.
225 |
226 | #### Parameters
227 |
228 | | Parameter | Type | Description |
229 | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
230 | | `type` | Predefined string as defined in [Loop Types](#loop-types) | Optional. The loop type to use. Defaults to `"cycle"` |
231 | | `duration` | Number | Optional. The number of composition seconds in a segment to loop, measured from the first keyframe. If unspecified (or `0`), the segment to loop begins at the layer Out point. Defaults to `0`. |
232 |
233 | #### Returns
234 |
235 | A looped value of the same property type as this current property.
236 |
237 | #### Example
238 |
239 | **To loop the first second of the entire animation:**
240 |
241 | ```js
242 | loopInDuration("cycle", 1);
243 | ```
244 |
245 | ---
246 |
247 | ### loopOut()
248 |
249 | `thisLayer.position.loopOut([type="cycle"][, numKeyframes=0])`
250 |
251 | #### Description
252 |
253 | Loops a segment of time that is measured from the last keyframe on the layer back toward the In point of the layer. The loop plays until the Out point of the layer.
254 |
255 | !!! info
256 | David Van Brink provides an instructional article and sample project on his [omino pixel blog](http://omino.com/pixelblog/2007/11/23/salmonella/) that show how to use the Echo effect, the Particle Playground effect, and the `loopOut()` method to animate a swarm of stylized swimming bacteria.
257 |
258 | #### Parameters
259 |
260 | | Parameter | Type | Description |
261 | | -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
262 | | `type` | Predefined string as defined in [Loop Types](#loop-types) | Optional. The loop type to use. Defaults to `"cycle"` |
263 | | `numKeyframes` | Number | Optional. The segment to loop, measured backward from the last keyframe. If unspecified (or `0`), all keyframes loop. Defaults to `0`. |
264 |
265 | #### Returns
266 |
267 | A looped value of the same property type as this current property.
268 |
269 | #### Example
270 |
271 | **To loop the segment bounded by the last keyframe and second-to-last keyframe:**
272 |
273 | ```js
274 | loopOut("cycle", 1);
275 | ```
276 |
277 | ---
278 |
279 | ### loopOutDuration()
280 |
281 | `thisLayer.position.loopOutDuration([type="cycle"][, duration=0])`
282 |
283 | #### Description
284 |
285 | Loops a segment of time that is measured from the last keyframe on the layer back toward the In point of the layer. The loop plays until the Out point of the layer.
286 |
287 | #### Parameters
288 |
289 | | Parameter | Type | Description |
290 | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
291 | | `type` | Predefined string as defined in [Loop Types](#loop-types) | Optional. The loop type to use. Defaults to `"cycle"` |
292 | | `duration` | Number | Optional. The number of composition seconds in a segment to loop, measured backward from the last keyframe. If unspecified (or `0`), the segment to loop begins at the layer In point. Defaults to `0`. |
293 |
294 | #### Returns
295 |
296 | A looped value of the same property type as this current property.
297 |
298 | #### Example
299 |
300 | **To loop the last second of the entire animation:**
301 |
302 | ```js
303 | loopOutDuration("cycle", 1);
304 | ```
305 |
306 | ---
307 |
308 | ### nearestKey()
309 |
310 | `thisLayer.position.nearestKey(t)`
311 |
312 | #### Description
313 |
314 | Returns the Key or MarkerKey object nearest to a designated time `t`.
315 |
316 | #### Parameters
317 |
318 | | Parameter | Type | Description |
319 | | --------- | ------ | ------------------------------------- |
320 | | `t` | Number | The time to find the nearest key from |
321 |
322 | #### Returns
323 |
324 | Key or MarkerKey
325 |
326 | #### Example
327 |
328 | **Get the nearest keyframe to the 2-second time in the comp:**
329 |
330 | ```js
331 | const twoSecondKey = thisLayer.scale.nearestKey(2);
332 |
333 | // and then, to get the value of that key:
334 | twoSecondKey.value;
335 | ```
336 |
337 | ---
338 |
339 | ### propertyGroup()
340 |
341 | `thisLayer.position.propertyGroup([countUp=1])`
342 |
343 | #### Description
344 |
345 | Returns a group of properties relative to the property on which the expression is written.
346 |
347 | For example, if you add the `propertyGroup(1)` expression to the Rotation property of a brush stroke, the expression targets the Transform property group, which contains the Rotation property. If you add `propertyGroup(2)` instead, the expression targets the Brush property group.
348 |
349 | This method lets you establish name-independent relationships in the property hierarchy. It is especially useful when duplicating properties that contain expressions.The `numProperties` method for `propertyGroup` returns the number of properties in the property group.
350 |
351 | #### Parameters
352 |
353 | | Parameter | Type | Description |
354 | | --------- | ------ | ------------------------------------------------------------------------------------- |
355 | | `countUp` | Number | Optional. The number of property groups "up" the hierarchy to climb. Defaults to `1`. |
356 |
357 | #### Returns
358 |
359 | [PropertyGroup object](./propertygroup.md)
360 |
361 | #### Example
362 |
363 | **Return the number of properties in the group that contains the property on which this expression is written:**
364 |
365 | ```js
366 | thisProperty.propertyGroup(1).numProperties;
367 | ```
368 |
369 | ---
370 |
371 | ### smooth()
372 |
373 | `thisLayer.position.smooth([width=.2][, samples=5][, t=time])`
374 |
375 | #### Description
376 |
377 | Smooths the property values over time, converting large, brief deviations in the value to smaller, more evenly distributed deviations. This smoothing is accomplished by applying a box filter to the value of the property at the specified time.
378 |
379 | #### Parameters
380 |
381 | +-----------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
382 | | Parameter | Type | Description |
383 | +===========+========+===========================================================================================================================================================+
384 | | `width` | Number | Optional. The range of time (in seconds) over which the filter is averaged. Defaults to `0.2`. |
385 | +-----------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
386 | | `samples` | Number | Optional. The number of discrete samples evenly spaced over time. Use a larger value for greater smoothness (but decreased performance). Defaults to `5`. |
387 | | | | |
388 | | | | Generally, you'll want samples to be an odd number so that the value at the current time is included in the average. |
389 | +-----------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
390 | | `t` | Number | Optional. The specified time (in comp seconds) to apply the smoothing filter to. Defaults to `time` (the current comp time, in seconds). |
391 | +-----------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
392 |
393 | #### Returns
394 |
395 | Number or Array
396 |
397 | #### Example
398 |
399 | **To smooth a position property's animation:**
400 |
401 | ```js
402 | position.smooth(0.1, 5)
403 | ```
404 |
405 | ---
406 |
407 | ### speedAtTime()
408 |
409 | `thisLayer.position.speedAtTime(t)`
410 |
411 | #### Description
412 |
413 | Returns the spatial speed value at the specified time.
414 |
415 | #### Parameters
416 |
417 | | Parameter | Type | Description |
418 | | --------- | ------ | ----------------------------------------------------------- |
419 | | `t` | Number | The specified time at which to get the spatial speed value. |
420 |
421 | #### Returns
422 |
423 | Number
424 |
425 | ---
426 |
427 | ### temporalWiggle()
428 |
429 | `thisLayer.position.temporalWiggle(freq, amp[, octaves=1][, amp_mult=0.5][, t=time])`
430 |
431 | #### Description
432 |
433 | Samples the property at a wiggled time.
434 |
435 | For this function to be meaningful, the property it samples must be animated, because the function alters only the time of sampling, not the value.
436 |
437 | #### Parameters
438 |
439 | | Parameter | Type | Description |
440 | | ---------- | ------ | -------------------------------------------------------------------------------------- |
441 | | `freq` | Number | The frequency, in wiggles per second. |
442 | | `amp` | Number | The amplitude, in units of the property to which it is applied. |
443 | | `octaves` | Number | Optional. The number of octaves of noise to add together. Defaults to `1`. |
444 | | `amp_mult` | Number | Optional. The amount that `amp` is multiplied by for each octave. Defaults to `0.5`. |
445 | | `t` | Number | Optional. The base start time. Defaults to `time` (the current comp time, in seconds). |
446 |
447 | #### Returns
448 |
449 | Number or Array
450 |
451 | #### Example
452 |
453 | **To add a temporal wiggle to scale:**
454 |
455 | ```js
456 | scale.temporalWiggle(5, 0.2)
457 | ```
458 |
459 | ---
460 |
461 | ### valueAtTime()
462 |
463 | `thisLayer.position.valueAtTime(t)`
464 |
465 | #### Description
466 |
467 | Returns the value of a property at the specified time, in seconds.
468 |
469 | !!! note
470 | Dan Ebberts provides more examples and techniques for using the `valueAtTime` and `velocityAtTime` methods on [MotionScript](http://www.motionscript.com/mastering-expressions/follow-the-leader.html).
471 |
472 | #### Parameters
473 |
474 | | Parameter | Type | Description |
475 | | --------- | ------ | ------------------------------------------- |
476 | | `t` | Number | The time, in seconds, to get the value from |
477 |
478 | #### Returns
479 |
480 | Number or Array
481 |
482 | #### Example
483 |
484 | For example, to have a property value for each frame chosen randomly from a set of four values, set your four values as keyframes at `0`, `1`, `2`, and `3` seconds, and then apply the following expression to the property:
485 |
486 | ```js
487 | valueAtTime(random(4))
488 | ```
489 |
490 | ---
491 |
492 | ### velocityAtTime()
493 |
494 | `thisLayer.position.velocityAtTime(t)`
495 |
496 | #### Description
497 |
498 | Returns the temporal velocity value at the specified time.
499 |
500 | #### Parameters
501 |
502 | | Parameter | Type | Description |
503 | | --------- | ------ | ------------------------------------------------------- |
504 | | `t` | Number | The time, in seconds, to get the temporal velocity from |
505 |
506 | #### Returns
507 |
508 | Number or Array
509 |
510 | ---
511 |
512 | ### wiggle()
513 |
514 | `thisLayer.position.wiggle(freq, amp[, octaves=1][, amp_mult=0.5][, t=time])`
515 |
516 | #### Description
517 |
518 | Randomly shakes (wiggles) the value of the property.
519 |
520 | !!! note
521 | Dan Ebberts provides an example expression and a detailed explanation on his [website](http://www.motionscript.com/design-guide/looping-wiggle.html) that shows how to use the time parameter of the wiggle method to create a looping animation.
522 |
523 | #### Parameters
524 |
525 | +------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
526 | | Parameter | Type | Description |
527 | +============+========+=========================================================================================================================================================================================================================================+
528 | | `freq` | Number | Frequency, in wiggles per second. |
529 | +------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
530 | | `amp` | Number | Amplitude, in units of the property to which it is applied. |
531 | +------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
532 | | `octaves` | Number | Optional. Number of octaves of noise to add together. This value controls how much detail is in the wiggle. |
533 | | | | |
534 | | | | Make this value higher than the default to include higher frequencies or lower to include amplitude harmonics in the wiggle. Defaults to `1`. |
535 | +------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
536 | | `amp_mult` | Number | Optional. Amount that `amp` is multiplied by for each octave. This value controls how fast the harmonics drop off. |
537 | | | | |
538 | | | | Make this value closer to `1` to have the harmonics added at the same amplitude as the base frequency, or closer to `0` to add in less detail. Defaults to `0.5`. |
539 | +------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
540 | | `t` | Number | Optional. Base start time. This value defaults to the current time. Use this parameter if you want the output to be a wiggle of the property value sampled at a different time. Defaults to `time` (the current comp time, in seconds). |
541 | +------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
542 |
543 | #### Returns
544 |
545 | Number or Array
546 |
547 | #### Example
548 |
549 | This produces about `5` wiggles per second with an average size of about 20 pixels. In addition to the main wiggle, two more levels of detailed wiggles occur with a frequency of `10` and `20` wiggles per second, and sizes of `10` and `5` pixels, respectively:
550 |
551 | ```js
552 | position.wiggle(5, 20, 3, 0.5);
553 | ```
554 |
555 | This example, on a two-dimensional property such as Scale, wiggles both dimensions by the same amount:
556 |
557 | ```js
558 | const v = wiggle(5, 10);
559 |
560 | [v[0], v[0]];
561 | ```
562 |
563 | This example, on a two-dimensional property, wiggles only along the y-axis:
564 |
565 | ```js
566 | const freq = 3;
567 | const amp = 50;
568 | const w = wiggle(freq,amp);
569 |
570 | [value[0], w[1]];
571 | ```
572 |
573 | ---
574 |
575 | ## Loop Types
576 |
577 | The following loop types are predefined strings used in the "type" parameter for:
578 |
579 | - [loopIn()](#loopin)
580 | - [loopInDuration()](#loopinduration)
581 | - [loopOut()](#loopout)
582 | - [loopOutDuration()](#loopoutduration)
583 |
584 | +--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----+
585 | | Type | Behaviour | |
586 | +==============+=======================================================================================================================================================================================================================================================+=====+
587 | | `"cycle"` | Default. Repeats the specified segment. | |
588 | +--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----+
589 | | `"pingpong"` | Repeats the specified segment, alternating between forward and backward. | |
590 | +--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----+
591 | | `"offset"` | Repeats the specified segment, but offsets each cycle by the difference in the value of the property at the start and end of the segment, multiplied by the number of times the segment has looped. | |
592 | +--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----+
593 | | `"continue"` | Does not repeat the specified segment, but continues to animate a property based on the velocity at the first or last keyframe. | |
594 | | | | |
595 | | | For example, if the last keyframe of a Scale property of a layer is `100%`, the layer continues to scale from `100%` to the Out point, instead of looping directly back to the Out point. This type does not accept a keyframes or duration argument. | |
596 | +--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----+
597 |
--------------------------------------------------------------------------------
/docs/objects/propertygroup.md:
--------------------------------------------------------------------------------
1 | # PropertyGroup
2 |
3 | `thisLayer("ADBE Effect Parade")`
4 |
5 | All properties in the Timeline are organized into groups, which share some attributes of properties like `name` and `propertyIndex`.
6 |
7 | Property Groups can have a fixed number of properties (e.g. an individual effect whose properties don't change) or a variable number of properties (e.g. the "Effects" group itself which can have any number of effect within it).
8 |
9 | #### Top-level groups in a Layer
10 |
11 | - Motion Trackers
12 | - Text
13 | - Contents
14 | - Masks
15 | - Effects
16 | - Transform
17 | - Layer Styles
18 | - Geometry Options
19 | - Material Options
20 | - Audio
21 | - Data
22 | - Essential Properties
23 |
24 | #### Nested groups
25 |
26 | - Individual effects
27 | - Individual masks
28 | - Shape groups
29 | - Text Animators
30 |
31 | !!! info
32 | On this page, we're going to use `thisLayer("ADBE Effect Parade")` (the "Effects" group) as a sample on how to call these items, however note that any method that returns a [PropertyGroup](#) will work.
33 |
34 | ---
35 |
36 | ## Attributes
37 |
38 | ### PropertyGroup.name
39 |
40 | `thisLayer("ADBE Effect Parade").name`
41 |
42 | #### Description
43 |
44 | Returns the name of the property group.
45 |
46 | #### Type
47 |
48 | String
49 |
50 | ---
51 |
52 | ### PropertyGroup.numProperties
53 |
54 | `thisLayer("ADBE Effect Parade").numProperties`
55 |
56 | #### Description
57 |
58 | Returns the number of properties or groups directly within a group.
59 |
60 | !!! note
61 | This does not include properties nested inside child groups.
62 |
63 | #### Type
64 |
65 | Number
66 |
67 | #### Example
68 |
69 | To find the number of effects applied to a layer:
70 |
71 | ```js
72 | thisLayer("ADBE Effect Parade").numProperties
73 | ```
74 |
75 | ---
76 |
77 | ### PropertyGroup.propertyIndex
78 |
79 | `thisLayer("ADBE Effect Parade").propertyIndex`
80 |
81 | #### Description
82 |
83 | Returns the index of a property group relative to other properties or groups in its property group.
84 |
85 | #### Type
86 |
87 | Number
88 |
89 | ---
90 |
91 | ## Methods
92 |
93 | ### PropertyGroup.propertyGroup()
94 |
95 | `propertyGroup([countUp=1])`
96 |
97 | #### Description
98 |
99 | Returns a higher-level property group relative to the property group on which the method is called.
100 |
101 | See [`propertyGroup()`](property.md#propertygroup) for additional details.
102 |
103 | #### Parameters
104 |
105 | | Parameter | Type | Description |
106 | | --------- | ------ | ------------------------------------------------------------------------------------- |
107 | | `countUp` | Number | Optional. The number of property groups "up" the hierarchy to climb. Defaults to `1`. |
108 |
109 |
110 | #### Returns
111 |
112 | [PropertyGroup object](#)
113 |
--------------------------------------------------------------------------------
/docs/text/sourcetext.md:
--------------------------------------------------------------------------------
1 | # Source Text
2 |
3 | `text.sourceText`
4 |
5 | These functions are accessible on the [Text.sourceText](text.md#textsourcetext) object in AE 17.0 and later.
6 |
7 | ---
8 |
9 | ## Attributes
10 |
11 | ### SourceText.isHorizontalText
12 |
13 | `text.sourceText.isHorizontalText`
14 |
15 | !!! note
16 | This functionality was added in After Effects 25.0.
17 |
18 | #### Description
19 |
20 | Returns `true` if the Text layer is horizontal and `false` if it is vertical.
21 |
22 | #### Type
23 |
24 | Boolean
25 |
26 | ---
27 |
28 | ### SourceText.isParagraphText
29 |
30 | `text.sourceText.isParagraphText`
31 |
32 | !!! note
33 | This functionality was added in After Effects 25.0.
34 |
35 | #### Description
36 |
37 | Returns `true` if a Text layer is Paragraph text. If the Text layer is a Point text, it returns `false`.
38 |
39 | #### Type
40 |
41 | Boolean
42 |
43 | ---
44 |
45 | ### SourceText.isPointText
46 |
47 | `text.sourceText.isPointText`
48 |
49 | !!! note
50 | This functionality was added in After Effects 25.0.
51 |
52 | #### Description
53 |
54 | Returns `true` if a Text layer is Point text. If the Text layer is Paragraph text, it returns `false`.
55 |
56 | #### Type
57 |
58 | Boolean
59 |
60 | ---
61 |
62 | ### SourceText.isVerticalText
63 |
64 | `text.sourceText.isVerticalText`
65 |
66 | !!! note
67 | This functionality was added in After Effects 25.0.
68 |
69 | #### Description
70 |
71 | Returns `true` if the Text layer is vertical and `false` if it is horizontal.
72 |
73 | #### Type
74 |
75 | Boolean
76 |
77 | ---
78 |
79 | ### SourceText.style
80 |
81 | `text.sourceText.style`
82 |
83 | #### Description
84 |
85 | Returns the [Text Style](./style.md) object for a given `sourceText` property.
86 |
87 | #### Type
88 |
89 | [Text Style](./style.md) object
90 |
91 | ---
92 |
93 | ## Methods
94 |
95 | ### SourceText.createStyle()
96 |
97 | `text.sourceText.createStyle()`
98 |
99 | #### Description
100 |
101 | Used to initialize an empty [Text Style](./style.md) object in which you'd manually bake in specific values.
102 |
103 | #### Returns
104 |
105 | Empty [Text Style](./style.md) object.
106 |
107 | #### Example
108 |
109 | To create a new style with font size 300 and the font Impact:
110 |
111 | ```js
112 | text.sourceText
113 | .createStyle()
114 | .setFontSize(300)
115 | .setFont("Impact");
116 | ```
117 |
118 | ---
119 |
120 | ### SourceText.getStyleAt()
121 |
122 | `text.sourceText.getStyleAt(charIndex[, time])`
123 |
124 | #### Description
125 |
126 | This function returns the [Text Style](./style.md) object of a particular character at a specific time.
127 |
128 | In case the style is keyframed and changes over time, use the second `time` parameter to specify the target time to get the style at.
129 |
130 | !!! note
131 | Using [SourceText.style](#sourcetextstyle) is the same as using `text.sourceText.getStyleAt(0,0)`
132 |
133 | #### Parameters
134 |
135 | | Parameter | Type | Description |
136 | | --------- | ------ | ------------------------------------------------------------------------------------ |
137 | | `index` | Number | The index of the letter or character whose style is needed |
138 | | `time` | Number | Optional. The time within the composition to get the style from. Defaults to `time`. |
139 |
140 | #### Returns
141 |
142 | [Text Style](./style.md) object
143 |
144 | #### Example
145 |
146 | To get the style of the first character at the beginning of the timeline:
147 |
148 | ```js
149 | text.sourceText.getStyleAt(0,0);
150 | ```
151 |
--------------------------------------------------------------------------------
/docs/text/text.md:
--------------------------------------------------------------------------------
1 | # Text
2 |
3 | `text`
4 |
5 | This category holds generic text-related entries for text layers.
6 |
7 | ---
8 |
9 | ## Attributes
10 |
11 | ### Text.sourceText
12 |
13 | `text.sourceText`
14 |
15 | #### Description
16 |
17 | Returns the text content of a text layer.
18 |
19 | !!! note
20 | As of After Effects 17.0, this property returns the [Source Text](./sourcetext.md) object to access text style properties. If no style properties are specified, this returns the text content as expected.
21 |
22 | #### Type
23 |
24 | String of text content, or [Source Text](./sourcetext.md) (AE 17.0+)
25 |
26 | ---
27 |
28 | ### Text.Font...
29 |
30 | #### Description
31 |
32 | !!! note
33 | This isn't actually an expression method! Instead, it's a button from the expression fly-out menu.
34 |
35 | Launches a dialog window for the user to specify a font name and weight.
36 |
37 | Upon selection, the internal font name is injected into the expression editor as a string.
38 |
39 | #### Type
40 |
41 | String
42 |
--------------------------------------------------------------------------------
/mkdocs.yml:
--------------------------------------------------------------------------------
1 | # Do not modify below line! Inherits common components.
2 | INHERIT: ./docs/_global/mkdocs.yml
3 |
4 | #### Site metadata & nav - update these!
5 |
6 | site_name: After Effects Expression Reference
7 | site_url: https://ae-expressions.docsforadobe.dev/
8 | repo_url: https://github.com/docsforadobe/after-effects-expression-reference/
9 | repo_name: "after-effects-expression-reference"
10 |
11 | nav:
12 | - Home: index.md
13 | - Introduction:
14 | - Changelog: introduction/changelog.md
15 | - Resources: introduction/resources.md
16 | - Examples: introduction/examples.md
17 | - General:
18 | - General: general/general.md
19 | - Global: general/global.md
20 | - Time Conversion: general/time-conversion.md
21 | - Vector Math: general/vector-math.md
22 | - Random Numbers: general/random-numbers.md
23 | - Interpolation: general/interpolation.md
24 | - Color Conversion: general/color-conversion.md
25 | - Other Math: general/other-math.md
26 | - Objects:
27 | - Project: objects/project.md
28 | - Comp: objects/comp.md
29 | - Footage: objects/footage.md
30 | - Camera: objects/camera.md
31 | - Light: objects/light.md
32 | - Property Group: objects/propertygroup.md
33 | - Effect: objects/effect.md
34 | - Mask: objects/mask.md
35 | - Property: objects/property.md
36 | - Marker Property: objects/marker-property.md
37 | - Path Property: objects/path-property.md
38 | - Key: objects/key.md
39 | - MarkerKey: objects/markerkey.md
40 | - Layer:
41 | - Layer: layer/layer.md
42 | - Layer Sub-objects: layer/sub-objects.md
43 | - Layer General: layer/general.md
44 | - Layer Properties: layer/properties.md
45 | - Layer Space Transforms: layer/layer-space-transforms.md
46 | - Layer 3D: layer/threed.md
47 | - Text:
48 | - Text: text/text.md
49 | - Source Text: text/sourcetext.md
50 | - Text Style: text/style.md
51 |
52 | #### Additional config below - modify sparingly!
53 |
54 | extra:
55 | # Custom guide-specific overrides
56 | #
57 | # Valid keys are:
58 | # custom_dir: str
59 | # hooks:
60 | # - path/to/hook.py
61 | # not_in_nav:
62 | # - gitignore_style/path/to/exclude
63 | # theme_features:
64 | # - theme.feature
65 | overrides: {}
66 |
67 | # CSS for this guide
68 | extra_css:
69 | - _static/extra.css
70 |
71 | # JS for this guide
72 | extra_javascript:
73 | - _static/extra.js
74 |
75 | markdown_extensions:
76 | attr_list: {}
77 |
78 | plugins: {}
79 |
80 | theme:
81 | icon:
82 | annotation: material/plus-circle-outline
83 |
--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
1 | # After Effects Expression Reference
2 |
3 | This repo hosts the After Effects Expression Reference community docs.
4 |
5 | The original documentation can be found over at [Adobe's Expression Language Reference](https://helpx.adobe.com/after-effects/using/expression-language-reference.html).
6 |
7 | ---
8 |
9 | ## Contributing
10 |
11 | This endeavour is primarily community-supported & run; contributors are welcome and encouraged to suggest fixes, adjustments, notes/warnings, and anything else that may help the project.
12 |
13 | For specific information on how to contribute & best practices, see the [Documentation Contribution Guide](https://docsforadobe.dev/contributing/contribution-guide/).
14 |
15 | ---
16 |
17 | ## Licensing & Ownership
18 |
19 | This project exists for educational purposes only.
20 |
21 | All content is copyright Adobe Systems Incorporated.
22 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | -r docs/_global/requirements.txt
2 |
--------------------------------------------------------------------------------