* Definition of the coordinate system used by the SensorEvent API. *
* ** The coordinate-system is defined relative to the screen of the phone in its * default orientation. The axes are not swapped when the device's screen * orientation changes. *
* ** The X axis is horizontal and points to the right, the Y axis is vertical and * points up and the Z axis points towards the outside of the front face of the * screen. In this system, coordinates behind the screen have negative Z values. *
* **
* Note: This coordinate system is different from the one used in the * Android 2D APIs where the origin is in the top-left corner. *
* * @see SensorManager * @see SensorEvent * @see Sensor * */ public class SensorEvent { /** ** The length and contents of the {@link #values values} array depends on * which {@link android.hardware.Sensor sensor} type is being monitored (see * also {@link SensorEvent} for a definition of the coordinate system used). *
* ** A sensor of this type measures the acceleration applied to the device * (Ad). Conceptually, it does so by measuring forces applied to the * sensor itself (Fs) using the relation: *
* ** In particular, the force of gravity is always influencing the measured * acceleration: *
* ** For this reason, when the device is sitting on a table (and obviously not * accelerating), the accelerometer reads a magnitude of g = 9.81 * m/s^2 *
* ** Similarly, when the device is in free-fall and therefore dangerously * accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a * magnitude of 0 m/s^2. *
* ** It should be apparent that in order to measure the real acceleration of * the device, the contribution of the force of gravity must be eliminated. * This can be achieved by applying a high-pass filter. Conversely, a * low-pass filter can be used to isolate the force of gravity. *
* *
*
* public void onSensorChanged(SensorEvent event)
* {
* // alpha is calculated as t / (t + dT)
* // with t, the low-pass filter's time-constant
* // and dT, the event delivery rate
*
* final float alpha = 0.8;
*
* gravity[0] = alpha * gravity[0] + (1 - alpha) * event.values[0];
* gravity[1] = alpha * gravity[1] + (1 - alpha) * event.values[1];
* gravity[2] = alpha * gravity[2] + (1 - alpha) * event.values[2];
*
* linear_acceleration[0] = event.values[0] - gravity[0];
* linear_acceleration[1] = event.values[1] - gravity[1];
* linear_acceleration[2] = event.values[2] - gravity[2];
* }
*
*
* * Examples: *
* 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) {
* // 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;
* // 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. *
** Note: Some proximity sensors only support a binary near or * far measurement. In this case, the sensor should report its * {@link android.hardware.Sensor#getMaximumRange() maximum range} value in * the far state and a lesser value in the near state. *
* *A three dimensional vector indicating the direction and magnitude of gravity. Units * are m/s^2. The coordinate system is the same as is used by the acceleration sensor.
*Note: When the device is at rest, the output of the gravity sensor should be identical * to that of the accelerometer.
* *The output of the accelerometer, gravity and linear-acceleration sensors must obey the * following relation:
*The rotation vector represents the orientation of the device as a combination of an angle * and an axis, in which the device has rotated through an angle θ around an axis * <x, y, z>.
*The three elements of the rotation vector are * <x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>, such that the magnitude of the rotation * vector is equal to sin(θ/2), and the direction of the rotation vector is equal to the * direction of the axis of rotation.
* The three elements of the rotation vector are equal to * the last three components of a unit quaternion * <cos(θ/2), x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>. *Elements of the rotation vector are unitless. * The x,y, and z axis are defined in the same way as the acceleration * sensor.
* The reference coordinate system is defined as a direct orthonormal basis, * where: * * **
values[3], originally optional, will always be present from SDK Level 18 onwards. * values[4] is a new value that has been added in SDK Level 18. *
* ** values[1]: Pitch, rotation around x-axis (-180 to 180), with positive * values when the z-axis moves toward the y-axis. *
* ** values[2]: Roll, rotation around the x-axis (-90 to 90) * increasing as the device moves clockwise. *
** Note: This definition is different from yaw, pitch and roll * used in aviation where the X axis is along the long side of the plane * (tail to nose). *
* ** Note: This sensor type exists for legacy reasons, please use * {@link android.hardware.SensorManager#getRotationMatrix * getRotationMatrix()} in conjunction with * {@link android.hardware.SensorManager#remapCoordinateSystem * remapCoordinateSystem()} and * {@link android.hardware.SensorManager#getOrientation getOrientation()} to * compute these values instead. *
* ** Important note: For historical reasons the roll angle is positive * in the clockwise direction (mathematically speaking, it should be * positive in the counter-clockwise direction). *
* ** When relative ambient air humidity and ambient temperature are * measured, the dew point and absolute humidity can be calculated. *
* Dew Point ** The dew point is the temperature to which a given parcel of air must be * cooled, at constant barometric pressure, for water vapor to condense * into water. *
*
* ln(RH/100%) + m·t/(Tn+t)
* td(t,RH) = Tn · ------------------------------
* m - [ln(RH/100%) + m·t/(Tn+t)]
* for example:
*
* h = Math.log(rh / 100.0) + (17.62 * t) / (243.12 + t);
* td = 243.12 * h / (17.62 - h);
*
* Absolute Humidity
* * The absolute humidity is the mass of water vapor in a particular volume * of dry air. The unit is g/m3. *
*
* RH/100%·A·exp(m·t/(Tn+t))
* dv(t,RH) = 216.7 · -------------------------
* 273.15 + t
* for example:
*
* dv = 216.7 *
* (rh / 100.0 * 6.112 * Math.exp(17.62 * t / (243.12 + t)) / (273.15 + t));
*
*
* * The values array is shown below: *
* x_uncalib, y_uncalib, z_uncalib are the measured magnetic field in X, Y, Z axes. * Soft iron and temperature calibrations are applied. But the hard iron * calibration is not applied. The values are in micro-Tesla (uT). *
** x_bias, y_bias, z_bias give the iron bias estimated in X, Y, Z axes. * Each field is a component of the estimated hard iron calibration. * The values are in micro-Tesla (uT). *
*Hard iron - These distortions arise due to the magnetized iron, steel or permanenet * magnets on the device. * Soft iron - These distortions arise due to the interaction with the earth's magentic * field. *
** In the ideal case, a phone rotated and returning to the same real-world * orientation will report the same game rotation vector * (without using the earth's geomagnetic field). However, the orientation * may drift somewhat over time. See {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR} * for a detailed description of the values. This sensor will not have * the estimated heading accuracy value. *
* ** No gyro-drift compensation is performed. Factory calibration and temperature * compensation is still applied to the rate of rotation (angular speeds). *
** The coordinate system is the same as is used for the * {@link android.hardware.Sensor#TYPE_ACCELEROMETER} * Rotation is positive in the counter-clockwise direction (right-hand rule). * 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. * The range would at least be 17.45 rad/s (ie: ~1000 deg/s). *
Pro Tip: Always use the length of the values array while performing operations * on it. In earlier versions, this used to be always 3 which has changed now.
* * @see GeomagneticField */ public final float[] values; /** * The sensor that generated this event. See * {@link android.hardware.SensorManager SensorManager} for details. */ public Sensor sensor; /** * The accuracy of this event. See {@link android.hardware.SensorManager * SensorManager} for details. */ public int accuracy; /** * The time in nanosecond at which the event happened */ public long timestamp; SensorEvent(int valueSize) { values = new float[valueSize]; } }