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

Class Vector3d

  object --+        
           |        
named._Named --+    
               |    
named._NamedBase --+
                   |
                  Vector3d
Known Subclasses:

Generic 3-D vector manipulation.

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

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:
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:
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:
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:
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:
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:
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:
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:
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:
Returns:
Cross product (Vector3d).
Raises:
  • TypeError - Incompatible other type.

__rsub__ (self, other)

 

Subtract this vector from an other vector.

Arguments:
Returns:
Difference (Vector3d).
Raises:
  • TypeError - Incompatible other type.

__sub__ (self, other)
(Subtraction operator)

 

Subtract an other vector from this vector.

Arguments:
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:
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:
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:
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.

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:

plus (self, other)

 

Add this vector and an other vector.

Arguments:
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:
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:
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.