Author: Kronus
Author Website:

Requirements: No addons required

Version: 1.0

Short description: A small library of functions to help with orientation representation.

Date: 2015-07-16 23:43

Comments: (0)


Matrix and Orientation Tool Pack

Kyle Kotowick

I've been working with ARMA for a while but have yet to make a substantial contribution of community content, so I thought this would be a good first step.

I've recently been using ARMA 3 as a research tool (simulator), and that work required some tools that didn't yet exist in ARMA. Specifically, manipulation of matricies and standardized representations of orientation. As you may know, ARMA uses a rather odd system for orientation of objects (vectorDirAndUp), and that system is not very compatible with standardized formats. BIS has offered a couple functions to convert orientations to/from the more standard Euler angles (roll, pitch, yaw) in BIS_fnc_getPitchBank and BIS_fnc_setPitchBank functions, but as stated in the notes for BIS_fnc_getPitchBank, "The bank returned by this command is not fully accurate, it can be off by up to 5% or so (depending on pitch), due to an unknown bug." In addition, Euler angles have issues with singularities (which is why quaternions were developed), and that was not acceptable for my research work. So, I decided to develop a small library of functions to help with orientation representation. In order to do so, I also had to develop a couple functions for matrix manipulation. These functions should avoid any issues that the BIS functions have with accuracy, and in theory should be a perfect representation.

In this package, there are three representations of orientations:
1) the ARMA "vectorDirAndUp" representation
2) Euler angle (roll-pitch-yaw) representation
3) direction cosine matrix (DCM) (a.k.a "rotation matrix") representation

The ARMA representation isn't good for much at all, but it's what we have to work with. Euler angles are great and easy to learn, but have limitations with singularities at certain angles. DCMs are a bit trickier to understand, but are a standardized representation that have no limitations and can be converted into anything with well-defined equations.

In this library, all matricies (2-dimensional arrays) are represented in the following format:
 [r1c1, r1c2, r1c3],
 [r2c1, r2c2, r2c3],
 [r3c1, r3c2, r3c3]

Where "r1" is "row 1" and "c1" is "column 1".

This library contains the following functions:
MOP_fnc_getDCM: this function will get the direction cosine matrix for a given object
MOP_fnc_vectorDirAndUp2DCM: this function will covert a given vectorDir and vectorUp to a DCM
MOP_fnc_DCM2vectorDirAndUp: this function will convert a given DCM to a vectorDir and vectorUp
MOP_fnc_DCM2RPY*: this function will convert a given DCM to an array of Euler angles [roll,pitch,yaw]
MOP_fnc_RPY2DCM*: this function will convert a given array of Euler angles [roll,pitch,yaw] to a DCM
MOP_matrixMultiply: this function will multiply two given matricies
MOP_matrixTranspose: this function will return the transpose of the given matrix

*Note: several of these functions (those marked by an asterisk) have an additional boolean parameter to determine if the Euler angles (roll-pitch-yaw) should be in degrees or radians.

I have found this library to be invaluble for my work, but obviously it will be of very limited use to the casual scripter/missionmaker. If there's any community interest in this, I might add more mathematical functions that aren't currently available. So, if you have a request, post it here!

Installation / Usage:
To use these functions, you might use a script that looks like this:
_vehicle = vehicle player;
_DCM = [_vehicle] call MOP_fnc_getDCM;
_RPY = [_DCM] call MOP_fnc_DCM2RPY;
hint format["Roll: %1, Pitch: %2, Yaw: %3", _RPY select 0, _RPY select 1, _RPY select 2];

I have also included a description.ext file which has content that must be added to your description.ext in order for these functions to be recognized by the game.

Known issues:
Please let me know if there are any bugs/issues with getting these functions installed and I'll see if I can make it easier.

- first release

Forum topic:
- BI forums

Enable javascript to be able to download from Armaholic please!

Tags: Matrix,   Orientation