CMAttitude Class Reference
Overview
An instance of the CMAttitude
class represents a measurement of the device’s attitude at a point in time. "Attitude” refers to the orientation of a body relative to a given frame of reference.
The CMAttitude
class offers three different mathematical representations of attitude: a rotation matrix, a quaternion, and Euler angles (roll, pitch, and yaw values). You access CMAttitude
objects through the attitude property of each CMDeviceMotion
objects passed to an application. An application starts receiving these devicemotion objects as a result of calling the startDeviceMotionUpdatesUsingReferenceFrame:toQueue:withHandler:
method, thestartDeviceMotionUpdatesToQueue:withHandler:
method, the startDeviceMotionUpdatesUsingReferenceFrame:
method or the startDeviceMotionUpdates
method of the CMMotionManager
class.
Tasks
Getting a Mathematical Representation of Attitude as Euler Angles
Getting a Mathematical Representation of Attitude as a Rotation Matrix

rotationMatrix
property
Getting a Mathematical Representation of Attitude as a Quaternion

quaternion
property
Obtaining the Change in Attitude
Properties
pitch
The pitch of the device, in radians. (readonly)
Discussion
A pitch is a rotation around a lateral axis that passes through the device from side to side.
Availability
 Available in iOS 4.0 and later.
See Also
Declared In
CMAttitude.h
quaternion
Returns a quaternion representing the device's attitude. (readonly)
Discussion
See the discussion of the CMQuaternion
type in “Constants” for further information.
Availability
 Available in iOS 4.0 and later.
See Also
Declared In
CMAttitude.h
roll
The roll of the device, in radians. (readonly)
Discussion
A roll is a rotation around a longitudinal axis that passes through the device from its top to bottom.
Availability
 Available in iOS 4.0 and later.
See Also
Declared In
CMAttitude.h
rotationMatrix
Returns a rotation matrix representing the device's attitude. (readonly)
Discussion
A rotation matrix in linear algebra describes the rotation of a body in threedimensional Euclidean space.
Availability
 Available in iOS 4.0 and later.
See Also
Declared In
CMAttitude.h
yaw
The yaw of the device, in radians. (readonly)
Discussion
A yaw is a rotation around an axis that runs vertically through the device. It is perpendicular to the body of the device, with its origin at the center of gravity and directed toward the bottom of the device.
Availability
 Available in iOS 4.0 and later.
See Also
Declared In
CMAttitude.h
Instance Methods
multiplyByInverseOfAttitude:
Yields the change in attitude given a specific attitude.
Parameters
 attitude
An object representing the device’s attitude at a given moment of measurement.
Discussion
This method multiplies the inverse of the specified CMAttitude
object by the attitude represented by the receiving object. It replaces the receiving instance with the attitude change relative to the object passed in attitude. You should cache the CMAttitude
instance you want to use as a reference and pass that object as the argument to subsequent calls of this method.
Availability
 Available in iOS 4.0 and later.
Declared In
CMAttitude.h
Constants
CMRotationMatrix
The type of a structure representing a rotation matrix.
typedef struct { double m11, m12, m13; double m21, m22, m23; double m31, m32, m33; } CMRotationMatrix;
Fields
m11—m33
Each field in this structure defines an element of the rotation matrix by its position. For example,
m11
is the element in row 1, column 1;m31
is the element in row 3, column 1;m13
is the element in row 1, column 3.
Availability
 Available in iOS 4.0 and later.
Declared In
CMAttitude.h
CMQuaternion
The type for a quaternion representing a measurement of attitude.
typedef struct { double x, y, z, w; } CMQuaternion
Constants
Discussion
A quaternion offers a way to parameterize attitude. If q
is an instance of CMQuaternion
, mathematically it represents the following unit quaternion: q.x*i + q.y*j + q.z*k + q.w
. A unit quaternion represents a rotation of theta radians about the unit vector {x,y,z}
, and {q.x, q.y, q.z, q.w}
satisfies the following:
q.x = x * sin(theta / 2) 
q.y = y * sin(theta / 2) 
q.z = z * sin(theta / 2) 
q.w = cos(theta / 2) 
Availability
 Available in iOS 4.0 and later.
Declared In
CMAttitude.h
CMAttitudeReferenceFrame
Enum constants for indicating the reference frames from which all attitude samples are referenced.
typedef enum { CMAttitudeReferenceFrameXArbitraryZVertical = 1 << 0, CMAttitudeReferenceFrameXArbitraryCorrectedZVertical = 1 << 1, CMAttitudeReferenceFrameXMagneticNorthZVertical = 1 << 2, CMAttitudeReferenceFrameXTrueNorthZVertical = 1 << 3 } CMAttitudeReferenceFrame;
Constants
CMAttitudeReferenceFrameXArbitraryZVertical
Describes a reference frame in which the Z axis is vertical and the X axis points in an arbitrary direction in the horizontal plane.
Available in iOS 5.0 and later.
Declared in
CMAttitude.h
.CMAttitudeReferenceFrameXArbitraryCorrectedZVertical
Describes the same reference frame as
CMAttitudeReferenceFrameXArbitraryZVertical
except that the magnetometer, when available and calibrated, is used to improve longterm yaw accuracy. Using this constant instead ofCMAttitudeReferenceFrameXArbitraryZVertical
results in increased CPU usage.Available in iOS 5.0 and later.
Declared in
CMAttitude.h
.CMAttitudeReferenceFrameXMagneticNorthZVertical
Describes a reference frame in which the Z axis is vertical and the X axis points toward magnetic north. Note that using this reference frame may require device movement to calibrate the magnetometer.
Available in iOS 5.0 and later.
Declared in
CMAttitude.h
.CMAttitudeReferenceFrameXTrueNorthZVertical
Describes a reference frame in which the Z axis is vertical and the X axis points toward true north. Note that using this reference frame may require device movement to calibrate the magnetometer. It also requires the location to be available in order to calculate the difference between magnetic and true north.
Available in iOS 5.0 and later.
Declared in
CMAttitude.h
.
Discussion
Constants of this data type are returned or referenced by the attitudeReferenceFrame
property and the startDeviceMotionUpdatesUsingReferenceFrame:toQueue:withHandler:
and startDeviceMotionUpdatesUsingReferenceFrame:
methods of the CMMotionManager
class. A bitmask of these constants is returned by the availableAttitudeReferenceFrames
class method.
Declared In
CMAttitude.h
Copyright © 2011 Apple Inc. All Rights Reserved. Terms of Use  Privacy Policy  Updated: 20111012