iOS Developer Library

Developer

CoreMotion Framework Reference CMAttitude Class Reference

Options
Deployment Target:

On This Page
Language:

CMAttitude

Inherits From


Conforms To


Import Statement


Swift

import CoreMotion

Objective-C

@import CoreMotion;

Availability


Available in iOS 4.0 and later

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.

  • roll roll Property

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

    Declaration

    Swift

    var roll: Double { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

    See Also

    pitch
    yaw

  • pitch pitch Property

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

    Declaration

    Swift

    var pitch: Double { get }

    Objective-C

    @property(readonly, nonatomic) double pitch

    Discussion

    A pitch is a rotation around a lateral axis that passes through the device from side to side.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

    See Also

    roll
    yaw

  • yaw yaw Property

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

    Declaration

    Swift

    var yaw: Double { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

    See Also

    roll
    pitch

  • Returns a rotation matrix representing the device's attitude. (read-only)

    Declaration

    Swift

    var rotationMatrix: CMRotationMatrix { get }

    Objective-C

    @property(readonly, nonatomic) CMRotationMatrix rotationMatrix

    Discussion

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

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

    See Also

    quaternion

  • Returns a quaternion representing the device's attitude. (read-only)

    Declaration

    Swift

    var quaternion: CMQuaternion { get }

    Objective-C

    @property(readonly, nonatomic) CMQuaternion quaternion

    Discussion

    See the discussion of the CMQuaternion type in “Constants” for further information.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

    See Also

    rotationMatrix

  • Yields the change in attitude given a specific attitude.

    Declaration

    Swift

    func multiplyByInverseOfAttitude(_ attitude: CMAttitude!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

Data Types

  • The type of a structure representing a rotation matrix.

    Declaration

    Swift

    struct CMRotationMatrix { var m11: Double var m12: Double var m13: Double var m21: Double var m22: Double var m23: Double var m31: Double var m32: Double var m33: Double init() init(m11 m11: Double, m12 m12: Double, m13 m13: Double, m21 m21: Double, m22 m22: Double, m23 m23: Double, m31 m31: Double, m32 m32: Double, m33 m33: Double) }

    Objective-C

    typedef struct { double m11, m12, m13; double m21, m22, m23; double m31, m32, m33; } CMRotationMatrix;

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

  • The type for a quaternion representing a measurement of attitude.

    Declaration

    Swift

    struct CMQuaternion { var x: Double var y: Double var z: Double var w: Double init() init(x x: Double, y y: Double, z z: Double, w w: Double) }

    Objective-C

    typedef struct { double x, y, z, w; } CMQuaternion

    Constants

    • x

      x

      A value for the X-axis.

    • y

      y

      A value for the Y-axis.

    • z

      z

      A value for the Z-axis.

    • w

      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)

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 4.0 and later

  • Enum constants for indicating the reference frames from which all attitude samples are referenced.

    Declaration

    Swift

    struct CMAttitudeReferenceFrame : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var XArbitraryZVertical: CMAttitudeReferenceFrame { get } static var XArbitraryCorrectedZVertical: CMAttitudeReferenceFrame { get } static var XMagneticNorthZVertical: CMAttitudeReferenceFrame { get } static var XTrueNorthZVertical: CMAttitudeReferenceFrame { get } }

    Objective-C

    typedef enum { CMAttitudeReferenceFrameXArbitraryZVertical = 1 << 0, CMAttitudeReferenceFrameXArbitraryCorrectedZVertical = 1 << 1, CMAttitudeReferenceFrameXMagneticNorthZVertical = 1 << 2, CMAttitudeReferenceFrameXTrueNorthZVertical = 1 << 3 } CMAttitudeReferenceFrame;

    Constants

    • XArbitraryZVertical

      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

    • XArbitraryCorrectedZVertical

      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

    • XMagneticNorthZVertical

      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

    • XTrueNorthZVertical

      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

    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.

    Import Statement

    Objective-C

    @import CoreMotion;

    Swift

    import CoreMotion

    Availability

    Available in iOS 5.0 and later