Inconsistency in functions documentation (Matrix3x3.h)

[damien-robotsix]

Hi! If we look in the documentation of the functions in Matrix3x3.h there is a inconsistency as the setEulerYPR function says

geometry2/tf2/include/tf2/LinearMath/Matrix3x3.h

Lines 169 to 177 in 18ed7cd

	/** @brief Set the matrix from euler angles YPR around ZYX axes
	* @param eulerZ Yaw aboud Z axis
	* @param eulerY Pitch around Y axis
	* @param eulerX Roll about X axis
	*
	* These angles are used to produce a rotation matrix. The euler
	* angles are applied in ZYX order. I.e a vector is first rotated
	* about X then Y and then Z
	**/

The euler angles are applied in ZYX order. I.e a vector is first rotated about X then Y and then Z is quite incoherent.

Also the getEulerRPY functions says

geometry2/tf2/include/tf2/LinearMath/Matrix3x3.h

Lines 281 to 284 in 18ed7cd

	/**@brief Get the matrix represented as euler angles around YXZ, roundtrip with setEulerYPR
	* @param yaw Yaw around Z axis
	* @param pitch Pitch around Y axis
	* @param roll around X axis */

Get the matrix represented as euler angles around YXZ is different than what is said in the setter (also what the name of the function suggests).

I guess (but I am not sure) that EulerYPR is rotation about ZYX fixed axes. (While RPY is rotation about XYZ fixed axis as described in the documentation).

If it is the case, then documentation of the getEulerRPY and setEulerRPY should probably be corrected.

[wjwwood]

We discussed this in the issue triage meeting and no one there felt comfortable investigating this issue right now, so we will put the help wanted label on this and invite anyone to investigate it and come up with how the think it should be done (if the current way isn't correct) and propose changes in a pull request.

@tfoote FYI also, in case you have any ideas or opinions.

[tfoote]

There definitely looks to be consistency. This is a copy of the upstream Bullet physics lineary math codebase. We've diverged in the past from that and it as a real pain to maintain it in parallel. We don't want to diverge in behaviors. Cleaning up the inconsistent docs is fine. But in general I'd like to encourage people to use an external linear math library. My hope had been that this would not have transitioned into ROS 2 but was needed for internal purposes and c++ doesn't have convenient isolation methods and thus gets exposed.