topologicpy.Vector module

class topologicpy.Vector.Vector(iterable=(), /)

Bases: list

Methods

Add(vectorA, vectorB)	Adds the two input vectors.
Angle(vectorA, vectorB[, mantissa, bracket])	Returns the angle in degrees between the two input vectors.
Average(vectors)	Returns the average vector of the input vectors.
AzimuthAltitude(vector[, mantissa])	Returns a dictionary of azimuth and altitude angles in degrees for the input vector.
Bisect(vectorA, vectorB)	Compute the bisecting vector of two input vectors.
ByAzimuthAltitude(azimuth, altitude[, ...])	Returns the vector specified by the input azimuth and altitude angles.
ByCoordinates(x, y, z)	Creates a vector by the specified x, y, z inputs.
ByVertices(*vertices[, normalize, mantissa, ...])	Creates a vector by the specified input list of vertices.
CompassAngle(vectorA, vectorB[, mantissa, ...])	Returns the horizontal compass angle in degrees between the two input vectors.
CompassDirection(vector[, tolerance, silent])	Returns the compass direction of the input direction.
CompassDirections()	Returns the list of allowed compass directions.
Coordinates(vector[, outputType, mantissa, ...])	Returns the coordinates of the input vector.
Cross(vectorA, vectorB[, mantissa, ...])	Returns the cross product of the two input vectors.
Dot(vectorA, vectorB[, mantissa, tolerance, ...])	Returns the dot product of the two input vectors which is a measure of how much they are aligned.
Down()	Returns the vector representing the down direction.
East()	Returns the vector representing the east direction.
IsAntiParallel(vectorA, vectorB)	Returns True if the input vectors are anti-parallel.
IsCollinear(vectorA, vectorB[, tolerance])	Returns True if the input vectors are collinear (parallel or anti-parallel) within a given tolerance.
IsParallel(vectorA, vectorB[, tolerance])	Returns True if the input vectors are parallel within a given tolerance.
IsSame(vectorA, vectorB[, tolerance])	Returns True if the input vectors are the same.
Length(vector[, mantissa])	Returns the length of the input vector.
Magnitude(vector[, mantissa])	Returns the magnitude of the input vector.
Multiply(vector, magnitude[, tolerance])	Multiplies the input vector by the input magnitude.
Normalize(vector)	Returns a normalized vector of the input vector.
North()	Returns the vector representing the north direction.
NorthEast()	Returns the vector representing the northeast direction.
NorthWest()	Returns the vector representing the northwest direction.
Quadrance(vector[, mantissa])	Returns the quadrance of the input vector.
Reverse(vector)	Returns a reverse vector of the input vector.
SetMagnitude(vector, magnitude)	Sets the magnitude of the input vector to the input magnitude.
South()	Returns the vector representing the south direction.
SouthEast()	Returns the vector representing the southeast direction.
SouthWest()	Returns the vector representing the southwest direction.
Spread(vectorA, vectorB[, mantissa, bracket])	Returns the spread between the two input vectors.
Subtract(vectorA, vectorB)	Subtracts the second input vector from the first input vector.
Sum(vectors)	Returns the sum vector of the input vectors.
TransformationMatrix(vectorA, vectorB)	Returns the transformation matrix needed to align vectorA with vectorB.
Up()	Returns the vector representing the up direction.
West()	Returns the vector representing the west direction.
XAxis()	Returns the vector representing the XAxis ([1, 0, 0])
YAxis()	Returns the vector representing the YAxis ([0, 1, 0])
ZAxis()	Returns the vector representing the ZAxis ([0, 0, 1])
append(object, /)	Append object to the end of the list.
clear(/)	Remove all items from list.
copy(/)	Return a shallow copy of the list.
count(value, /)	Return number of occurrences of value.
extend(iterable, /)	Extend list by appending elements from the iterable.
index(value[, start, stop])	Return first index of value.
insert(index, object, /)	Insert object before index.
pop([index])	Remove and return item at index (default last).
remove(value, /)	Remove first occurrence of value.
reverse(/)	Reverse IN PLACE.
sort(*[, key, reverse])	Sort the list in ascending order and return None.

static Add(vectorA, vectorB)

Adds the two input vectors.

Parameters

vectorAlist

The first vector.

vectorBlist

The second vector.

Returns

list

The sum vector of the two input vectors.

static Angle(vectorA, vectorB, mantissa: int = 6, bracket: bool = False)

Returns the angle in degrees between the two input vectors.

This implementation derives the angle from Rational Trigonometry’s Spread:

spread = sin^2(theta)

The acute angle is recovered as:

acute = asin(sqrt(spread)) in [0, 90]

The obtuse/acute distinction is recovered using the sign of the dot product. If bracket=True, the angle is forced into the acute range [0, 90].

Parameters

vectorAlist

The first vector (length 2 or 3).

vectorBlist

The second vector (length 2 or 3).

mantissaint, optional

The length of the desired mantissa. Default is 6.

bracketbool, optional

If set to True, the returned angle is bracketed between 0 and 90. Default is False.

Returns

float

The angle in degrees between the two input vectors.

static Average(vectors: list)

Returns the average vector of the input vectors.

Parameters

vectorslist

The input list of vectors.

Returns

list

The average vector of the input list of vectors.

static AzimuthAltitude(vector, mantissa: int = 6)

Returns a dictionary of azimuth and altitude angles in degrees for the input vector. North is assumed to be the positive Y axis [0, 1, 0]. Up is assumed to be the positive Z axis [0, 0, 1]. Azimuth is calculated in a counter-clockwise fashion from North where 0 is North, 90 is East, 180 is South, and 270 is West. Altitude is calculated in a counter-clockwise fashion where -90 is straight down (negative Z axis), 0 is in the XY plane, and 90 is straight up (positive Z axis). If the altitude is -90 or 90, the azimuth is assumed to be 0.

Parameters

vectorAlist

The input vector.

mantissaint, optional

The length of the desired mantissa. Default is 6.

Returns

dict

The dictionary containing the azimuth and altitude angles in degrees. The keys in the dictionary are ‘azimuth’ and ‘altitude’.

static Bisect(vectorA, vectorB)

Compute the bisecting vector of two input vectors.

Parameters

vectorAlist

The first input vector.

vectorBlist

The second input vector.

Returns

dict

The bisecting vector.

static ByAzimuthAltitude(azimuth: float, altitude: float, north: float = 0, reverse: bool = False, mantissa: int = 6, tolerance: float = 0.0001)

Returns the vector specified by the input azimuth and altitude angles.

Parameters

azimuthfloat

The input azimuth angle in degrees. The angle is computed in an anti-clockwise fashion. 0 is considered North, 90 East, 180 is South, 270 is West

altitudefloat

The input altitude angle in degrees from the XY plane. Positive is above the XY plane. Negative is below the XY plane

northfloat , optional

The angle of the north direction in degrees measured from positive Y-axis. The angle is added in anti-clockwise fashion. 0 is considered along the positive Y-axis, 90 is along the positive X-axis, 180 is along the negative Y-axis, and 270 along the negative Y-axis.

reversebool , optional

If set to True the direction of the vector is computed from the end point towards the origin. Otherwise, it is computed from the origin towards the end point.

mantissaint , optional

The desired mantissa. Default is 6.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

list

The resulting vector.

static ByCoordinates(x, y, z)

Creates a vector by the specified x, y, z inputs.

Parameters

xfloat

The X coordinate.

yfloat

The Y coordinate.

zfloat

The Z coodinate.

Returns

list

The created vector.

static ByVertices(*vertices, normalize: bool = True, mantissa: int = 6, silent: bool = False)

Creates a vector by the specified input list of vertices.

Parameters

*verticeslist

The the input list of topologic vertices. The first element in the list is considered the start vertex. The last element in the list is considered the end vertex.

normalizebool , optional

If set to True, the resulting vector is normalized (i.e. its length is set to 1)

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

Returns

list

The created vector.

static CompassAngle(vectorA, vectorB, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the horizontal compass angle in degrees between the two input vectors. The angle is measured in clockwise fashion. 0 is along the positive Y-axis, 90 is along the positive X axis. Only the first two elements in the input vectors are considered.

Parameters

vectorAlist

The first vector.

vectorBlist

The second vector.

mantissaint, optional

The length of the desired mantissa. Default is 6.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

float

The horizontal compass angle in degrees between the two input vectors.

static CompassDirection(vector, tolerance: float = 0.0001, silent: bool = False)

Returns the compass direction of the input direction. The possible returned values are: - North, East, South, West - Northeast, Southeast, Southwest, Northwest - A combination of the above (e.g. Up_Noertheast) - Up, Down - Origin

Parameters

vectorlist

The input vector.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

str

The compass direction of the input vector. The possible values are: - North, East, South, West - Northeast, Southeast, Southwest, Northwest - A combination of the above (e.g. Up_Noertheast) - Up, Down - Origin

static CompassDirections()

Returns the list of allowed compass directions.

Parameters

Returns

list

The list of compass directions. These are: - [“Origin”, “Up”, “Down”,

“North”, “Northeast”, “East”, “Southeast”, “South”, “Southwest”, “West”, “Northwest”, “Up_North”, “Up_Northeast”, “Up_East”, “Up_Southeast”, “Up_South”, “Up_Southwest”, “Up_West”, “Up_Northwest”,

“Down_North”, “Down_Northeast”, “Down_East”, “Down_Southeast”, “Down_South”, “Down_Southwest”, “Down_West”, “Down_Northwest”,

]

static Coordinates(vector, outputType='xyz', mantissa: int = 6, silent: bool = False)

Returns the coordinates of the input vector.

Parameters

vectorlist

The input vector.

outputTypestring, optional

The desired output type. Could be any permutation or substring of “xyz” or the string “matrix”. Default is “xyz”. The input is case insensitive and the coordinates will be returned in the specified order.

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

The coordinates of the input vertex.

static Cross(vectorA, vectorB, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the cross product of the two input vectors. The resulting vector is perpendicular to the plane defined by the two input vectors.

Parameters

vectorAlist

The first vector.

vectorBlist

The second vector.

mantissaint, optional

The length of the desired mantissa. Default is 6.

tolerancefloat, optional

the desired tolerance. Default is 0.0001.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

The vector representing the cross product of the two input vectors.

static Dot(vectorA, vectorB, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Returns the dot product of the two input vectors which is a measure of how much they are aligned.

Parameters

vectorAlist

The first vector.

vectorBlist

The second vector.

mantissaint, optional

The length of the desired mantissa. Default is 6.

tolerancefloat, optional

the desired tolerance. Default is 0.0001.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

The vector representing the cross product of the two input vectors.

static Down()

Returns the vector representing the down direction. In Topologic, the negative ZAxis direction is considered down ([0, 0, -1]).

Returns

list

The vector representing the down direction.

static East()

Returns the vector representing the east direction. In Topologic, the positive XAxis direction is considered east ([1, 0, 0]).

Returns

list

The vector representing the east direction.

static IsAntiParallel(vectorA, vectorB)

Returns True if the input vectors are anti-parallel. Returns False otherwise.

Parameters

vectorAlist

The first input vector.

vectorBlist

The second input vector.

Returns

bool

True if the input vectors are anti-parallel. False otherwise.

static IsCollinear(vectorA, vectorB, tolerance=0.0001)

Returns True if the input vectors are collinear (parallel or anti-parallel) within a given tolerance. Returns False otherwise.

Parameters

vectorAlist

The first input vector.

vectorBlist

The second input vector.

tolerancefloat, optional

The desired tolerance for determining collinearity. Default is 0.0001.

Returns

bool

True if the input vectors are collinear (parallel or anti-parallel). False otherwise.

static IsParallel(vectorA, vectorB, tolerance=0.0001)

Returns True if the input vectors are parallel within a given tolerance. Returns False otherwise.

Parameters

vectorAlist

The first input vector.

vectorBlist

The second input vector.

tolerancefloat, optional

The desired tolerance for determining parallelism. Default is 0.0001.

Returns

bool

True if the input vectors are parallel. False otherwise.

static IsSame(vectorA, vectorB, tolerance=0.0001)

Returns True if the input vectors are the same. Returns False otherwise.

Parameters

vectorAlist

The first input vector.

vectorBlist

The second input vector.

tolerancefloat , optional

The desired tolerance. Default is 0.0001.

Returns

bool

True if the input vectors are the same. False otherwise.

static Length(vector, mantissa: int = 6)

Returns the length of the input vector.

Parameters

vectorlist

The input vector.

mantissaint

The length of the desired mantissa. Default is 6.

Returns

float

The length of the input vector.

static Magnitude(vector, mantissa: int = 6)

Returns the magnitude of the input vector.

Parameters

vectorlist

The input vector.

mantissaint

The length of the desired mantissa. Default is 6.

Returns

float

The magnitude of the input vector.

static Multiply(vector, magnitude, tolerance=0.0001)

Multiplies the input vector by the input magnitude.

Parameters

vectorlist

The input vector.

magnitudefloat

The input magnitude.

tolerancefloat, optional

the desired tolerance. Default is 0.0001.

Returns

list

The created vector that multiplies the input vector by the input magnitude.

static Normalize(vector)

Returns a normalized vector of the input vector. A normalized vector has the same direction as the input vector, but its magnitude is 1.

Parameters

vectorlist

The input vector.

Returns

list

The normalized vector.

static North()

Returns the vector representing the north direction. In Topologic, the positive YAxis direction is considered north ([0, 1, 0]).

Returns

list

The vector representing the north direction.

static NorthEast()

Returns the vector representing the northeast direction. In Topologic, the positive YAxis direction is considered north and the positive XAxis direction is considered east. Therefore northeast is ([1, 1, 0]).

Returns

list

The vector representing the northeast direction.

static NorthWest()

Returns the vector representing the northwest direction. In Topologic, the positive YAxis direction is considered north and the negative XAxis direction is considered west. Therefore northwest is ([-1, 1, 0]).

Returns

list

The vector representing the northwest direction.

static Quadrance(vector, mantissa: int = 6)

Returns the quadrance of the input vector.

Quadrance is the rational trigonometry equivalent of vector magnitude and is defined as the sum of squares of the vector components.

Parameters

vectorlist

The input vector.

mantissaint

The length of the desired mantissa. Default is 6.

Returns

float

The quadrance of the input vector.

static Reverse(vector)

Returns a reverse vector of the input vector. A reverse vector multiplies all components by -1.

Parameters

vectorlist

The input vector.

Returns

list

The normalized vector.

static SetMagnitude(vector: list, magnitude: float) → list

Sets the magnitude of the input vector to the input magnitude.

Parameters

vectorlist

The input vector.

magnitudefloat

The desired magnitude.

Returns

list

The created vector.

static South()

Returns the vector representing the south direction. In Topologic, the negative YAxis direction is considered south ([0, -1, 0]).

Returns

list

The vector representing the south direction.

static SouthEast()

Returns the vector representing the southeast direction. In Topologic, the negative YAxis direction is considered south and the positive XAxis direction is considered east. Therefore southeast is ([1, -1, 0]).

Returns

list

The vector representing the southeast direction.

static SouthWest()

Returns the vector representing the southwest direction. In Topologic, the negative YAxis direction is considered south and the negative XAxis direction is considered west. Therefore southwest is ([-1, -1, 0]).

Returns

list

The vector representing the southwest direction.

static Spread(vectorA, vectorB, mantissa: int = 6, bracket: bool = False) → float

Returns the spread between the two input vectors.

Spread is the rational trigonometry equivalent of angle and is defined as:

spread = sin^2(theta)

Properties - spread = 0 : vectors are parallel - spread = 1 : vectors are perpendicular - 0 <= spread <= 1 - No trigonometric functions are used

Parameters

vectorAlist

The first input vector (length 2 or 3).

vectorBlist

The second input vector (length 2 or 3).

mantissaint , optional

The number of decimal places to round the result to. Default is 6.

bracketbool

If set to True, the spread is bracketed to represent the acute case (i.e. invariant under vector reversal). Default is False.

Returns

float

The spread between the two input vectors.

static Subtract(vectorA, vectorB)

Subtracts the second input vector from the first input vector.

Parameters

vectorAlist

The first vector.

vectorBlist

The second vector.

Returns

list

The vector resulting from subtracting the second input vector from the first input vector.

static Sum(vectors: list)

Returns the sum vector of the input vectors.

Parameters

vectorslist

The input list of vectors.

Returns

list

The sum vector of the input list of vectors.

static TransformationMatrix(vectorA, vectorB)

Returns the transformation matrix needed to align vectorA with vectorB.

Parameters

vectorAlist

The input vector to be transformed.

vectorBlist

The desired vector with which to align vectorA.

Returns

list

Transformation matrix that follows the Blender software convention (nested list)

static Up()

Returns the vector representing the up direction. In Topologic, the positive ZAxis direction is considered “up” ([0, 0, 1]).

Returns

list

The vector representing the “up” direction.

static West()

Returns the vector representing the west direction. In Topologic, the negative XAxis direction is considered west ([-1, 0, 0]).

Returns

list

The vector representing the west direction.

static XAxis()

Returns the vector representing the XAxis ([1, 0, 0])

Returns

list

The vector representing the XAxis.

static YAxis()

Returns the vector representing the YAxis ([0, 1, 0])

Returns

list

The vector representing the YAxis.

static ZAxis()

Returns the vector representing the ZAxis ([0, 0, 1])

Returns

list

The vector representing the ZAxis.