├── .gitattributes ├── .github └── workflows │ └── ci.yml ├── .gitignore ├── docs ├── CNAME ├── _global │ ├── .gitignore │ ├── css │ │ ├── global-syntax-highlight.css │ │ └── global.css │ ├── hooks │ │ ├── inline_pre_to_code_fence.py │ │ └── merge_inherited_config.py │ ├── js │ │ └── global.js │ ├── mkdocs.yml │ ├── overrides │ │ ├── 404.html │ │ ├── main.html │ │ ├── partials │ │ │ ├── copyright.html │ │ │ └── toc-item.html │ │ └── templates │ │ │ ├── print_site_banner.tpl │ │ │ └── print_site_cover_page.tpl │ ├── readme.md │ ├── requirements.txt │ └── scripts │ │ └── update-common-components.py ├── _static │ └── extra.css ├── general │ ├── color-conversion.md │ ├── general.md │ ├── global.md │ ├── interpolation.md │ ├── other-math.md │ ├── random-numbers.md │ ├── time-conversion.md │ └── vector-math.md ├── index.md ├── introduction │ ├── changelog.md │ ├── examples.md │ └── resources.md ├── layer │ ├── general.md │ ├── layer-space-transforms.md │ ├── layer.md │ ├── properties.md │ ├── sub-objects.md │ └── threed.md ├── objects │ ├── camera.md │ ├── comp.md │ ├── effect.md │ ├── footage.md │ ├── key.md │ ├── light.md │ ├── marker-property.md │ ├── markerkey.md │ ├── mask.md │ ├── path-property.md │ ├── project.md │ ├── property.md │ └── propertygroup.md └── text │ ├── sourcetext.md │ ├── style.md │ └── text.md ├── mkdocs.yml ├── readme.md └── requirements.txt /.gitattributes: -------------------------------------------------------------------------------- 1 | # Override linguist skipping main folder 2 | docs/** -linguist-documentation 3 | docs/** linguist-detectable 4 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: ci 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | - main 8 | permissions: 9 | contents: write 10 | jobs: 11 | deploy: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v4 15 | with: 16 | fetch-depth: 0 17 | - name: Configure Git Credentials 18 | run: | 19 | git config user.name github-actions[bot] 20 | git config user.email 41898282+github-actions[bot]@users.noreply.github.com 21 | 22 | - uses: actions/setup-python@v5 23 | with: 24 | python-version: 3.x 25 | 26 | - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 27 | 28 | - uses: actions/cache@v4 29 | with: 30 | key: mkdocs-material-${{ env.cache_id }} 31 | path: .cache 32 | restore-keys: | 33 | mkdocs-material- 34 | 35 | - name: Install Python dependencies 36 | uses: py-actions/py-dependency-install@v4 37 | 38 | - run: mkdocs gh-deploy --force 39 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.sublime-project 2 | *.sublime-workspace 3 | .DS_Store 4 | .vscode/ 5 | __pycache__/ 6 | site/ 7 | venv/ 8 | -------------------------------------------------------------------------------- /docs/CNAME: -------------------------------------------------------------------------------- 1 | ae-expressions.docsforadobe.dev 2 | -------------------------------------------------------------------------------- /docs/_global/.gitignore: -------------------------------------------------------------------------------- 1 | *.sublime-project 2 | *.sublime-workspace 3 | .DS_Store 4 | .vscode/ 5 | __pycache__/ 6 | site/ 7 | venv/ 8 | -------------------------------------------------------------------------------- /docs/_global/css/global-syntax-highlight.css: -------------------------------------------------------------------------------- 1 | /* Set light & dark mode syntax highlight */ 2 | 3 | @media screen { 4 | /* Light mode */ 5 | [data-md-color-scheme="default"] { 6 | --md-code-fg-color: #36464e; 7 | --md-code-bg-color: #f5f5f5; 8 | --md-code-hl-color: #4287ff; 9 | 10 | --md-code-hl-constant-color: #6e59d9; 11 | --md-code-hl-function-color: #a846b9; 12 | --md-code-hl-keyword-color: #3f6ec6; 13 | --md-code-hl-number-color: #d52a2a; 14 | --md-code-hl-special-color: #db1457; 15 | --md-code-hl-string-color: #1c7d4d; 16 | --md-code-hl-comment-color: var(--md-default-fg-color--light); 17 | --md-code-hl-generic-color: var(--md-default-fg-color--light); 18 | --md-code-hl-name-color: var(--md-code-fg-color); 19 | --md-code-hl-operator-color: var(--md-default-fg-color--light); 20 | --md-code-hl-punctuation-color: var(--md-default-fg-color--light); 21 | --md-code-hl-variable-color: var(--md-default-fg-color--light); 22 | } 23 | 24 | /* Dark mode */ 25 | [data-md-color-scheme="slate"] { 26 | --md-code-bg-color: #272a35; 27 | --md-code-fg-color: #d5d8e2d1; 28 | --md-code-hl-color: #2977ff; 29 | 30 | --md-code-hl-constant-color: #9383e2; 31 | --md-code-hl-function-color: #c973d9; 32 | --md-code-hl-keyword-color: #6791e0; 33 | --md-code-hl-number-color: #e6695b; 34 | --md-code-hl-special-color: #f06090; 35 | --md-code-hl-string-color: #2fb170; 36 | --md-code-hl-comment-color: var(--md-default-fg-color--light); 37 | --md-code-hl-generic-color: var(--md-default-fg-color--light); 38 | --md-code-hl-name-color: var(--md-code-fg-color); 39 | --md-code-hl-operator-color: var(--md-default-fg-color--light); 40 | --md-code-hl-punctuation-color: var(--md-default-fg-color--light); 41 | --md-code-hl-variable-color: var(--md-default-fg-color--light); 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /docs/_global/css/global.css: -------------------------------------------------------------------------------- 1 | /* 2 | Fix issue with 'code' text in tables wrapping to multiple lines 3 | Excludes any preformatted code blocks within tables 4 | */ 5 | td code:not(.md-code__content) { 6 | white-space: nowrap; 7 | } 8 | -------------------------------------------------------------------------------- /docs/_global/hooks/inline_pre_to_code_fence.py: -------------------------------------------------------------------------------- 1 | # Converts inline
code
blocks to pygments-highlighted html 2 | # Custom hook to highlight and format
code
code
blocks 3 | # 4 | # This is used for
 blocks embedded in tables, as these otherwise are skipped by pygments
 5 | #
 6 | # Note: It's possible this can be done better with Python-markdown inline patterns (https://python-markdown.github.io/reference/markdown/inlinepatterns),
 7 | #   but the below works For Now
 8 | 
 9 | import re
10 | import markdown
11 | 
12 | import mkdocs
13 | from mkdocs.structure.pages import Page
14 | from mkdocs.config.defaults import MkDocsConfig
15 | from mkdocs.structure.files import Files
16 | 
17 | from pymdownx.highlight import HighlightExtension
18 | 
19 | # Get current mkdocs config
20 | user_extensions = MkDocsConfig.markdown_extensions.__dict__.get('configdata');
21 | highlight_config = dict()
22 | 
23 | if 'pymdownx.highlight' in user_extensions:
24 |     highlight_config = user_extensions.get('pymdownx.highlight')
25 | 
26 | ExistingHighlighter = HighlightExtension().get_pymdownx_highlighter()(**highlight_config)
27 | 
28 | def on_page_content(html: str, page: Page, config: MkDocsConfig, files: Files, **kwargs):
29 |     def inline_pre_to_code_fence(match):
30 |         raw = match.group()
31 | 
32 |         ## Check for language
33 |         lang = ''
34 |         langmatch = re.search('lang="(.*?)"', raw)
35 | 
36 |         if langmatch:
37 |             lang = langmatch.group(1)
38 | 
39 |         ## Remove first tag
40 |         pre = re.sub('', '', raw)
41 | 
42 |         ## Strip end tag
43 |         pre = re.sub('
', '', pre) 44 | 45 | ## Swap html linebreaks 46 | pre = re.sub('
', '\n', pre) 47 | 48 | return ExistingHighlighter.highlight(pre, lang) 49 | 50 | result = re.sub('(.+)', inline_pre_to_code_fence, html) 51 | 52 | return result 53 | -------------------------------------------------------------------------------- /docs/_global/hooks/merge_inherited_config.py: -------------------------------------------------------------------------------- 1 | # Handles merging mkdocs config in a way the native inheritance feature doesn't quite cover 2 | # 3 | # This relies on a key in "extra.overrides" 4 | # Valid keys are `custom_dir: str` and `hooks: [-path/to.py, -path/to.py]`, e.g. 5 | # 6 | # ```yml 7 | # extra: 8 | # overrides: 9 | # custom_dir: overrides 10 | # extra_css: 11 | # - docs/_global/css/global.css 12 | # - docs/_global/css/global-syntax-highlight.css 13 | # extra_javascript: 14 | # - docs/_global/js/global.js 15 | # hooks: 16 | # - hooks/local_override.py 17 | # - hooks/local_override2.py 18 | # not_in_nav: 19 | # - gitignore_style/path/to/exclude 20 | # theme_features: 21 | # - theme.feature1 22 | # - theme.feature2 23 | # ``` 24 | 25 | import os 26 | 27 | from pathspec.gitignore import GitIgnoreSpec 28 | 29 | import mkdocs 30 | from mkdocs.config.defaults import MkDocsConfig 31 | from mkdocs.config.config_options import (File, FilesystemObject, Hooks, ListOfItems, PathSpec) 32 | from mkdocs.structure.files import (File as FileStructure, Files) 33 | 34 | # Load any local files into mkdocs 35 | def append_local_files(files: Files, config: MkDocsConfig, local_files: list[str]): 36 | for local_file_path in local_files: 37 | local_file = FileStructure( 38 | path= local_file_path, 39 | src_dir=config["docs_dir"] + "/../", 40 | dest_dir=config["site_dir"], 41 | use_directory_urls=False, 42 | ) 43 | 44 | files.append(local_file) 45 | 46 | # Load any override hooks 47 | def merge_local_hooks(config: MkDocsConfig, hooks: list[str]): 48 | try: 49 | paths = ListOfItems(File(exists=True)).validate(hooks) 50 | except Exception as e: 51 | raise e 52 | 53 | for name, path in zip(hooks, paths): 54 | config.plugins[name] = Hooks._load_hook(mkdocs, name, path) 55 | 56 | # Handle multiple "not in nav" entries 57 | # These are of a pathspec.gitignore.GitIgnoreSpec format and need to be converted to a multiline string 58 | def merge_local_not_in_nav(config: MkDocsConfig, not_in_nav: list[GitIgnoreSpec]): 59 | nav_str = "\n".join(not_in_nav) 60 | config["not_in_nav"] += PathSpec().run_validation(nav_str) 61 | 62 | # Add additional theme_override folder 63 | def merge_local_theme_override(config: MkDocsConfig, custom_dir: str): 64 | try: 65 | local_override_path = FilesystemObject(exists=True).validate(custom_dir) 66 | except Exception as e: 67 | raise e 68 | 69 | config.theme.dirs.insert(1, local_override_path) 70 | 71 | # Load any override theme features 72 | def merge_local_theme_features(config: MkDocsConfig, theme_features: list[str]): 73 | for local_feature in theme_features: 74 | config.theme["features"].append(local_feature) 75 | 76 | 77 | 78 | ##### MkDocs Event Hooks 79 | 80 | def on_files(files: Files, config: MkDocsConfig): 81 | if "overrides" in config.extra: 82 | extra_overrides = config.extra["overrides"] 83 | 84 | if "extra_css" in extra_overrides: 85 | extra_css = extra_overrides["extra_css"] 86 | append_local_files(files, config, extra_css) 87 | 88 | if "extra_javascript" in extra_overrides: 89 | extra_javascript = extra_overrides["extra_javascript"] 90 | append_local_files(files, config, extra_javascript) 91 | 92 | def on_config(config: MkDocsConfig): 93 | if "overrides" in config.extra: 94 | extra_overrides = config.extra["overrides"] 95 | 96 | # Keep Hooks first 97 | if "hooks" in extra_overrides: 98 | hooks = extra_overrides["hooks"] 99 | merge_local_hooks(config, hooks) 100 | 101 | if "custom_dir" in extra_overrides: 102 | custom_dir = extra_overrides["custom_dir"] 103 | merge_local_theme_override(config, custom_dir) 104 | 105 | if "extra_css" in extra_overrides: 106 | extra_css = extra_overrides["extra_css"] 107 | config.extra_css.extend(extra_css) 108 | 109 | if "extra_javascript" in extra_overrides: 110 | extra_javascript = extra_overrides["extra_javascript"] 111 | config.extra_javascript.extend(extra_javascript) 112 | 113 | if "not_in_nav" in extra_overrides: 114 | not_in_nav = extra_overrides["not_in_nav"] 115 | merge_local_not_in_nav(config, not_in_nav) 116 | 117 | if "theme_features" in extra_overrides: 118 | theme_features = extra_overrides["theme_features"] 119 | merge_local_theme_features(config, theme_features) 120 | -------------------------------------------------------------------------------- /docs/_global/js/global.js: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docsforadobe/after-effects-expression-reference/0cdf30d6c9a3edcad456c6dc4430392149efa808/docs/_global/js/global.js -------------------------------------------------------------------------------- /docs/_global/mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Shared config for all repos 2 | copyright: All content is copyright Adobe Systems Incorporated. 3 | 4 | extra: 5 | homepage: https://docsforadobe.dev 6 | 7 | # Using overrides here as we can't inherit "extra_css" 8 | overrides: 9 | extra_css: 10 | - docs/_global/css/global.css 11 | - docs/_global/css/global-syntax-highlight.css 12 | extra_javascript: 13 | - docs/_global/js/global.js 14 | 15 | hooks: 16 | - docs/_global/hooks/inline_pre_to_code_fence.py 17 | - docs/_global/hooks/merge_inherited_config.py 18 | 19 | markdown_extensions: 20 | admonition: {} 21 | markdown_grid_tables: {} 22 | md_in_html: {} 23 | pymdownx.details: {} 24 | pymdownx.highlight: 25 | line_spans: __span 26 | pygments_lang_class: true 27 | pymdownx.superfences: {} 28 | pymdownx.tabbed: 29 | alternate_style: true 30 | pymdownx.tasklist: 31 | custom_checkbox: true 32 | toc: 33 | title: Page Contents 34 | permalink: true 35 | toc_depth: 3 36 | 37 | not_in_nav: | 38 | _global 39 | 40 | plugins: 41 | git-revision-date-localized: {} 42 | search: 43 | separator: '[\s\-,\.:!=\[\]()"/]+' 44 | 45 | # Note: print-site must be last! 46 | print-site: 47 | add_cover_page: true 48 | add_print_site_banner: true 49 | cover_page_template: "docs/_global/overrides/templates/print_site_cover_page.tpl" 50 | print_page_title: "Offline Docs" 51 | print_site_banner_template: "docs/_global/overrides/templates/print_site_banner.tpl" 52 | 53 | theme: 54 | name: material 55 | custom_dir: docs/_global/overrides 56 | features: 57 | - announce.dismiss 58 | - content.action.edit 59 | - content.action.view 60 | - content.code.copy 61 | - search.highlight 62 | - search.suggest 63 | - toc.follow 64 | palette: 65 | # Palette toggle for dark mode 66 | - media: "(prefers-color-scheme: dark)" 67 | primary: black 68 | scheme: slate 69 | toggle: 70 | icon: material/brightness-4 71 | name: Switch to light mode 72 | 73 | # Palette toggle for light mode 74 | - media: "(prefers-color-scheme: light)" 75 | primary: white 76 | scheme: default 77 | toggle: 78 | icon: material/brightness-7 79 | name: Switch to dark mode 80 | -------------------------------------------------------------------------------- /docs/_global/overrides/404.html: -------------------------------------------------------------------------------- 1 | {% extends "main.html" %} 2 | 3 | 4 | {% block extrahead %} 5 | 10 | {% endblock %} 11 | 12 | {% block content %} 13 |

404 - Not found

14 | {% endblock %} 15 | -------------------------------------------------------------------------------- /docs/_global/overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block announce %} 4 | Welcome to the new docsforadobe guide! 5 | 6 | This is a work in progress. 7 | 8 | Please provide all feedback via 9 | 10 | 11 | {% include ".icons/octicons/comment-discussion-16.svg" %} 12 | 13 | the org's discussion forum 14 | . 15 | {% endblock %} 16 | -------------------------------------------------------------------------------- /docs/_global/overrides/partials/copyright.html: -------------------------------------------------------------------------------- 1 | 17 | 18 | 19 | 26 | -------------------------------------------------------------------------------- /docs/_global/overrides/partials/toc-item.html: -------------------------------------------------------------------------------- 1 |
  • 2 | 3 | 4 | {{ toc_item.title }} 5 | 6 | 7 | 8 | 9 | {% if toc_item.children %} 10 | 19 | {% endif %} 20 |
  • 21 | -------------------------------------------------------------------------------- /docs/_global/overrides/templates/print_site_banner.tpl: -------------------------------------------------------------------------------- 1 | 6 | 7 |
    8 | 9 |

    Note – This box will disappear during export!

    10 | 11 |

    This page has combined all site pages into one, and can be exported using native browser features.

    12 | 13 |

    You can export to PDF using File > Print > Save as PDF, or save as a single-page HTML file via File > Save As.

    14 | 15 |
    16 |

    Warning

    17 | 18 |

    Note that users may have issues printing to PDF on Firefox.

    19 |
    20 | 21 |
    22 | -------------------------------------------------------------------------------- /docs/_global/overrides/templates/print_site_cover_page.tpl: -------------------------------------------------------------------------------- 1 |
    2 | 3 | {% if config.site_name %} 4 |

    {{ config.site_name }}

    5 | {% endif %} 6 | 7 | {% if config.extra.homepage %} 8 | by

    {{ config.extra.homepage }}

    9 | {% endif %} 10 | 11 |
    12 | 13 | 14 | 15 | 16 | {% if config.site_description %} 17 | 18 | 19 | 20 | 21 | {% endif %} 22 | 23 | {% if config.site_url %} 24 | 25 | 26 | 27 | 28 | {% endif %} 29 | 30 | {% if config.repo_url %} 31 | 32 | 33 | 34 | 35 | {% endif %} 36 | 37 | {% if config.copyright %} 38 | 39 | 40 | 41 | 42 | {% endif %} 43 | 44 |
    Description{{ config.site_description }}
    Hosted at{{ config.site_url }}
    Repository{{ config.repo_url }}
    Copyright{{ config.copyright }}
    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 | --------------------------------------------------------------------------------