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

Module vector3d

Extended 3-D vector class Vector3d and functions.

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


Version: 21.10.25

Classes
  Vector3dBase
(INTERNAL) Generic 3-D vector base class.
  Vector3d
Extended 3-D vector.
Functions
 
intersection3d3(start1, end1, start2, end2, eps=2.22044604925e-16, useZ=True, **Vector_and_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_and_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, useZ=True)
Check whether a point is colinear with two other (2- or 3-D) points.
 
nearestOn(point, point1, point2, within=True, useZ=True, Vector=None, **Vector_kwds)
Locate the point between two points closest to a reference (2- or 3-D).
 
nearestOn6(point, points, closed=False, useZ=True, **Vector_and_kwds)
Locate the point on a path or polygon closest to a reference point.
 
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_and_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_and_kwds)
Trilaterate three spheres, each given as a (3-D) center and a radius.
Variables
  __all__ = _ALL_LAZY.vector3d
Function Details

intersection3d3 (start1, end1, start2, end2, eps=2.22044604925e-16, useZ=True, **Vector_and_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 force z=0 (bool).
  • Vector_and_kwds - Optional class Vector=None to return the intersection points and optional, additional Vector keyword arguments, otherwise start1's (sub-)class.
Returns:
An Intersection3Tuple(point, outside1, outside2) with point an instance of Vector or start1's (sub-)class.
Raises:
  • IntersectionError - Invalid, skew, non-co-planar or otherwise non-intersecting lines.

intersections2 (center1, radius1, center2, radius2, sphere=True, **Vector_and_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_and_kwds - Optional class Vector=None to return the intersection points and optional, additional Vector keyword arguments, otherwise center1's (sub-)class.
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, useZ=True)

 

Check whether a point is colinear with two other (2- or 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.
  • useZ - If True, use the Z components, otherwise force z=0 (bool).
Returns:
True if point is colinear point1 and point2, False otherwise.
Raises:
  • TypeError - Invalid point, point1 or point2.

See Also: Function nearestOn.

nearestOn (point, point1, point2, within=True, useZ=True, Vector=None, **Vector_kwds)

 

Locate the point between two points closest to a reference (2- or 3-D).

Arguments:
  • point - Reference point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • point1 - Start point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • point2 - End point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • within - If True return the closest point between both given points, otherwise the closest point on the extended line through both points (bool).
  • useZ - If True, use the Z components, otherwise force z=0 (bool).
  • Vector - Class to return closest point (Cartesian, Vector3d or Vector3Tuple) or None.
  • Vector_kwds - Optional, additional Vector keyword arguments, ignored if Vector is None.
Returns:
Closest point, either point1 or point2 or an instance of the point's (sub-)class or Vector if not None.
Raises:
  • TypeError - Invalid point, point1 or point2.

See Also: 3-D Point-Line Distance, Cartesian and LatLon methods nearestOn, method sphericalTrigonometry.LatLon.nearestOn3 and function sphericalTrigonometry.nearestOn3.

nearestOn6 (point, points, closed=False, useZ=True, **Vector_and_kwds)

 

Locate the point on a path or polygon closest to a reference point.

The closest point is either on and within the extent of a polygon edge or the nearest of that edge's end points.

Arguments:
  • point - Reference point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • points - The path or polygon points (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple[]).
  • closed - Optionally, close the path or polygon (bool).
  • useZ - If True, use the Z components, otherwise force z=0 (bool).
  • Vector_and_kwds - Optional class Vector=None to return the closest point and optional, additional Vector keyword arguments, otherwise point's (sub-)class.
Returns:
A NearestOn6Tuple(closest, distance, fi, j, start, end) with the closest, the start and the end point each an instance of the Vector keyword argument of if {Vector=None} or not specified, an instance of the point's (sub-)class.
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Non-cartesian point and points.

Note: Distances measured with method Vector3d.equirectangular.

See Also: Method LatLon.nearestOn6 or function nearestOn5 for geodetic points.

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:
A Vector instance or if Vector is None, a named Vector3Tuple(x, y, z).
Raises:

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:

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 - Check the trilaterated point delta on all 3 circles (scalar) or None.
  • Vector_and_kwds - Optional class Vector=None to return the trilateration and optional, additional Vector keyword arguments, otherwise (Vector3d).
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.

trilaterate3d2 (center1, radius1, center2, radius2, center3, radius3, eps=2.22044604925e-16, **Vector_and_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_and_kwds - Optional class Vector=None to return the trilateration and optional, additional Vector keyword arguments, otherwise center1's (sub-)class.
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.