:lang: en
:toc:

////////////////////////////////////////////////
use image:: for equation png files -- no latexmath
////////////////////////////////////////////////

[[cha:5-axis-kinematics]]
= 5-Axis Kinematics(((5-Axis Kinematics)))

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

== Introduction

Coordinated multi-axis CNC machine tools controlled with LinuxCNC, require a special kinematics component for each type of machine. This chapter describes some of the most popular 5-axis machine configurations and then develops the forward (from work to joint coordinates) and inverse (from joint to work) transformations in a general mathematical process for two types of machine.

The kinematics components are given as well as vismach simulation models to demonstrate their behaviour on a computer screen. Examples of HAL file data are also given.

Note that with these kinematics, the rotational axes move in the opposite direction of what the convention is. See section ["rotational axes"](https://linuxcnc.org/docs/html/gcode/machining-center.html#_rotational_axes) for details.

== 5-Axis Machine Tool Configurations

In this section we deal with the typical 5-axis milling or router machines with five joints or degrees-of-freedom which are controlled in coordinated moves.

3-axis machine tools cannot change the tool orientation, so  5-axis machine tools use two extra axes to set the cutting tool in an appropriate orientation for efficient machining of freeform surfaces.

Typical 5-axis machine tool configurations are shown in Figs. 3, 5, 7 and 9-11 [1,2] in section Figures.

The kinematics of 5-axes machine tools are much simpler than that of 6-axis serial arm robots, since 3 of the axes are normally linear axes and only two are rotational axes.

== Tool Orientation and Location

CAD/CAM systems are typically used to generate the 3D CAD models of the workpiece as well as the CAM data for input to the CNC 5-axis machine. The tool or cutter location (CL) data, is composed of the cutter tip position and the cutter orientation relative to the workpiece coordinate system. Two vectors, as generated by most CAM systems and shown in Fig. 1, contain this information:

image::5-axis-figures/equation__1.png[align="center"]

The K vector is equivalent to the 3rd vector from the pose matrix E~6~ that was used in the 6-axis robot kinematics [3] and the Q vector is equivalent to the 4th vector of E~6~. In MASTERCAM for example this information is contained in the intermediate output ".nci" file.

.Cutter location data
image::5-axis-figures/Figure-1.png[align="center",height=400]

== Translation and Rotation Matrices

Homogeneous transformations provide a simple way to describe the mathematics of
multi-axis machine kinematics. A transformation of the space H is a 4x4 matrix and can represent translation and rotation transformations. Given a point x,y,x described by a vector u = {x,y,z,1}^T^, then its transformation v is represented by the matrix product

image::5-axis-figures/equation__2.png[align="center"]

There are four fundamental transformation matrices on which 5-axis kinematics can be based:

image::5-axis-figures/equation__3.png[align="center"]

The matrix T(a,b,c) implies a translation in the X, Y, Z coordinate directions by the amounts a, b, c respectively. The R matrices imply rotations of the angle theta about the X, Y and Z coordinate axes respectively. The 'C' and 'S' symbols refer to cosine and sine functions respectively.

== Table Rotary/Tilting 5-Axis Configurations

In these machine tools the two rotational axes mount on the work table of the machine. Two forms are typically used:

* A rotary table which rotates about the vertical Z-axes (C-rotation, secondary) mounted on a tilting table which rotates about the X- or Y-axis (A- or B-rotation, primary). The workpiece is mounted on the rotary table.
* A tilting table which rotates about the X- or Y-axis (A- or B-rotation, secondary) is mounted on a rotary table which rotates about the Z-axis (C-rotation, primary), with the workpiece on the tilting table.

.General configuration and coordinate systems
image::5-axis-figures/Figure-2.png[align="center"]

A multi-axis machine can be considered to consist of a series of links connected by joints. By embedding a coordinate frame in each link of the machine and using homogeneous transformations, we can describe the relative position and orientation between these coordinate frames

We need to describe a relationship between the workpiece coordinate system and the tool coordinate system. This can be defined by a transformation matrix '^w^A~t~', which can be found by subsequent transformations between the different structural elements or links of the machine, each with its own defined coordinate system. In general such a transformation may look as follows:

image::5-axis-figures/equation__4.png[align="center"]

where each matrix '^i-1^A~j~' is a translation matrix 'T' or a rotation matrix 'R' of the form (2,3).

Matrix multiplication is a simple process in which the elements of each row of the lefthand matrix A is multiplied by the elements of each column of the righthand matrix B and summed to obtain an element in the result matrix C, ie.

image::5-axis-figures/equation__5.png[align="center"]

In Fig. 2 a generic configuration with coordinate systems is shown [4]. It includes table rotary/tilting axes as well as spindle rotary/tilting axes. Only two of the rotary axes are actually used in a machine tool.

First we will develop the transformations for the first type of configuration mentioned above, ie. a table tilting/rotary (trt) type with no rotating axis offsets. We may give it the name xyzac-trt configuration.

We also develop the transformations for the same type (xyzac-trt), but with rotating axis offsets.

Then we develop the transformations for a xyzbc-trt configuration with rotating axis offsets.

=== Transformations for a xyzac-trt machine tool with work offsets ===

.vismach model of xyzac-trt with coincident rotation axes
image::5-axis-figures/Figure-3.png[align="center"]

We deal here with a simplified configuration in which the tilting axis and rotary axis intersects at a point called the pivot point as shown in Fig. 4. therefore the two coordinate systems 'O~ws~' and 'O~wp~' of Fig. 2 are coincident.

.Table tilting/rotary configuration
image::5-axis-figures/Figure-4.png[align="center",height=400]

==== Forward transformation ====

The transformation can be defined by the sequential multiplication of the matrices:

image::5-axis-figures/equation__6.png[align="center"]

with the matrices built up as follows:

image::5-axis-figures/equation__7.png[align="center"]

In these equations L~x~, L~y~, L~z~ defines the offsets of the pivot point of the two rotary axes A and C relative to the workpiece coordinate system origin. Furthermore, P~x~, P~y~, P~z~ are the relative  distances of the pivot point to the cutter tip position, which can also be called the "joint coordinates" of the pivot point. The pivot point is at the intersection of the two rotary axes. The signs of the S~A~ and S~C~ terms are different to those in [2,3] since there the table rotations are negative relative to the workpiece coordinate axes (note that sin(-theta) = -sin(theta), cos(-theta) = cos(theta)).

When multiplied in accordance with (5), we obtain:

image::5-axis-figures/equation__8.png[align="center"]

We can now equate the third column of this matrix with our given tool orientation vector K, ie.:

image::5-axis-figures/equation__9.png[align="center"]

From these equations we can solve for the rotation angles theta~A~, theta~C~. From the third row we find:

image::5-axis-figures/equation__10.png[align="center"]

and by dividing the first row by the second row we find:

image::5-axis-figures/equation__11.png[align="center"]

These relationships are typically used in the CAM post-processor to convert the tool orientation vectors to rotation angles.

Equating the last column of (8) with the tool position vector Q, we can write:

image::5-axis-figures/equation__12.png[align="center"]

The vector on the right hand side can also be written as the product of a matrix and a vector resulting in:

image::5-axis-figures/equation__13.png[align="center"]

This can be expanded to give

image::5-axis-figures/equation__14.png[align="center"]

which is the 'forward transformation' of the kinematics.

==== Inverse Transformation

We can solve for P from  equation (13) as 'P = (^Q^A~P~)^-1^ * Q'. Noting that the square matrix is a homogeneous 4x4 matrix containing a rotation matrix R and translation vector q, for which the inverse can be written as:

image::5-axis-figures/equation__15.png[align="center"]

where R^T is the transpose of R (rows and columns swappped). We therefore obtain:

image::5-axis-figures/equation__16.png[align="center"]

The desired equations for the 'inverse transformation' of the kinematics thus can be written as:

image::5-axis-figures/equation__17.png[align="center"]

=== Transformations for a xyzac-trt machine  with rotary axis offsets

.vismach model of xyzac-trt with rotational axis offsets (positive)
image::5-axis-figures/Figure-5.png[align="center"]

We deal here with a extended configuration in which the tilting axis and rotary axis do not intersect at a point but have an offset D~y~.
Furthermore, there is also an z-offset between the two coordinate systems 'O~ws~' and 'O~wp~' of Fig. 2, called D~z~.
A vismach model is shown in Fig. 5 and the offsets are shown in Fig. 6 (positive offsets in this example).
To simplify the configuration, the offsets L~x~, L~y~, L~z~ of the previous case are not included.
They are probably not necessary if one uses the G54 offsets in LinuxCNC by means of the "touch of" facility.

.Table tilting/rotary xyzac-trt configuration, with axis offsets
image::5-axis-figures/Figure-6.png[align="center",height=350]

==== Forward Transformation

The transformation can be defined by the sequential multiplication of the matrices:

image::5-axis-figures/equation__18.png[align="center"]

with the matrices built up as follows:

image::5-axis-figures/equation__19.png[align="center"]

In these equations D~y~, D~z~ defines the offsets of the pivot point of the rotary axes A  relative to the workpiece coordinate system origin. Furthermore, P~x~, P~y~, P~z~ are the relative  distances of the pivot point to the cutter tip position, which can also be called the "joint coordinates" of the pivot point. The pivot point is on the A rotary axis.

When multiplied in accordance with (18), we obtain:

image::5-axis-figures/equation__20.png[align="center"]

We can now equate the third column of this matrix with our given tool orientation vector K, ie.:

image::5-axis-figures/equation__21.png[align="center"]

From these equations we can solve for the rotation angles theta~A~, theta~C~. From the third row we find:

image::5-axis-figures/equation__22.png[align="center"]

and by dividing the second row by the first row we find:

image::5-axis-figures/equation__23.png[align="center"]

These relationships are typically used in the CAM post-processor to convert the tool orientation vectors to rotation angles.

Equating the last column of (21) with the tool position vector Q, we can write:

image::5-axis-figures/equation__24.png[align="center"]

The vector on the right hand side can also be written as the product of a matrix and a vector resulting in:

image::5-axis-figures/equation__25.png[align="center"]

which is the 'forward transformation' of the kinematics.

==== Inverse Transformation

We can solve for P from  equation (25) as 'P = (^Q^A~P~)^-1^ * Q' using (15) as before.
We thereby obtain:

image::5-axis-figures/equation__26.png[align="center"]

The desired equations for the 'inverse transformation' of the kinematics thus can be written as:

image::5-axis-figures/equation__27.png[align="center"]

=== Transformations for a xyzbc-trt machine  with rotary axis offsets

.vismach model of xyzbc-trt with rotational axis offsets (negative)
image::5-axis-figures/Figure-7.png[align="center"]

We deal here again with a extended configuration in which the tilting axis (about the y-axis) and rotary axis do not intersect at a point but have an offset D~x~.
Furthermore, there is also an z-offset between the two coordinate systems 'O~ws~' and 'O~wp~' of Fig. 2, called D~z~.
A vismach model is shown in Fig. 7 (negative offsets in this example) and the positive offsets are shown in Fig. 8.

.Table tilting/rotary xyzbc-trt configuration, with axis offsets
image::5-axis-figures/Figure-8.png[align="center",height=350]

==== Forward Transformation

The transformation can be defined by the sequential multiplication of the matrices:

image::5-axis-figures/equation__28.png[align="center"]

with the matrices built up as follows:

image::5-axis-figures/equation__29.png[align="center"]

In these equations D~x~, D~z~ defines the offsets of the pivot point of the rotary axes B relative to the workpiece coordinate system origin.
Furthermore, P~x~, P~y~, P~z~ are the relative  distances of the pivot point to the cutter tip position, which can also be called the "joint coordinates" of the pivot point.
The pivot point is on the B rotary axis.

When multiplied in accordance with (29), we obtain:

image::5-axis-figures/equation__30.png[align="center"]

We can now equate the third column of this matrix with our given tool orientation vector K, i.e.:

image::5-axis-figures/equation__31.png[align="center"]

From these equations we can solve for the rotation angles theta~B~, theta~C~. From the third row we find:

image::5-axis-figures/equation__32.png[align="center"]

and by dividing the second row by the first row we find:

image::5-axis-figures/equation__33.png[align="center"]

These relationships are typically used in the CAM post-processor to convert the tool orientation vectors to rotation angles.

Equating the last column of (32) with the tool position vector Q, we can write:

image::5-axis-figures/equation__34.png[align="center"]

The vector on the right hand side can also be written as the product of a matrix and a vector resulting in:

image::5-axis-figures/equation__35.png[align="center"]

which is the 'forward transformation' of the kinematics.

==== Inverse Transformation

We can solve for P from  equation (37) as 'P = (^Q^A~P~)^-1^ * Q'.

With the same approach as before, we obtain:

image::5-axis-figures/equation__36.png[align="center"]

The desired equations for the 'inverse transformation' of the kinematics thus can be written as:

image::5-axis-figures/equation__37.png[align="center"]

== Table Rotary/Tilting Examples

LinuxCNC includes kinematics modules for the 'xyzac-trt' and 'xyzbc-trt' topologies
described in the mathematics detailed above.  For interested users, the source code
is available in the git tree in the 'src/emc/kinematics/' directory.

Example xyzac-trt and xyzbc-trt simulation configurations are located
in the Sample Configurations ('configs/sim/axis/vismach/5axis/table-rotary-tilting/')
directory.

The example configurations include the required INI files and an examples subdirectory
with G-code (NGC) files. These sim configurations invoke a realistic 3-dimensional model
using the LinuxCNC vismach facility.

=== Vismach Simulation Models

Vismach is a library of python routines to display a dynamic simulation of a CNC machine on the PC screen. The python script for a particular machine is loaded in HAL and data passed by HAL pin connections.  The non-realtime vismach model is loaded by a HAL command like:

[source,{hal}]
----
loadusr -W xyzac-trt-gui
----

and connections are made using HAL commands like:

----
net  :table-x   joint.0.pos-fb xyzac-trt-gui.table-x
net  :saddle-y  joint.1.pos-fb xyzac-trt-gui.saddle-y
...
----

See the simulation INI files for details of the HAL connections used for the vismach model.

=== Tool-Length Compensation

In order to use tools from a tool table sequentially with tool-length compensation applied automatically, a further Z-offset is required. For a tool that is longer than the "master" tool, which typically has a tool length of zero, LinuxCNC has a variable called "motion.tooloffset.z". If this variable is passed on to the kinematic component (and vismach python script), then the necessary additional Z-offset for a new tool can be accounted for by adding the component statement, for example:

image::5-axis-figures/equation__38.png[align="center"]

The required HAL connection (for xyzac-trt) is:

[source,{hal}]
----
net :tool-offset motion.tooloffset.z xyzac-trt-kins.tool-offset
----

where:

----
:tool-offset ---------------- signal name
motion.tooloffset.z --------- output HAL pin from LinuxCNC motion module
xyzac-trt-kins.tool-offset -- input  HAL pin to xyzac-trt-kins
----

== Custom Kinematics Components

LinuxCNC implements kinematics using a HAL component that is loaded
at startup of LinuxCNC.  The most common kinematics module, 'trivkins',
implements identity (trivial) kinematics where there is a one-to-one
correspondence between an axis coordinate letter and a motor joint.
Additional kinematics modules for more complex systems (including 'xyzac-trt'
and 'xyzbc-trt' described above) are available.

See the kins manpage (*\$ man kins*) for brief descriptions of the available
kinematics modules.

The kinematics modules provided by LinuxCNC are typically written in the
C-language.  Since a standard structure is used, creation of a custom
kinematics module is facilitated by copying an existing source file to a user
file with a new name, modifying it, and then installing.

Installation is done using halcompile:

----
sudo halcompile --install kinsname.c
----

where "kinsname" is the name you give to your component. The sudo prefix is
required to install it and you will be asked for your root password.  See the
halcompile man page for more information (*\$ man halcompile*)

Once it is compiled and installed you can reference it in your config setup of
your machine. This is done in the INI file of your config directory. For
example, the common INI specificaion:

[source,{ini}]
----
[KINS]
KINEMATICS = trivkins
----

is replaced by

[source,{ini}]
----
[KINS]
KINEMATICS = kinsname
----

where "kinsname" is the name of your kins program.
Additional HAL pins may be created by the module for variable configuration items
such as the D~x~, D~y~, D~z~, tool-offset used in the xyzac-trt kinematics module.
These pins can be connected to a signal for dynamic control or set once with HAL connections like:

[source,{hal}]
----
# set offset parameters
net :tool-offset motion.tooloffset.z xyzac-trt-kins.tool-offset
setp xyzac-trt-kins.y-offset 0
setp xyzac-trt-kins.z-offset 20
----

== Figures

.Table tilting/rotating configuration
image::5-axis-figures/Figure-9.png["Table tilting/rotating configuration",align="center",height=300]

.Spindle/table tilting configuration
image::5-axis-figures/Figure-10.png["Spindle/table tilting configuration",align="center",height=300]

.Spindle tilting/rotary configuration
image::5-axis-figures/Figure-11.png["Spindle tilting/rotary configuration",align="center",height=300]

/////////////////////////////////////////////////////
== References  nope nope nope pdf nope
/////////////////////////////////////////////////////

== REFERENCES

. AXIS MACHINE TOOLS: Kinematics and Vismach Implementation in LinuxCNC, RJ du Preez, SA-CNC-CLUB, April 7, 2016.
. A Postprocessor Based on the Kinematics Model for General Five-Axis machine
  Tools: C-H She, R-S Lee, J Manufacturing Processes, V2 N2, 2000.
. NC Post-processor for 5-axis milling of table-rotating/tilting type: YH Jung,
  DW Lee, JS Kim, HS Mok, J Materials Processing Technology,130-131 (2002)
  641-646.
. 3D 6-DOF Serial Arm Robot Kinematics, RJ du Preez, SA-CNC-CLUB, Dec. 5, 2013.
. Design of a generic five-axis postprocessor based on generalized kinematics
  model of machine tool: C-H She, C-C Chang, Int. J Machine Tools & Manufacture,
  47 (2007) 537-545.

// vim: set syntax=asciidoc:
