EyeonTips:Script/Reference/Applications/Fuse/Classes/Matrix4

From VFXPedia

Documentation

Refer to the file Matrix4.h in the C++ SDK for the description and formulas of these matrix methods.

To create a Matrix4 object, you can call:

-- <table> is a table of 16 elements
mat = Matrix4(<table>)

To convert a Matrix4 object back to a table (for printing etc...), call:

<table> = mat:GetTable()

Most matrix methods modify the existing matrix object and "add" their transformations to it (e.g. Move(), Scale(), ...). The Inverse() and Transpose() methods, however, simply return the desired matrix without modifying the object itself.

The Matrix4 class has overloaded operators in LUA, which means you can multiply and add matrices by simply writing

mat1 = Matrix4()
mat2 = Matrix4()
mat3 = mat1 * mat2    -- transform defined by mat1 followed by transform defined by mat2 

Operator overloading also works with the Vector4 class. To transform a vector with the matrix calculated above, simply write:

v = Vector4()
v2 = v * mat3

Row Vectors

Fusion's matrix and vector classes expect points as row vectors (DirectX style), not column vectors (OpenGL and wikipedia articles about matrix math). This means that to transform a vector, you'll have to put the matrix after the vector:

               | m11 m12 m13 m14 |
               |                 |  
               | m21 m22 m23 m24 |
(x y z 1)  *   |                 |  
               | m31 m32 m33 m34 |
               |                 |  
               | m41 m42 m43 m44 |

To convert a transformation matrix designed for use with column vectors (e.g. those) into a matrix that produces correct results in Fusion, use Matrix4:Transpose().

Matrix Math and Fusion's Coordinate System

In Fusion's coordinate system, 1.0 denotes full width (e.g. 1920 pixels in HD) but also full height (e.g. 1080 pixels). The coordinate system is squashed. The Matrix4 and Shape objects, however, work with coordinates that are scaled the same way in both directions.

In our example, where the horizontal image size was 1920, a Y value of "1" would also stand for 1920 vertical pixels. If you want to move a shape to the coordinates defined by the user using a OffsetControl input, you need to account for this. The formula to convert Fusion's y-coordinates for use with Matrix4 can be found in the ShapeTest example. It's goes like this:

 matrix_Y = fusion_Y * (img.Height * img.YScale) / (img.Width * img.XScale)

(img is the destination image and is used to retrieve the dimensions and pixel aspect ratio)