From 8e1a23eadfac4ae7103d6df16d0872e5a6409ee3 Mon Sep 17 00:00:00 2001 From: marioalexis Date: Sat, 28 May 2022 23:37:14 -0300 Subject: [PATCH] Base: Improve docstrings in RotationPy.xml --- src/Base/PlacementPy.xml | 2 +- src/Base/RotationPy.xml | 180 +++++++++++++++++++++------------------ 2 files changed, 100 insertions(+), 82 deletions(-) diff --git a/src/Base/PlacementPy.xml b/src/Base/PlacementPy.xml index 9121889bf0..b6f599fbc9 100644 --- a/src/Base/PlacementPy.xml +++ b/src/Base/PlacementPy.xml @@ -15,7 +15,7 @@ FatherNamespace="Base"> - Base.Placement class\n + Base.Placement class.\n A Placement defines an orientation (rotation) and a position (base) in 3D space. It is used when no scaling or other distortion is needed.\n The following constructors are supported:\n diff --git a/src/Base/RotationPy.xml b/src/Base/RotationPy.xml index 35e804d310..972018408d 100644 --- a/src/Base/RotationPy.xml +++ b/src/Base/RotationPy.xml @@ -16,157 +16,175 @@ This is the Rotation export class - - A Rotation using a quaternion. - The Rotation object can be created by: - -- an empty parameter list - -- a Rotation object - -- a Vector (axis) and a float (angle) - -- two Vectors (rotation from/to vector) - -- three floats (Euler angles) as yaw-pitch-roll in XY'Z'' convention - -- one string and three floats (Euler angles) as euler rotation - of a given type. Call toEulerSequence() for supported sequence types. - -- four floats (Quaternion) where the quaternion is specified as: - q=xi+yj+zk+w, i.e. the last parameter is the real part - -- three vectors that define rotated axes directions + an optional - 3-characher string of capital letters 'X', 'Y', 'Z' that sets the - order of importance of the axes (e.g., 'ZXY' means z direction is - followed strictly, x is used but corrected if necessary, y is ignored). - + Base.Rotation class.\n +A Rotation using a quaternion.\n +The following constructors are supported:\n +Rotation() +Empty constructor.\n +Rotation(rotation) +Copy constructor.\n +Rotation(Axis, Radian) +Rotation(Axis, Degree) +Define from an axis and an angle (in radians or degrees according to the keyword). +Axis : Base.Vector +Radian : float +Degree : float\n +Rotation(vector_start, vector_end) +Define from two vectors (rotation from/to vector). +vector_start : Base.Vector +vector_end : Base.Vector\n +Rotation(angle1, angle2, angle3) +Define from three floats (Euler angles) as yaw-pitch-roll in XY'Z'' convention. +angle1 : float +angle2 : float +angle3 : float\n +Rotation(seq, angle1, angle2, angle3) +Define from one string and three floats (Euler angles) as Euler rotation +of a given type. Call toEulerSequence() for supported sequence types. +seq : str +angle1 : float +angle2 : float +angle3 : float\n +Rotation(x, y, z, w) +Define from four floats (quaternion) where the quaternion is specified as: +q = xi+yj+zk+w, i.e. the last parameter is the real part. +x : float +y : float +z : float +w : float\n +Rotation(dir1, dir2, dir3, seq) +Define from three vectors that define rotated axes directions plus an optional +3-characher string of capital letters 'X', 'Y', 'Z' that sets the order of +importance of the axes (e.g., 'ZXY' means z direction is followed strictly, +x is used but corrected if necessary, y is ignored). +dir1 : Base.Vector +dir2 : Base.Vector +dir3 : Base.Vector +seq : str\n +Rotation(matrix) +Define from a matrix rotation in the 4D representation. +matrix : Base.Matrix\n +Rotation(*coef) +Define from 16 or 9 elements which represent the rotation in the 4D matrix +representation or in the 3D matrix representation, respectively. +coef : sequence of float - - invert() -> None - Sets the rotation to its inverse - + invert() -> None\n +Sets the rotation to its inverse. - - inverted() -> Rotation - Returns the inverse of the rotation - + inverted() -> Base.Rotation\n +Returns the inverse of the rotation. - - isSame(Rotation, [tolerance=0]) - Checks if the two quaternions perform the same rotation. - Optionally, a tolerance value greater than zero can be passed. - + isSame(rotation, tol=0) -> bool\n +Checks if `rotation` perform the same transformation as this rotation.\n +rotation : Base.Rotation +tol : float\n Tolerance used to compare both rotations. + If tol is negative or zero, no tolerance is used. - - multiply(Rotation) - Multiply this quaternion with another quaternion - + multiply(rotation) -> Base.Rotation\n +Right multiply this rotation with another rotation.\n +rotation : Base.Rotation\n Rotation by which to multiply this rotation. - - multVec(Vector) -> Vector - Compute the transformed vector using the rotation - + multVec(vector) -> Base.Vector\n +Compute the transformed vector using the rotation.\n +vector : Base.Vector\n Vector to be transformed. - - slerp(Rotation, Float) -> Rotation - Spherical linear interpolation of this and a given rotation. The float must be in the range of 0 and 1 - + slerp(rotation2, t) -> Base.Rotation\n +Spherical Linear Interpolation (SLERP) of this rotation and `rotation2`.\n +t : float\n Parameter of the path. t=0 returns this rotation, t=1 returns `rotation2`. - - setYawPitchRoll(angle1, angle2, angle3) - Set the Euler angles of this rotation - as yaw-pitch-roll in XY'Z'' convention. - - NOTE: The angles are in degree - + setYawPitchRoll(angle1, angle2, angle3) -> None\n +Set the Euler angles of this rotation as yaw-pitch-roll in XY'Z'' convention.\n +angle1 : float\n Angle around yaw axis in degrees. +angle2 : float\n Angle around pitch axis in degrees. +angle3 : float\n Angle around roll axis in degrees. - - getYawPitchRoll() -> list - Get the Euler angles of this rotation - as yaw-pitch-roll in XY'Z'' convention - NOTE: The angles are in degree - + getYawPitchRoll() -> tuple\n +Get the Euler angles of this rotation as yaw-pitch-roll in XY'Z'' convention. +The angles are given in degrees. - - setEulerAngles(seq, angle1, angle2, angle3) - Set the Euler angles in a given sequence for this rotation. - 'seq' is the Euler sequence name. You get all possible values with toEulerAngles() - + setEulerAngles(seq, angle1, angle2, angle3) -> None\n +Set the Euler angles in a given sequence for this rotation. +The angles must be given in degrees.\n +seq : str\n Euler sequence name. All possible values given by toEulerAngles(). +angle1 : float +angle2 : float +angle3 : float - - toEulerAngles(seq='') -> list - Get the Euler angles in a given sequence for this rotation. - Call this function without arguments to output all possible values of 'seq'. - + toEulerAngles(seq) -> list\n +Get the Euler angles in a given sequence for this rotation.\n +seq : str\n Euler sequnce name. If not given, the function returns + all possible values of `seq`. Optional. - - toMatrix() - convert the rotation to a matrix representation - + toMatrix() -> Base.Matrix\n +Convert the rotation to a 4D matrix representation. - - isNull() -> Bool - returns True if all Q values are zero - + isNull() -> bool\n +Returns True if all values in the quaternion representation are zero. - - isIdentity() -> Bool - returns True if the rotation equals the unity matrix - + isIdentity() -> bool\n +Returns True if the rotation equals the 4D identity matrix. - The rotation elements (as quaternion) + The rotation elements (as quaternion). - The rotation axis of the quaternion + The rotation axis of the quaternion. - The rotation axis without normalization + The rotation axis without normalization. - The rotation angle of the quaternion + The rotation angle of the quaternion.