# Py5Vector#

Class to describe a 2D, 3D, or 4D vector.

## Examples#

```import numpy as np

v1 = py5.Py5Vector(1, 2, 3)
print(v1)
# Py5Vector3D(1., 2., 3.)

v2 = py5.Py5Vector(dim=4)
print(v2)
# Py5Vector4D(0., 0., 0., 0.)

v3 = py5.Py5Vector(1 / 3, 1 / 7, dtype=np.float16)
print(v3)
# Py5Vector2D(0.3333, 0.1428)

v4 = py5.Py5Vector([1, 2, 3])
print(v4)
# Py5Vector3D(1., 2., 3.)

v5 = py5.Py5Vector(v4, 0)
print(v5)
# Py5Vector4D(1., 2., 3., 0.)

arr = np.array([1., 2., 3.])
v6 = py5.Py5Vector(arr, copy=False)
print(v6)
# Py5Vector3D(1., 2., 3.)
```

## Description#

Class to describe a 2D, 3D, or 4D vector. A vector is an entity that has both a magnitude and a direction. This datatype stores the components of the vector as a set of coordinates. A 3D vector, for example, has Py5Vector.x, Py5Vector.y, and Py5Vector.z values that quantify the vector along the 3 dimensions X, Y, and Z. The magnitude and direction can be accessed via the properties Py5Vector.mag and Py5Vector.heading.

In many of the py5 examples, you will see `Py5Vector` used to describe a position, velocity, or acceleration. For example, if you consider a rectangle moving across the screen, at any given instant it has a position (a vector that points from the origin to its location), a velocity (the rate at which the object’s position changes per time unit, expressed as a vector), and acceleration (the rate at which the object’s velocity changes per time unit, expressed as a vector).

The `Py5Vector` class works well with numpy and in most cases you will be able to do math operations that combine vectors and numpy arrays.

To create a vector, you can write code like `v = Py5Vector(1, 2, 3)`, which would create a 3D vector with the x, y, and z values equal to 1, 2, and 3. To create a vector of zeros, omit the vector values and specify the desired dimension with the `dim` parameter, such as `v = Py5Vector(dim=4)`.

Internally, Py5Vector stores the vector values in a numpy array. By default, the data type (dtype) of that numpy array is the default float size for your computer, which is typically a 64 bit float, or `np.float64`. To create a vector with a different float size, pass your desired numpy float dtype to the `dtype` parameter, like `v3 = py5.Py5Vector(1 / 3, 1 / 7, dtype=np.float16)`.

When creating a new Py5Vector, the initial vector values need not be discrete values. You can provide a list of numbers, a numpy array, or another Py5Vector. For example, `v4 = py5.Py5Vector([1, 2, 3])` creates a Py5Vector from a list, and `v5 = py5.Py5Vector(v4, 0)` creates a 4D Py5Vector from a 3D Py5Vector and a constant value.

When creating a new Py5Vector from a single numpy array, py5 will by default create its own copy of the numpy array for the Py5Vector to use. To instruct py5 to instead use the same numpy array and share its data with provided array, set the `copy` parameter to `False`, such as `v6 = py5.Py5Vector(arr, copy=False)`.

The following methods and fields are provided:

• angle_between(): Measure the angle between two vectors.

• astype(): Create a new Py5Vector instance with a specified numpy dtype.

• copy: Create an identical copy of this Py5Vector instance.

• cross(): Calculate the vector cross product of two 3D vectors.

• data: Numpy array used to store the vector’s data values.

• dim: The vector’s dimension.

• dist(): Calculate the distance between two vectors.

• dot(): Calculate the dot product between two vectors.

• dtype: Vector data type.

• lerp(): Calculates a vector between two vectors at a specific increment.

• mag: The vector’s magnitude.

• mag_sq: The square of the vector’s magnitude.

• norm: Normalized copy of the vector.

• normalize(): Normalize the vector by setting the vector’s magnitude to 1.0.

• random(): Create a new vector with random values.

• rotate(): Rotate vector by a specified angle.

• rotate_around(): Rotate around an arbitrary 3D vector.

• set_limit(): Constrain the vector’s magnitude to a specified value.

• set_mag(): Set the vector’s magnitude.

• set_mag_sq(): Set the vector’s squared magnitude.

• tolist(): Return the vector’s values as a list.

• w: The vector’s w dimension value.

• x: The vector’s x dimension value.

• y: The vector’s y dimension value.

• z: The vector’s z dimension value.

Updated on September 01, 2022 16:36:02pm UTC