`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. Return scalar t, unit vectors a, b so mat = t * np.outer(a, b) `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

`transforms3d.shears.``aff2sadn`(aff)

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

Parameters
matarray-like, shape (3,3)

shear matrix.

Returns
anglescalar

directionarray, shape (3,)

direction along which to shear

normalarray, shape (3,)

vector normal to shear plane

pointarray, shape (3,)

point that, with normal, defines shear plane.

Notes

The translation part of the affine shear matrix is calculated using:

This holds for the ``i``th coordinate:

Then:

This can be compared with the equation of the plane:

where `d` is the distance from the plane to the origin.

Examples

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

inverse_outer¶

`transforms3d.shears.``inverse_outer`(mat)

Return scalar t, unit vectors a, b so mat = t * np.outer(a, b)

Parameters
matarray-like, shape (3,3)

shear matrix

Returns
tfloat

Scalar such that mat = t * np.outer(a, b)

aarray, shape (3,)

Unit vector such that mat = t * np.outer(a, b)

barray, shape (3,)

Unit vector such that mat = t * np.outer(a, b)

`transforms3d.shears.``mat2sadn`(mat)

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

Parameters
matarray-like, shape (3,3)

shear matrix

Returns
anglescalar

directionarray, shape (3,)

direction along which to shear

normalarray, shape (3,)

vector defining shear plane, where shear plane passes through origin

Notes

The shear matrix we are decomposing was calculated using:

So the idea is to use an “inverse outer product” to recover the shears. See `inverse_outer()` for the implementation.

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
```

`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
anglescalar

directionarray-like, shape (3,)

direction along which to shear

normalarray-like, shape (3,)

vector normal to shear-plane

pointNone or array-like, shape (3,), optional

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

Returns
affarray 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
```

`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
anglescalar

directionarray-like, shape (3,)

direction along which to shear

normalarray-like, shape (3,)

vector defining shear plane, where shear plane passes through origin

Returns
matarray 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
striuarray, shape (N,)

vector giving triangle above diagonal of shear matrix.

Returns
SMarray, shape (N, N)

shear matrix

Notes

Shear lengths are triangular numbers.

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
```