From ad7f33a29c6ce41f2b662d1de9af7e9cf92f4dc9 Mon Sep 17 00:00:00 2001 From: Mathias Agopian Date: Wed, 7 Sep 2011 15:56:03 -0700 Subject: [PATCH] improve the gyroscope javadoc change the sample code to something more useful and more correct. Change-Id: Ia81f86a2f409edbb395405ababae307663824cb9 --- core/java/android/hardware/SensorEvent.java | 77 +++++++++++++++------ 1 file changed, 55 insertions(+), 22 deletions(-) diff --git a/core/java/android/hardware/SensorEvent.java b/core/java/android/hardware/SensorEvent.java index 0411b5c02f1b4..784bcc535be74 100644 --- a/core/java/android/hardware/SensorEvent.java +++ b/core/java/android/hardware/SensorEvent.java @@ -154,16 +154,16 @@ public class SensorEvent { * All values are in micro-Tesla (uT) and measure the ambient magnetic field * in the X, Y and Z axis. * - *

{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}:

- * All values are in radians/second and measure the rate of rotation - * around the X, Y and Z axis. The coordinate system is the same as is - * used for the acceleration sensor. Rotation is positive in the counter-clockwise - * direction. That is, an observer looking from some positive location on the x, y. - * or z axis at a device positioned on the origin would report positive rotation - * if the device appeared to be rotating counter clockwise. Note that this is the - * standard mathematical definition of positive rotation and does not agree with the - * definition of roll given earlier. - * + *

{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}: + *

All values are in radians/second and measure the rate of rotation + * around the device's local X, Y and Z axis. The coordinate system is the + * same as is used for the acceleration sensor. Rotation is positive in the + * counter-clockwise direction. That is, an observer looking from some + * positive location on the x, y or z axis at a device positioned on the + * origin would report positive rotation if the device appeared to be + * rotating counter clockwise. Note that this is the standard mathematical + * definition of positive rotation and does not agree with the definition of + * roll given earlier. * *

- * Typically the output of the gyroscope is integrated over time to calculate - * an angle, for example: + * Typically the output of the gyroscope is integrated over time to + * calculate a rotation describing the change of angles over the timestep, + * for example: *

+ * * 
      *     private static final float NS2S = 1.0f / 1000000000.0f;
+     *     private final float[] deltaRotationVector = new float[4]();
      *     private float timestamp;
-     *     public void onSensorChanged(SensorEvent event)
-     *     {
+     *
+     *     public void onSensorChanged(SensorEvent event) {
+     *          // This timestep's delta rotation to be multiplied by the current rotation
+     *          // after computing it from the gyro sample data.
      *          if (timestamp != 0) {
      *              final float dT = (event.timestamp - timestamp) * NS2S;
-     *              angle[0] += event.values[0] * dT;
-     *              angle[1] += event.values[1] * dT;
-     *              angle[2] += event.values[2] * dT;
+     *              // Axis of the rotation sample, not normalized yet.
+     *              float axisX = event.values[0];
+     *              float axisY = event.values[1];
+     *              float axisZ = event.values[2];
+     *
+     *              // Calculate the angular speed of the sample
+     *              float omegaMagnitude = sqrt(axisX*axisX + axisY*axisY + axisZ*axisZ);
+     *
+     *              // Normalize the rotation vector if it's big enough to get the axis
+     *              if (omegaMagnitude > EPSILON) {
+     *                  axisX /= omegaMagnitude;
+     *                  axisY /= omegaMagnitude;
+     *                  axisZ /= omegaMagnitude;
+     *              }
+     *
+     *              // Integrate around this axis with the angular speed by the timestep
+     *              // in order to get a delta rotation from this sample over the timestep
+     *              // We will convert this axis-angle representation of the delta rotation
+     *              // into a quaternion before turning it into the rotation matrix.
+     *              float thetaOverTwo = omegaMagnitude * dT / 2.0f;
+     *              float sinThetaOverTwo = sin(thetaOverTwo);
+     *              float cosThetaOverTwo = cos(thetaOverTwo);
+     *              deltaRotationVector[0] = sinThetaOverTwo * axisX;
+     *              deltaRotationVector[1] = sinThetaOverTwo * axisY;
+     *              deltaRotationVector[2] = sinThetaOverTwo * axisZ;
+     *              deltaRotationVector[3] = cosThetaOverTwo;
      *          }
      *          timestamp = event.timestamp;
+     *          float[] deltaRotationMatrix = new float[9];
+     *          SensorManager.getRotationMatrixFromVector(deltaRotationMatrix, deltaRotationVector);
+     *          // User code should concatenate the delta rotation we computed with the current rotation
+     *          // in order to get the updated rotation.
+     *          // rotationCurrent = rotationCurrent * deltaRotationMatrix;
      *     }
      *
- * - *

In practice, the gyroscope noise and offset will introduce some errors which need - * to be compensated for. This is usually done using the information from other - * sensors, but is beyond the scope of this document.

- * + *

+ * In practice, the gyroscope noise and offset will introduce some errors + * which need to be compensated for. This is usually done using the + * information from other sensors, but is beyond the scope of this document. + *

*

{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:

*