mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
203 lines
7.4 KiB
203 lines
7.4 KiB
For discussion. Unclear are: |
|
* is the definition of +/- values practical or counterintuitive? |
|
* are the definitions unambiguous and easy to follow? |
|
* are the examples correct? |
|
* should we have HOWTO engineer a correct matrix for a new device (without comparing to a different one)? |
|
|
|
==== |
|
|
|
|
|
Mounting matrix |
|
|
|
The mounting matrix is a device tree property used to orient any device |
|
that produce three-dimensional data in relation to the world where it is |
|
deployed. |
|
|
|
The purpose of the mounting matrix is to translate the sensor frame of |
|
reference into the device frame of reference using a translation matrix as |
|
defined in linear algebra. |
|
|
|
The typical usecase is that where a component has an internal representation |
|
of the (x,y,z) triplets, such as different registers to read these coordinates, |
|
and thus implying that the component should be mounted in a certain orientation |
|
relative to some specific device frame of reference. |
|
|
|
For example a device with some kind of screen, where the user is supposed to |
|
interact with the environment using an accelerometer, gyroscope or magnetometer |
|
mounted on the same chassis as this screen, will likely take the screen as |
|
reference to (x,y,z) orientation, with (x,y) corresponding to these axes on the |
|
screen and (z) being depth, the axis perpendicular to the screen. |
|
|
|
For a screen you probably want (x) coordinates to go from negative on the left |
|
to positive on the right, (y) from negative on the bottom to positive on top |
|
and (z) depth to be negative under the screen and positive in front of it, |
|
toward the face of the user. |
|
|
|
A sensor can be mounted in any angle along the axes relative to the frame of |
|
reference. This means that the sensor may be flipped upside-down, left-right, |
|
or tilted at any angle relative to the frame of reference. |
|
|
|
Another frame of reference is how the device with its sensor relates to the |
|
external world, the environment where the device is deployed. Usually the data |
|
from the sensor is used to figure out how the device is oriented with respect |
|
to this world. When using the mounting matrix, the sensor and device orientation |
|
becomes identical and we can focus on the data as it relates to the surrounding |
|
world. |
|
|
|
Device-to-world examples for some three-dimensional sensor types: |
|
|
|
- Accelerometers have their world frame of reference toward the center of |
|
gravity, usually to the core of the planet. A reading of the (x,y,z) values |
|
from the sensor will give a projection of the gravity vector through the |
|
device relative to the center of the planet, i.e. relative to its surface at |
|
this point. Up and down in the world relative to the device frame of |
|
reference can thus be determined. and users would likely expect a value of |
|
9.81 m/s^2 upwards along the (z) axis, i.e. out of the screen when the device |
|
is held with its screen flat on the planets surface and 0 on the other axes, |
|
as the gravity vector is projected 1:1 onto the sensors (z)-axis. |
|
|
|
If you tilt the device, the g vector virtually coming out of the display |
|
is projected onto the (x,y) plane of the display panel. |
|
|
|
Example: |
|
|
|
^ z: +g ^ z: > 0 |
|
! /! |
|
! x=y=0 / ! x: > 0 |
|
+--------+ +--------+ |
|
! ! ! ! |
|
+--------+ +--------+ |
|
! / |
|
! / |
|
v v |
|
center of center of |
|
gravity gravity |
|
|
|
|
|
If the device is tilted to the left, you get a positive x value. If you point |
|
its top towards surface, you get a negative y axis. |
|
|
|
(---------) |
|
! ! y: -g |
|
! ! ^ |
|
! ! ! |
|
! ! |
|
! ! x: +g <- z: +g -> x: -g |
|
! 1 2 3 ! |
|
! 4 5 6 ! ! |
|
! 7 8 9 ! v |
|
! * 0 # ! y: +g |
|
(---------) |
|
|
|
|
|
- Magnetometers (compasses) have their world frame of reference relative to the |
|
geomagnetic field. The system orientation vis-a-vis the world is defined with |
|
respect to the local earth geomagnetic reference frame where (y) is in the |
|
ground plane and positive towards magnetic North, (x) is in the ground plane, |
|
perpendicular to the North axis and positive towards the East and (z) is |
|
perpendicular to the ground plane and positive upwards. |
|
|
|
|
|
^^^ North: y > 0 |
|
|
|
(---------) |
|
! ! |
|
! ! |
|
! ! |
|
! ! > |
|
! ! > North: x > 0 |
|
! 1 2 3 ! > |
|
! 4 5 6 ! |
|
! 7 8 9 ! |
|
! * 0 # ! |
|
(---------) |
|
|
|
Since the geomagnetic field is not uniform this definition fails if we come |
|
closer to the poles. |
|
|
|
Sensors and driver can not and should not take care of this because there |
|
are complex calculations and empirical data to be taken care of. We leave |
|
this up to user space. |
|
|
|
The definition we take: |
|
|
|
If the device is placed at the equator and the top is pointing north, the |
|
display is readable by a person standing upright on the earth surface, this |
|
defines a positive y value. |
|
|
|
|
|
- Gyroscopes detects the movement relative the device itself. The angular |
|
velocity is defined as orthogonal to the plane of rotation, so if you put the |
|
device on a flat surface and spin it around the z axis (such as rotating a |
|
device with a screen lying flat on a table), you should get a negative value |
|
along the (z) axis if rotated clockwise, and a positive value if rotated |
|
counter-clockwise according to the right-hand rule. |
|
|
|
|
|
(---------) y > 0 |
|
! ! v---\ |
|
! ! |
|
! ! |
|
! ! <--\ |
|
! ! ! z > 0 |
|
! 1 2 3 ! --/ |
|
! 4 5 6 ! |
|
! 7 8 9 ! |
|
! * 0 # ! |
|
(---------) |
|
|
|
|
|
So unless the sensor is ideally mounted, we need a means to indicate the |
|
relative orientation of any given sensor of this type with respect to the |
|
frame of reference. |
|
|
|
To achieve this, use the device tree property "mount-matrix" for the sensor. |
|
|
|
This supplies a 3x3 rotation matrix in the strict linear algebraic sense, |
|
to orient the senor axes relative to a desired point of reference. This means |
|
the resulting values from the sensor, after scaling to proper units, should be |
|
multiplied by this matrix to give the proper vectors values in three-dimensional |
|
space, relative to the device or world point of reference. |
|
|
|
For more information, consult: |
|
https://en.wikipedia.org/wiki/Rotation_matrix |
|
|
|
The mounting matrix has the layout: |
|
|
|
(mxx, myx, mzx) |
|
(mxy, myy, mzy) |
|
(mxz, myz, mzz) |
|
|
|
Values are intended to be multiplied as: |
|
|
|
x' = mxx * x + myx * y + mzx * z |
|
y' = mxy * x + myy * y + mzy * z |
|
z' = mxz * x + myz * y + mzz * z |
|
|
|
It is represented as an array of strings containing the real values for |
|
producing the transformation matrix. |
|
|
|
Examples: |
|
|
|
Identity matrix (nothing happens to the coordinates, which means the device was |
|
mechanically mounted in an ideal way and we need no transformation): |
|
|
|
mount-matrix = "1", "0", "0", |
|
"0", "1", "0", |
|
"0", "0", "1"; |
|
|
|
The sensor is mounted 30 degrees (Pi/6 radians) tilted along the X axis, so we |
|
compensate by performing a -30 degrees rotation around the X axis: |
|
|
|
mount-matrix = "1", "0", "0", |
|
"0", "0.866", "0.5", |
|
"0", "-0.5", "0.866"; |
|
|
|
The sensor is flipped 180 degrees (Pi radians) around the Z axis, i.e. mounted |
|
upside-down: |
|
|
|
mount-matrix = "0.998", "0.054", "0", |
|
"-0.054", "0.998", "0", |
|
"0", "0", "1"; |
|
|
|
???: this does not match "180 degrees" - factors indicate ca. 3 degrees compensation
|
|
|