Piga Animator/Manual

From PigaLore
Jump to navigationJump to search

This draft pre-dates the division of Animator into various components

This is the manual for Piga Animator, a free software 2D computer animation tool focusing on procedural animation, digital puppetry and machininma. This contrasts it with other tools such as Pencil2D for frame-by-frame animation and Synfig or Tupi for vector animation. However, Animator is also being designed to be capable of taking in graphics and animations created in other programs designed for more detailed work, for areas where a mixed-media approach would work better.



The horizon is a horizontal line that defines the point in which objects can not traverse without going into the air.


  • Backdrop:
  • Overlay:
  • Music:
  • FX:
  • Material: describes the make up of the base background, e.g. grass, snow, dirt, water, etc.
  • Mode: determines whether the interface is controled via keyboard commands/shortcuts or mouse and button clicks.


  • Head-On:
  • Sideways:
  • Top-Down:
  • Close-Up:


There are also a few post-effects avialable.

  • Shake: emulates a shaking camera.
  • Blur: adds a blur over everything.
  • Water: makes it look as though the scene is underwater.
  • Rain: provides the effect of precipitation.
  • Snow: same thing as rain, only as snowflakes.


  • Speed: multplication factor for all other relevant values.
  • Gravity: controls the rate that objects are drawn back to the horizen.
  • Friction: controls resistance against the air and surfaces.



Character movement is handled in a similar fashion to 2D game engines, with modes for the actor for each of the cardinal and ordinal/diagonal orientations. The actor can be treated as a single unit, with sprites provided accordingly, or as a system of individual parts as follows, each with their own animations. Animator is not yet designed for full skeletal animation (requiring more advanced physics and vector rotation than available in Gambas at present), but does divide the body into a selection of overlays to be created in other tools.

There are two modes simply for the importing of finished images.

  • Sprite: loads still sprites or runs through them in sequence.
  • Animation: plays selected animated GIF or MNG sequences.

Then there are the segmented actors which allow for skeletal animation.

  • Rigid: segmented, but with no elbows or kneees.
  • Jointed: fully segmented.



  • Theme:
  • Group:
  • Name:


  • X:
  • Y:
  • Z:
  • Width:
  • Height:
  • Angle:


Causes motion based on the increments set in the stride value in the Movement menu.

Right clicks translate the object by one stride, left clicks cause them to keep moving by strides.

  • Up: moves the actor or prop further up the stage.
  • Down: moves the actor or prop further down the stage.
  • Left: moves the actor or prop further to the left on the stage.
  • Right: moves the actor or prop further to the right on the stage.
  • Up-Left: moves the actor or prop further up and to the left on the stage.
  • Up-Right: moves the actor or prop further up and to the right on the stage.
  • Down-Left: moves the actor or prop further down and to the left on the stage.
  • Down Right: moves the actor or prop further down and to the right on the stage.
  • Stop/Shake: Right click stops the actor/prop from moving, left click causes it to convulse.
  • Beacon: cause the actor to approach the mouse designated beacon.


Causes objects to be transformd in terms of width, height and other properties based on the current increment value.

  • Increment: allows the selection of the desired increment for transformations.
  • Snap: makes the currently selected actor or prop snap to the native size of their source image.
  • Rotate: raster rotates the actor. Right goes clockwise, left goes counterclockwise.
  • Flip/Mirror: flips or mirrors the actor. Left clock mirrors horizontally, right click flips vertically.
  • Scale: scales the actor. Left click scales up, right click scales down.
  • Compress: compresses the actor. Left click compresses horizontally, right click compreses vertically.
  • Widen: manipulates the object's width. Left clicks adds width, right click decreases it.
  • Heighten: manipulates the object's height. Left clicks adds height, right click decreases it.
  • Skew:



  • Stride: value controls the movement applied during object (actor or prop) translations.
  • Bob: controls to what extent the selected actor bobs up and down while being translated.
  • Arm Wave: controls whether, if segemented, the actor's arms wave from side to side while in walk cycle.
  • Z Scaling: controls whether the actor is scaled to provide a 2.5D illusion of depth into and out of the screen.


  • Conversation: a list of imported speech files making up a conversation stack.
  • Speech Edit (Waveform): loads the Speech Generator window.
  • Speech Bubble (Balloon): determines whether a transcribed speech bubble is shown during dialouge.
  • Speech Play (Lips): left click plays the selected speech file, right continues playing down the conversation list.

Cut Outs[edit]

The base unit is the torso/trunk, which then has protrusions for the various limbs, and then the head, which has separate overlays for the eyes and mouth.


See: Piga Animator/Manual#Head


Two overlays are provided, with which one being controlled changed by clicking again on the overlay selection button.

  • None
  • Limp
  • Shrug
  • Grab
  • Punch
  • Stop
  • Grab Up
  • Grab Down
  • Clap
  • Hold
  • Salute


See: Piga Animator/Manual#Hand



Two overlays are provided, with which one being controlled changed by clicking again on the overlay selection button.




In order to bring together a complete expression of character, these various bits and pieces have to coordinated into the overall pose intended. Emotions can be expressed just as much through posture, the tilt of the head or the position of the arms as they can through the eyes and mouth.

Close Ups[edit]


Facial expressions in Animator work through the combined poses of the eyes and mouth, and work somewhat similar to the actual Facial Action Coding System, only considerably simplified closer to the level of emoticons.

  • None
  • Forward
  • Backward
  • Left
  • Right
  • Front-Left
  • Front-Right
  • Back-Left
  • Back-Right


  • Back
  • Left
  • Right
  • Bangs


Both eyes are contained in one object, though a cross-eyed mode is available to overcome this if necessary. The eye overlay is actually made up of two objects that are controlled in tandem: the base eyeball, which directs where the character is looking, and then the eyelid which is used to define mood. Different moods are produced through the combinations of the various mouths in order to produce complete facial expressions. As part of idling, the eyes are by default set to blink at odd intervals.


  • None (removes the entire set of eyes)
  • Look Forward
  • Look Up
  • Look Down
  • Look Left
  • Look Right
  • Up-Left
  • Up-Right
  • Down-Left
  • Down-Right
  • Cross-eyed





As with the eyes, the mouth works in tandem with its other facial counterpart in order to produce particular expressions. A frown or a smirk can greatly change the portrayed by the side shock/wide eyes. A peculiarity of the mouth compared the the eyes is that each pose also requires it has its own version of mouth movements, or else it will default to the neutral mouth movement series.


  • Wrist
  • Palm
  • Index Finger
  • Middle Finger
  • Ring Finger
  • Little Finger
  • Thumb

Artificial Intelligence (AI)[edit]


Even within limited animation, the illusion or motion is best preserved if nothing remains still on the screen for too long. Animator has a selection of pre-coded idling animation modes which can be drawn for actors. All of these may also be called by the puppeteer in order to be completed with certain timing.

With limited animation, it can be tempting to just try and do all exposition as dialogue, especially if you have a system of obscuring or automating mouth movement, however a little motion can do wonders to enhancing a scene. For example, after an important revelation through spoken words, a slight movement or gesture on the part of the character can attract the audience's attention further and/or reinforce its importance.

  • Blinking: This idling mode is activated by default, and simply causes the character to blink periodically.
  • Sniffing: A default sound effect is provided, which can be customized to a given voice actor.
  • Shrugging: A raising of the arms and shoulders as a basic shrug.
  • Sighing: A default sigh sound effect is provided, male and female, which can be customized to a given voice actor.
  • Twitches: Causes various applicable components to translate slightly, to simulate muscle contraction.
  • Head Turns: Based on the given perspective, this mode will have the head occasionally turn in a different direction (but never a full 360 degrees!).


  • Wander:
  • Pace:
  • Collect:


Lip Flap[edit]

In many anime, owing to the legacy of limited animation from Osamu Tezuka, mouth movement is handled merely as the opening and closing of the lips and jaw, without any special phontic mouth shapes. This movement is then tied to the amplitude (or, in laymen's terms, loudness) of the voice at any given time, producing a convincing, if unrealistic, effect sometimes known as "lip flap". There is another advantage to this style however, and one that no doubt aids its usage in anime. This simplified representation is largely language neutral, making it more convincing upon placing over a foreign dub; this is also commonly exploited in AMVs. The technique is also used in other low-end animation productions, such as the works of Filmation.

The design of a lip flap is based on creating a simulation of the human lips. The angle or expression dictates the shape and whether or not teeth will be shown. If the expression is a smirk or smile for example, as opposed to a grin, the upper lip will raise a bit when talking. In a grin, cringe, gritted teeth or similar the upper lip has already been raised, and so it will not move. From here the most important thing is making the lower jaw drop by the right amount. This is typically divided into two frames: one for a slight opening, representing emissions of comparatively low amplitude, and a longer one for louder speech. A third one for a full out yell may also be added. The mouth may also get wider as the jaw is lowered, stretching the edges of the lips. A dynamic mouth mode is also available that simply resizes a simple geometric shape to the current amplitude value.


See Also: Papagayo

Considered the most realistic form of mouth animation, Animator automates this normally arduous task (though not neccesairly with full accuracy) through the use of a speech-to-text back-end. To accomplish its task, it transcribes the spoken audio from the voice file, transforms it into a text string and then calculates what phonetic pose the mouth of the character should form for each letter at given intervals. The animator thus needs to create each of these poses for the given actor.


  • Dynamic:
  • Poses:
  • Background:


Animator derives its amplitude data from generating waveform visualizations from audio files using ffmpeg. The graphs are all 100 pixels tall as to create a standardized range of 0-100, while their widths are derived from having five samples/pixels per second of audio. The various peaks and troughs are then extracted from samples one pixel in length to get an array of amplitude values. The waveforms are also built from standardizing the audio to a single aggregate mono channel regardless of the amount of channels in the source audio. The waveforms may also be companded in order to make a more striking visual.

Random/Sine Waves[edit]

Fundamentally, all that an animation needs to do is to make the viewer aware of motion. Therefore, at its most basic level, a simple mouth open/mouth close animation is capable of suggesting that a character is speaking and/or allowing the viewer to know which character is currently speaking. This mode is also useful during the prototyping phases of animation, before moving on to more advanced and accurate techniques. To generate this effect, a simple sine waveform may be generated by left-clicking on what is normally the random button. Also, even a unmatched waveform can produce a somewhat convincing lip flap effect, so a complelty random waveform mode is available.



There are several configurable parameters for eSpeak and eSpeak-NG.

  • Amplitude:
  • Pitch:
  • Speed:
  • Gap:

As well as several buttons and options:

  • Read Text: sets the program to use text-to-speech rather than from audio files.
  • Get Length: gets the amount of samples and length of dialogue.
  • Voices: drops down a list of voices and voice variants.
  • Reset: returns all above values to their default settings.
  • Narrator: sets the narrator to the voice selected.

Speech Bubbles[edit]

Speech Files[edit]


Directing in animation is a little bit different than directing a live-action production. While a film director takes already given assets, such as actors, props and sets, and is in charge of arrangement, timing and effects such as lighting and angle of shots, an animation director needs to take a more hands-on approach while the frames are being drawn.


Allows the execution of shell commands.

Script Editor[edit]

This system records your inputed actions and allows you to replay perviously played out scenes, as well as to correct and tweak the timing of the sequence.


Allows the deselection, rearrangment, grouping and seperation of the various interface features.



  • Resolutions: Live capture to video is done via the ffmepg system through capturing the animations displayed on screen, at every average 480p resolution, covering both standard and wide-screen resolutions; high definition support may be added later on.
  • Formats/Codecs:
  • ffmpeg: This is a in-built front end for ffmpeg to handle screen capture.


The most fundamental ideas of animation were encapsulated by Disney Old Men Ollie Johnston and Frank Thomas in their twelve basic principles of animation, and reviewing these remains a good starting point. From here, we shall outline in detail a few essential principles required for masterful use of Animator. Many of these concepts were learned by designer Graham L. Wilson as he developed this program, all while thinking about how to make these work in real-time through automation or procedure.

Note: for help tweening your animations, please refer to the Synfig documentation.

Model Sheet[edit]

Character design is one of the most important aspects of creating an animated production, and usually begins with the creation of a model sheet in order to define a character's proportions, appearance, apparel, accessories and even body language and emotional attitudes. A full turn around or model rotation sheet is used in order to define a character's appearance from various angles.

Cartoon Style[edit]

One of the most common designs in animation dating back to the early Fleischer brothers, Walt Disney and Warner Bros features, this style is designed to be created in such a way as to avoid realism and the uncanny valley. Heads are large compared to the rest of the body, allowing for exaggerated facial features. Arms and legs are the same length for simplicity, and hands can be large, and often are drawn with only four fingers again to make easier to draw. Given that in traditional animation, every single frame had to be redrawn from scratch, it was important to simplfy characters to a degree to make it manageable; as it has been with fast-produced comic strips.

Anime Style[edit]

Proportionate Style[edit]

More realistic drawing is based on the study of actual body proportions, which of course vary from person to person but have been relatively standardized for beginners. The average male is eight heads tall while a female is seven heads tall, but this can be further abstracted as a ratio, with women typically shorter than men.

Walk Cycle[edit]

The walk cycle is one of the most fundamental concepts in animation, usually taught to aspiring animators soon after the bouncing ball (handled in Animator, though procedural techniques). It can be achieved through any number of combinations of frames (usually to build up to 24 or 30 FPS), but here we will start with two and then double it through until we hit sixteen (the typical frame-rate of high-end traditional animation; a full thirty frames-per-second is possible, but best left for tweening).

Note: As part of the principle of squash and stretch, a walk cylce is supposed to have a figure highest in the air during high point and lowest with recoil. Animator has a mode which simulates these translations automatically, allowing walk cycles to be done in the same frame size.

Two Framed[edit]

Used commonly in 8-bit era video games. As well as the standing pose, there is one frame to represent the contact of both legs against the ground (with it made not to imply that one leg is over the other and so function as a trick of the eye). If held loose, the arms are also held out ahead and behind the character. When played rapidly and with enough relative obscurity even this limited technique can be adequately convincing. If the idling pose is suitable only one frame may need be drawn new.

Four Framed[edit]

Used commonly in 16-bit era video games. This expands upon the contact frame used in two frame animation, this time adding two for both legs (with proper dominance given to one or the other), as well as passing poses as both legs go beside the other. This is also done for the arms, with the dominant arm being opposed to the dominant leg. Three frame variants of this also exist where a single passing pose is used instead of one for each leg, with both legs roughly even.

Eight Framed[edit]

Usually considered a decent enough target for web animations. Adds two more frames: low-point (or recoil) and high-point (or ascended) for each leg. A seven frame variant may also be used with the combined passing pose as described previously. Although this also applies to the passing frames described earlier, now is a good time to discuss a stylistic consideration. The height the leg climbs can be used to communicate the desired tone of the animation. Lower to the ground gives it a more grounded realistic air, while higher gives it a more exaggerated and cartoonish feel. There is also a stripped down six frame variant that skips the passing frames.

Sixteen Framed[edit]

Usually the target for professional level animation, though higher still can be achieved, often through automated tweening.


Animator is not a graphics editor and it is presumed that all source material used in Animator will be created in other specialized raster or vector tools such as KolourPaint, MyPaint, Pinta, GIMP or Inkscape. There are a couple of things that should be borne in mind when importing graphics into Animator. First off is that every frame of a sample animation must be an independent file, and that animated GIFs, APNGs or MNGs are not applicable. The same applies in vector for SVG animation. Synfig allows for the export of tweened animation as a series of individual image files.

Another important consideration is that Animator assumes that every frame has the same width and height. This is important in order to keep the applied transformations by Animator proportionate to the various source images. If there is a varying amount of background space, certain frames may appear squashed or stretched. Although an image does not strictly need to be transparent to be used in Animator, it limits the amount of compositing (such as with the background and overlay options) that can be done.

Supported image formats include GIF, PNG, JPEG, SVG files. Audio files supported include Ogg Vorbis, FLAC and, codecs allowing, MP3. MIDI and WAV are also supported by lack duration detection, which is used to automatically time mouth movements. The two art styles Animator was designed in mind for are pixel art and vector art, although any image with transparent bordering can conceivably be used.