# GetElementMatrix

This function gets an element's transform matrix. This contains 16 float values that multiplied to a point will give you the point transformed. It is most useful for matrix calculations such as calculating offsets. For further information, please refer to a tutorial of matrices in computer graphics programming.

Note that the matrix returned by this function is not setup correctly for some calculations.

For matrix manipulation which goes beyond the basic examples given on this page, see the Lua matrix library.

## Syntax

```table getElementMatrix ( element theElement )
```

### Required Arguments

• theElement: The element which you wish to retrieve the matrix for

### Returns

Returns a multi-dimensional array containing a 4x4 matrix. Returns false if the element is not streamed in.

## Example

This example creates a utility function that turns an offset into a position that is relative to the specified element.

```function getPositionFromElementOffset(element,offX,offY,offZ)
local m = getElementMatrix ( element )  -- Get the matrix
local x = offX * m[1][1] + offY * m[2][1] + offZ * m[3][1] + m[4][1]  -- Apply transform
local y = offX * m[1][2] + offY * m[2][2] + offZ * m[3][2] + m[4][2]
local z = offX * m[1][3] + offY * m[2][3] + offZ * m[3][3] + m[4][3]
return x, y, z                               -- Return the transformed point
end

-- Get the position of a point 3 units to the left of the element:
x,y,z = getPositionFromElementOffset(element,3,0,0)

-- Get the position of a point 2 units in front of the element:
x,y,z = getPositionFromElementOffset(element,0,2,0)

-- Get the position of a point 1 unit above the element:
x,y,z = getPositionFromElementOffset(element,0,0,1)

```

This example creates some more matrix utility functions

```function getMatrixLeft(m)
return m[1][1], m[1][2], m[1][3]
end
function getMatrixForward(m)
return m[2][1], m[2][2], m[2][3]
end
function getMatrixUp(m)
return m[3][1], m[3][2], m[3][3]
end
function getMatrixPosition(m)
return m[4][1], m[4][2], m[4][3]
end

local mat = getElementMatrix(element)  -- Get the matrix
x,y,z = getMatrixLeft(mat)     -- Get the matrix left direction
x,y,z = getMatrixForward(mat)  -- Get the matrix forward direction
x,y,z = getMatrixUp(mat)       -- Get the matrix up direction

```