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

# Class Vector3d

           object --+
                    |
         named._Named --+
                        |
         named._NamedBase --+
                            |
    vector3dBase.Vector3dBase --+
                                |
                               Vector3d

Known Subclasses:
  - ltpTuples._Vector3d
  - , nvectorBase.NvectorBase
  - , cartesianBase.CartesianBase

Extended 3-D vector.

In a geodesy context, these may be used to represent:

- n-vector, the normal to a point on the earth's surface
- Earth-Centered, Earth-Fixed (ECEF) cartesian (== spherical n-vector)
- great circle normal to the vector
- motion vector on the earth's surface
- etc.

Instance Methods
bearing(self, useZ=True) Get this vector's "bearing", the angle off the +Z axis, clockwise. |
circin6(self, point2, point3, eps=8.881784197001252e-16) Return the radius and center of the inscribed aka In- circle of a (3-D) triangle formed by this and two other points. |
circum3(self, point2, point3, circum=True, eps=8.881784197001252e-16) Return the radius and center of the smallest circle through or containing this and two other (3-D) points. |
circum4_(self, *points) Best-fit a sphere through this and two or more other (3-D) points. |
iscolinearWith(self, point1, point2, eps=2.220446049250313e-16) Check whether this and two other (3-D) points are colinear. |
meeus2(self, point2, point3, circum=False) Return the radius and Meeus' Type of the smallest circle through or containing this and two other (3-D) points. |
nearestOn(self, point1, point2, within=True) Locate the point between two points closest to this point. |
nearestOn6(self, points, closed=False, useZ=True) Locate the point on a path or polygon closest to this point. |
parse(self, str3d, sep=',', **name) Parse an `"x, y, z"` string to a Vector3d instance. |
radii11(self, point2, point3) Return the radii of the `Circum-`, `In-`, Soddy and `Tangent` circles of a (3-D) triangle. |
soddy4(self, point2, point3, eps=8.881784197001252e-16) Return the radius and center of the `inner` Soddy circle of a (3-D) triangle. |
toCartesian(self, Cartesian, **Cartesian_kwds) Return this `Vector3d` as a `Cartesian`. |
trilaterate2d2(self, radius, center2, radius2, center3, radius3, eps=8.881784197001252e-16, z=0) Trilaterate this and two other circles, each given as a (2-D) center and a radius. |
trilaterate3d2(self, radius, center2, radius2, center3, radius3, eps=8.881784197001252e-16) Trilaterate this and two other spheres, each given as a (3-D) center and a radius. |
Inherited from `vector3dBase.Vector3dBase`: `__abs__`, `__add__`, `__bool__`, `__ceil__`, `__cmp__`, `__div__`, `__divmod__`, `__eq__`, `__float__`, `__floor__`, `__floordiv__`, `__ge__`, `__gt__`, `__hash__`, `__iadd__`, `__idiv__`, `__ifloordiv__`, `__imatmul__`, `__imod__`, `__imul__`, `__init__`, `__int__`, `__ipow__`, `__isub__`, `__itruediv__`, `__le__`, `__long__`, `__lt__`, `__matmul__`, `__mod__`, `__mul__`, `__ne__`, `__neg__`, `__nonzero__`, `__pos__`, `__pow__`, `__radd__`, `__rdiv__`, `__rdivmod__`, `__rfloordiv__`, `__rmatmul__`, `__rmod__`, `__rmul__`, `__round__`, `__rpow__`, `__rsub__`, `__rtruediv__`, `__sub__`, `__truediv__`, `__trunc__`, `angleTo`, `apply`, `bools`, `cmp`, `cross`, `dividedBy`, `dot`, `equals`, `equirectangular`, `fabs`, `floats`, `intermediateTo`, `ints`, `isconjugateTo`, `isequalTo`, `minus`, `minus_`, `negate`, `others`, `plus`, `plus_`, `rotate`, `rotateAround`, `sum`, `times`, `times_`, `to3xyz`, `toStr`, `unit` Inherited from `named._NamedBase`: `__repr__`, `__str__`, `toRepr` Inherited from `named._Named`: `__format__`, `attrs`, `classof`, `copy`, `dup`, `methodname`, `rename`, `renamed`, `toStr2` Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
Inherited from `vector3dBase.Vector3dBase`: `crosserrors`, `euclid`, `homogeneous`, `length`, `length2`, `x`, `x2y2z2`, `xyz`, `xyz3`, `y`, `z` Inherited from `named._Named`: `classname`, `classnaming`, `iteration`, `name`, `named`, `named2`, `named3`, `named4`, `sizeof`, `typename` Inherited from `object`: `__class__`

Method Details

### bearing (self, useZ=True) |
Get this vector's "bearing", the angle off the +Z axis, clockwise. Arguments: `useZ` - If `True`, use the Z component, otherwise ignore the Z component and consider the +Y as the +Z axis. Returns: Bearing (compass `degrees`).

### circin6 (self, point2, point3, eps=8.881784197001252e-16) |
Return the radius and center of the inscribed aka In- circle of a (3-D) triangle formed by this and two other points. Arguments: `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. Returns: Circin6Tuple`(radius, center, deltas, cA, cB, cC)`. The `center` and contact points `cA`, `cB` and `cC`, each an instance of this (sub-)class, are co-planar with this and the two given points. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10. `IntersectionError` - Near-coincident or -colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point2` or `point3`. See Also: Function pygeodesy.circin6, Incircle and Contact Triangle.

### circum3 (self, point2, point3, circum=True, eps=8.881784197001252e-16) |
Return the radius and center of the smallest circle through or containing this and two other (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 passed to function pygeodesy.trilaterate3d2. Returns: A Circum3Tuple`(radius, center, deltas)`. The `center`, an instance of this (sub-)class, is co-planar with this and the two given points. Raises: `ImportError` - Package `numpy` not found, not installed or older than version 1.10. `IntersectionError` - Near-concentric, -coincident or -colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point2` or `point3`. See Also: Function pygeodesy.circum3 and methods circum4_ and meeus2.

### circum4_ (self, *points) |
Best-fit a sphere through this and two or more other (3-D) points. Arguments: `points` - Other points (each a `Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). Returns: Circum4Tuple`(radius, center, rank, residuals)` with `center` an instance if this (sub-)class. 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` invalid. See Also: Function pygeodesy.circum4_ and methods circum3 and meeus2.

### iscolinearWith (self, point1, point2, eps=2.220446049250313e-16) |
Check whether this and two other (3-D) points are colinear. Arguments: `point1` - One point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `point2` - An other point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `eps` - Tolerance (`scalar`), same units as `x`, `y`, and `z`. Returns: `True` if this point is colinear with `point1` and `point2`, `False` otherwise. Raises: `TypeError` - Invalid `point1` or `point2`. See Also: Method nearestOn.

### meeus2 (self, point2, point3, circum=False) |
Return the radius and Meeus' Type of the smallest circle through or containing this and two other (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, overriding Meeus' Type II case (`bool`). Returns: Meeus2Tuple`(radius, Type)`, with `Type` the `circumcenter` iff `circum=True`. Raises: `IntersectionError` - Coincident or colinear points, iff `circum=True`. `TypeError` - Invalid `point2` or `point3`. See Also: Function pygeodesy.meeus2 and methods circum3 and circum4_.

### nearestOn (self, point1, point2, within=True) |
Locate the point between two points closest to this point. Arguments: `point1` - Start point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `point2` - End point (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `within` - If `True`, return the closest point between the given points, otherwise the closest point on the extended line through both points (`bool`). Returns: Closest point, either `point1` or `point2` or an instance of this (sub-)class. Raises: `TypeError` - Invalid `point1` or `point2`. See Also: Method sphericalTrigonometry.LatLon.nearestOn3 and 3-D Point-Line Distance.

### nearestOn6 (self, points, closed=False, useZ=True) |
Locate the point on a path or polygon closest to this 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: `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=INT0` (`bool`). Returns: A NearestOn6Tuple`(closest, distance, fi, j, start, end)` with the `closest`, the `start` and the `end` point each an instance of this point's (sub-)class. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Non-cartesian `points`. Note: Distances measured with method Vector3d.equirectangular. See Also: Function nearestOn6.

### parse (self, str3d, sep=',', **name) |
Parse an `"x, y, z"` string to a Vector3d instance. Arguments: `str3d` - X, y and z string (`str`), see function parse3d. `sep` - Optional separator (`str`). `name` - Optional instance `name=NN` (`str`), overriding this name. Returns: The instance (Vector3d). Raises: `VectorError` - Invalid `str3d`.

### radii11 (self, point2, point3) |
Return the radii of the `Circum-`, `In-`, Soddy and `Tangent` circles of a (3-D) triangle. Arguments: `point2` - Second point (`Cartesian`, Vector3d, `Vector3Tuple`, `Vector4Tuple` or `Vector2Tuple` if `useZ=False`). `point3` - Third point (`Cartesian`, Vector3d, `Vector3Tuple`, `Vector4Tuple` or `Vector2Tuple` if `useZ=False`). Returns: Radii11Tuple`(rA, rB, rC, cR, rIn, riS, roS, a, b, c, s)`. Raises: `TriangleError` - Near-coincident or -colinear points. `TypeError` - Invalid `point2` or `point3`. See Also: Function pygeodesy.radii11, Incircle, Soddy Circles and Tangent Circles.

### soddy4 (self, point2, point3, eps=8.881784197001252e-16) |
Return the radius and center of the `inner` Soddy circle of a (3-D) triangle. Arguments: `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. Returns: Soddy4Tuple`(radius, center, deltas, outer)`. 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. `IntersectionError` - Near-coincident or -colinear points or a trilateration or `numpy` issue. `TypeError` - Invalid `point2` or `point3`. See Also: Function pygeodesy.soddy4.

### toCartesian (self, Cartesian, **Cartesian_kwds) |
Return this `Vector3d` as a `Cartesian`. Arguments: `Cartesian` - The `Cartesian` class to use. `Cartesian_kwds` - Optional, additional `Cartesian` keyword arguments. Returns: The `Cartesian` instance.

### trilaterate2d2 (self, radius, center2, radius2, center3, radius3, eps=8.881784197001252e-16, z=0) |
Trilaterate this and two other circles, each given as a (2-D) center and a radius. Arguments: `radius` - Radius of this circle (same `units` as this `x` and `y`. `center2` - Center of the 2nd circle (`Cartesian`, Vector3d, `Vector2Tuple`, `Vector3Tuple` or `Vector4Tuple`). `radius2` - Radius of this circle (same `units` as this `x` and `y`. `center3` - Center of the 3rd circle (`Cartesian`, Vector3d, `Vector2Tuple`, `Vector3Tuple` or `Vector4Tuple`). `radius3` - Radius of the 3rd circle (same `units` as this `x` and `y`. `eps` - Tolerance to check the trilaterated point delta on all 3 circles (`scalar`) or `None` for no checking. `z` - Optional Z component of the trilaterated point (`scalar`). Returns: Trilaterated point, an instance of this (sub-)class with `z=z`. 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`. `TypeError` - Invalid `center2` or `center3`. `UnitError` - Invalid `radius1`, `radius2` or `radius3`. See Also: Function pygeodesy.trilaterate2d2.

### trilaterate3d2 (self, radius, center2, radius2, center3, radius3, eps=8.881784197001252e-16) |
Trilaterate this and two other spheres, each given as a (3-D) center and a radius. Arguments: `radius` - Radius of this sphere (same `units` as this `x`, `y` and `z`). `center2` - Center of the 2nd sphere (`Cartesian`, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius2` - Radius of this sphere (same `units` as this `x`, `y` and `z`). `center3` - Center of the 3rd sphere (`Cartesian`, , Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius3` - Radius of the 3rd sphere (same `units` as this `x`, `y` and `z`). `eps` - Pertubation tolerance (`scalar`), same units as `x`, `y` and `z` or `None` for no pertubations. Returns: 2-Tuple with two trilaterated points, each an instance of this (sub-)class. Both points are the same instance if all three spheres intersect or abut 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 or `numpy` issue. `NumPyError` - Some `numpy` issue. `TypeError` - Invalid `center2` or `center3`. `UnitError` - Invalid `radius`, `radius2` or `radius3`. Note: Package numpy is required, version 1.10 or later. See Also: Norrdine, A. An Algebraic Solution to the Multilateration Problem and implementation.