CMAttitude Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/CoreMotion.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Event Handling Guide for iOS
Declared in
CMAttitude.h

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 device-motion 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

Getting a Mathematical Representation of Attitude as a Quaternion

Obtaining the Change in Attitude

Properties

pitch

The pitch of the device, in radians. (read-only)

@property(readonly, nonatomic) double pitch
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. (read-only)

@property(readonly, nonatomic) CMQuaternion quaternion
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. (read-only)

@property(readonly, nonatomic) double roll
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. (read-only)

@property(readonly, nonatomic) CMRotationMatrix rotationMatrix
Discussion

A rotation matrix in linear algebra describes the rotation of a body in three-dimensional Euclidean space.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
CMAttitude.h

yaw

The yaw of the device, in radians. (read-only)

@property(readonly, nonatomic) double yaw
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.

- (void)multiplyByInverseOfAttitude:(CMAttitude *)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
x

A value for the X-axis.

y

A value for the Y-axis.

z

A value for the Z-axis.

w

A value for the W-axis.

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 long-term yaw accuracy. Using this constant instead of CMAttitudeReferenceFrameXArbitraryZVertical 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


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)

Did this document help you? Yes It's good, but... Not helpful...