Package pygeodesy :: Module vector3d |
[frames] | no frames]

# Module vector3d

Extended 3-D vector class Vector3d and functions.

Function intersection3d3, intersections2, iscolinearWith, nearestOn, parse3d, sumOf, trilaterate2d2 and trilaterate3d2.

Version: 21.08.21

Classes
| Vector3dBase (INTERNAL) Generic 3-D vector base class.
| Circum3Tuple 3-Tuple `(radius, center, deltas)` with the `circumradius` and trilaterated `circumcenter` of the `circumcircle` through 3 points (aka {Meeus}' Type II circle) or the `radius` and `center` of the smallest Meeus' Type I circle.
| Circum4Tuple 4-Tuple `(radius, center, rank, residuals)` with `radius` and `center` of a sphere least-squares fitted through given points and the `rank` and `residuals` -if any- from numpy.linalg.lstsq.
| Meeus2Tuple 2-Tuple `(radius, Type)` with `radius` and Meeus' `Type` of the smallest circle containing 3 points.
| Vector3d Extended 3-D vector.

Functions
circum3(point1, point2, point3, circum=True, eps=8.881784197e-16, useZ=True) Return the radius and center of the smallest circle through or containing three (3-D) points. |
circum4_(*points, **Vector_Vector_kwds) Best-fit a sphere through three or more (3-D) points. |
intersection3d3(start1, end1, start2, end2, eps=2.22044604925e-16, useZ=True, Vector=None, **Vector_kwds) Compute the intersection point of two lines, each defined by or through a start and end point (3-D). |
intersections2(center1, radius1, center2, radius2, sphere=True, Vector=None, **Vector_kwds) Compute the intersection of two spheres or circles, each defined by a (3-D) center point and a radius. |
iscolinearWith(point, point1, point2, eps=2.22044604925e-16) Check whether a point is colinear with two other (3-D) points. |
meeus2(point1, point2, point3, circum=False, useZ=True) Return the radius and Meeus' Type of the smallest circle through or containing three (3-D) points. |
parse3d(str3d, sep=',', Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) Parse an `"x, y, z"` string. |
sumOf(vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) Compute the vectorial sum of several vectors. |
trilaterate2d2(x1, y1, radius1, x2, y2, radius2, x3, y3, radius3, eps=None, Vector=None, **Vector_kwds) Trilaterate three circles, each given as a (2-D) center and a radius. |
trilaterate3d2(center1, radius1, center2, radius2, center3, radius3, eps=2.22044604925e-16, Vector=None, **Vector_kwds) Trilaterate three spheres, each given as a (3-D) center and a radius. |

Variables
| __all__ = `_ALL_LAZY.vector3d`

Function Details

### circum3 (point1, point2, point3, circum=True, eps=8.881784197e-16, useZ=True) |
Return the radius and center of the smallest circle through or containing three (3-D) points. Arguments: `point2` - Second point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `point3` - Third point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `circum` - If `True` return the `circumradius` and `circumcenter` always, ignoring the Meeus' Type I case (`bool`). `eps` - Tolerance for function trilaterate3d2 if `useZ=True` else trilaterate2d2. `useZ` - If `True`, use the Z components, otherwise use `z=0` (`bool`). Returns: A Circum3Tuple`(radius, center, deltas)`. The `center`, an instance of `point1`'s (sub-)class, is coplanar with the three given points. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10 and `useZ=True`. `IntersectionError` - Near-concentric, coincident or colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point2` or `point3`. See Also: Jean Meeus, "Astronomical Algorithms", 2nd Ed. 1998, page 127ff, circumradius, circumcircle and functions pygeodesy.circum4_ and pygeodesy.meeus2.

### circum4_ (*points, **Vector_Vector_kwds) |
Best-fit a sphere through three or more (3-D) points. Arguments: `points` - The points (each a `Cartesian`, Vector3d, `Vector3Tuple`, or `Vector4Tuple`). `Vector_Vector_kwds` - Optional class `Vector=None` to return the center and additional `Vector` keyword arguments. Returns: Circum4Tuple`(radius, center, rank, residuals)` with `center` an instance of `points[0]`' (sub-)class or `Vector` if specified. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10. `NumPyError` - Some `numpy` issue. `PointsError` - Too few `points`. `TypeError` - One of the `points` is invalid. See Also: Charles F. Jekel, "Least Squares Sphere Fit", Sep 13, 2015 and Appendix A, numpy.linalg.lstsq, Eberly 6 and functions pygeodesy.circum3 and pygeodesy.meeus2.

### intersection3d3 (start1, end1, start2, end2, eps=2.22044604925e-16, useZ=True, Vector=None, **Vector_kwds) |
Compute the intersection point of two lines, each defined by or through a start and end point (3-D). Arguments: `start1` - Start point of the first line (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `end1` - End point of the first line (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `start2` - Start point of the second line (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `end2` - End point of the second line (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `eps` - Tolerance for skew line distance and length (`EPS`). `useZ` - If `True`, use the Z components, otherwise use `z=0` (`bool`). `Vector` - Class to return intersections (`Cartesian`, Vector3d or `Vector3Tuple`) or `None` for Vector3d. `Vector_kwds` - Optional, additional `Vector` keyword arguments, ignored if `Vector is None`. Returns: An Intersection3Tuple`(point, outside1, outside2)` with `point` an instance of `Vector` or `start1`'s (sub-)class. Raises: `IntersectionError` - Invalid, skew, non-coplanar or otherwise non-intersecting lines. See Also: Line-line intersection and line-line distance, skew lines and point-line distance.

### intersections2 (center1, radius1, center2, radius2, sphere=True, Vector=None, **Vector_kwds) |
Compute the intersection of two spheres or circles, each defined by a (3-D) center point and a radius. Arguments: `center1` - Center of the first sphere or circle (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius1` - Radius of the first sphere or circle (same units as the `center1` coordinates). `center2` - Center of the second sphere or circle (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius2` - Radius of the second sphere or circle (same units as the `center1` and `center2` coordinates). `sphere` - If `True` compute the center and radius of the intersection of two spheres. If `False`, ignore the `z`-component and compute the intersection of two circles (`bool`). `Vector` - Class to return intersections (`Cartesian`, Vector3d or `Vector3Tuple`) or `None` for an instance of `center1`'s (sub-)class. `Vector_kwds` - Optional, additional `Vector` keyword arguments, ignored if `Vector is None`. Returns: If `sphere` is `True`, a 2-tuple of the `center` and `radius` of the intersection of the spheres. The `radius` is `0.0` for abutting spheres (and the `center` is aka radical center). If `sphere` is `False`, a 2-tuple with the two intersection points of the circles. For abutting circles, both points are the same instance, aka radical center. Raises: `IntersectionError` - Concentric, invalid or non-intersecting spheres or circles. `TypeError` - Invalid `center1` or `center2`. `UnitError` - Invalid `radius1` or `radius2`. See Also: Sphere-Sphere and Circle-Circle Intersection.

### iscolinearWith (point, point1, point2, eps=2.22044604925e-16) |
Check whether a point is colinear with two other (3-D) points. Arguments: `point` - The point (Vector3d, `Vector3Tuple` or `Vector4Tuple`). `point1` - First point (Vector3d, `Vector3Tuple` or `Vector4Tuple`). `point2` - Second point (Vector3d, `Vector3Tuple` or `Vector4Tuple`). `eps` - Tolerance (`scalar`), same units as `x`, `y` and `z`. Returns: `True` if `point` is colinear `point1` and `point2`, `False` otherwise. Raises: `TypeError` - Invalid `point`, `point1` or `point2`. See Also: Function vector3d.nearestOn.

### meeus2 (point1, point2, point3, circum=False, useZ=True) |
Return the radius and Meeus' Type of the smallest circle through or containing three (3-D) points. Arguments: `point1` - First point (`Cartesian`, Vector3d, `Vector3Tuple`, `Vector4Tuple` or `Vector2Tuple` if `useZ=False`). `point2` - Second point (`Cartesian`, Vector3d, `Vector3Tuple`, `Vector4Tuple` or `Vector2Tuple` if `useZ=False`). `point3` - Third point (`Cartesian`, Vector3d, `Vector3Tuple`, `Vector4Tuple` or `Vector2Tuple` if `useZ=False`). `circum` - If `True` return the non-zero `circumradius` always, ignoring the Meeus' Type I case (`bool`). `useZ` - If `True`, use the Z components, otherwise use `z=0` (`bool`). Returns: Meeus2Tuple`(radius, Type)`. Raises: `IntersectionError` - Coincident or linear points, iff `circum=True`. `TypeError` - Invalid `point1`, `point2` or `point3`. See Also: Jean Meeus, "Astronomical Algorithms", 2nd Ed. 1998, page 127ff, circumradius, circumcircle and functions pygeodesy.circum3 and pygeodesy.circum4_.

### parse3d (str3d, sep=',', Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) |
Parse an `"x, y, z"` string. Arguments: `str3d` - X, y and z values (`str`). `sep` - Optional separator (`str`). `Vector` - Optional class (Vector3d). `Vector_kwds` - Optional `Vector` keyword arguments, ignored if `Vector is None`. Returns: New `Vector` or if `Vector` is `None`, a named Vector3Tuple`(x, y, z)`. Raises: `VectorError` - Invalid `str3d`.

### sumOf (vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) |
Compute the vectorial sum of several vectors. Arguments: `vectors` - Vectors to be added (Vector3d[]). `Vector` - Optional class for the vectorial sum (Vector3d). `Vector_kwds` - Optional `Vector` keyword arguments, ignored if `Vector is None`. Returns: Vectorial sum as `Vector` or if `Vector` is `None`, a named Vector3Tuple`(x, y, z)`. Raises: `VectorError` - No `vectors`.

### trilaterate2d2 (x1, y1, radius1, x2, y2, radius2, x3, y3, radius3, eps=None, Vector=None, **Vector_kwds) |
Trilaterate three circles, each given as a (2-D) center and a radius. Arguments: `x1` - Center `x` coordinate of the 1st circle (`scalar`). `y1` - Center `y` coordinate of the 1st circle (`scalar`). `radius1` - Radius of the 1st circle (`scalar`). `x2` - Center `x` coordinate of the 2nd circle (`scalar`). `y2` - Center `y` coordinate of the 2nd circle (`scalar`). `radius2` - Radius of the 2nd circle (`scalar`). `x3` - Center `x` coordinate of the 3rd circle (`scalar`). `y3` - Center `y` coordinate of the 3rd circle (`scalar`). `radius3` - Radius of the 3rd circle (`scalar`). `eps` - Check the trilaterated point delta on all 3 circles (`scalar`) or `None`. `Vector` - Class to return the trilateration (Vector3d) or `None`. `Vector_kwds` - Optional, additional `Vector` keyword arguments, ignored if `Vector is None`. Returns: Trilaterated point as `Vector(x, y, **Vector_kwds)` or Vector2Tuple`(x, y)` if `Vector is None`.. Raises: `IntersectionError` - No intersection, colinear or near-concentric centers, trilateration failed some other way or the trilaterated point is off one circle by more than `eps`. `UnitError` - Invalid `radius1`, `radius2` or `radius3`. See Also: Issue #49, Find X location using 3 known (X,Y) location using trilateration and trilaterate3d2.

### trilaterate3d2 (center1, radius1, center2, radius2, center3, radius3, eps=2.22044604925e-16, Vector=None, **Vector_kwds) |
Trilaterate three spheres, each given as a (3-D) center and a radius. Arguments: `center1` - Center of the 1st sphere (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius1` - Radius of the 1st sphere (same `units` as `x`, `y` and `z`). `center2` - Center of the 2nd sphere (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius2` - Radius of this sphere (same `units` as `x`, `y` and `z`). `center3` - Center of the 3rd sphere (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius3` - Radius of the 3rd sphere (same `units` as `x`, `y` and `z`). `eps` - Tolerance (`scalar`), same units as `x`, `y`, and `z`. `Vector` - Class to return intersections (`Cartesian`, Vector3d or `Vector3Tuple`) or `None` for `center1`'s (sub-)class. `Vector_kwds` - Optional, additional `Vector` keyword arguments, ignored if `Vector is None`. Returns: 2-Tuple with two trilaterated points, each a `Vector` instance. Both points are the same instance if all three spheres abut/intersect in a single point. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10. `IntersectionError` - Near-concentric, colinear, too distant or non-intersecting spheres. `NumPyError` - Some `numpy` issue. `TypeError` - Invalid `center1`, `center2` or `center3`. `UnitError` - Invalid `radius1`, `radius2` or `radius3`. See Also: Norrdine, A. An Algebraic Solution to the Multilateration Problem and implementation and trilaterate2d2.