README.md

orx-keyframer

Create animated timelines by specifying properties and times in keyframes, then play it back at any speed (even backwards) automatically interpolating properties. Save, load, use mathematical expressions and callbacks. Powerful and highly reusable.

What this allows you to do:

1. Create a keyframed animation in a json file.

[
  {
    "time": 0.0,
    "easing": "cubic-in-out",
    "x": 3.0,
    "y": 4.0,
    "z": 9.0,
    "r": 0.1,
    "g": 0.5,
    "b": 0.2,
    "radius": 50
  },
  {
    "time": 2.0,
    "easing": "cubic-in-out",
    "r": 0.6,
    "g": 0.5,
    "b": 0.1
  },
  {
    "time": 4.0,
    "easing": "cubic-in-out",
    "x": 10.0,
    "y": 4.0,
    "radius": 400
  },
  {
    "time": 5.0,
    "easing": "cubic-in-out",
    "x": 100.0,
    "y": 320.0,
    "radius": 400
  },
  {
    "time": 5.3,
    "easing": "cubic-in-out",
    "x": 100.0,
    "y": 320.0,
    "radius": {
      "value": 50.0,
      "easing": "linear"
    }
  }
]

2. Map the animation data to Kotlin types:

class Animation : Keyframer() {
    val position by Vector2Channel(arrayOf("x", "y"))
    val radius by DoubleChannel("radius")
    val color by RGBChannel(arrayOf("r", "g", "b"))
}

val animation = Animation()
animation.loadFromJson(File("data/keyframes/animation.json"))

3. Animate! (from an OPENRNDR program)

extend {
    animation(seconds)
    drawer.fill = animation.color
    drawer.circle(animation.position, animation.radius)
}

Easing

All the easing functions of orx-easing are available

• linear
• back-in
• back-out
• back-in-out
• bounce-in
• bounce-out
• bounce-in-out
• circ-in
• circ-out
• circ-in-out
• cubic-in
• cubic-out
• cubic-in-out
• elastic-in
• elastic-out
• elastic-in-out
• expo-in
• expo-out
• expo-in-out
• quad-in
• quad-out
• quad-in-out
• quart-in
• quart-out
• quart-in-out
• quint-in
• quint-out
• quint-in-out
• sine-in
• sine-out
• sine-in-out
• one
• zero

More expressive interface

orx-keyframer has two ways of programming key frames. The first is the "x": <number> style we have seen before. The second way uses a dictionary instead of a number value.

For example:

[
  {
    "time": 0.0,
    "x": 320.0,
    "y": 240.0
  },
  {
    "time": 10.0,
    "easing": "cubic-out",
    "x": {
      "easing": "cubic-in-out",
      "value": 0.0
    },
    "y": {
      "duration": -5.0,
      "easing": "cubic-in",
      "value": 0.0
    }
  },
  {
    "time": 20.0,
    "x": 640.0,
    "y": 480.0,
    "easing": "cubic-in-out"
  }
]

Inside the value dictionary one can set value, easing, duration and envelope.

• value the target value, required value
• easing easing method that overrides the key's easing method, optional value
• duration an optional duration for the animation, set to 0 to jump from the previous value to the new value, a negative value will start the interpolation before time. A positive value wil start the interpolation at time and end at time + duration
• envelope optional 2-point envelope that modifies the playback of the animation. The default envelope is [0.0, 1.0]. Reverse playback is achieved by supplying [1.0, 0.0]. To start the animation later try [0.1, 1.0], to end the animation earlier try [0.0, 0.9]

Advanced features

orx-keyframer uses two file formats. A SIMPLE format and a FULL format. For reference check the example full format .json and the example program. The full format adds a parameters block and a prototypes block.

Expressions, expression mechanism. Currently uses values r to indicate repeat index and t the last used key time, v the last used value (for the animated attribute).

Supported functions in expressions:

• min(x, y), max(x, y)
• cos(x), sin(x), acos(x), asin(x), tan(x), atan(x), atan2(y, x)
• abs(x), saturate(x)
• degrees(x), radians(x)
• pow(x, y), sqrt(x), exp(x)
• mix(left, right, x)
• smoothstep(t0, t1, x)
• map(leftBefore, rightBefore, leftAfter, rightAfter, x)
• random(), random(min, max)

Parameters and prototypes

Demos

DemoEvelope01

source code

DemoFull01

source code

DemoScrub01

source code

DemoSimple01

source code

DemoSimple02

source code

DemoSimpleExpressions01

source code