From de091f4a07995e393834ea1059d8b49a60dc6aad Mon Sep 17 00:00:00 2001 From: Alexander Fabisch Date: Thu, 1 Feb 2024 15:02:32 +0100 Subject: [PATCH] Reference references in docs --- doc/source/euler_angles.rst | 8 +++---- doc/source/rotations.rst | 40 +++++++++++++++++++++++----------- doc/source/transformations.rst | 34 ++++++++++++++--------------- 3 files changed, 47 insertions(+), 35 deletions(-) diff --git a/doc/source/euler_angles.rst b/doc/source/euler_angles.rst index 4659d06a3..969f52e12 100644 --- a/doc/source/euler_angles.rst +++ b/doc/source/euler_angles.rst @@ -4,7 +4,7 @@ Euler Angles ============ -Since Euler angles are an intuitive way to specify a rotation in 3D, they +Since Euler angles [1]_ are an intuitive way to specify a rotation in 3D, they are often exposed at user interfaces. However, there are 24 different conventions that could be used. Furthermore, you have to find out whether degrees or radians are used to express the angles (we will only use @@ -180,6 +180,6 @@ API: Euler Angles from Rotation Matrix / Quaternion References ---------- -1. Malcolm D. Shuster: A Survery of Attitude Representations. - In: The Journal of Astronautical Sciences, Vol. 41, No.4, 1993, - pp. 475-476, http://malcolmdshuster.com/Pub_1993h_J_Repsurv_scan.pdf +.. [1] Shuster, M. D. (1993). A Survery of Attitude Representations. + The Journal of Astronautical Sciences, 41(4), pp. 475-476. + http://malcolmdshuster.com/Pub_1993h_J_Repsurv_scan.pdf diff --git a/doc/source/rotations.rst b/doc/source/rotations.rst index d418c6d0c..6e382abbb 100644 --- a/doc/source/rotations.rst +++ b/doc/source/rotations.rst @@ -4,7 +4,7 @@ SO(3): 3D Rotations The group of all rotations in the 3D Cartesian space is called :math:`SO(3)` (SO: special orthogonal group). It is typically represented by 3D rotations -matrices. The minimum number of components that are required to describe +matrices [7]_. The minimum number of components that are required to describe any rotation from :math:`SO(3)` is 3. However, there is no representation that is non-redundant, continuous, and free of singularities. We will now take a closer look at competing representations of rotations and the orientations they @@ -226,7 +226,7 @@ Note that the axis-angle representation has a singularity at represent the identity rotation in this case. However, we can modify the representation to avoid this singularity. -It is possible to write this in a more compact way as a rotation vector: +It is possible to write this in a more compact way as a rotation vector [2]_: .. math:: @@ -236,7 +236,7 @@ pytransform3d uses a numpy array of shape (3,) for the compact axis-angle representation of a rotation and typically we use the variable name a. We can also refer to this representation as **exponential coordinates of -rotation**. We can easily represent angular velocity as +rotation** [5]_. We can easily represent angular velocity as :math:`\hat{\boldsymbol{\omega}} \dot{\theta}` and angular acceleration as :math:`\hat{\boldsymbol{\omega}} \ddot{\theta}` so that we can easily do @@ -299,7 +299,7 @@ and an vector / imaginary part There are two different quaternion conventions: Hamilton's convention defines :math:`ijk = -1` and the Shuster or JPL convention (from NASA's - Jet Propulsion Laboratory, JPL) defines :math:`ijk = 1`. + Jet Propulsion Laboratory, JPL) defines :math:`ijk = 1` [1]_. These two conventions result in different multiplication operations and conversions to other representations. We use Hamilton's convention. @@ -403,7 +403,7 @@ Rotors .. plot:: ../../examples/plots/plot_bivector.py Rotors and quaternions are very similar concepts in 3D. However, rotors are -more general as they can be extended to more dimensions. +more general as they can be extended to more dimensions [3]_ [4]_. The concept of a quaternion builds on the axis-angle representation, in which we rotate by an angle about a rotation axis (see black arrow in the @@ -450,7 +450,7 @@ Modified Rodrigues Parameters ----------------------------- Another minimal representation of rotation are modified Rodrigues parameters -(MRP) +(MRP) [6]_ .. math:: @@ -490,10 +490,24 @@ parameters. References ---------- -1. Why and How to Avoid the Flipped Quaternion Multiplication: https://arxiv.org/pdf/1801.07478.pdf -2. Kindr cheat sheet: https://docs.leggedrobotics.com/kindr/cheatsheet_latest.pdf -3. Let's remove Quaternions from every 3D Engine: https://marctenbosch.com/quaternions/ -4. Applications of Geometric Algebra: http://geometry.mrao.cam.ac.uk/wp-content/uploads/2015/02/01ApplicationsI.pdf -5. Euler–Rodrigues formula variations, quaternion conjugation and intrinsic connections: https://doi.org/10.1016/j.mechmachtheory.2015.03.004 -6. Terzakis, Lourakis, Alt-Boudaoud: Modified Rodrigues Parameters: An Efficient Representation of Orientation in 3D Vision and Graphics, https://link.springer.com/article/10.1007/s10851-017-0765-x -7. Hauser, Kris: Robotic Systems (draft), http://motion.pratt.duke.edu/RoboticSystems/3DRotations.html +.. [1] Sommer, H., Gilitschenski, I., Bloesch, M., Weiss, S., Siegwart, R., Nieto, + J. (2018). Why and How to Avoid the Flipped Quaternion Multiplication. + Aerospace, 5(3), pp. 2226-4310, doi: 10.3390/aerospace5030072. + https://arxiv.org/pdf/1801.07478.pdf +.. [2] Gehring, C., Bellicoso, C. D., Bloesch, M., Sommer, H., Fankhauser, P., + Hutter, M., Siegwart, R. (2024). Kindr cheat sheet. + https://docs.leggedrobotics.com/kindr/cheatsheet_latest.pdf +.. [3] ten Bosch, M. (2020). Let's remove Quaternions from every 3D Engine. + https://marctenbosch.com/quaternions/ +.. [4] Doran, C. (2015). Applications of Geometric Algebra. + http://geometry.mrao.cam.ac.uk/wp-content/uploads/2015/02/01ApplicationsI.pdf +.. [5] Dai, J. S. (2015). Euler–Rodrigues formula variations, quaternion + conjugation and intrinsic connections, Mechanism and Machine Theory, 92, + pp. 144-152, doi: 10.1016/j.mechmachtheory.2015.03.004. + https://doi.org/10.1016/j.mechmachtheory.2015.03.004 +.. [6] Terzakis, G., Lourakis, M., Ait-Boudaoud, D. (2017). Modified Rodrigues + Parameters: An Efficient Representation of Orientation in 3D Vision and + Graphics. J Math Imaging Vis, 60, pp. 422-442, + doi: 10.1007/s10851-017-0765-x. +.. [7] Hauser, K.: Robotic Systems (draft), + http://motion.pratt.duke.edu/RoboticSystems/3DRotations.html diff --git a/doc/source/transformations.rst b/doc/source/transformations.rst index 3ef842a81..c2b37208d 100644 --- a/doc/source/transformations.rst +++ b/doc/source/transformations.rst @@ -12,7 +12,7 @@ in different ways. :depth: 1 For most representations of orientations we can find -an analogous representation of transformations: +an analogous representation of transformations [1]_: * A **transformation matrix** :math:`\boldsymbol T` is similar to a rotation matrix :math:`\boldsymbol R`. @@ -138,9 +138,10 @@ Screw Parameters Just like any rotation can be expressed as a rotation by an angle about a 3D unit vector, any transformation (rotation and translation) can be expressed -by a motion along a screw axis. The **screw parameters** that describe a screw -axis include a point vector :math:`\boldsymbol{q}` through which the screw -axis passes, a (unit) direction vector :math:`\hat{\boldsymbol{s}}` that +by a motion along a screw axis [2]_ [3]_ [4]_. The **screw parameters** that +describe a screw axis include a point vector :math:`\boldsymbol{q}` through +which the screw axis passes, a (unit) direction vector +:math:`\hat{\boldsymbol{s}}` that indicates the direction of the axis, and the pitch :math:`h`. The pitch represents the ratio of translation and rotation. A screw motion translates along the screw axis and rotates about it. @@ -256,8 +257,8 @@ Dual Quaternions ---------------- Similarly to unit quaternions for rotations, unit dual quaternions are -an alternative to represent transformations. They support similar operations -as transformation matrices. +an alternative to represent transformations [5]_ [6]_ [7]_. They support +similar operations as transformation matrices. A dual quaternion consists of a real quaternion and a dual quaternion: @@ -292,21 +293,18 @@ component and the scalar 0, and rotation quaternions have the same ambiguity. References ---------- -1. Lynch, Park: Modern Robotics (2017); available at +.. [1] Lynch, K. M., Park, F. C. (2017). Modern Robotics. http://hades.mech.northwestern.edu/index.php/Modern_Robotics -2. Bradley Evan Paden: Kinematics and Control of Robot Manipulators, PhD - thesis (1985); available at - https://digitalassets.lib.berkeley.edu/techreports/ucb/text/ERL-86-5.pdf -3. Peter Corke: Robotics, Vision and Control, 2nd Edition (2017), +.. [2] Corke, P. (2017). Robotics, Vision and Control, 2nd Edition, https://link.springer.com/book/10.1007/978-3-319-54413-7 -4. Ethan Eade: Lie Groups for 2D and 3D Transformations (2017); available at +.. [3] Eade, E. (2017). Lie Groups for 2D and 3D Transformations. https://ethaneade.com/lie.pdf -5. Sola, Deray, Atchuthan: A micro Lie theory for state estimation in robotics - (2018), technical report; available at: +.. [4] Sola, J., Deray, J., Atchuthan, D. (2018). + A micro Lie theory for state estimation in robotics. Technical Report. http://www.iri.upc.edu/files/scidoc/2089-A-micro-Lie-theory-for-state-estimation-in-robotics.pdf -6. Wikipedia: Dual Quaternion; available at +.. [5] Wikipedia: Dual Quaternion. https://en.wikipedia.org/wiki/Dual_quaternion -7. Yan-Bin Jia: Dual Quaternions; available at - http://web.cs.iastate.edu/~cs577/handouts/dual-quaternion.pdf -8. Ben Kenwright: A Beginners Guide to Dual-Quaternions; available at +.. [6] Jia, Y.-B.: Dual Quaternions. + https://faculty.sites.iastate.edu/jia/files/inline-files/dual-quaternion.pdf +.. [7] Kenwright, B. A Beginners Guide to Dual-Quaternions. http://wscg.zcu.cz/WSCG2012/!_WSCG2012-Communications-1.pdf