요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
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
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
초안의 검토 질문
1-9이 문서는 논의를 위한 초안이며 다음 사항이 불분명하다고 밝힙니다. 양수/음수 값 정의가 실용적인지 또는 직관에 반하는지, 정의가 모호하지 않고 따라가기 쉬운지, 예제가 올바른지, 다른 device와 비교하지 않고 새 device의 올바른 matrix를 설계하는 HOWTO가 필요한지를 검토해야 합니다.
Sensor frame에서 device frame으로
10-46Mounting matrix는 3차원 데이터를 생성하는 device가 배치된 세계를 기준으로 그 device의 방향을 정하는 device-tree property입니다. Linear algebra의 transformation matrix를 사용해 sensor frame of reference를 device frame of reference로 변환합니다.
일반적인 component는 (x,y,z) 좌표를 서로 다른 register에서 읽는 식으로 내부 표현을 가지며, 이 표현은 component가 특정 device frame에 대해 정해진 방향으로 장착되어야 함을 전제합니다. Screen과 같은 chassis에 accelerometer, gyroscope 또는 magnetometer를 장착한 device에서는 보통 screen을 (x,y,z) 기준으로 삼습니다. (x,y)는 screen 평면의 축이고 (z)는 screen에 수직인 depth 축입니다.
Screen 기준으로 x는 왼쪽의 음수에서 오른쪽의 양수로, y는 아래의 음수에서 위의 양수로, z는 screen 아래의 음수에서 사용자 얼굴 방향인 screen 앞의 양수로 두는 것이 바람직합니다. Sensor는 frame에 대해 뒤집히거나 좌우가 바뀌거나 임의 각도로 기울어질 수 있습니다.
또 다른 frame은 sensor를 포함한 device와 외부 세계의 관계입니다. 보통 sensor data로 세계에 대한 device 방향을 구합니다. Mounting matrix를 사용하면 sensor와 device 방향이 같아지므로 주변 세계와 관련된 data 자체에 집중할 수 있습니다.
Accelerometer와 gravity projection
47-92Accelerometer의 world frame은 보통 행성 중심인 gravity center를 향합니다. Sensor의 (x,y,z)는 지표의 해당 지점에서 device를 통과하는 gravity vector의 projection을 나타내므로 device frame에 대한 세계의 위아래를 판별할 수 있습니다. Screen을 행성 표면에 평평하게 두면 gravity vector가 sensor z axis에 1:1로 projection되어 사용자는 screen 밖을 향하는 z에서 9.81 m/s^2, 다른 축에서 0을 기대합니다.
Device를 기울이면 display 밖으로 나오던 g vector가 display panel의 (x,y) plane에도 projection됩니다. 왼쪽으로 기울이면 x가 양수가 되고, device 상단을 지표 쪽으로 향하게 하면 y가 음수가 됩니다.
원문의 평평한 device와 기울어진 device ASCII 그림을 같은 의미의 단계로 정리합니다.
원문의 keypad 형태 axis 그림을 screen 방향과 부호 표로 다시 그렸습니다.
Magnetometer의 지자기 기준
93-128Magnetometer(compass)의 world frame은 geomagnetic field를 기준으로 합니다. Local Earth geomagnetic frame에서 y는 ground plane에 있고 magnetic North 쪽이 양수입니다. x도 ground plane에 있지만 North axis와 수직이며 East 쪽이 양수입니다. z는 ground plane에 수직이고 위쪽이 양수입니다.
Geomagnetic field가 균일하지 않으므로 극점에 가까워지면 이 정의는 성립하지 않습니다. 복잡한 계산과 empirical data가 필요하므로 sensor와 driver가 이를 처리할 수도 없고 처리해서도 안 되며 user space에 맡깁니다.
채택한 정의에서는 device를 적도에 놓고 상단이 북쪽을 향하며 지표에 똑바로 선 사람이 display를 읽을 수 있을 때 y가 양수입니다.
원문의 compass ASCII 그림을 local geomagnetic frame 표로 정리했습니다.
Gyroscope와 right-hand rule
129-149Gyroscope는 device 자체에 대한 움직임을 검출합니다. Angular velocity는 rotation plane에 직교하는 방향으로 정의합니다. Screen이 있는 device를 table에 평평하게 놓고 z axis 주위로 회전하면 right-hand rule에 따라 clockwise rotation은 z axis의 음수, counter-clockwise rotation은 양수가 되어야 합니다.
원문의 회전 ASCII 그림을 right-hand rule의 방향 흐름으로 다시 그렸습니다.
3x3 mount-matrix와 예제
150-203Sensor가 이상적인 방향으로 장착되지 않았다면 해당 sensor의 frame에 대한 상대 방향을 표시할 방법이 필요합니다. 이를 위해 sensor node의 `mount-matrix` device-tree property를 사용합니다.
`mount-matrix`는 엄밀한 linear algebra 의미의 3x3 rotation matrix를 제공하여 원하는 기준점에 대한 sensor axis 방향을 맞춥니다. 적절한 단위로 scaling한 sensor 결과에 이 matrix를 곱하면 device 또는 world 기준의 올바른 3차원 vector를 얻습니다. 자세한 내용은 `https://en.wikipedia.org/wiki/Rotation_matrix`를 참조합니다.
Matrix 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 * zProperty는 transformation matrix의 real value를 string array로 표현합니다. Identity matrix는 좌표를 바꾸지 않으며 device가 기계적으로 이상적인 방향으로 장착되어 transformation이 필요 없음을 뜻합니다.
mount-matrix = "1", "0", "0",
"0", "1", "0",
"0", "0", "1";Sensor가 X axis를 따라 30도(Pi/6 radian) 기울어져 장착되었다면 X axis 주위로 -30도 rotation하여 보정합니다.
mount-matrix = "1", "0", "0",
"0", "0.866", "0.5",
"0", "-0.5", "0.866";마지막 예제는 sensor가 Z axis 주위로 180도(Pi radian) 뒤집혀 장착된 경우라고 설명합니다. 다만 원문 자체의 검토 메모는 제시된 factor가 180도와 일치하지 않고 약 3도 보정을 나타낸다고 지적합니다.
mount-matrix = "0.998", "0.054", "0",
"-0.054", "0.998", "0",
"0", "0", "1";
요약과 해설
mount-matrix.txt:1-203Accelerometer, magnetometer와 gyroscope axis convention을 구조화했습니다.