angutils package

Submodules

angutils.angutils module

angutils.angutils.DCM2EulerAng(DCM: ndarray[tuple[int, ...], dtype[float64]], rotSet: List[int] | Tuple[int] | ndarray[tuple[int, ...], dtype[int64]], body: bool = True) → List[float][source]
Parameters:

  • DCM (numpy.ndarray) – Direction Cosine Matrix

  • rotSet (iterable) – 3-element iterable defining order of rotations of a body Euler angle set. See validateEulerAngSet().

  • body (bool) – True for body rotations, False for space rotations. Defaults to True.

Returns:

List of the three computed angles

Return type:

list

angutils.angutils.DCM2axang(DCM: ndarray[tuple[int, ...], dtype[float64]]) → Tuple[ndarray[tuple[int, ...], dtype[float64]], float][source]

Given a direction cosine matrix \({}^\mathcal{B}C^\mathcal{A}\) compute the axis and angle of the rotation. Inverse of calcDCM().

Parameters:

DCM (numpy.ndarray) – 3x3 Direction cosine matrix transforming vector components from frame \(\mathcal{A}\) to frame \(\mathcal{B}\).

Returns:

n (numpy.ndarray):

3x1 matrix representation of the unit vector of the axis of rotation

th (float):

Expression for the angle of rotation. Will always be between 0 and pi

Return type:

tuple

angutils.angutils.EulerAng2DCM(rotSet: List[int] | Tuple[int] | ndarray[tuple[int, ...], dtype[int64]], angs: List[float] | Tuple[float] | ndarray[tuple[int, ...], dtype[float64]], body: bool = True) → ndarray[tuple[int, ...], dtype[float64]][source]

Calculate the equivalent direction cosine matrix for an Euler Angle set

Parameters:

  • rotSet (iterable) – 3-element iterable defining order of rotations of a body Euler angle set. See validateEulerAngSet().

  • angs (iterable) – 3-element iterable of symbols or expressions defining the angle of each rotation.

  • body (bool) – True for body rotations, False for space rotations. Defaults to True.

Returns:

3x3 equivalent direction cosine matrix \({}^\mathcal{B}C^\mathcal{A}\)

Return type:

numpy.ndarray

angutils.angutils.calcDCM(n: List[float] | Tuple[float] | ndarray[tuple[int, ...], dtype[float64]], th: float) → ndarray[tuple[int, ...], dtype[float64]][source]

Rodrigues formula: Calculates the DCM \({}^\mathcal{A}C^\mathcal{B}\) for a rotation of the given angle about a given axis. This is a generalization of rotMat().

Parameters:

  • n (iterable) – 3 element vector representing rotation axis

  • th (float) – Angle of rotation

Returns:

3x3 rotation matrix

Return type:

numpy.ndarray

Note

n need not be normalized - it will automatically be transformed to a unit vector as part of the calculation.

angutils.angutils.calcang(x: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], y: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], z: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → float[source]

Compute the angle between vectors x and y when rotating counter-clockwise about vector z

Parameters:

  • x (iterable) – 3 components of x vector

  • y (iterable) – 3 components of y vector

  • z (iterable) – 3 components of z vector

Returns:

Angle in radians

Return type:

float

angutils.angutils.cart2sphere(n: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Tuple[float | ndarray[tuple[int, ...], dtype[float64]], float | ndarray[tuple[int, ...], dtype[float64]]][source]

Convert a vector, or an array of vectors, to spherical angles. Inverse of sphere2cart().

Parameters:

n (array_like) – Component representation of a vector (3 elements), or a 3xN array of N vectors as columns.

Returns:

lam (float or numpy.ndarray):

Azimuth angle (radians). A scalar if n is a single vector, otherwise a length-N array paired with n’s columns.

phi (float or numpy.ndarray):

Zenith/polar angle (radians), paired with lam.

Return type:

tuple

Note

n need not be normalized - the result depends only on direction, not magnitude.

angutils.angutils.colVec(n: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray[tuple[int, ...], dtype[float64]][source]

Turn any 3-element iterable into a 3x1 column vector

Parameters:

n (iterable) – 3 element iterable

Returns:

3x1 component representation of the vector

Return type:

numpy.ndarray

angutils.angutils.forwardAzimuth(cart: ndarray[tuple[int, ...], dtype[float64]]) → float[source]

Compute the forward azimuth (initial bearing) from a start point to an end point on a unit sphere, measured from north (the frame’s z-axis).

The azimuth is the angle between the great-circle plane through the start and end points and the great-circle plane through the start point and the north direction \(\mathbf{N} = (0, 0, 1)\), resolved into \((-\pi, \pi]\) via arctan2 with sign fixed relative to the start point (the local vertical).

Parameters:

cart (numpy.ndarray) – 3x2 array of Cartesian point vectors. Column 0 is the start point, column 1 is the end point.

Returns:

Forward azimuth angle (radians), measured clockwise from north, in the range \((-\pi, \pi]\).

Return type:

float

Note

cart’s columns need not be normalized - the result depends only on their directions, not their magnitudes. North is always assumed to be the frame’s z-axis.

Note

This is undefined (rather than an error) when the start and end points coincide, or when the start point lies on the north/south pole - in both cases, 0.0 is returned.

angutils.angutils.genGreatCircle(lam: List[float] | Tuple[float] | ndarray[tuple[int, ...], dtype[float64]], phi: List[float] | Tuple[float] | ndarray[tuple[int, ...], dtype[float64]], npts: int = 1000) → Tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]

Generate points sampled around the great circle passing through two points on a unit sphere.

The circle is constructed by building the meridian great circle through the start point (rotating the prototype meridian \((\cos\theta, 0, \sin\theta)\) about the z-axis via rotMat()), then rotating that meridian about the start point’s own position vector, via calcDCM(), by the initial bearing (forwardAzimuth()) from the start point to the end point. The sampled points are converted back to spherical angles via cart2sphere().

Parameters:

  • lam (iterable) – 2-element iterable of azimuth angles (radians): lam[0] is the start point, lam[1] is the end point.

  • phi (iterable) – 2-element iterable of zenith angles (radians), paired with lam.

  • npts (int) – Number of points to sample around the circle. Defaults to 1000.

Returns:

lam (numpy.ndarray):

Azimuth angles (radians) of npts points sampled around the full great circle.

phi (numpy.ndarray):

Zenith angles (radians) of npts points sampled around the full great circle, paired with lam.

Return type:

tuple

Note

The output samples the entire great circle, not just the arc between the two input points. Degenerate inputs (coincident start/end points, or a start point at a pole) propagate the singularity behavior documented in forwardAzimuth().

angutils.angutils.projplane(v: ndarray[tuple[int, ...], dtype[float64]], nv: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]][source]

Project vectors v onto a plane normal to nv

Parameters:

  • v (numpy.ndarray) – 3xn vectors to be projected

  • nv (numpy.ndarray) – 3x1 or 1x3 components of vector orthogonal to plane of projection

Returns:

Output has equivalent size to v and contains the projected vectors

Return type:

numpy.ndarray

angutils.angutils.rotMat(axis: int, angle: float) → ndarray[tuple[int, ...], dtype[float64]][source]

Returns the DCM \({}^\mathcal{B}C^\mathcal{A}\) for a rotation of the given angle about the specified axis of frame \(\mathcal{A}\)

Parameters:

  • axis (int) – Body axis to rotate about (1, 2, or 3 only)

  • angle (float) – Angle of rotation

Returns:

3x3 rotation matrix

Return type:

numpy.ndarray

angutils.angutils.skew(v: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]][source]

Given 3x1 vector v, return skew-symmetric matrix

Parameters:

v (iterable) – Component representation of vector. Must have 3 elements

Returns:

3x3 skew-symmetric matrix

Return type:

numpy.ndarray

angutils.angutils.sphere2cart(lam: float | List[float] | Tuple[float] | ndarray[tuple[int, ...], dtype[float64]], phi: float | List[float] | Tuple[float] | ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]][source]

Convert spherical angle(s) to unit vector(s). Inverse of cart2sphere().

Parameters:

  • lam (float or iterable) – Azimuth angle(s) (radians). A scalar, or a length-N array-like to convert N points at once.

  • phi (float or iterable) – Zenith/polar angle(s) (radians), paired elementwise with lam.

Returns:

3x1 unit vector if lam/phi are scalars, or a 3xN array of N unit vectors as columns if lam/phi are length-N array-likes.

Return type:

numpy.ndarray

angutils.angutils.validateEulerAngSet(rotSet: List[int] | Tuple[int] | ndarray[tuple[int, ...], dtype[int64]]) → int[source]

Ensure that a rotation set is valid and return the number of unique elements

Parameters:

rotSet (iterable) – 3-element iterable defining order of rotations of a body Euler angle set. Indexing is 1-based, so valid rotation sets may only contains 1, 2, or 3. A valid rotation set contains exactly 3 elements, at least 2 of which are distinct, and with no rotations about the same axis repeated in a row. [1, 2, 3] and [1, 3, 1] are valid, but [1, 1, 2] is not.

Returns:

Number of unique axes used in rotation (2 or 3).

Return type:

int

angutils.angutils.vnorm(v: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]][source]

Return components of unit vector of input vector

Parameters:

v (numpy.ndarray) – Components of vector

Returns:

Components of unit vector

Return type:

numpy.ndarray

Module contents