Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 086d840d authored by Brian Duddie's avatar Brian Duddie
Browse files

Clarify documentation for sensor placement

Update documentation to be in sync with new language added to HAL
interface, which better explains the expected payload, format, and
usage.

Fixes: 133264933
Test: make docs, view HTML
Change-Id: Ib602674d395cb8c8e6431d23b051685c8d172560
parent b613fec2
Loading
Loading
Loading
Loading
+43 −5
Original line number Diff line number Diff line
@@ -119,12 +119,50 @@ public class SensorAdditionalInfo {
    public static final int TYPE_VEC3_CALIBRATION = 0x10002;

    /**
     * Sensor placement. Describes location and installation angle of the sensor device.
     * Sensor placement.
     *
     * Payload:
     *     floatValues[0..11]: First 3 rows of homogeneous matrix in row major order that describes
     *     the location and orientation of the sensor. Origin of reference will be the mobile device
     *     geometric sensor. Reference frame is defined as the same as Android sensor frame.
     * Provides the orientation and location of the sensor element in terms of the
     * Android coordinate system. This data is given as a 3x4 matrix consisting of a 3x3 rotation
     * matrix (R) concatenated with a 3x1 location vector (t). The rotation matrix provides the
     * orientation of the Android device coordinate frame relative to the local coordinate frame of
     * the sensor. Note that assuming the axes conventions of the sensor are the same as Android,
     * this is the inverse of the matrix applied to raw samples read from the sensor to convert them
     * into the Android representation. The location vector represents the translation from the
     * origin of the Android sensor coordinate system to the geometric center of the sensor,
     * specified in millimeters (mm).
     * <p>
     * <b>Payload</b>:
     *     <code>floatValues[0..11]</code>: 3x4 matrix in row major order [R; t]
     * </p>
     * <p>
     * <b>Example</b>:
     *     This raw buffer: <code>{0, 1, 0, 0, -1, 0, 0, 10, 0, 0, 1, -2.5}</code><br>
     *     Corresponds to this 3x4 matrix:
     *     <table>
     *      <thead>
     *       <tr><td colspan="3">Orientation</td><td>Location</tr>
     *      </thead>
     *      <tbody>
     *       <tr><td>0</td><td>1</td><td>0</td><td>0</td></tr>
     *       <tr><td>-1</td><td>0</td><td>0</td><td>10</td></tr>
     *       <tr><td>0</td><td>0</td><td>1</td><td>-2.5</td></tr>
     *      </tbody>
     *     </table>
     *     The sensor is oriented such that:
     *     <ul>
     *        <li>The device X axis corresponds to the sensor's local -Y axis
     *        <li>The device Y axis corresponds to the sensor's local X axis
     *        <li>The device Z axis and sensor's local Z axis are equivalent
     *     </ul>
     *     In other words, if viewing the origin of the Android coordinate system from the positive
     *     Z direction, the device coordinate frame is to be rotated 90° counter-clockwise about the
     *     Z axis to align with the sensor's local coordinate frame. Equivalently, a vector in the
     *     Android coordinate frame may be multiplied with R to rotate it 90° clockwise (270°
     *     counter-clockwise), yielding its representation in the sensor's coordinate frame.
     *     Relative to the origin of the Android coordinate system, the physical center of the
     *     sensor is located 10mm in the positive Y direction, and 2.5mm in the negative Z
     *     direction.
     * </p>
     */
    public static final int TYPE_SENSOR_PLACEMENT = 0x10003;