Merge "Clarify documentation for sensor placement" into qt-dev
am: 6e9c0741b5
Change-Id: I56695e9ea76f802b171c47fbb3f2dead651eb697
diff --git a/core/java/android/hardware/SensorAdditionalInfo.java b/core/java/android/hardware/SensorAdditionalInfo.java
index 5ff627f..12edc5e 100644
--- a/core/java/android/hardware/SensorAdditionalInfo.java
+++ b/core/java/android/hardware/SensorAdditionalInfo.java
@@ -119,12 +119,50 @@
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;