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

# Module vector2d

2- or 3-D vectorial functions circin6, circum3, circum4_, iscolinearWith, meeus2, nearestOn, radii11, soddy4, triaxum5 and trilaterate2d2.

Note: Functions circin6, circum3, circum4_, soddy4 and triaxum5 require numpyhttps://PyPI.org/project/numpy> version 1.10 or newer to be installed.

Version: 25.04.30

Classes
| Circin6Tuple 6-Tuple `(radius, center, deltas, cA, cB, cC)` with the `radius`, the trilaterated `center` and contact points of the inscribed aka In- circle of a triangle.
| 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.
| Radii11Tuple 11-Tuple `(rA, rB, rC, cR, rIn, riS, roS, a, b, c, s)` with the `Tangent` circle radii `rA`, `rB` and `rC`, the `circumradius` `cR`, the `Incircle` radius `rIn` aka `inradius`, the inner and outer Soddy circle radii `riS` and `roS`, the sides `a`, `b` and `c` and semi-perimeter `s` of a triangle, all in `meter` conventionally.
| Soddy4Tuple 4-Tuple `(radius, center, deltas, outer)` with `radius` and (trilaterated) `center` of the inner Soddy circle and the radius of the `outer` Soddy circle.
| Triaxum5Tuple 5-Tuple `(a, b, c, rank, residuals)` with the (unordered) triaxial radii `a`, `b` and `c` of an ellipsoid least-squares fitted through given points and the `rank` and `residuals` -if any- from numpy.linalg.lstsq.

Functions
circin6(point1, point2, point3, eps=8.881784197001252e-16, useZ=True) Return the radius and center of the inscribed aka Incircle of a (2- or 3-D) triangle. |
circum3(point1, point2, point3, circum=True, eps=8.881784197001252e-16, useZ=True) Return the radius and center of the smallest circle through or containing three (2- or 3-D) points. |
circum4(points, useZ=True, **Vector_and_kwds) Best-fit a sphere through three or more (3-D) points. |
circum4_(*points, **useZ_Vector_and_kwds) Best-fit a sphere through three or more (3-D) positional points. |
meeus2(point1, point2, point3, circum=False, useZ=True) Return the radius and Meeus' Type of the smallest circle through or containing three (2- or 3-D) points. |
radii11(point1, point2, point3, useZ=True) Return the radii of the `In-`, Soddy and `Tangent` circles of a (2- or 3-D) triangle. |
soddy4(point1, point2, point3, eps=8.881784197001252e-16, useZ=True) Return the radius and center of the `inner` Soddy circle of a (2- or 3-D) triangle. |
triaxum5(points, useZ=True) Best-fit a triaxial ellipsoid through three or more (3-D) points. |
trilaterate2d2(x1, y1, radius1, x2, y2, radius2, x3, y3, radius3, eps=None, **Vector_and_kwds) Trilaterate three circles, each given as a (2-D) center and a radius. |

Variables
| __all__ = `_ALL_LAZY.vector2d`

Function Details

### circin6 (point1, point2, point3, eps=8.881784197001252e-16, useZ=True) |
Return the radius and center of the inscribed aka Incircle of a (2- or 3-D) triangle. 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`). `eps` - Tolerance for function pygeodesy.trilaterate3d2 if `useZ is True` else pygeodesy.trilaterate2d2. `useZ` - If `True`, use the Z components, otherwise force `z=INT0` (`bool`). Returns: Circin6Tuple`(radius, center, deltas, cA, cB, cC)`. The `center` and contact points `cA`, `cB` and `cC`, each an instance of `point1`'s (sub-)class, are co-planar with the three given points. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10 and `useZ is True`. `IntersectionError` - Near-coincident or -colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point1`, `point2` or `point3`. See Also: Functions radii11 and circum3, Contact Triangle and Incircle.

### circum3 (point1, point2, point3, circum=True, eps=8.881784197001252e-16, useZ=True) |
Return the radius and center of the smallest circle through or containing three (2- or 3-D) points. Arguments: `point1` - First point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `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 pygeodesy.trilaterate3d2 if `useZ is True` else pygeodesy.trilaterate2d2. `useZ` - If `True`, use the Z components, otherwise force `z=INT0` (`bool`). Returns: A Circum3Tuple`(radius, center, deltas)`. The `center`, an instance of `point1`'s (sub-)class, is co-planar with the three given points. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10 and `useZ is True`. `IntersectionError` - Near-coincident or -colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point1`, `point2` or `point3`. See Also: Functions pygeodesy.circum4_ and pygeodesy.meeus2 and Meeus, J. Astronomical Algorithms, 2nd Ed. 1998, page 127ff, circumradius and circumcircle.

### circum4 (points, useZ=True, **Vector_and_kwds) |
Best-fit a sphere through three or more (3-D) points. Arguments: `points` - Iterable of points (each a `Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `useZ` - If `True`, use the points' Z component, otherwise force `z=INT0` (`bool`). `Vector_and_kwds` - Optional class `Vector=None` to return the center point and optionally, additional `Vector` keyword arguments, otherwise the `points`' (sub-)class. 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: Functions pygeodesy.circum3 and pygeodesy.meeus2, Charles Jekel's "Least Squares Sphere Fit", Appendix A, numpy.linalg.lstsq and Eberly 6.

### circum4_ (*points, **useZ_Vector_and_kwds) |
Best-fit a sphere through three or more (3-D) positional points. Arguments: `points` - The points (each a `Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`), all positional. `useZ_Vector_and_kwds` - Keyword arguments `useZ=True` and `Vector=None`, see function circum4. See Also: Function circum4 for further details.

### meeus2 (point1, point2, point3, circum=False, useZ=True) |
Return the radius and Meeus' Type of the smallest circle through or containing three (2- or 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 `circumradius` and `circumcenter` always, overriding Meeus' Type II case (`bool`). `useZ` - If `True`, use the Z components, otherwise force `z=INT0` (`bool`). Returns: Meeus2Tuple`(radius, Type)`, with `Type` the `circumcenter` iff `circum=True`. Raises: `IntersectionError` - Near-coincident or -colinear points, iff `circum=True`. `TypeError` - Invalid `point1`, `point2` or `point3`. See Also: Functions pygeodesy.circum3 and pygeodesy.circum4_ and Meeus, J. Astronomical Algorithms, 2nd Ed. 1998, page 127ff, circumradius and circumcircle.

### radii11 (point1, point2, point3, useZ=True) |
Return the radii of the `In-`, Soddy and `Tangent` circles of a (2- or 3-D) triangle. 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`). `useZ` - If `True`, use the Z components, otherwise force `z=INT0` (`bool`). Returns: Radii11Tuple`(rA, rB, rC, cR, rIn, riS, roS, a, b, c, s)`. Raises: `TriangleError` - Near-coincident or -colinear points. `TypeError` - Invalid `point1`, `point2` or `point3`. See Also: Circumradius, Incircle, Soddy Circles and Tangent Circles.

### soddy4 (point1, point2, point3, eps=8.881784197001252e-16, useZ=True) |
Return the radius and center of the `inner` Soddy circle of a (2- or 3-D) triangle. 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`). `eps` - Tolerance for function pygeodesy.trilaterate3d2 if `useZ is True` otherwise pygeodesy.trilaterate2d2. `useZ` - If `True`, use the Z components, otherwise force `z=INT0` (`bool`). Returns: Soddy4Tuple`(radius, center, deltas, outer)`. The `center`, an instance of `point1`'s (sub-)class, is co-planar with the three given points. The `outer` Soddy radius may be `INF`. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10 and `useZ is True`. `IntersectionError` - Near-coincident or -colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point1`, `point2` or `point3`. See Also: Functions radii11 and circum3 and Soddy Circles.

### triaxum5 (points, useZ=True) |
Best-fit a triaxial ellipsoid through three or more (3-D) points. Arguments: `points` - Iterable of points (each a `Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `useZ` - If `True`, use the points' Z component, otherwise force `z=INT0` (`bool`). Returns: Triaxum5Tuple`(a, b, c, rank, residuals)` with the unordered triaxial radii `a`, `b` and `c` in `meter`, same units as the points' coordinates. 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 Jekel's "Least Squares Ellipsoid Fit" and numpy.linalg.lstsq.

### trilaterate2d2 (x1, y1, radius1, x2, y2, radius2, x3, y3, radius3, eps=None, **Vector_and_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` - Tolerance to check the trilaterated point delta on all 3 circles (`scalar`) or `None` for no checking. `Vector_and_kwds` - Optional class `Vector=None` to return the trilateration and optionally, additional `Vector` keyword arguments). Returns: Trilaterated point as `Vector(x, y, **Vector_kwds)` or Vector2Tuple`(x, y)` if `Vector is None`. Raises: `IntersectionError` - No intersection, near-concentric or -colinear 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 function pygeodesy.trilaterate3d2.