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

7.2 KiB
Raw Permalink Blame History

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

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

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): 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 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