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) 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`. |
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. |
negate(self) Return this vector in opposite direction. |
others(self, other, name=`'``other``'`, up=1) 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. |
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`).
| length Get the length (norm, magnitude) 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` 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) |
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. 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`.

### 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 for equality (`scalar`). 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`.

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

### others (self, other, name=`'``other``'`, up=1) |
Refined class comparison. Arguments: `other` - The other vector (Vector3d). `name` - Optional, other's name (`str`). `up` - Number of call stack frames up (`int`). 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

### 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`).

### 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.

### 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.