# resqpy.olio.vector_utilities¶

Utilities for working with 3D vectors in cartesian space.

note: some of these functions are redundant as they are provided by built-in numpy operations.

a vector is a one dimensional numpy array with 3 elements: x, y, z. some functions accept a tuple or list of 3 elements as an alternative to a numpy array.

Functions

 `add` Returns vector sum a+b. `amplify` Returns vector with direction of v, amplified by scaling. `area_of_triangle` Returns the area of the triangle defined by three vertices. `area_of_triangles` Returns numpy array of areas of triangles, optionally when projected onto xy plane. `azimuth` Returns the compass bearing in degrees of the direction of v (x = East, y = North), ignoring z. `azimuths` Returns the compass bearings in degrees of the direction of each vector in va (x = East, y = North), ignoring z. `clockwise` Returns a +ve value if 2D points a,b,c are in clockwise order, 0.0 if in line, -ve for ccw. `clockwise_sorted_indices` Returns a clockwise sorted numpy list of indices b into the points p. `clockwise_triangles` Returns a numpy array of +ve values where triangle points are in clockwise order, 0.0 if in line, -ve for ccw. `cross_product` Returns the cross product (vector product) of the two vectors. `degrees_difference` Returns the angle between two vectors, in degrees. `degrees_from_radians` Converts angle from radians to degrees. `determinant` Returns the determinant of the 3 x 3 matrix comprised of the 3 vectors. `determinant_3x3` Returns the determinant of the 3 x 3 matrix. `dot_product` Returns the dot product (scalar product) of the two vectors. `dot_products` Returns the dot products of pairs of vectors; last axis covers element of a vector. `elemental_multiply` Returns vector with products of corresponding elements of a and b. `in_circumcircle` Returns True if point d lies within the circumcircle pf ccw points a, b, c, projected onto xy plane. `in_triangle` Returns True if point d lies wholly within the triangle pf ccw points a, b, c, projected onto xy plane. `in_triangle_edged` Returns True if d lies within or on the boudnary of triangle of ccw points a,b,c projected onto xy plane. `inclination` Returns the inclination in degrees of v (angle relative to +ve z axis). `inclinations` Returns the inclination in degrees of each vector in a (angle relative to +ve z axis). `is_close` Returns True if the two points are extremely close to one another (ie. `is_obtuse_2d` Returns True if the angle at point p subtended by points p1 and p2, in xy plane, is greater than 90 degrees; else False. `isclose` Returns True if the two points are extremely close to one another (ie. `manhattan_distance` Returns the Manhattan distance between two points. `manhatten_distance` Returns the Manhattan distance between two points. `mesh_points_in_triangle` Calculates which implicit mesh points are within a triangle in 2D for normalised triangle. `meshgrid` Returns coordinate matrices from coordinate vectors x and y. `naive_2d_length` Returns the length of the vector projected onto xy plane, assuming consistent units. `naive_2d_lengths` Returns the lengths of the vectors projected onto xy plane, assuming consistent units. `naive_length` Returns the length of the vector assuming consistent units. `naive_lengths` Returns the lengths of the vectors assuming consistent units. `nan_inclinations` Returns the inclination in degrees of each vector in a (angle relative to +ve z axis), allowing NaNs. `nan_unit_vectors` Returns vectors with same direction as those in v but with unit length, allowing NaNs. `nearest_point_projected` Returns the index into points array closest to point p; projection is 'xy', 'xz' or 'yz'. `no_rotation_matrix` Returns a rotation matrix which will not move points (identity matrix). `perspective_vector` Returns a version of vector with a perspective applied. `point_distance_sqr_to_points_projected` Returns an array of projected distances squared between p and points; projection is 'xy', 'xz' or 'yz'. `point_distance_to_line_2d` Ignoring any z values, returns the xy distance of point p from line passing through l1 and l2. `point_distance_to_line_segment_2d` Ignoring any z values, returns the xy distance of point p from line segment between l1 and l2. `point_in_polygon` Calculates if a point in within a polygon in 2D. `point_in_triangle` Calculates if a point in within a triangle in 2D. `points_direction_vector` Returns an average direction vector based on first and last non-NaN points or slices in given axis. `points_in_polygon` Calculates which points are within a polygon in 2D. `points_in_polygons` Calculates which points are within which polygons in 2D. `points_in_triangle` Calculates which points are within a triangle in 2D. `points_in_triangles` Returns 2D numpy bool array indicating which of points da are within which triangles. `points_in_triangles_aligned` Calculates which points are within which triangles in 2D for a regular mesh of aligned points. `points_in_triangles_aligned_optimised` Calculates which points are within which triangles in 2D for a regular mesh of aligned points. `points_in_triangles_njit` Calculates which points are within which triangles in 2D. `project_points_onto_plane` Modifies array of xyz points in situ to project onto a plane defined by a point and normal vector. `radians_difference` Returns the angle between two vectors, in radians. `radians_from_degrees` Converts angle from degrees to radians. `reverse_rotation_3d_matrix` Returns a rotation matrix which will rotate points about the y, z, then x axis by angles in degrees. `rotate_array` Returns a copy of array a with each vector rotated by the rotation matrix. `rotate_array_njit` Returns a copy of array a with each vector rotated by the rotation matrix. `rotate_vector` Returns the rotated vector. `rotate_xyz_array_around_z_axis` Returns a copy of array a suitable for presenting a cross-section using the resulting x,z values. `rotation_3d_matrix` Returns a rotation matrix which will rotate points about the x, z, then y axis by angles in degrees. `rotation_3d_matrix_njit` Returns a rotation matrix which will rotate points about the x, z, then y axis by angles in degrees. `rotation_matrix_3d_axial` Returns a rotation matrix which will rotate points about axis (0: x, 1: y, or 2: z) by angle in degrees. `rotation_matrix_3d_vector` Returns a rotation matrix which will rotate vector v to the vertical (z) axis. `rotation_matrix_3d_vector_njit` Returns a rotation matrix which will rotate points by inclination and azimuth of vector. `subtract` Returns vector difference a-b. `tilt_3d_matrix` Returns a 3D rotation matrix for applying a dip in a certain azimuth. `tilt_points` Modifies array of xyz points in situ to apply dip in direction of azimuth, about pivot point. `triangle_box` Finds the minimum and maximum x and y values of a single traingle. `triangle_normal_vector` For a triangle in 3D space, defined by 3 vertex points, returns a unit vector normal to the plane of the triangle. `triangle_normal_vector_numba` For a triangle in 3D space, defined by 3 vertex points, returns a unit vector normal to the plane of the triangle. `unit_corrected_length` Returns the length of the vector v after applying the unit_conversion factors. `unit_vector` Returns vector with same direction as v but with unit length. `unit_vector_from_azimuth` Returns horizontal unit vector in compass bearing given by azimuth (x = East, y = North). `unit_vector_from_azimuth_and_inclination` Returns unit vector with compass bearing of azimuth and inclination off +z axis. `unit_vector_njit` Returns vector with same direction as v but with unit length. `unit_vectors` Returns vectors with same direction as those in v but with unit length. `v_3d` Returns a 3D vector for a 2D or 3D vector. `vertical_intercept` Finds the y value of a straight line between two points at a given x. `xy_sorted` Returns copy of points p sorted according to x or y (whichever has greater range). `xy_sorted_njit` Returns copy of points p sorted according to x or y (whichever has greater range). `zero_vector` Returns a zero vector [0.0, 0.0, 0.0].