Scipy: 3D Rotation Formalism Weekly Checklist - adbugger/scipy GitHub Wiki

GSoC 2018 Project Wiki: Scipy - Rotation Formalism in three dimensions

Welcome to the wiki for scipy's GSoC 2018 project. The official blog for this project can be found here. Stay tuned for more updates.

This wiki is mainly for recording the weekly coding tasks and my personal checklist.

Week 6:

  • Pull request #8945 into scipy has been opened. This is a major milestone as it represents completion of the first phase of the project.
  • Initial implementation of quaternion slerp has already been pushed. Fix merge conflicts once main rotation branch if finalised.

Week 4:

  • Rotation composition: For this we support the following 2 cases:

    • Composing N rotations with N rotations. This is relatively straightforward as we already have the compose_quat function implemented.
    • Composing N rotations with a single rotation. For this there are 2 possible implementations:
      • Broadcast the single quaternion to N and use the compose_quat function.
      • Convert the single quaternion to a 4 x 4 matrix and then let np.dot() optimize the matrix multiplication

    API decisions to be made for composition:

    • Using the 4 x 4 matrix approach for the first case does not really make sense.
    • Benchmarks will be made for these 2 approaches and uploaded to the wiki.
    • We will use the __mul__ operator for this.
  • Rotation application: Again there are multiple cases for this:

    • Multiple rotation on a single point. In which case, the Rodrigues formula approach using vector cross and dot products makes sense.
    • Single rotation on multiple points. Here, there are two possible approaches:
      • Again, the Rodrigues formula approach might be appropriate.
      • We could also convert the rotation to dcm and again let numpy optimize the matrix vector multiplication.
    • N rotations on N points. Here, I think the Rogrigues formula approach will be most appropriate.

    API decisions to be made for application:

    • Do we overload the __mul__ operator, or use the __matmul__ operator for this, implement another function Rotation.apply()?
    • Should there be an optional reversed flag in the function to allow the user to apply the inverse rotation?
  • Rotation inversion: Pretty straightforward implementation.

    API decisions for this:

    • Invert the rotation as soon as the Rotation.inv() function is called and return a new object.
    • Return a new object with the same quaternions but with a self._inverted flag added. We make minor modifications to the code to check for this flag, and perform the inversion when we actually require it, sort of like a lazy evaluation scheme.

UPDATE: It took a bit longer because we needed to discuss optimization vs maintainability.


Week 2:

  • from_rotvec: Initialization from rotation vector. Norm of rotation vector is angle and direction is axis. Use Taylor expansion for small angles to prevent floating point inconsistencies.
  • to_rotvec: Conversion of quaternion to rotation vector. Derive the Taylor expansion for this case.
  • from_angles: Initialization from Euler angles. There are certain API decisions that need to be made after discussion.
  • as_angles: Read paper (to be shared by mentor) and implement. Keep in mind transforms3D package.

Completion of both the ..._angles functions is slightly ambitious and may not be possible. EDIT: Yup, it took 2 weeks


Week 1:

  • The main Rotation class
  • __init__ method to accept quaternions, possibly normalizing them. API signature same as from_quaternion
  • from_quaternion, to_quaternion: Accept/return an [N x 4] matrix, where each row mat[i] represents the ith unit quaternion corresponding to a rotation.
  • from_matrix, to_matrix: Accept/return an [N x 3 x 3] ndarray, where each matrix mat[i] corresponds to the ith DCM. Read the following papers and choose a method of orthogonalizing the input matrix:

Documentation and tests as required. Since the apply method has not been implemented as of now, the testing process will consist of trivial/identity rotations.

Comments from a mentor

  • I would suggest alternative names: quaternion -> quat (probably quaternion is better, but still consider it) and matrix -> dcm (this, I think, is a better and more specific name for our application).
  • I'm quite sure that each from_... should accept either a single object or a stack of objects. So either [N x 4] or just 4 for from_quaternion. And to_... also should return either a single object or a stack of objects, depending on how Rotation was created.
  • As an alternative I suggest to consider as_... instead of to_....

Replies

  • quat is indeed shorter and will be easier to write code in. However I think we can add a few characters for the sake of descriptive ability, so I will stick with quaternion. Agree with you on the dcm part.
  • I should have been clearer on this point. I always had in mind that each from_... and to_... method will accept/return a single object or a matrix of numbers, that is, either 4 or [N x 4].
  • Now that you mention it, I think as_... will be better than to_.... It emphasizes that we're simply returning a representation, not modifying the underlying object.