Documentation


Get up and running in no time.

Contents

 

*New Dark Theme

This latest update to Core Animator contains many new UI improvements including the ability to select the new dark theme. Go to View/Dark Theme to enable.

 

 

 

 

 

Getting Started

Open Core Animator and you will be presented with sample tutorial projects or the option to create a new project.

Each sample project has accompanying video help for both working in Core Animator itself, and how to integrate the exported Code into your Xcode projects. 

 
ios device sizes.png

Canvas size

The Canvas size is in “points”. Not pixels.

Get with your developer team and decide what Canvas Size will make sense for your particular project.

The accompanying graphic shows common iOS screen sizes in point values as a reference, though it is unlikely you will want to use any particular device reference as a canvas size, unless you are doing a full screen project that is not universal.

If you are doing a UI button for instance, you might wish to use the Canvas Size to define the hit area.

If you are doing a full screen, fully animated storybook, you may want to use something like 768 x 1136. From there, you could stay within a central "safe zone" and simply crop in a little for each different device but you would only need to produce your animations once.

You can even specify a nil 0x0 point canvas if desired.

 

Developers will already be familiar with how point sizes work, but as Core Animator is a tool that will also be used by designers and others that might expect "pixel behavior" from the canvas one additional example is shown here.

Basically, do not expect an @2x asset to appear twice as big as an 1x asset on your Core Animator Canvas, if it does appear bigger, then you probably forgot the @2x suffix to the filename.

Best Practices recommends that you use the @2x suffix on the images you import. Core Animator will auto-detect this suffix and will automatically create the matching 1x assets for you. You can always manage this later in Xcode assets catalogs if desired.

 

 

Importing Images

There are multiple ways to get your assets imported into Core Animator. PNG and JPG files are supported. Remember, it is recommended to use the @2x suffix to your filenames.

1.

1.

1. In the top tool bar press the "import" button.

2.

2.

 

2. From the top MenuBar/Element/Import Items ( ⌘I )

 

3.

3.

3. Drag items directly into the Canvas from Finder.

 

elements panel

You can arrange imported images here. 

An element name being above another corresponds to how it will visually appear above the other on the canvas.

Drag the items up and down or use the forward ⌘] and backward ⌘[ buttons on the toolbar to arrange the elements in the desired layer order.

You can create groups by making a selection of multiple items and using the group button above in the toolbar. Alternately ⌘G shortcut. Groups act like any other element with their own anchor point and transform properties.

Ungroup using the button in the toolbar or ⌘G

In addition to grouping, you may "nest" elements inside one another by dragging the element on top of another until highlighted, then release. In the example here, the "foot side r 2" element is nested inside of the "leg shin 1" element.

Click on the eyeball to turn off visibility for the element.

Click on the dot next to the eyeball to lock an element down and prevent accidental modification. Useful for backgrounds or guides you may import.

All element names must be unique. By default, names will be the filename of the imported image. This panel may be hidden using the flyout arrow icon.

 

setup

On the top tool bar, the Setup state is active when highlighted blue (keyboard shortcut is "1"). If there are no animations in your project, then setup state is the default. In Setup mode, you define the initial global properties of all of your elements by arranging them on the canvas. Elements will default to snapping to guides. Turn off snapping via the top Menubar/View/Show Guidelines.

This is also where you define your anchor points to each element. 

Later, as you add animations, each animation row will reference back to this initial setup state as the starting point.  

 

Animations

On the top tool bar press animation mode on to enter an animation (keyboard shortcut is "2"). By default on the first press Core Animator will automatically create an "Untitled Animation" for you.

Use the plus symbol icon to add a new animation. Animations can be renamed, duplicated, or deleted using the right click contextual menu.

 

You may create as many animation rows as you desire. Each animation will references the initial setup state as it's universal starting point. However, you may change the first keyframe of an animation at time 0 if you want to define an initial state for that animation other than the setup state.

 

 

timeline

timeline.jpg

The timeline bottom panel shows the keyframe property value changes over time for the elements of a selected animation. Single diamonds indicate tweened keyframes, while double diamonds indicate an instant keyframe value change. The easing graph in the timeline title bar will determine how the next keyframe created with be tweened or if it will be instant. Click on a tween line to change it's easing style.

You can select multiple keyframes by holding shift or command. You can also click and drag to make a selection box of keyframes. A single keyframe may be alt-dragged to create a copy. Right click options for keyframes allow you to change from tweened to instant and vice versa.

Properties that can be animated include: Translation, Scale, Rotation, Opacity, and Image Contents. Children Z-position may also be animated, if you are selected on a group that contains multiple elements (more on that later).

The loop icon is next to the create keyframe button on each individual property line. Looping has three toggle states: off, loop, and auto-reverse loop. Looping will begin automatically, using the last keyframe of the row as it's loop point. 

The red line is the location of the actual playhead. The auto preview skimbar (blue line) is on by default. You may turn it off in the top Menu Bar/ View/Show Skimbar.

 

Keyall

This special keyframe will "lock down" everything at a particular point in time. It won't automatically create an explicit keyframe for every single property of every single element, but this is implied.

When you change any property value at a point in time that is either before or after the key all point, then the implied keyframe in question will be made explicit at the keyall point in time.

You can use as many keyall keyframes as you wish in a timeline. They can also be deleted later. Use this great feature to "lock down" how everything looks in your project at a specific point in time. This can be useful especially when you are animating out to a point in time that you have many element properties that you may or may not change, and just want to feel it out. Just start by locking everything down, then move out in time and start making changes.

This can also work in reverse. You may want to start your project first off by placing a keyall point out to the ending point in time. This will ensure that you can loop everything back to this locked down state that exactly matches the initial state.

 

Properties Panel

properties.jpg

Here is where you can view and change the values for different properties of each element. You can hover over each input field to use scrubby sliders. You can also directly enter values into the input fields. You can also just use the manipulation handles around the bounding box of the selected element in the canvas.

Clicking the circle icon by the property titles will stamp a keyframe of the current values into the timeline at the current playhead position.

In Setup Mode: All these properties are absolute values and they define the global starting points of all elements.

In Animation Mode: All these properties are relative to the initial Global Setup state.

This means that if you create some animations, and then go back to the setup mode and make changes, the changes in setup mode will affect everything everywhere. For example, shrinking the scale of a character in setup will shrink that character across all animations. So be aware that Setup values will affect everything globally in your project. Use this to your advantage to make sweeping changes when desired. If you want to make changes to a single animation, remember that you can change the values at frame 0 to get an entirely different starting animation level "setup" than the one that globally exists in the setup mode.

 This panel may be hidden using the flyout arrow icon.

 

Tool Bar

Center Section

Center Section

Right Side

Right Side

We already discussed the items in the toolbar that are located on the left side when we discussed the Elements Panel. Now let's tackle the rest.

In the Center Section you'll find the name of the project, where you can click and change it's save location etc. You'll also find your cursor tools used for manipulating elements on the canvas. The first Select Tool will highlight the first layer it comes in contact with. This means it will select the group level and not go inside the group to select a single internal element. To go inside a group and select an individual element you are targeting, use the Direct Selection Tool. You can also hold command to temporarily use the white Direct Selection Tool. The hand tool can be used to move the canvas view around. Hold space bar to use the Hand Tool temporarily. 

The Right Side of the tool bar has zoom options for the canvas view. It also has the export button for when you want to preview your animations fully and generate your code.

 

Keyframing

There are multiple ways to create keyframes in the timeline. Place the red playhead line any place in time and then any change to a property of any element will generate a keyframe at that point in time.

The most straight forward way to make changes is to use the selection box handles in the canvas to manipulate the values by clicking, dragging, scaling, and rotating with the contextual cursors.

You can also use the scrubby sliders in the properties panel, or enter numerical values in the text fields. Additionally there is a circular key frame icon in the timeline by each property that allows you to "stamp" a keyframe at the current playhead.

You can duplicate a keyframe by option dragging any keyframe diamond. You can select multiple keyframes by using command or shift clicking. You can also click and drag a selection box over multiple keyframes.

Keyframes are color coded to see at a glance the property they represent.

  • Orange -    Translation

  • Purple   -    Scale

  • Blue      -    Rotation

  • Grey     -    Opacity

  • Green   -    Image Source (Instant key framing only)

  • Pink      -    Zposition (Instant key framing only)

Easing between keyframes is defaulted to linear. You can change this default in the Timeline row options "Next Easing". You can also change any easing at any time by clicking on the easing spline and selecting a new easing option.

Easing splines give you a graphical approximation of what to expect from each different spline path shape.

You can click on a property row name in the timeline to select all the keyframes in that particular row at once.

 

 

 

 

Children Z-positions

This is an animatable property that can be very handy, but may require a little further explanation. It may not be immediately intuitive where it is even possible to animate the Z-position. First off, Z-position as we are using the term here, refers to whether one element appears "in front of" or "behind" another element. Photoshop users would be familiar with how this works with respect to layer order, above in the layer palette means in front. There is a limitation in Core Animation that only allows for elements in the same parent level hierarchy to animate Z-order with each other. So if you want to be able to animate Z-order between two elements, make sure that they are in the same group together, or simply both not in any group and thus both would be on the canvas level of the hierarchy together. 

Let's look at an example where we want to animate some clouds that start in front of an airplane, but as the plane passes through, the clouds end up behind. In this example both the clouds and the plane have to be on the same parent level. This means they either both need to be at the same level inside the same group, or that they must both be out on the root level (in the implied Canvas group). We'll look at the latter first.

z-order-canvas-children.jpg

A Z-position keyframe can only be instantaneous as it is basically  just a single snapshot of a particular layer order arrangement at a given time. 

Now, using the same project, the pilot is part of the plane group. He is situated between the plane body and the plane tail as he sits in the cockpit. If we want to animate the pilot as he ejects so that he ends up behind the plane tail, then we can work from the plane group parent level to animate the Z-order.

 

Exporting

The export module can be launched using the keyboard shortcut (⌘Enter) or by pressing the export icon in the top toolbar. Once in the module, you will have the ability to review all of your animations and run them simultaneously and asynchronously as desired. The default behavior next to each animation is for the animation to remain on the last frame after it has played through. At that point the animation row will remain selected in red. Click on it again to reset the particular animation row.

If you select the options tab, there are several useful options to choose from. Obj-C or Swift code. Clipped or Unbounded canvas edges. Including the images in the project with your export or not (you may already have the images in your Xcode project). And finally, if you want to clean out the old image directory in case things have changed since your last export. 

 

exporting png sequences and .mov files

The options for png sequences and movies are found in the export module using the share/export icon next to the animation row name. Options will be given to specify frame rate for the png sequence. Mov files will automatically use the Canvas size for resolution and render at full quality with no other options given in the app. If you need to adjust the video size, codec etc.., you will need to use a dedicated video application to re-render later.

 

Inside the Exported code

When you export a project, the result is a single view-class that represents the canvas. On iOS, this class is a UIView subclass. On OS X, an NSView. The name of the class will be the name of your project with “View” appended. When the class is instantiated (either through code or by being included in a xib or storyboard), it builds a hierarchy of subviews, representing the elements in your project. 

iOS: Each group from your Core Animator project becomes a UIView, while each individual element becomes a UIImageView.

OS X: Groups and elements are both represented by a CALayer (with layers representing elements having their contents property set with the appropriate image).

Each animation that was defined in your Core Animator project is accessible via methods available on the generated class. For each animation, there are several different methods that are generated. The main job of these methods is to start and stop your animation. For example, if you defined an animation in your Core Animator project and named it “open lid”, the following methods would be generated (among others):

addOpenLidAnimation

removeOpenLidAnimation

These methods (and their variants) will allow you to easily kick off the animations that were defined in Core Animator, as well as remove them when needed.

 

Including generated files in Xcode

During the export process, the class file (.swift or .h and .m) is exported. An images directory is also (optionally) exported.

Of course, you can manage your projects as you see fit, but here are a few things we’ve found to be helpful:

  • Export to the same directory that contains your Core Animator project
  • Add the actual Core Animator project to Xcode and source control. This way you can make tweaks to the project and simply re-export for updated functionality in your app. 
  • Do NOT add the Core Animator project to any app targets. Core Animator projects include the project images in a package. Copying them into a target would only use up additional space, essentially doubling up on the images.
  • Remember to add the generated images directory to your project! Otherwise, you won’t see anything :)
 

Using generated files in Xcode

Once you have your file(s) added to Xcode, you use them as you would any other class. You can instantiate them programmatically if needed or simply add them to a storyboard (or xib). 

Note that each generated class is marked as IBDesignable. This means that you will be able to preview, at design time, the setup state of your Core Animator class. 

Note when using Storyboards: On iOS, generated views respect the ContentMode property of UIView. The values that are respected are ScaleToFill, AspectFit and AspectFill. Note that blank UIViews that are added to a storyboard start with a contentMode of ScaleToFill. This is often not what you want. You can change the contentMode using the dropdown in the properties inspector.