shears

Functions for working with shears

Terms used in function names:

• mat : array shape (3, 3) (3D non-homogenous coordinates)
• aff : affine array shape (4, 4) (3D homogenous coordinates)
• striu : shears encoded by vector giving triangular portion above diagonal of NxN array (for ND transformation)
• sadn : shears encoded by angle scalar, direction vector, normal vector (with optional point vector)

aff2sadn(aff)	Return shear angle, direction and plane normal from shear matrix.
mat2sadn(mat)	Return shear angle, direction and plane normal from shear matrix.
sadn2aff(angle, direction, normal[, point])	Affine for shear by angle along vector direction on shear plane.
sadn2mat(angle, direction, normal)	Matrix for shear by angle along direction vector on shear plane.
striu2mat(striu)	Construct shear matrix from upper triangular vector

aff2sadn

transforms3d.shears.aff2sadn(aff)

Return shear angle, direction and plane normal from shear matrix.

Parameters:

mat : array-like, shape (3,3)

shear matrix.

Returns:

angle : scalar

angle to shear, in radians

direction : array, shape (3,)

direction along which to shear

normal : array, shape (3,)

vector normal to shear plane

point : array, shape (3,)

point that, with normal, defines shear plane.

Examples

>>> A = sadn2aff(0.5, [1, 0, 0], [0, 1, 0])
>>> angle, direction, normal, point = aff2sadn(A)
>>> angle, direction, normal, point
(0.5, array([-1.,  0.,  0.]), array([ 0., -1.,  0.]), array([ 0.,  0.,  0.]))
>>> A_again = sadn2aff(angle, direction, normal, point)
>>> np.allclose(A, A_again)
True

mat2sadn

transforms3d.shears.mat2sadn(mat)

Return shear angle, direction and plane normal from shear matrix.

Parameters:

mat : array-like, shape (3,3)

shear matrix

Returns:

angle : scalar

angle to shear, in radians

direction : array, shape (3,)

direction along which to shear

normal : array, shape (3,)

vector defining shear plane, where shear plane passes through origin

Examples

>>> M = sadn2mat(0.5, [1, 0, 0], [0, 1, 0])
>>> angle, direction, normal = mat2sadn(M)
>>> angle, direction, normal
(0.5, array([-1.,  0.,  0.]), array([ 0., -1.,  0.]))
>>> M_again = sadn2mat(angle, direction, normal)
>>> np.allclose(M, M_again)
True

sadn2aff

transforms3d.shears.sadn2aff(angle, direction, normal, point=None)

Affine for shear by angle along vector direction on shear plane.

The shear plane is defined by a point and normal vector. The direction vector must be orthogonal to the plane’s normal vector.

A point P is transformed by the shear matrix into P” such that the vector P-P” is parallel to the direction vector and its extent is given by the angle of P-P’-P”, where P’ is the orthogonal projection of P onto the shear plane.

Parameters:

angle : scalar

angle to shear, in radians

direction : array-like, shape (3,)

direction along which to shear

normal : array-like, shape (3,)

vector normal to shear-plane

point : None or array-like, shape (3,), optional

point, that, with normal defines shear plane. Defaults to None, equivalent to shear-plane through origin.

Returns:

aff : array shape (4,4)

affine shearing matrix

Examples

>>> angle = (np.random.random() - 0.5) * 4*math.pi
>>> direct = np.random.random(3) - 0.5
>>> normal = np.cross(direct, np.random.random(3))
>>> S = sadn2mat(angle, direct, normal)
>>> np.allclose(1.0, np.linalg.det(S))
True

sadn2mat

transforms3d.shears.sadn2mat(angle, direction, normal)

Matrix for shear by angle along direction vector on shear plane.

The shear plane is defined by normal vector normal, and passes through the origin. The direction vector must be orthogonal to the plane’s normal vector.

A point P is transformed by the shear matrix into P” such that the vector P-P” is parallel to the direction vector and its extent is given by the angle of P-P’-P”, where P’ is the orthogonal projection of P onto the shear plane.

Parameters:

angle : scalar

angle to shear, in radians

direction : array-like, shape (3,)

direction along which to shear

normal : array-like, shape (3,)

vector defining shear plane, where shear plane passes through origin

Returns:

mat : array shape (3,3)

shear matrix

Examples

>>> angle = (np.random.random() - 0.5) * 4*math.pi
>>> direct = np.random.random(3) - 0.5
>>> normal = np.cross(direct, np.random.random(3))
>>> S = sadn2aff(angle, direct, normal)
>>> np.allclose(1.0, np.linalg.det(S))
True

striu2mat

transforms3d.shears.striu2mat(striu)

Construct shear matrix from upper triangular vector

Parameters:

striu : array, shape (N,)

vector giving triangle above diagonal of shear matrix.

Returns:

SM : array, shape (N, N)

shear matrix

Notes

Shear lengths are triangular numbers.

See http://en.wikipedia.org/wiki/Triangular_number

Examples

>>> S = [0.1, 0.2, 0.3]
>>> striu2mat(S)
array([[ 1. ,  0.1,  0.2],
       [ 0. ,  1. ,  0.3],
       [ 0. ,  0. ,  1. ]])
>>> striu2mat([1])
array([[ 1.,  1.],
       [ 0.,  1.]])
>>> striu2mat([1, 2])
Traceback (most recent call last):
   ...
ValueError: 2 is a strange number of shear elements