Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: Updated descriptions of device orientation angles." into mnc-docs

Browse Source
This commit is contained in:
Kevin Hufnagle
2016-07-20 00:45:08 +00:00
committed by Android (Google) Code Review
parent 05dd9d2c29 b4839dee24
commit d312201b74
2 changed files with 196 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
core/java/android/hardware/SensorManager.java
View File

@@ -1227,20 +1227,35 @@ public abstract class SensorManager {
/** /**
* Computes the device's orientation based on the rotation matrix. * Computes the device's orientation based on the rotation matrix.
* <p> * <p>
* When it returns, the array values is filled with the result: * When it returns, the array values are as follows:
* <ul> * <ul>
* <li>values[0]: <i>azimuth</i>, rotation around the -Z axis, * <li>values[0]: <i>Azimuth</i>, angle of rotation about the -z axis.
* i.e. the opposite direction of Z axis.</li> * This value represents the angle between the device's y
* <li>values[1]: <i>pitch</i>, rotation around the -X axis, * axis and the magnetic north pole. When facing north, this
* i.e the opposite direction of X axis.</li> * angle is 0, when facing south, this angle is &pi;.
* <li>values[2]: <i>roll</i>, rotation around the Y axis.</li> * Likewise, when facing east, this angle is &pi;/2, and
* when facing west, this angle is -&pi;/2. The range of
* values is -&pi; to &pi;.</li>
* <li>values[1]: <i>Pitch</i>, angle of rotation about the x axis.
* This value represents the angle between a plane parallel
* to the device's screen and a plane parallel to the ground.
* Assuming that the bottom edge of the device faces the
* user and that the screen is face-up, tilting the top edge
* of the device toward the ground creates a positive pitch
* angle. The range of values is -&pi; to &pi;.</li>
* <li>values[2]: <i>Roll</i>, angle of rotation about the y axis. This
* value represents the angle between a plane perpendicular
* to the device's screen and a plane perpendicular to the
* ground. Assuming that the bottom edge of the device faces
* the user and that the screen is face-up, tilting the left
* edge of the device toward the ground creates a positive
* roll angle. The range of values is -&pi;/2 to &pi;/2.</li>
* </ul> * </ul>
* <p> * <p>
* Applying these three intrinsic rotations in azimuth, pitch and roll order transforms * Applying these three rotations in the azimuth, pitch, roll order
* identity matrix to the rotation matrix given in input R. * transforms an identity matrix to the rotation matrix passed into this
* All three angles above are in <b>radians</b> and <b>positive</b> in the * method. Also, note that all three orientation angles are expressed in
* <b>counter-clockwise</b> direction. Range of output is: azimuth from -&pi; to &pi;, * <b>radians</b>.
* pitch from -&pi;/2 to &pi;/2 and roll from -&pi; to &pi;.
* *
* @param R * @param R
* rotation matrix see {@link #getRotationMatrix}. * rotation matrix see {@link #getRotationMatrix}.

259
docs/html/guide/topics/sensors/sensors_position.jd
View File

@@ -8,7 +8,7 @@ page.tags=sensorevent,orientation,proximity
<ol> <ol>
<li><a href="#sensors-pos-gamerot">Using the Game Rotation Vector Sensor</a></li> <li><a href="#sensors-pos-gamerot">Using the Game Rotation Vector Sensor</a></li>
<li><a href="#sensors-pos-geomrot">Using the Geomagnetic Rotation Vector Sensor</a></li> <li><a href="#sensors-pos-geomrot">Using the Geomagnetic Rotation Vector Sensor</a></li>
<li><a href="#sensors-pos-orient">Using the Orientation Sensor</a></li> <li><a href="#sensors-pos-orient">Computing the Device's Orientation</a></li>
<li><a href="#sensors-pos-mag">Using the Geomagnetic Field Sensor</a></li> <li><a href="#sensors-pos-mag">Using the Geomagnetic Field Sensor</a></li>
<li><a href="#sensors-pos-prox">Using the Proximity Sensor</a></li> <li><a href="#sensors-pos-prox">Using the Proximity Sensor</a></li>
</ol> </ol>
@@ -42,38 +42,49 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/Senso
</div> </div>
</div> </div>
<p>The Android platform provides two sensors that let you determine the position of a device: the <p>
geomagnetic field sensor and the orientation sensor. The Android platform also The Android platform provides two sensors that let you determine the position
provides a sensor that lets you determine how close the face of a device is to an object (known as of a device: the geomagnetic field sensor and the accelerometer. The Android
the proximity sensor). The geomagnetic field sensor and the proximity sensor are hardware-based. platform also provides a sensor that lets you determine how close the face of
Most a device is to an object (known as the <em>proximity sensor</em>). The
handset and tablet manufacturers include a geomagnetic field sensor. Likewise, handset manufacturers geomagnetic field sensor and the proximity sensor are hardware-based. Most
usually include a proximity sensor to determine when a handset is being held close to a user's face handset and tablet manufacturers include a geomagnetic field sensor. Likewise,
(for example, during a phone call). The orientation sensor is software-based and derives its data handset manufacturers usually include a proximity sensor to determine when a
from the accelerometer and the geomagnetic field sensor.</p> handset is being held close to a user's face (for example, during a phone
call). For determining a device's orientation, you can use the readings from
the device's accelerometer and the geomagnetic field sensor.
</p>
<p class="note"><strong>Note:</strong> The orientation sensor was deprecated in Android 2.2 (API <p class="note">
Level 8).</p> <strong>Note:</strong> The orientation sensor was deprecated in Android 2.2
(API level 8), and the orientation sensor type was deprecated in Android 4.4W
(API level 20).
</p>
<p>Position sensors are useful for determining a device's physical position in the <p>
world's frame of reference. For example, you can use the geomagnetic field sensor in Position sensors are useful for determining a device's physical position in
combination with the accelerometer to determine a device's position relative to the world's frame of reference. For example, you can use the geomagnetic field
the magnetic North Pole. You can also use the orientation sensor (or similar sensor-based sensor in combination with the accelerometer to determine a device's position
orientation methods) to determine a device's position in your application's frame of reference. relative to the magnetic north pole. You can also use these sensors to
Position sensors are not typically used to monitor device movement or motion, such as shake, tilt, determine a device's orientation in your application's frame of reference.
or thrust (for more information, see <a Position sensors are not typically used to monitor device movement or motion,
href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion Sensors</a>).</p> such as shake, tilt, or thrust (for more information, see <a
href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion Sensors</a>).
</p>
<p>The geomagnetic field sensor and orientation sensor return multi-dimensional arrays of sensor <p>
values The geomagnetic field sensor and accelerometer return multi-dimensional arrays
for each {@link android.hardware.SensorEvent}. For example, the orientation sensor provides of sensor values for each {@link android.hardware.SensorEvent}. For example,
geomagnetic the geomagnetic field sensor provides geomagnetic field strength values for
field strength values for each of the three coordinate axes during a single sensor event. Likewise, each of the three coordinate axes during a single sensor event. Likewise, the
the orientation sensor provides azimuth (yaw), pitch, and roll values during a single sensor event. accelerometer sensor measures the acceleration applied to the device during a
For more information about the coordinate systems that are used by sensors, see <a sensor event. For more information about the coordinate systems that are used
href="{@docRoot}guide/topics/sensors/sensors_overview.html#sensors-coords">Sensor Coordinate by sensors, see <a
Systems</a>. The proximity sensor provides a single value for each sensor event. Table 1 summarizes href="{@docRoot}guide/topics/sensors/sensors_overview.html#sensors-coords">
the position sensors that are supported on the Android platform.</p> Sensor Coordinate Systems</a>. The proximity sensor provides a single value
for each sensor event. Table 1 summarizes the position sensors that are
supported on the Android platform.
</p>
<p class="table-caption" id="table1"> <p class="table-caption" id="table1">
<strong>Table 1.</strong> Position sensors that are supported on the Android platform.</p> <strong>Table 1.</strong> Position sensors that are supported on the Android platform.</p>
@@ -174,14 +185,17 @@ the position sensors that are supported on the Android platform.</p>
</tr> </tr>
</table> </table>
<p class="note"><sup><strong>1</strong></sup> This sensor was deprecated in Android 2.2 (API Level <p class="note">
8). The sensor framework provides alternate methods for acquiring device orientation, which are <sup><strong>1</strong></sup>This sensor was deprecated in Android 2.2 (API
discussed in <a href="#sensors-pos-orient">Using the Orientation Sensor</a>.</p> level 8), and this sensor type was deprecated in Android 4.4W (API level 20).
The sensor framework provides alternate methods for acquiring device
orientation, which are discussed in <a href="#sensors-pos-orient">Computing
the Device's Orientation</a>.
</p>
<p class="note"><sup><strong>2</strong></sup> Some proximity sensors provide only binary values <p class="note"><sup><strong>2</strong></sup> Some proximity sensors provide only binary values
representing near and far.</p> representing near and far.</p>
<h2 id="sensors-pos-gamerot">Using the Game Rotation Vector Sensor</h2> <h2 id="sensors-pos-gamerot">Using the Game Rotation Vector Sensor</h2>
<p>The game rotation vector sensor is identical to the <p>The game rotation vector sensor is identical to the
@@ -228,71 +242,106 @@ mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTO
</pre> </pre>
<h2 id="sensors-pos-orient">Using the Orientation Sensor</h2> <h2 id="sensors-pos-orient">Computing the Device's Orientation</h2>
<p>The orientation sensor lets you monitor the position of a device relative to the earth's frame of
reference (specifically, magnetic north). The following code shows you how to get an instance of the
default orientation sensor:</p>
<p>By computing a device's orientation, you can monitor the position of the
device relative to the earth's frame of reference (specifically, the magnetic
north pole). The following code shows you how to compute a device's
orientation:
</p>
<pre> <pre>
private SensorManager mSensorManager; private SensorManager mSensorManager;
private Sensor mSensor;
... ...
mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); // Rotation matrix based on current readings from accelerometer and magnetometer.
mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION); final float[] rotationMatrix = new float[9];
mSensorManager.getRotationMatrix(rotationMatrix, null,
accelerometerReading, magnetometerReading);
// Express the updated rotation matrix as three orientation angles.
final float[] orientationAngles = new float[3];
mSensorManager.getOrientation(rotationMatrix, orientationAngles);
</pre> </pre>
<p>The system computes the orientation angles by using a device's geomagnetic
<p>The orientation sensor derives its data by using a device's geomagnetic field sensor in field sensor in combination with the device's accelerometer. Using these two
combination with a device's accelerometer. Using these two hardware sensors, an orientation sensor hardware sensors, the system provides data for the following three
provides data for the following three dimensions:</p> orientation angles:
</p>
<ul> <ul>
<li>Azimuth (degrees of rotation around the z axis). This is the angle between magnetic north <li>
and the device's y axis. For example, if the device's y axis is aligned with magnetic north <strong>Azimuth (degrees of rotation about the -z axis).</strong> This is
this value is 0, and if the device's y axis is pointing south this value is 180. Likewise, when the angle between the device's current compass direction and magnetic north.
the y axis is pointing east this value is 90 and when it is pointing west this value is 270.</li> If the top edge of the device faces magnetic north, the azimuth is 0
<li>Pitch (degrees of rotation around the x axis). This value is positive when the positive z axis degrees; if the top edge faces south, the azimuth is 180 degrees. Similarly,
rotates toward the positive y axis, and it is negative when the positive z axis if the top edge faces east, the azimuth is 90 degrees, and if the top edge
rotates toward the negative y axis. The range of values is 180 degrees to -180 faces west, the azimuth is 270 degrees.
degrees.</li> </li>
<li>Roll (degrees of rotation around the y axis). This value is positive when the positive z axis <li>
rotates toward the positive x axis, and it is negative when the positive z axis <strong>Pitch (degrees of rotation about the x axis).</strong> This is the
rotates toward the negative x axis. The range of values is 90 degrees to -90 angle between a plane parallel to the device's screen and a plane parallel
degrees.</li> to the ground. If you hold the device parallel to the ground with the bottom
edge closest to you and tilt the top edge of the device toward the ground,
the pitch angle becomes positive. Tilting in the opposite direction&mdash;
moving the top edge of the device away from the ground&mdash;causes
the pitch angle to become negative. The range of values is -180 degrees to
180 degrees.
</li>
<li>
<strong>Roll (degrees of rotation about the y axis).</strong> This is the
angle between a plane perpendicular to the device's screen and a plane
perpendicular to the ground. If you hold the device parallel to the ground
with the bottom edge closest to you and tilt the left edge of the device
toward the ground, the roll angle becomes positive. Tilting in the opposite
direction&mdash;moving the right edge of the device toward the ground&mdash;
causes the roll angle to become negative. The range of values is -90 degrees
to 90 degrees.
</li>
</ul> </ul>
<p>This definition is different from yaw, pitch, and roll used in aviation, where the X axis is <p class="note">
along the long side of the plane (tail to nose). Also, for historical reasons the roll angle is <strong>Note:</strong>The sensor's roll definition has changed to reflect the
positive in the clockwise direction (mathematically speaking, it should be positive in the vast majority of implementations in the geosensor ecosystem.
counter-clockwise direction).</p> </p>
<p>The orientation sensor derives its data by processing the raw sensor data from the accelerometer <p>
and the geomagnetic field sensor. Because of the heavy processing that is involved, the accuracy and Note that these angles work off of a different coordinate system than the
precision of the orientation sensor is diminished (specifically, this sensor is only reliable when one used in aviation (for yaw, pitch, and roll). In the aviation system, the
the roll component is 0). As a result, the orientation sensor was deprecated in Android 2.2 (API x axis is along the long side of the plane, from tail to nose.
level 8). Instead of using raw data from the orientation sensor, we recommend that you use the </p>
{@link android.hardware.SensorManager#getRotationMatrix getRotationMatrix()} method in conjunction
with the {@link android.hardware#getOrientation getOrientation()} method to compute orientation
values. You can also use the {@link android.hardware.SensorManager#remapCoordinateSystem
remapCoordinateSystem()} method to translate the orientation values to your application's frame of
reference.</p>
<p>The following code sample shows how to acquire orientation data directly from the orientation <p>
sensor. We recommend that you do this only if a device has negligible roll.</p> The orientation sensor derives its data by processing the raw sensor data
from the accelerometer and the geomagnetic field sensor. Because of the heavy
processing that is involved, the accuracy and precision of the orientation
sensor is diminished. Specifically, this sensor is reliable only when the roll
angle is 0. As a result, the orientation sensor was deprecated in Android
2.2 (API level 8), and the orientation sensor type was deprecated in Android
4.4W (API level 20).
Instead of using raw data from the orientation sensor, we recommend that you
use the {@link android.hardware.SensorManager#getRotationMatrix getRotationMatrix()}
method in conjunction with the
{@link android.hardware.SensorManager#getOrientation getOrientation()} method
to compute orientation values, as shown in the following code sample. As part
of this process, you can use the
{@link android.hardware.SensorManager#remapCoordinateSystem remapCoordinateSystem()}
method to translate the orientation values to your application's frame of
reference.
</p>
<pre> <pre>
public class SensorActivity extends Activity implements SensorEventListener { public class SensorActivity extends Activity implements SensorEventListener {
private SensorManager mSensorManager; private SensorManager mSensorManager;
private Sensor mOrientation; private final float[] mAccelerometerReading = new float[3];
private final float[] mMagnetometerReading = new float[3];
private final float[] mRotationMatrix = new float[9];
private final float[] mOrientationAngles = new float[3];
&#64;Override &#64;Override
public void onCreate(Bundle savedInstanceState) { public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState); super.onCreate(savedInstanceState);
setContentView(R.layout.main); setContentView(R.layout.main);
mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
mOrientation = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION);
} }
&#64;Override &#64;Override
@@ -304,31 +353,63 @@ public class SensorActivity extends Activity implements SensorEventListener {
&#64;Override &#64;Override
protected void onResume() { protected void onResume() {
super.onResume(); super.onResume();
mSensorManager.registerListener(this, mOrientation, SensorManager.SENSOR_DELAY_NORMAL);
// Get updates from the accelerometer and magnetometer at a constant rate.
// To make batch operations more efficient and reduce power consumption,
// provide support for delaying updates to the application.
//
// In this example, the sensor reporting delay is small enough such that
// the application receives an update before the system checks the sensor
// readings again.
mSensorManager.registerListener(this, Sensor.TYPE_ACCELEROMETER,
SensorManager.SENSOR_DELAY_NORMAL, SensorManager.SENSOR_DELAY_UI);
mSensorManager.registerListener(this, Sensor.TYPE_MAGNETIC_FIELD,
SensorManager.SENSOR_DELAY_NORMAL, SensorManager.SENSOR_DELAY_UI);
} }
&#64;Override &#64;Override
protected void onPause() { protected void onPause() {
super.onPause(); super.onPause();
// Don't receive any more updates from either sensor.
mSensorManager.unregisterListener(this); mSensorManager.unregisterListener(this);
} }
// Get readings from accelerometer and magnetometer. To simplify calculations,
// consider storing these readings as unit vectors.
&#64;Override &#64;Override
public void onSensorChanged(SensorEvent event) { public void onSensorChanged(SensorEvent event) {
float azimuth_angle = event.values[0]; if (event.sensor == Sensor.TYPE_ACCELEROMETER) {
float pitch_angle = event.values[1]; System.arraycopy(event.values, 0, mAccelerometerReading,
float roll_angle = event.values[2]; 0, mAccelerometerReading.length);
// Do something with these orientation angles. }
else if (event.sensor == Sensor.TYPE_MAGNETIC_FIELD) {
System.arraycopy(event.values, 0, mMagnetometerReading,
0, mMagnetometerReading.length);
}
}
// Compute the three orientation angles based on the most recent readings from
// the device's accelerometer and magnetometer.
public void updateOrientationAngles() {
// Update rotation matrix, which is needed to update orientation angles.
mSensorManager.getRotationMatrix(mRotationMatrix, null,
mAccelerometerReading, mMagnetometerReading);
// "mRotationMatrix" now has up-to-date information.
mSensorManager.getOrientation(mRotationMatrix, mOrientationAngles);
// "mOrientationAngles" now has up-to-date information.
} }
} }
</pre> </pre>
<p>You do not usually need to perform any data processing or filtering of the raw data that you <p>
obtain from an orientation sensor, other than translating the sensor's coordinate system to your You don't usually need to perform any data processing or filtering of the
application's frame of reference. The <a device's raw orientation angles other than translating the sensor's
href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer Play</a> sample shows coordinate system to your application's frame of reference.
you how to translate acceleration sensor data into another frame of reference; the technique is </p>
similar to the one you might use with the orientation sensor.</p>
<h2 id="sensors-pos-mag">Using the Geomagnetic Field Sensor</h2> <h2 id="sensors-pos-mag">Using the Geomagnetic Field Sensor</h2>