Package pygeodesy :: Module vector3dBase :: Class Vector3dBase |
[frames] | no frames]

# Class Vector3dBase

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

Known Subclasses:
  - vector3d.Vector3d

(INTERNAL) Generic 3-D vector base class.

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 cartesian (= spherical n-vector)
- 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). |
__bool__(self) Is this vector non-zero? |
__ceil__(self) Not implemented. |
__cmp__(self, other) Compare this and an other vector (Vector3d). |
__div__(self, scalar) Divide this vector by a scalar, `this / scalar`. |
__divmod__(self, other) Not implemented. |
__eq__(self, other) Is this vector equal to an other vector? |
__float__(self) Not implemented. |
__floor__(self) Not implemented. |
__floordiv__(self, other) Not implemented. |
__format__(self, *other) Not implemented. |
__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? |
__hash__(self) Return this instance' `hash`. |
__iadd__(self, other) Add this and an other vector in-place, `this += other`. |
__idiv__(self, scalar) Divide this vector by a scalar in-place, `this /= scalar`. |
__ifloordiv__(self, other) Not implemented. |
__imatmul__(self, other) Cross multiply this and an other vector in-place, `this @= other`. |
__imod__(self, other) Not implemented. |
__imul__(self, scalar) Multiply this vector by a scalar in-place, `this *= scalar`. |
__init__(self, x_xyz, y=0, z=0, ll=None, name='') New Vector3d or `Vector3dBase` instance. |
__int__(self) Not implemented. |
__ipow__(self, other, *mod) Not implemented. |
__isub__(self, other) Subtract an other vector from this one in-place, `this -= other`. |
__itruediv__(self, scalar) Divide this vector by a scalar in-place, `this /= scalar`. |
__le__(self, other) Is this vector shorter than or equal to an other vector? |
__long__(self) Not implemented. |
__lt__(self, other) Is this vector shorter than an other vector? |
__matmul__(self, other) Compute the cross product of this and an other vector, `this @ other`. |
__mod__(self, other) Not implemented. |
__mul__(self, scalar) Multiply this vector by a scalar, `this * scalar`. |
__ne__(self, other) Is this vector not equal to an other vector? |
__neg__(self) Return this vector in opposite direction. |
__nonzero__(self) Is this vector non-zero? |
__pos__(self) Return this vector as-is or a copy. |
__pow__(self, other, *mod) Not implemented. |
__radd__(self, other) Add this to an other vector (Vector3d). |
__rdiv__(self, scalar) Not implemented. |
__rdivmod__(self, other) Not implemented. |
__rfloordiv__(self, other) Not implemented. |
__rmatmul__(self, other) Compute the cross product of an other and this vector, `other @ this`. |
__rmod__(self, other) Not implemented. |
__rmul__(self, scalar) Multiply this vector by a scalar, `this * scalar`. |
__round__(self, ndigits=None) Not implemented. |
__rpow__(self, other, *mod) Not implemented. |
__rsub__(self, other) Subtract this vector from an other vector, `other - this`. |
__rtruediv__(self, scalar) Not implemented. |
__sub__(self, other) Subtract an other vector from this vector, `this - other`. |
__truediv__(self, scalar) Divide this vector by a scalar, `this / scalar`. |
__trunc__(self) Not implemented. |
angleTo(self, other, vSign=None, wrap=False) Compute the angle between this and an other vector. |
apply(self, fun2, other_x, *y_z, **fun2_kwds) Apply a 2-argument function pairwise to the components of this and an other vector. |
cmp(self, other) Compare this and an other vector (Vector3d). |
cross(self, other, raiser=None, eps0=2.220446049250313e-16) Compute the cross product of this and an other vector. |
dividedBy(self, divisor) 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`. |
equirectangular(self, other) Approximate the different between this and an other vector. |
intermediateTo(self, other, fraction, **unused) Locate the vector at a given fraction between (or along) this and an other vector. |
isconjugateTo(self, other, minum=1, eps=2.220446049250313e-16) Determine whether this and an other vector are conjugates. |
isequalTo(self, other, units=False, eps=2.220446049250313e-16) Check if this and an other vector are equal or equivalent. |
minus(self, other) Subtract an other vector from this vector. |
minus_(self, other_x, *y_z) Subtract separate X, Y and Z components from this vector. |
negate(self) Return this vector in opposite direction. |
others(self, *other, **name_other_up) Refined class comparison. |
plus(self, other) Add this vector and an other vector. |
plus_(self, other_x, *y_z) Sum of this vector and separate X, Y and Z components. |
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. |
times_(self, other_x, *y_z) Multiply this vector's components by separate X, Y and Z factors. |
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`: `attrs`, `classof`, `copy`, `dup`, `methodname`, `rename`, `toStr2` Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| crosserrors Class `property` with retrievable name.
| euclid Approximate the length (norm, magnitude) of this vector (`Float`).
| 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`).
| x2y2z2 Get the X, Y and Z components squared (3-tuple `(x**2, y**2, z**2)`).
| 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`, `iteration`, `name`, `named`, `named2`, `named3`, `named4`, `sizeof` 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 (Vector3d). Returns: -1, 0 or +1 (`int`). Raises: `TypeError` - Incompatible `other` `type`.

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

### __format__ (self, *other) |
Not implemented. Overrides: object.__format__

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

### __hash__ (self) (Hashing function) |
Return this instance' `hash`. Overrides: object.__hash__

### __iadd__ (self, other) |
Add this and an other vector in-place, `this += other`. Arguments: `other` - The other vector (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __idiv__ (self, scalar) |
Divide this vector by a scalar in-place, `this /= scalar`. Arguments: `scalar` - The divisor (`scalar`). Raises: `TypeError` - Non-scalar `scalar`.

### __imatmul__ (self, other) |
Cross multiply this and an other vector in-place, `this @= other`. Arguments: `other` - The other vector (Vector3d). Raises: `TypeError` - Incompatible `other` `type`. Overrides: named._Named.__imatmul__ See Also: Luciano Ramalho, "Fluent Python", page 397-398, O'Reilly 2016.

### __imul__ (self, scalar) |
Multiply this vector by a scalar in-place, `this *= scalar`. Arguments: `scalar` - Factor (`scalar`). Raises: `TypeError` - Non-scalar `scalar`.

### __init__ (self, x_xyz, y=0, z=0, ll=None, name='') (Constructor) |
New Vector3d or `Vector3dBase` instance. The vector may be normalised or use x, y, z for position and distance from earth centre or height relative to the surface of the earth' sphere or ellipsoid. Arguments: `x_xyz` - X component of vector (`scalar`) or a (3-D) vector (`Cartesian`, Ecef9Tuple, `Nvector`, Vector3d, Vector3Tuple, Vector4Tuple or a `tuple` or `list` of 3+ `scalar` values). `y` - Y component of vector (`scalar`), ignored if `x_xyz` is not `scalar`, otherwise same units as `x_xyz`. `z` - Z component of vector (`scalar`), ignored if `x_xyz` is not `scalar`, otherwise same units as `x_xyz`. `ll` - Optional latlon reference (`LatLon`). `name` - Optional name (`str`). Raises: `VectorError` - Invalid `x_xyz`. Overrides: object.__init__

### __isub__ (self, other) |
Subtract an other vector from this one in-place, `this -= other`. Arguments: `other` - The other vector (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### __itruediv__ (self, scalar) |
Divide this vector by a scalar in-place, `this /= scalar`. Arguments: `scalar` - The divisor (`scalar`). Raises: `TypeError` - Non-scalar `scalar`.

### __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, `this @ other`. Arguments: `other` - The other vector (Vector3d). Returns: Cross product (Vector3d). Raises: `TypeError` - Incompatible `other` `type`. Overrides: named._Named.__matmul__

### __mul__ (self, scalar) |
Multiply this vector by a scalar, `this * 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) |
Return this vector in opposite direction. Returns: New, opposite vector (Vector3d).

### __pos__ (self) |
Return this vector as-is or a copy. Returns: This instance (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, `other @ this`. Arguments: `other` - The other vector (Vector3d). Returns: Cross product (Vector3d). Raises: `TypeError` - Incompatible `other` `type`. Overrides: named._Named.__rmatmul__

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

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

### __truediv__ (self, scalar) |
Divide this vector by a scalar, `this / 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. `wrap` - If `True`, wrap/unroll the angle to +/-PI (`bool`). Returns: Angle (`radians`). Raises: `TypeError` - If `other` or `vSign` not a Vector3d.

### apply (self, fun2, other_x, *y_z, **fun2_kwds) |
Apply a 2-argument function pairwise to the components of this and an other vector. Arguments: `fun2` - 2-Argument callable (`any(scalar, scalar`), return a `scalar` or INT0 result. `other_x` - Other X component (`scalar`) or a vector with X, Y and Z components (`Cartesian`, Ecef9Tuple, `Nvector`, Vector3d, Vector3Tuple or Vector4Tuple). `y_z` - Other Y and Z components, positional (`scalar`, `scalar`). `fun2_kwds` - Optional keyword arguments for `fun2`. Returns: New, applied vector (Vector3d). Raises: `ValueError` - Invalid `other_x` or `y_z`.

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

### cross (self, other, raiser=None, eps0=2.220446049250313e-16) |
Compute the cross product of this and an other vector. Arguments: `other` - The other vector (Vector3d). `raiser` - Optional, CrossError label if raised (`str`, non-NN). `eps0` - Near-zero tolerance (`scalar`), same units as `x`, `y`, and `z`. Returns: Cross product (Vector3d). Raises: `CrossError` - Zero or near-zero cross product and both `raiser` and pygeodesy.crosserrors set. `TypeError` - Incompatible `other` `type`.

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

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

### equals (self, other, units=False) |
DEPRECATED, use method `isequalTo`. Decorators: `@deprecated_method`

### equirectangular (self, other) |
Approximate the different between this and an other vector. Arguments: `other` - Vector to subtract (`Vector3dBase`). Returns: The lenght squared of the difference (`Float`). Raises: `TypeError` - Incompatible `other` `type`. See Also: Property `length2`.

### intermediateTo (self, other, fraction, **unused) |
Locate the vector at a given fraction between (or along) this and an other vector. Arguments: `other` - The other vector (Vector3d). `fraction` - Fraction between both vectors (`scalar`, 0.0 for this and 1.0 for the other vector). Returns: Intermediate vector (Vector3d). Raises: `TypeError` - Incompatible `other` `type`.

### isconjugateTo (self, other, minum=1, eps=2.220446049250313e-16) |
Determine whether this and an other vector are conjugates. Arguments: `other` - The other vector (`Cartesian`, Ecef9Tuple, Vector3d, `Vector3Tuple` or `Vector4Tuple`). `minum` - Minimal number of conjugates required (`int`, 0..3). `eps` - Tolerance for equality and conjugation (`scalar`), same units as `x`, `y`, and `z`. Returns: `True` if both vector's components either match or at least `minum` have opposite signs. Raises: `TypeError` - Incompatible `other` `type`. See Also: Method `isequalTo`.

### isequalTo (self, other, units=False, eps=2.220446049250313e-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`), same units as `x`, `y`, and `z`. Returns: `True` if vectors are identical, `False` otherwise. Raises: `TypeError` - Incompatible `other` `type`. See Also: Method `isconjugateTo`.

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

### minus_ (self, other_x, *y_z) |
Subtract separate X, Y and Z components from this vector. Arguments: `other_x` - X component (`scalar`) or a vector's X, Y, and Z components (`Cartesian`, Ecef9Tuple, `Nvector`, Vector3d, Vector3Tuple, Vector4Tuple). `y_z` - Y and Z components (`scalar`, `scalar`), ignored if `other_x` is not `scalar`. Returns: New, vectiorial vector (Vector3d). Raises: `ValueError` - Invalid `other_x` or `y_z`.

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

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

### plus_ (self, other_x, *y_z) |
Sum of this vector and separate X, Y and Z components. Arguments: `other_x` - X component (`scalar`) or a vector's X, Y, and Z components (`Cartesian`, Ecef9Tuple, `Nvector`, Vector3d, Vector3Tuple, Vector4Tuple). `y_z` - Y and Z components (`scalar`, `scalar`), ignored if `other_x` is not `scalar`. Returns: New, vectiorial vector (Vector3d). Raises: `ValueError` - Invalid `other_x` or `y_z`.

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

### rotateAround (self, axis, theta) |
DEPRECATED, use method `rotate`. Decorators: `@deprecated_method`

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

### times_ (self, other_x, *y_z) |
Multiply this vector's components by separate X, Y and Z factors. Arguments: `other_x` - X scale factor (`scalar`) or a vector's X, Y, and Z components as scale factors (`Cartesian`, Ecef9Tuple, `Nvector`, Vector3d, Vector3Tuple, Vector4Tuple). `y_z` - Y and Z scale factors (`scalar`, `scalar`), ignored if `other_x` is not `scalar`. Returns: New, scaled vector (Vector3d). Raises: `ValueError` - Invalid `other_x` or `y_z`.

### to3xyz (self) |
DEPRECATED, use property xyz. Decorators: `@deprecated_method`

### toStr (self, prec=5, fmt='(%s)', sep=', ') |
Return a string representation of this vector. Arguments: `prec` - Number of decimal places (`int`). `fmt` - Enclosing format to use (`str`). `sep` - 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. Arguments: `ll` - Optional, original location (`LatLon`). Returns: Normalized vector (Vector3d).

Property Details

### crosserrors Class `property` with retrievable name. 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 (`Float`). Get method: euclid(self) - Approximate the length (norm, magnitude) of this vector (`Float`). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. See Also: Properties `length` and `length2` and function pygeodesy.euclid_.

### 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: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. 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: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. See Also: Property length and method `equirectangular`.

### x Get the X component (`float`). Get method: x(self) - Get the X component (`float`). Set method: x(self, x) - Set the X component, if different (`float`). Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### x2y2z2 Get the X, Y and Z components squared (3-tuple `(x**2, y**2, z**2)`). Get method: x2y2z2(self) - Get the X, Y and Z components squared (3-tuple `(x**2, y**2, z**2)`). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### 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: xyz(self, xyz) - Set the X, Y and Z components (`Cartesian`, Ecef9Tuple, `Nvector`, Vector3d, Vector3Tuple, Vector4Tuple or a `tuple` or `list` of 3+ `scalar` values). Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### y Get the Y component (`float`). Get method: y(self) - Get the Y component (`float`). Set method: y(self, y) - Set the Y component, if different (`float`). Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### z Get the Z component (`float`). Get method: z(self) - Get the Z component (`float`). Set method: z(self, z) - Set the Z component, if different (`float`). Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.