Base ExampleCommandModel.png Tutorial

Time to complete
20 minutes
FreeCAD version
0.14 or above
Example File(s)
[1] example data set #5


This tutorial will animate a key in a simple fashion. This tutorial continues on from tutorial YYY where we used the Part workbench to create a key to fit the lock housing.

Animated key.gif

Problem Background

This tutorial will take the work from the previous 2 tutorials, and use it to create a simple animation. The emphasis here is to create a simple animation to demonstrate the techniques, and to provide example code that can be taken and adapted for more complex situations.


FreeCAD has numerous facilities and features. To make our work easier in this tutorial, we need to make sure some of them are visible. From the menu bar at the top of the screen select the option View->Views->Combo View. This will produce the Combo View which is a browser with two panes, one above the other. The upper pane has two tabs Model and Tasks - select Model. The lower pane also has two tabs View and Data - select Data.

As you will be working with Python code running within FreeCAD, also enable View->Views->Python Console and View->Views->Report View. The Python Console will show all the Python statements as they execute while the Report View will list any error messages.

Preparation for Animation

This tutorial is a slightly hybrid one, in that it supplies code which depends on the basis of two modeling sessions. As consequence there is one more step must be taken before the animation code can be used. Animation in FreeCAD is achieved by manipulating the X,Y,Z coordinates as well as the values for rotation. Any object may be repositioned and rotated. The key that was generated in the previous tutorial is a number of discrete objects. We will use the Part Union.png Union to make a single object from the different component objects. Dealing with one object is much simpler when animating.

  1. Open the work you saved at the end of the previous tutorial.
  2. In the Combo View single-click the key shaft in the Combo View to select it
  3. Holding down Command, single-click on the following objects to select them:
    • key teeth
    • key handle part 1
    • key handle part 2
  4. Click on Part Union.png Union to fuse the 4 objects into one object. It is this resultant object that we will now animate. Notice that the resultant is another object called something like 'Fusion'. This is very important as the Python code used in this tutorial will only work with n object called Fusion. The objects that were used to form the result are encapsulated within the resulting object. Click to the left of 'Fusion" to view the objects used to form it.

Code for Animation

The following Python code will take our newly crated object Fusion and animate it. The code is:

#			Python example code to accompany tutorial YYY
# This code is written to achieve two purposes:
# 1)	a working example of animation for the completed model from tutorial YYY
# 2)	an example of code which can be used as a starting point for persons
#		wishing to incorporate simple animation into their FreeCAD models
#	WARNING:	This source code makes numerous assumptions which are part of the tutorial YYY.
#				Fore example the code will only animate one object, in one fashion and only if
#				the object has the exact name "Fusion". This is not intended to be robust code
#				but rather example code serving part of a tutorial.
#	For further details on the use of this code, refer to the Wiki page on tutorial YYY

from FreeCAD import Base,Placement
from time import sleep
import math

# UI Class definitions

# Class definitions

# Function definitions

def setInitialPosition():
	# reset the position of the Fusion object so the animation stays on the screen
	FreeCAD.ActiveDocument.Fusion.Placement =	App.Placement(App.Vector(0,0,0),

def wait(milliseconds):
	# for the time interval received, remain in a tight loop to simulate smooth movement
   for i in range(milliseconds/10):

def updatePlacement(obj, start, end, movementType):
	# use Case statement to step through the 4 types of movement
	# rotateCW	rotate the object clockwise around the Z-axis
	# rotateCCW	rotate the object counter-clockwise around the Z-axis
	# moveUp	increase the elevation (position on Z-axis)
	# arcUp		increase the elevation (position on the Z-axis) while also increasing the pitch of the object
	if movementType == rotateCW:
		# handle the clockwise rotation around Z-axis
		for idx in range(int(end-start)):
			obj.Placement = App.Placement(App.Vector(0,0,0),
	elif movementType == rotateCCW:
		# handle the counter-clockwise rotation around Z-axis
		for idx in range(int(end-start)):
			obj.Placement = App.Placement(App.Vector(0,0,0),
	elif movementType == moveUp:
		# handle the raising up the Z-axis
		for idx in range(int(end-start)):
			obj.Placement = App.Placement(App.Vector(0,0,idx),
	elif movementType == arcUp:
		# handle the raising up the Z-axis while also increasing the pitch
		for idx in range(int(end-start)):
			obj.Placement = App.Placement(App.Vector(0,0,start+idx),

# Constant definitions
rotateCW		= 1		# rotate clockwise
rotateCCW		= 2		# rotate counter-clockwise
moveUp			= 3		# raise elevation
arcUp			= 4		# raise elevation while increasing pitch (i.e. front of object is rising)
waitInterval	= 25	# count of millisecond to wait between incrementing placement data

# code ***********************************************************************************

setInitialPosition() # reset Fusion object to starting position

# the next lines of code locate our 'Fusion' object, and extract the x,y,z for it's position in 3-space
# as well as the yaw, pitch and roll of the object
doc			= FreeCAD.ActiveDocument
object		= doc.Fusion
objectP		= object.Placement
objectB		= objectP.Base
x			= objectB.x
y			= objectB.y
z			= objectB.z
objectR		= objectP.Rotation
objectE		= objectR.toEuler()
yaw			= objectE[0]
pitch		= objectE[1]
roll		= objectE[2]

# our animation is in 5 segments:
# 1	rotate the key clockwise
# 2 rotate the key counter-clockwise
# 3	rotate the key clockwise
# 4 extract the key from the lock housing
# 5	retract the key

updatePlacement(object, pitch, pitch+25, rotateCW)
updatePlacement(object, pitch-25, pitch+25, rotateCCW)
updatePlacement(object, pitch+25, pitch+50, rotateCW)
updatePlacement(object, z, z+50, moveUp)
updatePlacement(object, z+50, z+100, arcUp) 

Putting It All Together

  1. make sure the output from the previous tutorials is loaded
  2. make sure the object Fusion exists - this is the only object that the Python code will animate
  3. copy the Python code and paste into the Python Console

Further Information

For continuing to learn about using Python within FreeCAD, the FreeCAD Wiki has other articles on:

To Do