Vector API Reference#
Constructor#
- class pyevspace.Vector([{x, y, z | initializer}])#
Create a
Vectorobject and initialize components.A vector can be constructed directly by setting the x, y and z components, from an iterable object of length three, or to zero if all arguments are omitted. If initializing the components directly all components must be set. If initializing from an iterable the iterable must be the only parameter. All components will be set to zero if all arguments are omitted.
- Parameters:
x (numeric) – value to initialize the x-component to (the y and z parameters must also be filled when initializing directly)
y (numeric) – value to initialize the y-component to (the x and z parameters must also be filled when initializing directly)
z (numeric) – value to initialize the z-component to (the x and y parameters must also be filled when initializing directly)
initializer (iterable) – an iterable object of length three with numeric values (this must be the only parameter when initializing from an iterable)
- Raises:
TypeError – if x, y, z or initializer is not an iterable
TypeError – if a value of initializer is not a numeric type
TypeError – if exactly three direct initializers aren’t used or iterable is not the only argument
ValueError – if initializer does not have a length of exactly three
Attributes#
- Vector.e1#
Elementary vector that represents the x-axis of the standard basis. This value should not be edited.
- Value:
Vector(1, 0, 0)- Type:
- Vector.e2#
Elementary vector that represents the y-axis of the standard basis. This value should not be edited.
- Value:
Vector(0, 1, 0)- Type:
Arithmetic Operators#
- Vector.__add__(other)#
Standard vector addition.
- Vector.__sub__(other)#
Standard vector subtraction.
- Vector.__mul__(scalar)#
Standard scalar multiplication.
- Vector.__matmul__(matrix)#
Multiplication with the vector on the left side.
- Vector.__truediv__(scalar)#
Standard scalar division.
- Vector.__neg__()#
Negates each component of a vector.
- Returns:
the negative of a vector
- Return type:
- Vector.__iadd__(other)#
Inplace standard vector addition.
- Vector.__isub__(other)#
Inplace standard vector subtraction.
- Vector.__imul__(scalar)#
Inplace standard scalar multiplication.
- Vector.__itruediv__(scalar)#
Inplace standard scalar division.
- Vector.__repr__()#
Returns a string representation of self, representative of a constructor call with the component values of the vector. The format fo the components follows the same as
Vector.__str__().- Returns:
a string representation of self
- Return type:
str
- Vector.__str__()#
Returns a string representation of self. The format of the output string is similar to a
list, the components enclosed by square brackets. The format of the components are either decimal or scientific notation, whichever requires fewer bytes to store their string representations.- Returns:
a string representation of self
- Return type:
str
- Vector.__reduce__()#
Allows support for pickling.
- Returns:
a tuple used for reconstructing self’s state
- Return type:
tuple
Module Methods#
- pyevspace.dot(lhs, rhs)#
Computes the dot product between two vectors. The order of arguments is not significant as
dot(v1, v2) == dot(v2, v1).
- pyevspace.cross(lhs, rhs)#
Computes the cross product between two vectors. A left-handed coordinate frame is used. If a right-handed cross product is needed, simply negate the answer.
>>> left_cross = cross(Vector.e1, Vector.e2) >>> print(left_cross) [0, 0, 1] >>> right_cross = -cross(Vector.e1, Vector.e2) >>> print(right_cross) [0, 0, -1]
- pyevspace.norm(vector)#
Returns a normalized version of vector. This creates a new vector, as opposed to the ‘inplace’ normalize method provided by the Vector class. See (
Vector.normalize()).>>> vector1 = Vector((1, 2, 3)) >>> vector2 = norm(vector1) >>> vector1.normalize() >>> print(vector1) [0.267261, 0.534522, 0.801784] >>> print(vector2) [0.267261, 0.534522, 0.801784]
- pyevspace.vang(lhs, rhs)#
Computes the shortest angle between two vectors. This relies on the definition of the vector dot product to compute. Since v1 * v2 = |v1|*|v2|*cos(theta), the dot product of v1 and v2, and the magnitude of v1 and v2 is all we need to compute the angle between the two vectors.
>>> lhs = Vector((1, 2, 3)) >>> rhs = Vector((4, 2, -3)) >>> acos(dot(lhs, rhs) / (lhs.mag() * rhs.mag())) 1.6204458893289022 >>> vang(lhs, rhs) 1.6204458893289022
In the plane of the two vectors, two angles can be computed between them. Only enough information is able to determine these angles, not which one is necessarily desired. Therefore, the smallest of these two angles is always the one that is returned.
The order of arguments is not significant, so
vang(lhs, rhs) == vang(rhs, lhs).
- pyevspace.vxcl(vector, exclude)#
Excludes all portions of one vector from another. This results in a linearly independent vector to exclude.
>>> ones = Vector((1, 1, 1)) >>> excl = vxcl(ones, Vector.e1) >>> print(excl) [0, 1, 1] >>> dot(excl, Vector.e1) 0.0 >>> vector = Vector((3, 2, 1)) >>> vector_excl = Vector((1.5, 0.75, 0)) >>> excl2 = vxcl(vector, Vector.e2) >>> print(excl2) [-0.2, 0.4, 1] >>> dot(excl2, vector_excl) 0.0
This effectively produces the projection of vector onto the plane whose normal vector is exclude.
Logical Operators#
- Vector.__eq__(other)#
Compares each element of two vectors for equality.
- Vector.__ne__(other)#
Compares each element of two vectors for an inequality.
All other logic operators are not implemented and will raise a
TypeError.
Vector Operators#
- Vector.mag()#
Computes the geometric length of the vector.
- Returns:
the magnitude of self
- Return type:
float
- Vector.mag2()#
Computes the square of the magnitude of the vector. Use this instead of squaring the result of
Vector.mag()to avoid rounding errors.>>> vector = Vector((0.619286, 0.581799, 0.913961)) >>> mag = vector.mag() >>> magSquared = vector.mag2() >>> magSquared == (mag * mag) False
This yields the same result as
dot(self, self). See also (py:func:dot).- Returns:
the square of
self.mag()- Return type:
float
- Vector.normalize()#
Normalizes the vector by dividing each element by the magnitude of the vector. This results in a vector with length equal to one.
- Returns:
None
Sequence Protocol#
- Vector.__len__()#
Returns the length of the
Vector. This always returns three.- Returns:
3
- Return type:
int
- Vector.__getitem__(index)#
Retrieves the indexed value of the underlying array.
- Parameters:
index (int) – the index of the value to retrieve
- Returns:
the indexed value of self
- Return type:
float
- Raises:
TypeError – if index is not or cannot be converted to an int
ValueError – if index is not in the interval [0, 2]
- Vector.__setitem__(index, value)#
Sets the indexed value of the underlying array.
- Parameters:
index (int) – the index of the value to set
value (float or int) – the value to set the array component to
- Raises:
TypeError – if index is not or cannot be converted to an int
TypeError – if value is not a numeric type
ValueError – if index is not in the interval [0, 2]
>>> vector = Vector((1, 2, 3))
>>> len(vector)
3
>>> vector[0]
1.0
>>> vector[1] = 5
>>> print(vector)
[1, 5, 3]
Iterator Protocol#
Buffer Protocol#
The Vector class supports the buffer protocol and can be
used by other object which also support the buffer interface. For
example it can be used to instantiate a memoryview object
>>> vector = Vector((1, 2, 3))
>>> view = memoryview(vector)
>>> view[2] = 3.14
>>> print(vector)
[1, 2, 3.14]