Encapsulation of a mobile device rotation set by the device's IMU sensor. More...

#include <SLDeviceRotation.h>

Public Member Functions
	SLDeviceRotation ()

void	init ()

void	onRotationQUAT (SLfloat quatX, SLfloat quatY, SLfloat quatZ, SLfloat quatW)

void	isUsed (SLbool isUsed)
	Setter that turns on the device rotation sensor. More...

void	hasStarted (SLbool started)

void	zeroYawAtStart (SLbool zeroYaw)

void	numAveraged (SLint numAvg)
	Returns the device rotation averaged over multple frames. More...

void	offsetMode (SLRotOffsetMode rom)

void	updateRPY (SLbool doUpdate)

SLbool	isUsed () const

SLMat3f	rotation () const

SLMat3f	rotationAveraged ()

SLQuat4f	quaternion () const

SLfloat	pitchRAD () const

SLfloat	pitchDEG () const

SLfloat	yawRAD () const

SLfloat	yawDEG () const

SLfloat	rollRAD () const

SLfloat	rollDEG () const

SLbool	zeroYawAtStart () const

SLfloat	startYawRAD () const

SLint	numAveraged ()

SLRotOffsetMode	offsetMode ()

SLstring	offsetModeStr () const
	Returns the rotation offset mode as string. More...

SLbool	updateRPY () const

Private Attributes
SLbool	_isUsed
	Flag if device rotation is used. More...

SLbool	_isFirstSensorValue
	Flag for the first sensor values. More...

SLfloat	_pitchRAD
	Device pitch angle in radians. More...

SLfloat	_yawRAD
	Device yaw angle in radians. More...

SLfloat	_rollRAD
	Device roll angle in radians. More...

SLMat3f	_rotation
	Mobile device rotation as matrix. More...

Averaged< SLMat3f >	_rotationAvg
	Component wise averaged rotation matrix. More...

SLQuat4f	_quaternion

SLbool	_zeroYawAtStart
	Quaternion rotation that is set by IMU. More...

SLfloat	_startYawRAD
	Initial yaw angle after _zeroYawAfterSec in radians. More...

SLRotOffsetMode	_offsetMode
	Rotation offset mode. More...

SLbool	_updateRPY
	Calculate roll pitch yaw in onRotationQUAT. More...

Detailed Description

Encapsulation of a mobile device rotation set by the device's IMU sensor.

This class is only used if SLProject runs on a mobile device. Check out the app-demo/android and app_demo_slproject/ios how the sensor data is generated and passed to this object hold by AppCommon. It stores the devices rotation that it gets from its IMU (inertial measurement unit) sensor. This is a fused orientation that is calculated from the magnetometer, the accelerometer and the gyroscope. The device rotation can be used in the active camera to apply it to the scene camera (s. SLCamera::setView).

Definition at line 39 of file SLDeviceRotation.h.

Constructor & Destructor Documentation

◆ SLDeviceRotation()

SLDeviceRotation::SLDeviceRotation ( )

Definition at line 14 of file SLDeviceRotation.cpp.

 {
     init();
 }

Member Function Documentation

◆ hasStarted()

void SLDeviceRotation::hasStarted ( SLbool started )

inline

Definition at line 50 of file SLDeviceRotation.h.

50 { _isFirstSensorValue = started; }

SLDeviceRotation::_isFirstSensorValue

SLbool _isFirstSensorValue

Flag for the first sensor values.

Definition: SLDeviceRotation.h:76

◆ init()

void SLDeviceRotation::init ( )

Definition at line 19 of file SLDeviceRotation.cpp.

 {
     _rotation.identity();
     _pitchRAD = 0.0f;
     _yawRAD   = 0.0f;
     _rollRAD  = 0.0f;
     _rotationAvg.init(3, SLMat3f());
     _zeroYawAtStart     = true;
     _startYawRAD        = 0.0f;
     _isFirstSensorValue = false;
     _isUsed             = false;
     _offsetMode         = ROM_none;
     _updateRPY          = true;
 }

◆ isUsed() [1/2]

SLbool SLDeviceRotation::isUsed ( ) const

inline

Definition at line 57 of file SLDeviceRotation.h.

57 { return _isUsed; }

◆ isUsed() [2/2]

void SLDeviceRotation::isUsed ( SLbool isUsed )

Setter that turns on the device rotation sensor.

Definition at line 105 of file SLDeviceRotation.cpp.

 {
     if (!_isUsed && use == true)
         _isFirstSensorValue = true;
  
     _isUsed = use;
 }

◆ numAveraged() [1/2]

SLint SLDeviceRotation::numAveraged ( )

inline

Definition at line 69 of file SLDeviceRotation.h.

69 { return (int)_rotationAvg.size(); }

◆ numAveraged() [2/2]

void SLDeviceRotation::numAveraged ( SLint numAvg )

Returns the device rotation averaged over multple frames.

Definition at line 114 of file SLDeviceRotation.cpp.

 {
     assert(numAvg > 0 && "Num. of averaged values must be greater than zero");
     _rotationAvg.init(numAvg, _rotationAvg.average());
 }

◆ offsetMode() [1/2]

SLRotOffsetMode SLDeviceRotation::offsetMode ( )

inline

Definition at line 70 of file SLDeviceRotation.h.

70 { return _offsetMode; }

◆ offsetMode() [2/2]

void SLDeviceRotation::offsetMode ( SLRotOffsetMode rom )

inline

Definition at line 53 of file SLDeviceRotation.h.

53 { _offsetMode = rom; }

◆ offsetModeStr()

SLstring SLDeviceRotation::offsetModeStr ( ) const

Returns the rotation offset mode as string.

Definition at line 121 of file SLDeviceRotation.cpp.

 {
     switch (_offsetMode)
     {
         case ROM_none: return "None";
         case ROM_oneFingerX: return "OneFingerX";
         case ROM_oneFingerXY: return "OneFingerXY";
         default: return "Unknown";
     }
 }

◆ onRotationQUAT()

void SLDeviceRotation::onRotationQUAT	(	SLfloat	quatX,
		SLfloat	quatY,
		SLfloat	quatZ,
		SLfloat	quatW
	)

onRotationQUAT: Event handler for rotation change of a mobile device from a rotation quaternion. This function will only be called in an Android or iOS project. See e.g. onSensorChanged in GLES3Activity.java in the Android project. This handler is only called if the flag SLScene::_usesRotation is true. If so the mobile device turns on it's IMU sensor system. The device rotation is so far only used in SLCamera::setView if the cameras animation is on CA_deciveRotYUp. If _zeroYawAfterStart is true the start yaw value is subtracted. This means that the magnetic north will be ignored. The angles should be:
Roll from -halfpi (ccw) to zero (horizontal) to +halfpi (clockwise)
Pitch from -halfpi (down) to zero (horizontal) to +halfpi (up)
Yaw from -pi (south) to zero (north) to +pi (south)

Definition at line 47 of file SLDeviceRotation.cpp.

 {
     _quaternion = SLQuat4f(quatX, quatY, quatZ, quatW);
     _rotation   = _quaternion.toMat3();
     _rotationAvg.set(_rotation);
  
     if (_updateRPY)
         _quaternion.toEulerAnglesXYZ(_pitchRAD, _rollRAD, _yawRAD);
  
     /*
      Android sensor coordinate system:
      (https://developer.android.com/guide/topics/sensors/sensors_overview)
  
     Up = z   North = y
          |  /
          | /
          |/
          +------ East = x
         +---------+
        / +-----+ /
       / /     / /
      / /     / /
     / +-----+ /
    /    0    /
   +---------+
  
      iOS sensor coordinate system:
      (https://developer.apple.com/documentation/coremotion/getting_processed_device-motion_data/understanding_reference_frames_and_device_attitude)
      In iOS we configure CMMotionManager with xMagneticNorthZVertical which means its a frame, where x points north, y points west and z points up (NWU).
      In the iOS code, we add rotation of 90 deg. around z-axis to relate the sensor rotation to an ENU-frame (as in Android).
  
      Up = z   West = y
           |  /
           | /
           |/
           +------ North = x
          +---------+
         / +-----+ /
        / /     / /
       / /     / /
      / +-----+ /
     /    0    /
    +---------+
  
      */
  
     if (_zeroYawAtStart && _isFirstSensorValue)
     {
         // store initial rotation in yaw for referencing of initial alignment
         _startYawRAD        = _yawRAD;
         _isFirstSensorValue = false;
     }
 }

◆ pitchDEG()

SLfloat SLDeviceRotation::pitchDEG ( ) const

inline

Definition at line 62 of file SLDeviceRotation.h.

62 { return _pitchRAD * Utils::RAD2DEG; }

Utils::RAD2DEG

static const float RAD2DEG

Definition: Utils.h:238

◆ pitchRAD()

SLfloat SLDeviceRotation::pitchRAD ( ) const

inline

Definition at line 61 of file SLDeviceRotation.h.

61 { return _pitchRAD; }

◆ quaternion()

SLQuat4f SLDeviceRotation::quaternion ( ) const

inline

Definition at line 60 of file SLDeviceRotation.h.

60 { return _quaternion; }

◆ rollDEG()

SLfloat SLDeviceRotation::rollDEG ( ) const

inline

Definition at line 66 of file SLDeviceRotation.h.

66 { return _rollRAD * Utils::RAD2DEG; }

◆ rollRAD()

SLfloat SLDeviceRotation::rollRAD ( ) const

inline

Definition at line 65 of file SLDeviceRotation.h.

65 { return _rollRAD; }

◆ rotation()

SLMat3f SLDeviceRotation::rotation ( ) const

inline

Definition at line 58 of file SLDeviceRotation.h.

58 { return _rotation; }

◆ rotationAveraged()

SLMat3f SLDeviceRotation::rotationAveraged ( )

inline

Definition at line 59 of file SLDeviceRotation.h.

59 { return _rotationAvg.average(); }

◆ startYawRAD()

SLfloat SLDeviceRotation::startYawRAD ( ) const

inline

Definition at line 68 of file SLDeviceRotation.h.

68 { return _startYawRAD; }

◆ updateRPY() [1/2]

SLbool SLDeviceRotation::updateRPY ( ) const

inline

Definition at line 72 of file SLDeviceRotation.h.

72 { return _updateRPY; }

◆ updateRPY() [2/2]

void SLDeviceRotation::updateRPY ( SLbool doUpdate )

inline

Definition at line 54 of file SLDeviceRotation.h.

54 { _updateRPY = doUpdate; }

◆ yawDEG()

SLfloat SLDeviceRotation::yawDEG ( ) const

inline

Definition at line 64 of file SLDeviceRotation.h.

64 { return _yawRAD * Utils::RAD2DEG; }

◆ yawRAD()

SLfloat SLDeviceRotation::yawRAD ( ) const

inline

Definition at line 63 of file SLDeviceRotation.h.

63 { return _yawRAD; }

◆ zeroYawAtStart() [1/2]

SLbool SLDeviceRotation::zeroYawAtStart ( ) const

inline

Definition at line 67 of file SLDeviceRotation.h.

67 { return _zeroYawAtStart; }

◆ zeroYawAtStart() [2/2]

void SLDeviceRotation::zeroYawAtStart ( SLbool zeroYaw )

inline

Definition at line 51 of file SLDeviceRotation.h.

51 { _zeroYawAtStart = zeroYaw; }

Member Data Documentation

◆ _isFirstSensorValue

SLbool SLDeviceRotation::_isFirstSensorValue

private

Flag for the first sensor values.

Definition at line 76 of file SLDeviceRotation.h.

◆ _isUsed

SLbool SLDeviceRotation::_isUsed

private

Flag if device rotation is used.

Definition at line 75 of file SLDeviceRotation.h.

◆ _offsetMode

SLRotOffsetMode SLDeviceRotation::_offsetMode

private

Rotation offset mode.

Definition at line 85 of file SLDeviceRotation.h.

◆ _pitchRAD

SLfloat SLDeviceRotation::_pitchRAD

private

Device pitch angle in radians.

Definition at line 77 of file SLDeviceRotation.h.

◆ _quaternion

SLQuat4f SLDeviceRotation::_quaternion

private

Definition at line 82 of file SLDeviceRotation.h.

◆ _rollRAD

SLfloat SLDeviceRotation::_rollRAD

private

Device roll angle in radians.

Definition at line 79 of file SLDeviceRotation.h.

◆ _rotation

SLMat3f SLDeviceRotation::_rotation

private

Mobile device rotation as matrix.

Definition at line 80 of file SLDeviceRotation.h.

◆ _rotationAvg

Averaged<SLMat3f> SLDeviceRotation::_rotationAvg

private

Component wise averaged rotation matrix.

Definition at line 81 of file SLDeviceRotation.h.

◆ _startYawRAD

SLfloat SLDeviceRotation::_startYawRAD

private

Initial yaw angle after _zeroYawAfterSec in radians.

Definition at line 84 of file SLDeviceRotation.h.

◆ _updateRPY

SLbool SLDeviceRotation::_updateRPY

private

Calculate roll pitch yaw in onRotationQUAT.

Definition at line 86 of file SLDeviceRotation.h.

◆ _yawRAD

SLfloat SLDeviceRotation::_yawRAD

private

Device yaw angle in radians.

Definition at line 78 of file SLDeviceRotation.h.

◆ _zeroYawAtStart

SLbool SLDeviceRotation::_zeroYawAtStart

private

Quaternion rotation that is set by IMU.

Flag if yaw angle should be zeroed at sensor start

Definition at line 83 of file SLDeviceRotation.h.

The documentation for this class was generated from the following files:

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SLDeviceRotation()

Member Function Documentation

◆ hasStarted()

◆ init()

◆ isUsed() [1/2]

◆ isUsed() [2/2]

◆ numAveraged() [1/2]

◆ numAveraged() [2/2]

◆ offsetMode() [1/2]

◆ offsetMode() [2/2]

◆ offsetModeStr()

◆ onRotationQUAT()

◆ pitchDEG()

◆ pitchRAD()

◆ quaternion()

◆ rollDEG()

◆ rollRAD()

◆ rotation()

◆ rotationAveraged()

◆ startYawRAD()

◆ updateRPY() [1/2]

◆ updateRPY() [2/2]

◆ yawDEG()

◆ yawRAD()

◆ zeroYawAtStart() [1/2]

◆ zeroYawAtStart() [2/2]

Member Data Documentation

◆ _isFirstSensorValue

◆ _isUsed

◆ _offsetMode

◆ _pitchRAD

◆ _quaternion

◆ _rollRAD

◆ _rotation

◆ _rotationAvg

◆ _startYawRAD

◆ _updateRPY

◆ _yawRAD

◆ _zeroYawAtStart