Home

Vectors

Easy-to-use and fast vector classes implemented entirely in Cython.
All vector classes: Vec2 Vec3 Vec4 and integer vectors Vec2i Vec3i Vec4i.
Since the 6 vector classes are mostly similar, Vec3 is used in this section, and methods specific to a class are particularized.

Instantiation

• Vec3(x: float | int, y: float | int, z: float | int) returns Vec3(x, y, z)
• Vec3(value: float | int) returns Vec3(value, value, value)
• Vec3() returns Vec3(0.0, 0.0, 0.0)
• Vec3(vec: Vec3) returns a copy of that vector
• Vec3(vec: Vec3i) converts Vec3i to Vec3
• Any combination of vectors and numbers that has 3 dimensions in total is also supported, however, this doesn't include vector classes of a different data type.
  • Vec3(a: Vec2, b: float | int)
  • Vec3(a: float | int, b: Vec2)

Properties

• x: float y: float z: float
• length: float the length of the vector
• length_sqr: float the squared length of the vector
• normalized: Vec3 the normalized vector
• "Swizzling": any combinations of x y z o l are properties of the vector.
  • These properties return a vector of the length of the property's name.
  • x y z represents the components of this vector.
  • o represents zero and l represents one.
  • Combinations consisting of only constants (o and l) are not included (eg. vec.lol).
  • Examples (Assume that vec = Vec3(2, 3, 4)):
    • vec.zyx gives Vec3(4.0, 3.0, 2.0)
    • vec.zx gives Vec2(4.0, 2.0)
    • vec.xxxx gives Vec4(2.0, 2.0, 2.0, 2.0)
    • vec.xoly gives Vec4(2.0, 0.0, 1.0, 4.0)

Operations

In this section, a and b represent two Vec3s.

• a + b
• a - b
• a * b multiplied each component of a and b together
• a / b divide each component of a by b
• For + - * and /, b can also be a number, in which b is treated as Vec3(b)
• +a returns a copy of a
• -a the inverse vector of a
• a == b a != b check for exact equality
• a.is_close(b, rel_tol=1e-5, abs_tol=1e-14) check for equality with tolerance (similar to math.isclose())
• bool(a) returns True if a is NOT a zero vector, False otherwise
• a @ b the dot product of a and b
• a ^ b the cross product of a and b (Only avaliable in Vec3 and Vec3i)
• len(a) returns the component count of a (NOT its length!!!)
• a.distance_to(b)
• a.distance_sqr_to(b) returns the squared distance between a and b
• a | b same as a.distance_to(b)
• a[i] a[i] = value get and set the ith component of a
• Vectors are iterable: iter(a) returns an internal iterator object

vec = Vec3(1, 2, 3)

for i, value in enumerate(vec):
    print(f"Component {i}: {value}")

x, y, z = vec
print("Unpacking:", x, y, z)

print("Unpacking to params:", *vec)

print("Unpacking to list:", [*vec])

vec = Vec3(1, 2, 2)
print("Unpacking to set:", {*vec})

Output:

Component 0: 1.0
Component 1: 2.0
Component 2: 3.0
Unpacking: 1.0 2.0 3.0
Unpacking params: 1.0 2.0 3.0
Unpacking to list: [1.0, 2.0, 3.0]
Unpacking to set: {1.0, 2.0}

Transform2D

Representing a linear transformation (a 2*3 matrix) in 2D.

Instantiation

• Transform2D() returns an identity transform
• Transform2D(xx: float, xy: float, yx: float, yy: float, ox: float, oy: float)
• Transform2D(x: Vec2, y: Vec2, origin: Vec2) constructs the transform from the 3 columns
• Transform2D(transform: Transform2D) returns a copy of transform
• Transform2D.translating(translation: Vec2) returns a transform representing a translation
• Transform2D.scaling(scale: Vec2, origin: Vec2 = None) returns a transform representing a scaling transformation, and optionally a translation in addition
• Transform2D.rotating(rotation: float, origin: Vec2 = None) returns a transform representing a rotation, and optionally a translation in addition

Properties

• x: Vec2 y: Vec2 origin: Vec2 the columns of the matrix (origin can be seen as the translation)
• determinant returns the determinant of the matrix
• rotation: float
• scale: Vec2

Operations

In this section, a and b represent two Transform2Ds and v to represent a Vec2.

• a @ b a(b) matrix multiplication (b transformed by a)
• a @= b inplace transforms a with b, which is NOT equivalent to a = a @ b! This is to make in place transforming a transform with another more convenient.
• a * v a(v) return v transformed by a
• v * a returns v transformed by the INVERSE of a
• ~a the inverse of a
• a == b a != b check for exact equality
• a.is_close(b, rel_tol=1e-5, abs_tol=1e-14) check for equality with tolerance (similar to math.isclose())
• a[i] a[i] = v gets or sets the ith column of the matrix (0 for x, 1 for y, and 2 for origin)
• len(a) the number of columns (always 3)
• a.translated(translation: Vec2) returns a copy of this transform translated by translation
• a.rotated(rotation: float) returns a copy of this transform rotated by rotation
• a.scaled(scale: Vec2) returns a copy of this transform scaled by scale
• translate_ip rotate_ip and scale_ip as the in-place counterparts of translated rotated and scaled

Transform3D

Representing a linear transformation (a 3*4 matrix) in 3D.

Instantiation

• Transform3D() returns an identity transform
• Transform3D(xx: float, xy: float, xz: float, yx: float, yy: float, yz: float, zx: float, zy: float, zz: float, ox: float, oy: float, oz: float)
• Transform3D(x: Vec3, y: Vec3, z: Vec3, origin: Vec3) constructs the transform from the 4 columns
• Transform3D(transform: Transform3D) returns a copy of transform
• Transform3D.translating(translation: Vec3) returns a transform representing a translation
• Transform3D.scaling(scale: Vec3, origin: Vec3 = None) returns a transform representing a scaling transformation, and optionally a translation in addition
• Transform3D.rotating(axis: Vec3, angle: float, origin: Vec2 = None) returns a transform representing a rotation around axis (axis must be normalized), and optionally a translation in addition

Properties

• x: Vec3 y: Vec3 z: Vec3 origin: Vec3 the columns of the matrix (origin can be seen as the translation)
• determinant returns the determinant of the matrix

Operations

In this section, a and b represent two Transform3Ds and v to represent a Vec3.

• a @ b a(b) matrix multiplication (b transformed by a)
• a @= b inplace transforms a with b, which is NOT equivalent to a = a @ b! This is to make in place transforming a transform with another more convenient.
• a * v a(v) return v transformed by a
• v * a returns v transformed by the INVERSE of a
• ~a the inverse of a
• a == b a != b check for exact equality
• a.is_close(b, rel_tol=1e-5, abs_tol=1e-14) check for equality with tolerance (similar to math.isclose())
• a[i] a[i] = v gets or sets the ith column of the matrix (0 for x, 1 for y, 2 for z, and 3 for origin)
• len(a) the number of columns (always 4)
• a.translated(translation: Vec3) returns a copy of this transform translated by translation
• a.rotated(axis: Vec3, angle: float) returns a copy of this transform rotated by angle around axis (must be normalized)
• a.scaled(scale: Vec3) returns a copy of this transform scaled by scale
• translate_ip rotate_ip and scale_ip as the in-place counterparts of translated rotated and scaled