SensorEvent.java revision 612ff27425cf2976396d992f32b58ab900c7d708
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware; 18 19/** 20 * <p> 21 * This class represents a {@link android.hardware.Sensor Sensor} event and 22 * holds informations such as the sensor's type, the time-stamp, accuracy and of 23 * course the sensor's {@link SensorEvent#values data}. 24 * </p> 25 * 26 * <p> 27 * <u>Definition of the coordinate system used by the SensorEvent API.</u> 28 * </p> 29 * 30 * <p> 31 * The coordinate-system is defined relative to the screen of the phone in its 32 * default orientation. The axes are not swapped when the device's screen 33 * orientation changes. 34 * </p> 35 * 36 * <p> 37 * The X axis is horizontal and points to the right, the Y axis is vertical and 38 * points up and the Z axis points towards the outside of the front face of the 39 * screen. In this system, coordinates behind the screen have negative Z values. 40 * </p> 41 * 42 * <p> 43 * <center><img src="../../../images/axis_device.png" 44 * alt="Sensors coordinate-system diagram." border="0" /></center> 45 * </p> 46 * 47 * <p> 48 * <b>Note:</b> This coordinate system is different from the one used in the 49 * Android 2D APIs where the origin is in the top-left corner. 50 * </p> 51 * 52 * @see SensorManager 53 * @see SensorEvent 54 * @see Sensor 55 * 56 */ 57 58public class SensorEvent { 59 /** 60 * <p> 61 * The length and contents of the {@link #values values} array depends on 62 * which {@link android.hardware.Sensor sensor} type is being monitored (see 63 * also {@link SensorEvent} for a definition of the coordinate system used). 64 * </p> 65 * 66 * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER 67 * Sensor.TYPE_ACCELEROMETER}:</h4> All values are in SI units (m/s^2) 68 * 69 * <ul> 70 * <p> 71 * values[0]: Acceleration minus Gx on the x-axis 72 * </p> 73 * <p> 74 * values[1]: Acceleration minus Gy on the y-axis 75 * </p> 76 * <p> 77 * values[2]: Acceleration minus Gz on the z-axis 78 * </p> 79 * </ul> 80 * 81 * <p> 82 * A sensor of this type measures the acceleration applied to the device 83 * (<b>Ad</b>). Conceptually, it does so by measuring forces applied to the 84 * sensor itself (<b>Fs</b>) using the relation: 85 * </p> 86 * 87 * <b><center>Ad = - ∑Fs / mass</center></b> 88 * 89 * <p> 90 * In particular, the force of gravity is always influencing the measured 91 * acceleration: 92 * </p> 93 * 94 * <b><center>Ad = -g - ∑F / mass</center></b> 95 * 96 * <p> 97 * For this reason, when the device is sitting on a table (and obviously not 98 * accelerating), the accelerometer reads a magnitude of <b>g</b> = 9.81 99 * m/s^2 100 * </p> 101 * 102 * <p> 103 * Similarly, when the device is in free-fall and therefore dangerously 104 * accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a 105 * magnitude of 0 m/s^2. 106 * </p> 107 * 108 * <p> 109 * It should be apparent that in order to measure the real acceleration of 110 * the device, the contribution of the force of gravity must be eliminated. 111 * This can be achieved by applying a <i>high-pass</i> filter. Conversely, a 112 * <i>low-pass</i> filter can be used to isolate the force of gravity. 113 * </p> 114 * <p> 115 * <u>Examples</u>: 116 * <ul> 117 * <li>When the device lies flat on a table and is pushed on its left side 118 * toward the right, the x acceleration value is positive.</li> 119 * 120 * <li>When the device lies flat on a table, the acceleration value is 121 * +9.81, which correspond to the acceleration of the device (0 m/s^2) minus 122 * the force of gravity (-9.81 m/s^2).</li> 123 * 124 * <li>When the device lies flat on a table and is pushed toward the sky 125 * with an acceleration of A m/s^2, the acceleration value is equal to 126 * A+9.81 which correspond to the acceleration of the device (+A m/s^2) 127 * minus the force of gravity (-9.81 m/s^2).</li> 128 * </ul> 129 * 130 * 131 * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD 132 * Sensor.TYPE_MAGNETIC_FIELD}:</h4> 133 * All values are in micro-Tesla (uT) and measure the ambient magnetic field 134 * in the X, Y and Z axis. 135 * 136 * <h4>{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}:</h4> 137 * All values are in radians/second and measure the rate of rotation 138 * around the X, Y and Z axis. The coordinate system is the same as is 139 * used for the acceleration sensor. Rotation is positive in the counter-clockwise 140 * direction. That is, an observer looking from some positive location on the x, y. 141 * or z axis at a device positioned on the origin would report positive rotation 142 * if the device appeared to be rotating counter clockwise. Note that this is the 143 * standard mathematical definition of positive rotation and does not agree with the 144 * definition of roll given earlier. 145 * 146 * <h4>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h4> 147 * 148 * <ul> 149 * <p> 150 * values[0]: Ambient light level in SI lux units 151 * </ul> 152 * 153 * <h4>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}: 154 * </h4> 155 * 156 * <ul> 157 * <p> 158 * values[0]: Proximity sensor distance measured in centimeters 159 * </ul> 160 * 161 * <p> 162 * <b>Note:</b> Some proximity sensors only support a binary <i>near</i> or 163 * <i>far</i> measurement. In this case, the sensor should report its 164 * {@link android.hardware.Sensor#getMaximumRange() maximum range} value in 165 * the <i>far</i> state and a lesser value in the <i>near</i> state. 166 * </p> 167 * 168 * <h4>{@link android.hardware.Sensor#TYPE_GRAVITY Sensor.TYPE_GRAVITY}:</h4> 169 * A three dimensional vector indicating the direction and magnitude of gravity. Units 170 * are m/s^2. The coordinate system is the same as is used by the acceleration sensor. 171 * 172 * <h4>{@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION Sensor.TYPE_LINEAR_ACCELERATION}:</h4> 173 * A three dimensional vector indicating acceleration along each device axis, not including 174 * gravity. All values have units of m/s^2. The coordinate system is the same as is used by the 175 * acceleration sensor. 176 * 177 * <h4>{@link android.hardware.Sensor#TYPE_ROTATION_VECTOR Sensor.TYPE_ROTATION_VECTOR}:</h4> 178 * The rotation vector represents the orientation of the device as a combination of an angle 179 * and an axis, in which the device has rotated through an angle theta around an axis 180 * <x, y, z>. The three elements of the rotation vector are 181 * <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude of the rotation 182 * vector is equal to sin(theta/2), and the direction of the rotation vector is equal to the 183 * direction of the axis of rotation. The three elements of the rotation vector are equal to 184 * the last three components of a unit quaternion 185 * <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>. Elements of the rotation 186 * vector are unitless. The x,y, and z axis are defined in the same way as the acceleration 187 * sensor. 188 * 189 * <h4>{@link android.hardware.Sensor#TYPE_ORIENTATION 190 * Sensor.TYPE_ORIENTATION}:</h4> All values are angles in degrees. 191 * 192 * <ul> 193 * <p> 194 * values[0]: Azimuth, angle between the magnetic north direction and the 195 * y-axis, around the z-axis (0 to 359). 0=North, 90=East, 180=South, 196 * 270=West 197 * </p> 198 * 199 * <p> 200 * values[1]: Pitch, rotation around x-axis (-180 to 180), with positive 201 * values when the z-axis moves <b>toward</b> the y-axis. 202 * </p> 203 * 204 * <p> 205 * values[2]: Roll, rotation around y-axis (-90 to 90), with positive values 206 * when the x-axis moves <b>toward</b> the z-axis. 207 * </p> 208 * </ul> 209 * 210 * <p> 211 * <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b> 212 * used in aviation where the X axis is along the long side of the plane 213 * (tail to nose). 214 * </p> 215 * 216 * <p> 217 * <b>Note:</b> This sensor type exists for legacy reasons, please use 218 * {@link android.hardware.SensorManager#getRotationMatrix 219 * getRotationMatrix()} in conjunction with 220 * {@link android.hardware.SensorManager#remapCoordinateSystem 221 * remapCoordinateSystem()} and 222 * {@link android.hardware.SensorManager#getOrientation getOrientation()} to 223 * compute these values instead. 224 * </p> 225 * 226 * <p> 227 * <b>Important note:</b> For historical reasons the roll angle is positive 228 * in the clockwise direction (mathematically speaking, it should be 229 * positive in the counter-clockwise direction). 230 * </p> 231 * 232 * @see SensorEvent 233 * @see GeomagneticField 234 */ 235 236 public final float[] values; 237 238 /** 239 * The sensor that generated this event. See 240 * {@link android.hardware.SensorManager SensorManager} for details. 241 */ 242 public Sensor sensor; 243 244 /** 245 * The accuracy of this event. See {@link android.hardware.SensorManager 246 * SensorManager} for details. 247 */ 248 public int accuracy; 249 250 251 /** 252 * The time in nanosecond at which the event happened 253 */ 254 public long timestamp; 255 256 257 SensorEvent(int size) { 258 values = new float[size]; 259 } 260} 261
