vectorose.util#

Utility functions

This module provides utility functions for manipulating vectors in Cartesian and spherical coordinates.

References

Classes#

`AngularIndex`	Angular index definition.
`AngleName`	Angular index definition.
`MagnitudeType`	Type of vector magnitude.

Functions#

`convert_vectors_to_data_frame`(→ pandas.DataFrame)	Convert vector array into a DataFrame.
`compute_vector_magnitudes`(→ numpy.ndarray)	Compute vector magnitudes.
`flatten_vector_field`(→ numpy.ndarray)	Flatten a vector field into a 2D vector list.
`remove_zero_vectors`(→ numpy.ndarray)	Prune zero-vectors.
`normalise_array`(→ numpy.ndarray)	Normalise an array.
`normalise_vectors`(→ Tuple[numpy.ndarray, numpy.ndarray])	Normalise an array of vectors.
`convert_vectors_to_axes`(→ numpy.ndarray)	Convert vectors to axes.
`create_symmetric_vectors_from_axes`(→ numpy.ndarray)	Create a set of symmetric vectors from axes.
`convert_spherical_to_cartesian_coordinates`(→ numpy.ndarray)	Convert spherical coordinates to cartesian coordinates.
`compute_vector_orientation_angles`(→ numpy.ndarray)	Compute the vector orientation angles phi and theta.
`compute_spherical_coordinates`(→ numpy.ndarray)	Compute spherical coordinates for a set of vectors.
`convert_to_math_spherical_coordinates`(→ numpy.ndarray)	Convert to the mathematical definition of spherical coordinates.
`convert_math_spherical_coordinates_to_vr_coordinates`(...)	Convert mathematical spherical coordinates to vectorose conventions.
`rotate_vectors`(→ numpy.ndarray)	Rotate a set of vectors.
`compute_arc_lengths`(→ numpy.ndarray)	Compute the arc lengths between a vector and many vectors.

Module Contents#

class vectorose.util.AngularIndex[source]#

Bases: enum.IntEnum

Angular index definition.

Stores the index of the different angles to avoid ambiguity in code.

PHI = 0#: Angle phi, in-plane with respect to positive y; index 0.

THETA = 1#: Angle theta, incline with respect to positive z; index 1.

class vectorose.util.AngleName[source]#

Bases: str, enum.Enum

Angular index definition.

Stores the name of the different angles to avoid ambiguity in code.

PHI = 'phi'#: Angle phi, in-plane with respect to positive y; index 0.

THETA = 'theta'#: Angle theta, incline with respect to positive z; index 1.

class vectorose.util.MagnitudeType[source]#

Bases: enum.IntEnum

Type of vector magnitude.

THREE_DIMENSIONAL = 0#: Euclidean magnitude in 3D space.

IN_PLANE = 1#: Magnitude of the (x,y)-projection of the vector.

vectorose.util.convert_vectors_to_data_frame(vectors: numpy.ndarray) → pandas.DataFrame[source]#

Convert vector array into a DataFrame.

Convert an array of vectors into a pandas pandas.DataFrame.

Parameters:: vectors – Array of shape (n, 3) or (n, 6) containing the vectors. If three columns are present, they are considered as the x, y, z vector components, respectively. If six columns are present, the final three columns are considered as the vector components, while the first three columns are considered the x, y, z spatial locations of the vectors.
Returns:: pandas.DataFrame – Data frame of the same shape as vectors. Spatial columns, if present, are labelled x, y, z while the vector component columns are labelled vx, vy, vz.

vectorose.util.compute_vector_magnitudes(vectors: numpy.ndarray) → numpy.ndarray[source]#

Compute vector magnitudes.

Compute vector magnitudes in 3D, as well as the component of the magnitude in the (x,y)-plane.

Parameters:: vectors – Array of shape (n, 3) containing the x, y and z components of the n 3-dimensional vectors.
Returns:: numpy.ndarray – Array of shape (n, 2) containing the vector magnitudes. The first column contains the true 3D vector magnitude. While the second column contains the magnitude of the projection onto the xy-plane.

Notes

The vector magnitudes are computed using the following equations:

\[ \begin{align}\begin{aligned}\| v \| &= \sqrt{{v_x}^2 + {v_y}^2 + {v_z} ^ 2}\\\| v \|_{xy} &= \sqrt{{v_x}^2 + {v_y}^2}\end{aligned}\end{align} \]

The both magnitudes are implemented in numpy.linalg.norm().

vectorose.util.flatten_vector_field(vector_field: numpy.ndarray) → numpy.ndarray[source]#

Flatten a vector field into a 2D vector list.

Convert an n-dimensional vector image volume into a 2D list of vectors, with rows reflecting vectors and the columns reflecting each component.

Parameters:: vector_field – Array containing the vector field. If this array is 2D, then the rows are considered to correspond to the vectors, while the columns correspond to the components. If the vector has higher dimension, the last axis is assumed to distinguish between the components.
Returns:: numpy.ndarray – 2D array containing the vectors as rows and the components as columns. If the original array was 2D, this original array is returned without copying.

vectorose.util.remove_zero_vectors(vectors: numpy.ndarray) → numpy.ndarray[source]#

Prune zero-vectors.

Remove vectors of zero magnitude from the list of vectors.

Parameters:: vectors – n by 6 or n by 3 array of vectors. If the array has 6 columns, the last 3 are assumed to be the vector components.
Returns:: numpy.ndarray – List of vectors with the same number of columns as the original without any vectors of zero magnitude.

vectorose.util.normalise_array(arr: numpy.ndarray, axis: int | None = None) → numpy.ndarray[source]#

Normalise an array.

Normalise the provided array so that all entries sum to one along the specified axis.

Parameters:

arr – The array to normalise. This array can have any shape.
axis – The axis along which to normalise. If None, then overall normalisation is performed.

Returns:

numpy.ndarray – The normalised array, such that the sum of all entries is 1 along the specified axis.

vectorose.util.normalise_vectors(vectors: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray][source]#

Normalise an array of vectors.

Rescale a series of vectors to ensure that all non-zero vectors have unit length.

Parameters:

vectors – n by 6 or n by 3 array of vectors. If the array has 6 columns, the last 3 are assumed to be the vector components. This array must contain no zero-vectors.

Returns:

normalised_vectors (numpy.ndarray) – Array of the same shape as vectors, but with all vector components rescaled to ensure that the vectors have unit length.
magnitudes (numpy.ndarray) – Array of shape (n,) containing the magnitud of each vector.

Notes

This function does not modify the original array. A new array is created and returned.

The 3D magnitude is used to perform the normalisation. This magnitude is computed as

\[\|\vec{v}\| = \sqrt{v_x^2 + v_y^2 + v_z^2}\]

where \(v_i\) refers to the component of \(\vec{v}\) along the i-th axis.

vectorose.util.convert_vectors_to_axes(vectors: numpy.ndarray) → numpy.ndarray[source]#

Convert vectors to axes.

Reflect all vectors so that they are oriented in the four octants that have positive z-values. These correspond to the axes conventionally used in directional statistics (see the book by Fisher, Lewis and Embleton [1]).

Parameters:: vectors – Array of shape (n, 3) or (n, 6) containing the vectors. The last three columns are assumed to be the vector components.
Returns:: numpy.ndarray – Array of the same shape as the original, but with all vectors oriented towards a non-negative Z value.

vectorose.util.create_symmetric_vectors_from_axes(axes: numpy.ndarray) → numpy.ndarray[source]#

Create a set of symmetric vectors from axes.

Duplicate a collection of axes to produce vectors pointing in both directions corresponding to each orientation.

Parameters:: axes – Array of shape (n, 3) or (n, 6) containing the axes. All entries in this array should have a positive Z-components. The vector coordinates are assumed to be in the last three columns if spatial coordinates are also present.
Returns:: numpy.ndarray – Array of shape (2n, 3) containing the vectors along each direction. The inverted vectors appear in the same order as the axes after the non-inverted vectors.

Warning

The inverted vectors, having negative z-values, are appended after the non-inverted vectors. Corresponding vectors are not interleaved.

vectorose.util.convert_spherical_to_cartesian_coordinates(angular_coordinates: numpy.ndarray, radius: float | numpy.ndarray = 1, use_degrees: bool = False) → numpy.ndarray[source]#

Convert spherical coordinates to cartesian coordinates.

Convert spherical coordinates provided in terms of phi and theta into cartesian coordinates. For the conversion to be possible, a sphere radius must also be specified. If none is provided, the sphere is assumed to be the unit sphere.

Parameters:

angular_coordinates – Array with >=2 columns representing \(\phi\) and \(\theta\), respectively (see AngularIndex), and n rows representing the data points. This function can also be used on the output of np.mgrid(), if the arrays have been stacked such that the final axis is used to distinguish between phi and theta.
radius – A float or numpy.ndarray representing the radius of the sphere. If the value passed is an array, it must have n rows, one for each data point. Default: radius=1.
use_degrees – Indicate whether the provided angular coordinates are in degrees. If False (default), radians are assumed.

Returns:

numpy.ndarray – Array with 3 columns, corresponding to the cartesian coordinates in X, Y, Z, and n rows, one for each data point. If mgrids are provided, then multiple sheets will be returned in this array, with the -1 axis still used to distinguish between x, y, z.

Notes

The equations governing the conversion are:

\[ \begin{align}\begin{aligned}x &= r \sin(\theta)\sin(\phi)\\y &= r \cos(\theta)\sin(\phi)\\z &= r \cos(\phi)\end{aligned}\end{align} \]

The input is provided as a 2D array with 2 columns representing the angles phi and theta, and n rows, representing the datapoints. The returned array is also a 2D array, with three columns (X, Y, Z) and n rows.

vectorose.util.compute_vector_orientation_angles(vectors: numpy.ndarray, use_degrees: bool = False) → numpy.ndarray[source]#

Compute the vector orientation angles phi and theta.

For all provided vectors, compute the phi and theta angles. The phi angle corresponds to the co-latitude, representing the tilt with respect to the z-axis, while theta is the azimuthal angle in the xy-plane with respect to the positive y-axis.

Parameters:

vectors – Array of shape (n, 3) containing 3 columns, corresponding to the x, y and z components of n 3-dimensional vectors.
use_degrees – Indicate whether the returned angles should be in degrees. Otherwise, the angles are in radians.

Returns:

numpy.ndarray – Array of shape (n, 2) containing the phi and theta angles for each vector.

Notes

In this package, we define the angles to be:

\(\phi\) - The angle of tilt with respect to the positive \(z\)-axis. A vector with \(\phi=0\) will be oriented parallel to the \(z\)-axis, while a vector with \(\phi=\pi/2\) will be oriented parallel to the \((x,y)\)-plane. A vector with \(\phi=\pi\) will be oriented parallel to the negative \(z\)-axis.
\(\theta\) - The orientation in the \((x,y)\)-plane with respect to the positive \(y\)-axis. A vector with \(\theta=0\) will be parallel to the positive \(y\)-axis, while a vector with \(\theta=\pi/2\) will be oriented parallel to the positive \(x\)-axis.

These angles are computed in the following manner:

\[ \begin{align}\begin{aligned}\phi_i &= \textup{arctan} \left( \frac{\sqrt{{x_i} ^ 2 + {y_i} ^ 2}}{z_i} \right)\\\theta_i &= \textup{arctan} \left( \frac{x_i}{y_i} \right)\end{aligned}\end{align} \]

To ensure that each direction has a unique description, we restrict the angles to specific ranges. The phi angle is in the range 0 <= phi <= 180 degrees, or 0 <= phi <= pi radians, while the theta angle is in the range 0 <= theta < 360 degrees or 0 <= theta < 2 * pi radians.

vectorose.util.compute_spherical_coordinates(vectors: numpy.ndarray, use_degrees: bool = False) → numpy.ndarray[source]#

Compute spherical coordinates for a set of vectors.

Compute true spherical coordinates for a set of provided vectors. These coordinates express a vector as an orientation, consisting of the angles phi and theta, and a magnitude.

Parameters:

vectors – 2D NumPy array containing 3 columns, corresponding to the x, y and z components of the vectors, and n rows, one for each vector. Note: We only require the vector components, not the coordinates in space.
use_degrees – indicate whether the returned angles should be in degrees. If False (default), the angles will be returned in radians.

Returns:

numpy.ndarray – Array of shape (n, 3) containing the vectors in spherical coordinates, consisting of phi, theta and magnitude columns.