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

# Class Vector3d

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

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

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 vector. |
__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. |
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) 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``'`) Refined class comparison. |
parse(self, str3d, sep=`'``,``'`) Parse an "x, y, z" string representing a Vector3d. |
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) Convert this vector to (geodetic) lat- and longitude in `radians`. |
to2ll(self) Convert this vector to (geodetic) lat- and longitude in `degrees`. |
to3xyz(self) Return this vector as a 3-tuple. |
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__`, `toStr2` Inherited from `named._Named`: `classof`, `copy` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| crosserrors Get CrossError exceptions (`bool`).
| length Get the length (norm, magnitude) of this vector (`float`).
| x Get the X component (`float`).
| 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 Parameters: `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. Parameters: `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? Parameters: `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? Parameters: `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? Parameters: `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 vector. 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. Parameters: `x` - X component of vector (`scalar`). `y` - Y component of vector (`scalar`). `z` - Z component of vector (`scalar`). `ll` - Optional, original latlon (`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? Parameters: `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? Parameters: `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. Parameters: `other` - The other vector (Vector3d). Returns: Cross product (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

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

### __ne__(self, other) |
Is this vector not equal to an other vector? Parameters: `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. Parameters: `other` - The other vector (Vector3d). Returns: Cross product (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __rsub__(self, other) |
Subtract this vector from an other vector. Parameters: `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. Parameters: `other` - The other vector (Vector3d). Returns: Difference (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __truediv__(self, scalar) |
Divide this vector by a scalar. Parameters: `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. Parameters: `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.

### cross(self, other, raiser=None) |
Compute the cross product of this and an other vector. Parameters: `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. Parameters: `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. Parameters: `other` - The other vector (Vector3d). Returns: Dot product (`float`). Raises: `TypeError` - Incompatible `other` `type`.

### isequalTo(self, other, units=False) |
Check if this and an other vector are equal or equivalent. Parameters: `other` - The other vector (Vector3d). `units` - Optionally, compare the normalized, unit version of both vectors. 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. Parameters: `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``'`) |
Refined class comparison. Parameters: `other` - The other vector (Vector3d). `name` - Optional, other's name (`str`). Returns: `None`. Raises: `TypeError` - Incompatible `other` `type`. Overrides: named._NamedBase.others

### parse(self, str3d, sep=`'``,``'`) |
Parse an "x, y, z" string representing a Vector3d. Parameters: `str3d` - X, y and z value (`str`). `sep` - Optional separator (`str`). Returns: New vector (Vector3d). Raises: `VectorError` - Invalid `str3d`.

### plus(self, other) |
Add this vector and an other vector. Parameters: `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. Parameters: `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. Parameters: `other` - The other vector (Vector3d). Returns: Vectorial sum (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

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

### to2ab(self) |
Convert this vector to (geodetic) lat- and longitude in `radians`. Returns: A PhiLam2Tuple`(phi, lam)`. Example:
    >>> v = Vector3d(0.500, 0.500, 0.707)
    >>> a, b = v.to2ab()  # 0.785323, 0.785398

### to2ll(self) |
Convert this vector to (geodetic) lat- and longitude in `degrees`. Returns: A LatLon2Tuple`(lat, lon)`. Example:
    >>> v = Vector3d(0.500, 0.500, 0.707)
    >>> a, b = v.to2ll()  # 44.99567, 45.0

### to3xyz(self) |
Return this vector as a 3-tuple. Returns: A Vector3Tuple`(x, y, z)`.

### toStr(self, prec=5, fmt=`'``(%s)``'`, sep=`'``,` `'`) |
Return a string representation of this vector. Parameters: `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`). Overrides: named._Named.toStr

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

Property Details

### crosserrors Get 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: Read_Only(self, ignored) - Throws an `AttributeError`, always.

### x Get the X component (`float`). Get Method: x(self) - Get the X component (`float`). Set Method: Read_Only(self, ignored) - Throws an `AttributeError`, always.

### y Get the Y component (`float`). Get Method: y(self) - Get the Y component (`float`). Set Method: Read_Only(self, ignored) - Throws an `AttributeError`, always.

### z Get the Z component (`float`). Get Method: z(self) - Get the Z component (`float`). Set Method: Read_Only(self, ignored) - Throws an `AttributeError`, always.