1. Introduction
---------------

First of all I want to reduce the expectations of all those who are too
enthusiastic. Synfig is a 2D animation program and it is not intended for
drawing layers in 3D. There are some restriction that need to be kept in mind:
- The more layers a drawing has, the more issues will come up with layers that
  have the wrong Z-depth. Especially if layers are overlapping, certain errors
  are unavoidable.
- The layers are shown in parallel projection which does not look very
  realistic if the layers are close to the viewer.
- Editing the drawing needs a lot of concentrated work. Points can only be 
  changed by editing long mathematical functions.

At this point, I don't want to explain how mathematical functions can be 
introduced into Synfig. There are already some good tutorials available, for
example the tutorial "Parabolic Shot" which can be found under 
"Advanced Tutorials". I only want to show the necessary functions for drawing
3D Objects.


2. Rotating points in a 3D coordinate system, some mathematics
--------------------------------------------------------------

For those who want to step further into the mathematical basics, I can recommend
two Wikipedia articles:
http://en.wikipedia.org/wiki/Rotation_matrix
http://en.wikipedia.org/wiki/Matrix_multiplication


x0, y0, z0:  coordinates of a point in a coordinate system
roll:        rotation angle about the x-axis
yaw:         rotation angle about the y-axis

Rotation matrix for the rotation about the x-axis, angle roll:

     ⎛1   0           0        ⎞ 
Rx = ⎜0   cos(roll)  -sin(roll)⎟
     ⎝0   sin(roll)   cos(roll)⎠

Rotation matrix for the rotation about the y-axis, angle yaw:

     ⎛ cos(yaw)   0    sin(yaw)⎞
Ry = ⎜ 0          1    0       ⎟
     ⎝-sin(yaw)   0    cos(yaw)⎠


In a first step, we want to rotate the point P(x0/y0/z0) about the x-axis.
The coordinates of the point after the rotation are calculated by multiplying
the rotation matrix Rx with the point vector:

Coordinates after rotating:

⎛x1⎞   ⎛1   0           0        ⎞   ⎛x0⎞   ⎛ x0                             ⎞
⎜y1⎟ = ⎜0   cos(roll)  -sin(roll)⎟ * ⎜y0⎟ = ⎜ y0 * cos(roll) + z0 * sin(roll)⎟
⎝z1⎠   ⎝0   sin(roll)   cos(roll)⎠   ⎝z0⎠   ⎝-y0 * sin(roll) + z0 * cos(roll)⎠


Now comes the second step. We want to rotate the point about the y-axis. We
calculate this by multiplying the result of the first step with the rotation
matrix Ry.

⎛x2⎞   ⎛ cos(yaw)    0     sin(yaw)⎞   ⎛x1⎞   
⎜y2⎟ = ⎜ 0           1     0       ⎟ * ⎜y2⎟ = 
⎝z2⎠   ⎝-sin(yaw)    0     cos(yaw)⎠   ⎝z2⎠   

       ⎛ cos(yaw)    0     sin(yaw)⎞   ⎛ x0                             ⎞
     = ⎜ 0           1     0       ⎟ * ⎜ y0 * cos(roll) + z0 * sin(roll)⎟
       ⎝-sin(yaw)    0     cos(yaw)⎠   ⎝-y0 * sin(roll) + z0 * cos(roll)⎠

       ⎛x0 * cos(yaw) + sin(yaw) * (y0 * sin(roll) - z0 * cos(roll))⎞
     = ⎜y0 * cos(roll) + z0 * sin(roll)                             ⎟
       ⎝x0 * sin(yaw) - cos(yaw) * (y0 * sin(roll) - z0 * cos(roll))⎠



x0, y0, z0:  coordinates of a point in a coordinate system
roll:        rotation angle about the x-axis
yaw:         rotation angle about the y-axis

Rotating the point about x-axis (roll) and y-axis (yaw), we get the X- and Y-
coordinates of the projected point: 

X = x0 * cos(yaw) + sin(yaw) * (y0 * sin(roll) - z0 * cos(roll))
Y = y0 * cos(roll) + z0 * sin(roll)

These are the formulas that we have to introduce for each point of each layer. 



3. The Z-depth of a layer
-------------------------

The next challenge is to find the right Z-depth for each layer. As reference
for the Z-depth we use the Z-coordinate of a point in the centre of the layer.

Z = x0 * sin(yaw) - cos(yaw) * (y0 * sin(roll) - z0 * cos(roll))

But two things need to be taken into account:

A higher value of the Z-coordinate means the layer is closer to the viewer
which means the layer needs to get a lower Z-depth. To achieve this, the 
Z-coordinate is multyplied by -1.

All layers have a "natural" Z-depth, automatically assigned by the order. To
eliminate the influence of the "natural" Z-depth we must subtract the "natural"
Z-depth. The result is the following formula:

Z-depth = -Z - Zn

or

Z-depth = -(x0 * sin(yaw) - cos(yaw) * (y0 * sin(roll) - z0 * cos(roll))) - Zn

after rotating, with

x0, y0, z0:  coordinates of the centre point in a coordinate system
roll:        rotation angle about the x-axis
yaw:         rotation angle about the y-axis
Zn:          "natural" Z-depth


4. Drawing 3D Objects
---------------------

Attached you will find a Synfig-file which contains four layers. One is a simple
circle without any special funcions. The second one is a polygon with four edges.
Additionally, there are two rotation layers, named "roll" and "yaw". If you edit
one or both of the rotation angles, you can see that the polygon seems to be 
rotated around the circle. This is possible because each edge contains the
formulas that are described above.
If you want to build up a 3D object, copy the polygon and edit formulas of the
Z-depth and the edges.