Files
AniCraft/docs/guide/data-driven-animation.md
T

143 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Data-driven animation
Numbers can animate for you. Keep a table of them in your document, let a column drive a
property of an instance, and the animation follows the data: a bar chart that grows month by
month, a marker that moves with a measured level, an outline that changes with a record. When
the numbers are revised, import the file again and every frame follows, with no keyframes to
redo.
![A bar chart: each bar's height follows a column of a table, with the binding in Properties](images/data-chart.png)
## Importing a table
**File › Import › Import Data Table…** reads a table of numbers into the Library from:
* **CSV** or **TSV** text (comma, semicolon or tab separated), as spreadsheets export it. The
first line names the columns. In semicolon and tab files a decimal comma is read (`3,5`).
* **JSON**: a list of records (`[{"age": 100, "pinus": 12}, …]`), a list of rows with the names
first (`[["age", "pinus"], [100, 12], …]`), or columns by name (`{"age": [100, …], "pinus":
[12, …]}`).
A table keeps numbers. A cell that isn't a number (an empty cell, `n/a`) becomes a **gap**, and
a column with no numbers at all, such as sample names, is left out; the status bar tells you
which. A table holds up to 100,000 rows, 256 columns and a million cells, and a file up to
32 MB is read.
The table appears in the **Library** with a small grid icon, like a symbol or a sound. The
Library shows its first rows; **View Table** (or a double-click) opens every row and column.
![The table viewer: every row and column of a table, with its key column and Import Again](images/data-table.png)
### A row per frame, or a row per time
How rows are looked up is the table's **Key**:
* **Row number** (the default): rows are counted from the top. Bind a column over as many
frames as the table has rows and each frame shows one row.
* **A column**, such as an age, a depth or a time in seconds: rows are looked up by that
column's value, and the table sorts itself by it. Choose this when your rows aren't evenly
spaced.
Set it in the Library, under the table's preview, or in the viewer.
### When the data changes
Select the table and choose **Import Again…**, then pick the file (the same one, revised, or
another). The table's values are replaced and everything bound to it follows at once. Bindings
find their columns by name, so the columns may come in another order. If a column a binding
reads is gone, that binding rests (its instance stays as you placed it) and the status bar names
the column.
## Binding a column to an instance
Data drives **symbol instances**. To bind one:
1. Select the instance on the stage (convert artwork with **Modify › Convert to Symbol** first).
2. Choose **Modify › Data › Bind to Data…**, or **Bind to Data** in the **Data** section of
Properties, and pick the property there.
3. In Properties, under **Data**, choose the **Table** and the **Column**.
The stage shows the result as you change it. You can bind each of these once per instance:
| Property | The column's number is |
|---|---|
| **X**, **Y** | the position in pixels |
| **Scale X**, **Scale Y** | the size in percent (100 is the size you drew) |
| **Rotation** | degrees, clockwise |
| **Alpha** | opacity in percent |
| **Frame shown** | which frame of a graphic symbol shows, counted from 0 |
Under each binding:
* **Frames**: the first frame of the span the table plays over, and how many frames it lasts.
Before the span the instance shows the first frame's value and after it the last's, so a
chart holds its last value when the data ends.
* **Rows** (or **Keys**, for a table with a key column): what the first and the last frame of
the span show. They start as the whole table; **All** goes back to that. Set the second
before the first to play the table backwards, for ages that run from old to young.
* **Value**: the column's number **×** a scale **+** an offset. Use them to turn your units into
pixels or percent: a rainfall of 0 to 300 mm with × 0.5 is a bar 0 to 150 % tall.
* **Between**: **Linear** moves straight from one row's value to the next; **Step** holds each
row's value until the next row.
The number beside the binding's name is what it gives at the playhead. A binding replaces the
property; the rest still animates as usual, so an instance whose X is tweened and whose Y is
bound moves along both.
> **A bar that grows from its foot.** Scale and rotation turn about the instance's
> transformation point. With the Free Transform tool, drag the small circle to the bar's foot
> (or set **Pivot** in Properties), and a bound **Scale Y** grows the bar upwards.
### A shape that changes with the data
Draw the states in a **graphic** symbol, one per frame, or a shape tween from one outline to
another. Bind the instance's **Frame shown** to a column: the data picks which frame of the
symbol shows. 0 is the symbol's first frame; use **Value** to turn your numbers into frames. With
**Step** the outline holds through each regime; with **Linear** it changes smoothly.
## Baking to keyframes
**Bake to Keyframes** (in the Data section, or **Modify › Data › Bake Data to Keyframes**)
writes what the bindings show as ordinary keyframes and removes the bindings. Every frame looks
as it did. Bake when you want to adjust keys by hand, or before **Lottie** export, which writes
keys rather than pictures. The other exports (PNG, GIF, video, HTML canvas, sprite sheets) show
bindings as they are.
Baking can't cut a motion tween (remove the tween first) or work on an armature layer or a
locked layer; it tells you, and changes nothing.
**Modify › Data › Remove Data Bindings** takes the bindings off the selected instances without
writing keys: each property is the instance's own again.
## Managing tables
A table is a Library item: rename it, put it in a folder, or delete it there. Deleting a table
also removes the bindings that read it; **Edit › Undo** brings both back. The **Uses** column
counts the bindings that read each table, and **Select Unused Items** finds tables nothing
reads.
The numbers are saved inside your `.anicraft` file, so the document carries its data with it.
The table remembers the name of the file it came from, never its folder.
## From scripts and AI assistants
Every step is a command, so a pipeline can build a chart without the window (see
[Working headless](working-headless.md)): `data.import_table` or `data.set_table` for the
numbers, `data.bind` for each instance, `data.bake` for plain keys, and `data.list`, `data.get`
and `data.bindings` to read them back. The [command reference](reference/commands.md) lists
their parameters. Plug-ins can use all of them except reading a file.
## Not yet
* Copying, pasting or duplicating a bound instance doesn't copy its bindings.
* Cells can't be edited in the viewer yet (`data.set_cell` changes one from a script).
* Only symbol instances are bound, and only the properties above; captions driven by text
columns are planned.
* Baking inside a motion tween.
## Next steps
* [Tweens](tweens.md): animate the properties data doesn't drive.
* [Symbols and the Library](symbols-and-library.md): graphic symbols and the transformation point.
* [Exporting and Publish](exporting-and-publish.md): share the result.