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

# Class Vector3d

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

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

Generic 3-D vector manipulation.

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

- n-vector representing a normal to point on earth's surface
- earth-centered, earth-fixed vector (= n-vector for spherical model)
- great circle normal to vector
- motion vector on earth's surface
- etc.

Instance Methods
__abs__(self) Return the norm of this vector. |
__add__(self, other) Add this to an other vector (Vector3d). |
__cmp__(self, other) Compare this and an other vector |
__div__(self, scalar) Divide this vector by a scalar. |
__eq__(self, other) Is this vector equal to an other vector? |
__ge__(self, other) Is this vector longer than or equal to an other vector? |
__gt__(self, other) Is this vector longer than an other vector? |
__init__(self, x, y, z, ll=None, name=`'````'`) New 3-D Vector3d. |
__le__(self, other) Is this vector shorter than or equal to an other vector? |
__lt__(self, other) Is this vector shorter than an other vector? |
__matmul__(self, other) Compute the cross product of this and an other vector. |
__mul__(self, scalar) Multiply this vector by a scalar |
__ne__(self, other) Is this vector not equal to an other vector? |
__neg__(self) Negate this vector. |
__pos__(self) Copy this vector. |
__radd__(self, other) Add this to an other vector (Vector3d). |
__rmatmul__(self, other) Compute the cross product of an other and this vector. |
__rsub__(self, other) Subtract this vector from an other vector. |
__sub__(self, other) Subtract an other vector from this vector. |
__truediv__(self, scalar) Divide this vector by a scalar. |
angleTo(self, other, vSign=None, wrap=False) Compute the angle between this and an other vector. |
cmp(self, other) Compare this and an other vector |
cross(self, other, raiser=None) Compute the cross product of this and an other vector. |
dividedBy(self, factor) Divide this vector by a scalar. |
dot(self, other) Compute the dot (scalar) product of this and an other vector. |
equals(self, other, units=False) DEPRECATED, use method `isequalTo`. |
iscolinearWith(self, point1, point2, eps=2.22044604925e-16) Check whether this and two other points are colinear. |
isequalTo(self, other, units=False, eps=2.22044604925e-16) Check if this and an other vector are equal or equivalent. |
minus(self, other) Subtract an other vector from this vector. |
nearestOn(self, other1, other2, within=True) Locate the point between two points closest to this point. |
negate(self) Return this vector in opposite direction. |
others(self, *other, **name_other_up) Refined class comparison. |
parse(self, str3d, sep=`'``,``'`, name=`'````'`) Parse an `"x, y, z"` string to a similar Vector3d instance. |
plus(self, other) Add this vector and an other vector. |
rotate(self, axis, theta) Rotate this vector around an axis by a specified angle. |
rotateAround(self, axis, theta) DEPRECATED, use method `rotate`. |
sum(self, other) Add this vector and an other vector. |
times(self, factor) Multiply this vector by a scalar. |
to2ab(self) DEPRECATED, use property `Nvector.philam`. |
to2ll(self) DEPRECATED, use property `Nvector.latlon`. |
to3xyz(self) DEPRECATED, use property `xyz`. |
toStr(self, prec=5, fmt=`'``(%s)``'`, sep=`'``,` `'`) Return a string representation of this vector. |
trilaterate3d2(self, radius, center2, radius2, center3, radius3, eps=2.22044604925e-16) Trilaterate this and two other spheres, each given as a (3d) center and radius. |
unit(self, ll=None) Normalize this vector to unit length. |
Inherited from `named._NamedBase`: `__repr__`, `__str__`, `toRepr` Inherited from `named._Named`: `_dot_`, `attrs`, `classof`, `copy`, `toStr2` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| crosserrors Property to raise or ignore CrossError exceptions (`bool`).
| euclid Approximate the length (norm, magnitude) of this vector.
| length Get the length (norm, magnitude) of this vector (`float`).
| length2 Get the length squared of this vector (`float`).
| x Get the X component (`float`).
| xyz Get the X, Y and Z components (Vector3Tuple`(x, y, z)`).
| y Get the Y component (`float`).
| z Get the Z component (`float`).
Inherited from `named._Named`: `classname`, `classnaming`, `name`, `named`, `named2`, `named3`, `named4` Inherited from `object`: `__class__`

Method Details

### __abs__ (self) |
Return the norm of this vector. Returns: Norm, unit length (`float`);

### __add__ (self, other) (Addition operator) |
Add this to an other vector (Vector3d). Returns: Vectorial sum (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __cmp__ (self, other) (Comparison operator) |
Compare this and an other vector Arguments: `other` - The other vector (Vector3d). Returns: -1, 0 or +1 (`int`). Raises: `TypeError` - Incompatible `other` `type`.

### __div__ (self, scalar) |
Divide this vector by a scalar. Arguments: `scalar` - The divisor (`scalar`). Returns: Quotient (Vector3d). Raises: `TypeError` - Non-scalar `scalar`.

### __eq__ (self, other) (Equality operator) |
Is this vector equal to an other vector? Arguments: `other` - The other vector (Vector3d). Returns: `True` if equal, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`.

### __ge__ (self, other) (Greater-than-or-equals operator) |
Is this vector longer than or equal to an other vector? Arguments: `other` - The other vector (Vector3d). Returns: `True` if so, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`.

### __gt__ (self, other) (Greater-than operator) |
Is this vector longer than an other vector? Arguments: `other` - The other vector (Vector3d). Returns: `True` if so, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`.

### __init__ (self, x, y, z, ll=None, name=`'````'`) (Constructor) |
New 3-D Vector3d. The vector may be normalised or use x/y/z values for height relative to the surface of the sphere or ellipsoid, distance from earth centre, etc. Arguments: `x` - X component of vector (`scalar`). `y` - Y component of vector (`scalar`). `z` - Z component of vector (`scalar`). `ll` - Optional latlon reference (`LatLon`). `name` - Optional name (`str`). Overrides: object.__init__

### __le__ (self, other) (Less-than-or-equals operator) |
Is this vector shorter than or equal to an other vector? Arguments: `other` - The other vector (Vector3d). Returns: `True` if so, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`.

### __lt__ (self, other) (Less-than operator) |
Is this vector shorter than an other vector? Arguments: `other` - The other vector (Vector3d). Returns: `True` if so, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`.

### __matmul__ (self, other) |
Compute the cross product of this and an other vector. Arguments: `other` - The other vector (Vector3d). Returns: Cross product (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __mul__ (self, scalar) |
Multiply this vector by a scalar Arguments: `scalar` - Factor (`scalar`). Returns: Product (Vector3d).

### __ne__ (self, other) |
Is this vector not equal to an other vector? Arguments: `other` - The other vector (Vector3d). Returns: `True` if so, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`.

### __neg__ (self) |
Negate this vector. Returns: Negative (Vector3d)

### __pos__ (self) |
Copy this vector. Returns: Positive (Vector3d)

### __radd__ (self, other) (Right-side addition operator) |
Add this to an other vector (Vector3d). Returns: Vectorial sum (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __rmatmul__ (self, other) |
Compute the cross product of an other and this vector. Arguments: `other` - The other vector (Vector3d). Returns: Cross product (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __rsub__ (self, other) |
Subtract this vector from an other vector. Arguments: `other` - The other vector (Vector3d). Returns: Difference (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __sub__ (self, other) (Subtraction operator) |
Subtract an other vector from this vector. Arguments: `other` - The other vector (Vector3d). Returns: Difference (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __truediv__ (self, scalar) |
Divide this vector by a scalar. Arguments: `scalar` - The divisor (`scalar`). Returns: Quotient (Vector3d). Raises: `TypeError` - Non-scalar `scalar`.

### angleTo (self, other, vSign=None, wrap=False) |
Compute the angle between this and an other vector. Arguments: `other` - The other vector (Vector3d). `vSign` - Optional vector, if supplied (and out of the plane of this and the other), angle is signed positive if this->other is clockwise looking along vSign or negative in opposite direction, otherwise angle is unsigned. `warp` - Wrap/unroll the angle to +/-PI (c{bool}). Returns: Angle (`radians`). Raises: `TypeError` - If `other` or `vSign` not a Vector3d.

### cmp (self, other) |
Compare this and an other vector Arguments: `other` - The other vector (Vector3d). Returns: -1, 0 or +1 (`int`). Raises: `TypeError` - Incompatible `other` `type`.

### cross (self, other, raiser=None) |
Compute the cross product of this and an other vector. Arguments: `other` - The other vector (Vector3d). `raiser` - Optional, CrossError label if raised (`str`). Returns: Cross product (Vector3d). Raises: `CrossError` - Zero or near-zero cross product and both `raiser` and crosserrors set. `TypeError` - Incompatible `other` `type`.

### dividedBy (self, factor) |
Divide this vector by a scalar. Arguments: `factor` - The divisor (`scalar`). Returns: New, scaled vector (Vector3d). Raises: `TypeError` - Non-scalar `factor`. `VectorError` - Invalid or zero `factor`.

### dot (self, other) |
Compute the dot (scalar) product of this and an other vector. Arguments: `other` - The other vector (Vector3d). Returns: Dot product (`float`). Raises: `TypeError` - Incompatible `other` `type`.

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

### isequalTo (self, other, units=False, eps=2.22044604925e-16) |
Check if this and an other vector are equal or equivalent. Arguments: `other` - The other vector (Vector3d). `units` - Optionally, compare the normalized, unit version of both vectors. `eps` - Tolerance (`scalar`), same units as `x`, `y`, and `z`. Returns: `True` if vectors are identical, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`. Example:
    >>> v1 = Vector3d(52.205, 0.119)
    >>> v2 = Vector3d(52.205, 0.119)
    >>> e = v1.isequalTo(v2)  # True

### minus (self, other) |
Subtract an other vector from this vector. Arguments: `other` - The other vector (Vector3d). Returns: New vector difference (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### nearestOn (self, other1, other2, within=True) |
Locate the point between two points closest to this point. Arguments: `other1` - Start point (Vector3d). `other2` - End point (Vector3d). `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 (Vector3d). Raises: `TypeError` - If `other1` or `other2` is not Vector3d. See Also: Method sphericalTrigonometry.LatLon.nearestOn3 and 3-D Point-Line distance.

### negate (self) |
Return this vector in opposite direction. Returns: New, opposite vector (Vector3d).

### others (self, *other, **name_other_up) |
Refined class comparison. Arguments: `other` - The other vector (Vector3d). `name_other_up` - Overriding `name=other` and `up=1` keyword arguments. Returns: The `other` if compatible. Raises: `TypeError` - Incompatible `other` `type`. Overrides: named._NamedBase.others

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

### plus (self, other) |
Add this vector and an other vector. Arguments: `other` - The other vector (Vector3d). Returns: Vectorial sum (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### rotate (self, axis, theta) |
Rotate this vector around an axis by a specified angle. See Rotation matrix from axis and angle and Quaternion-derived rotation matrix. Arguments: `axis` - The axis being rotated around (Vector3d). `theta` - The angle of rotation (`radians`). Returns: New, rotated vector (Vector3d). JS name: rotateAround.

### sum (self, other) |
Add this vector and an other vector. Arguments: `other` - The other vector (Vector3d). Returns: Vectorial sum (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### times (self, factor) |
Multiply this vector by a scalar. Arguments: `factor` - Scale factor (`scalar`). Returns: New, scaled vector (Vector3d). Raises: `TypeError` - Non-scalar `factor`.

### to2ab (self) |
DEPRECATED, use property `Nvector.philam`. Returns: A PhiLam2Tuple`(phi, lam)`.

### to2ll (self) |
DEPRECATED, use property `Nvector.latlon`. Returns: A LatLon2Tuple`(lat, lon)`.

### to3xyz (self) |
DEPRECATED, use property `xyz`. Returns: A Vector3Tuple`(x, y, z)`.

### toStr (self, prec=5, fmt=`'``(%s)``'`, sep=`'``,` `'`) |
Return a string representation of this vector. Arguments: `prec` - Optional number of decimal places (`int`). `fmt` - Optional, enclosing format to use (`str`). `sep` - Optional separator between components (`str`). Returns: Vector as "(x, y, z)" (`str`). Raises: `AssertionError` - Always, see function notOverloaded. Overrides: named._Named.toStr

### trilaterate3d2 (self, radius, center2, radius2, center3, radius3, eps=2.22044604925e-16) |
Trilaterate this and two other spheres, each given as a (3d) center and radius. Arguments: `radius` - Radius of this sphere (same `units` as this `x`, `y` and `z`). `center2` - Center of the 2nd sphere (Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius2` - Radius of this sphere (same `units` as this `x`, `y` and `z`). `center3` - Center of the 3rd sphere (Vector3d, `Vector3Tuple` or `Vector4Tuple`). `radius3` - Radius of the 3rd sphere (same `units` as this `x`, `y` and `z`). `eps` - Tolerance (`scalar`), same units as `x`, `y`, and `z`. Returns: 2-Tuple with two trilaterated points, each an instance of this Vector3d (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.15. `IntersectionError` - No intersection, colinear or near concentric centers or trilateration failed some other way. `TypeError` - Invalid `center2` or `center3`. `UnitError` - Invalid `radius`, `radius2` or `radius3`. Note: Package numpy is required, version 1.15 or later. See Also: Norrdine, A. An Algebraic Solution to the Multilateration Problem and implementation.

### unit (self, ll=None) |
Normalize this vector to unit length. Arguments: `ll` - Optional, original location (`LatLon`). Returns: Normalized vector (Vector3d).

Property Details

### crosserrors Property to raise or ignore CrossError exceptions (`bool`). Get method: crosserrors(self) - Get CrossError exceptions (`bool`). Set method: crosserrors(self, raiser) - Raise CrossError exceptions (`bool`).

### euclid Approximate the length (norm, magnitude) of this vector. Get method: euclid(self) - Approximate the length (norm, magnitude) of this vector. Set method: immutable(inst, value) - Throws an `AttributeError`, always. See Also: Function euclid_ and properties `length` and `length2`.

### length Get the length (norm, magnitude) of this vector (`float`). Get method: length(self) - Get the length (norm, magnitude) of this vector (`float`). Set method: immutable(inst, value) - Throws an `AttributeError`, always. See Also: Properties `length2` and `euclid`.

### length2 Get the length squared of this vector (`float`). Get method: length2(self) - Get the length squared of this vector (`float`). Set method: immutable(inst, value) - Throws an `AttributeError`, always. See Also: Property `length`.

### x Get the X component (`float`). Get method: x(self) - Get the X component (`float`). Set method: immutable(inst, value) - Throws an `AttributeError`, always.

### xyz Get the X, Y and Z components (Vector3Tuple`(x, y, z)`). Get method: xyz(self) - Get the X, Y and Z components (Vector3Tuple`(x, y, z)`). Set method: immutable(inst, value) - Throws an `AttributeError`, always.

### y Get the Y component (`float`). Get method: y(self) - Get the Y component (`float`). Set method: immutable(inst, value) - Throws an `AttributeError`, always.

### z Get the Z component (`float`). Get method: z(self) - Get the Z component (`float`). Set method: immutable(inst, value) - Throws an `AttributeError`, always.