/TcTransform

Coordinate System and Transformation Library for Beckhoff TwinCAT 3 PLC Environment

MIT LicenseMIT

TcTransform

Description

A TwinCAT 3 Library for 3D Coordinate System Transformations.

Features include:

Compare to:

TwinCAT 3 Installation

From Binary

  1. Go to the releases page and download the *.library file from the latest release, saving it to a temporary directory somewhere on the computer running TwinCAT.
  2. Follow the library installation instructions from Beckhoff, using the 'Install' option and browsing for the local copy you had just downloaded.
  3. After installtion, you may delete the local copy of the library that you had downloaded. Beckhoff has likely copied it to a version-specific folder in C:\TwinCAT\3.1\Components\Plc\Managed Libraries\Burks\TcMatrix\

From Source

Preconditions:

  • TwinCAT 3.1.4024 XAE
  • TwinCAT 3.1.4024 XAR, ideally configured with an isolated core
  • Visual Studio Community or Shell, 2019 or higher
  • TcUnit v1.2 or higher
  • TcMatrix : Matrix math library

Compilation:

  1. Clone the repository to a computer running TwinCAT 3
  2. Open the main solution file in Visual Studio
  3. Within the Visual Studio TcTransform project, right click on the TcTransform/TcTransform Project item and select Rebuild
    1. There should be no compile errors, although there may be warnings
  4. Right click on the TcTransform/TcTransform Project item again and select Save as library and install
    1. The file can be saved anywhere, but a local Builds folder is always a good choice

Test:

  1. Within the Visual Studio TcTransformTest project, right click on the PLC/TcTransformTest/TcTransformTest Project item and select Rebuild
    1. There should be no compile errors, although there may be warnings
  2. Open the SYSTEM/Real-Time item and click Read From Target, then assign all tasks to an isolated core from your system
  3. In the Visual Studio toolbar (or TwinCAT file menu) click Activate Configuration
  4. When prompted, agree to start the project in run mode and auto-start the boot project
  5. After a few seconds the TcUnit results should be visible in the Error List window. Verify that all tests have passed.

Library Components

Vector3 Class

This class is a 3x1 column vector with X, Y, and Z components. It derives from the base TcMatrix.Matrix FB and inherits all of that base functionality, but its size is fixed at 3x1. Unlike the base Matrix FB, instances of Vector3 can be assigned (:=) or returned from functions directly by value (no internal pointers!).

Initialization

These methods all clear the previous contents of the vector and set it to the new values.

  • FB_init : When initialized by TwinCAT (called implicitley) the vector sets the value of all three components (X,Y,Z) to 0.0
  • Clear() : (From base class) Resets all three components (X,Y,Z) to 0.0;
  • SetFromComponents(X,Y,Z) : Allows initializing all three components (X,Y,Z) in once line
  • SetAsCrossProduct(A,B) : Allows initializing the vector as the cross product of two other vectors (A x B)

Properties

  • X : Get or set the first element (I=0) of the vector
  • Y : Get or set the second element (I=1) of the vector
  • Z : Get or set the third element (I=2) of the vector

Modifiers

These methods are used to alter the value of an existing vector.

  • Reverse() : Equivalent to scaling the vector by -1, this reverses the value of each element of the vector
  • SumWith(V) : Sets each element of this vector to the sum of its current value and the value of its corresponding element in the supplied vector
  • RotateBy(R) : Rotates the current vector out of the supplied rotation frame
  • RotateByReverse(R) : Rotates the current vector into the supplied rotation frame
  • TransformBy(H) : Transforms the current vector out of the supplied coordinate system
  • TransformByReverse(H) : Transforms the current vector into the supplied coordinate system

Getters

These methods are used to return a new vector based on the values of the current vector and other supplied objects.

  • GetScaled(S) : Returns a vector where each element as been scaled by the supplied LREAL
  • GetReversed() : Returns a vector where each element has been scaled by -1
  • GetVector3Sum(V) : Returns a vector where each element is the sum of the corresponding values in this vector and the supplied vector
  • GetVector3Difference(V) : Returns a vector where each element is the sum of the corresponding values in this vector (as minuend) and the supplied vector (as subtrahend)
  • GetVector3DotProduct(V) : Returns an LREAL that is the dot product of this vector and the supplied vector
  • GetVector3CrossProduct(V) : Returns a vector that is the cross product of this vector and the supplied vector

RMatrix (Rotation Matrix) Class

This class is a 3x3 matrix that describes a rotation in 3D. There are a ton of resources available to learn more about 3D rotation matricies and help develop an intuition for them.