Refactoring plan

Note the Naming conventions.

Base the module distinctions on the naming conventions.

In general, routines that create or break down affines, rather than, say 3x3 matrices, go with the - say - 3x3 routines, and are named aff2something, something2aff.

Routines that only apply to affines, like compose, decompose, go into the affines module.

Different decompositions might have different names - such as decompose_szrt, returning transformations in order that they are performed - here shears, zooms, rotations, translations.

Move the SPM (ND affine) decompose to decompose_szrt_nd.

Maybe move the comments from Euler code out into doc tree.

To integrate

  • projection_matrix, projection_from_matrix: move to own module, rename to projpn2aff. aff2projpn.

  • clip_matrix: move to own module, rename to clip2aff

  • decompose_matrix, compose_matrix: move to affines module, rename to decompose_zsrtp, compose_zsrtp

  • orthogonalization_matrix: move to misc module, rename to orth_aff

  • superimposition_matrix: move to misc module, rename to vecs2aff

  • quaterion_about_axis, quaternion_matrix, quaternion_from_matrix, quaternion_multiply, quaternion_conjugate, quaternion_inverse: check against my code

  • quaternion_real, quaternion_imag: needed?

  • quaternion_slerp, random_quaternion: move to quaternions module, rename qslerp, rand_quat.

  • random_rotation_matrix: move to some module as rand_rmat

  • Arcball class, arcball_map_to_sphere, arcball_constrain_to_axis, arcball_nearest_axis: to own module

  • vector_norm: move to utils module, review use after refactoring

  • unit_vector: replace with utils.normalized_vector

  • random_vector, inverse_matrix, concatenate_matrices: not obviously used, very simple code, remove?

  • _import_module: for preferring C functions. Move to utils for now, consider C / python cooexistence strategy.

C / python integration

See scipy.spatial - parallel C and Python routines, but there in a very simple case.

How about:

  1. Import all the Python names via the __init__.py

  2. Import all the C names (after renaming with agreed scheme as above or differently) into a c.py __init__ -like module. Thus something like:

    >>> import transforms3d as t3d
    >>> M = t3d.euler3rmat(0.1, 0.3, 0.2)
    

for the python code, and:

>>> import transforms3d.c as t3dc
>>> M = t3dc.euler2mat(0.1, 0.3, 0.2)

for the C code? Or the other way round of course:

>>> import transforms3d as t3d
>>> import transforms3d.python as t3dpy

or both, and switch the __init__ to import from the C or Python namespace with a one-liner.

Questions for Christoph

Does this refactoring plan make sense?

Does the naming scheme make sense (drawing distinction for example between 3x3 rotation matrix and affine)?

Now about the naming scheme for compose - e.g compose_szrtp?

OK to return a 3x3 rotation matrix from decompose rather then Euler angles?

How to classify clip_matrix, orthogonalization_matrix, superimposition_matrix?

OK to remove: quaternion_real, quaternion_imag, random_vector, inverse_matrix, concatenate_matrices ?

What do you think of the C / Python scheme (it’s about the same as your current one)?

How do you see the relationship between your current code and this code?