Skip to content

Home

Jump to bottom
shBLOCK edited this page Dec 2, 2023 · 11 revisions

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
Clone this wiki locally