vec

A reasonable, performant 2D vector object for games

Copyright 2019-2023 by Larry Hastings

Overview

vec is a module currently containing one class: Vector2, a 2D vector object designed for game development.

Features:

• Vector2 objects are immutable.
• Vector2 support all the usual features, including operator overloading.
• Attributes of Vector2 objects are lazily-computed where possible.
• Vector2 objects effortlessly support both cartesian and polar coordinates.

vec supports Python 3.6+, and passes its unit test suite with 100% coverage.

Why Another Vector Class?

I've participated in three PyWeek gaming challenges. In two of those three times, mid-week I wrote my own vector class out of sheer frustration.

The biggest problem with most Python vector objects in is that they're mutable. Frankly this way lies madness. Vector objects should be immutable--it just makes sense from an API perspective. What if you set the position of some game-engine pawn to be a particular vector object, then modify that vector object? Should the pawn update its position automatically--and if so, how is it supposed to know the value changed?

Similarly, some vector classes use degrees for polar coordinates instead of radians. Again this way lies madness. The trigonometric functions in Python's math module operate in the radians domain, and having to keep track of which domain something is in--and translate back and forth--is a needless conceptual complication. You've got a game to write!

(Some vector classes support both radians and degrees for polar coordinates. This is simply bad API design--it doubles the surface area of your API, adding needless complexity and increasing maintenance and testing overhead. Embrace the radian, folks.)

On a related note, many vector classes make polar coordinates second-class citizens. Most vector classes only store vectors in cartesian coordinates, so either the programmer must perform all polar operations externally to the vector objects, or they incur the overhead and cumulative error of translating to polar and back again with every operation.

vec.Vector2 avoids all these problems:

• vec.Vector2 objects are immutable,
• they support vectors defined with either polar or cartesian coordinates, and
• they strictly use radians for polar coordinates.

The Conceptual Model

vec.Vector2 objects conceptually represent a vector. They can be defined using either cartesian or polar coordinates, and any vec.Vector2 can be queried for both its cartesian and polar coordinates.

Most vector objects in games are defined using cartesian coordinates. vec.Vector2 makes that easy, supporting any number of invocations to create one. Discrete parameters, iterables, and objects that support x and y attributes all work fine:

vec.Vector2(0, 1)
vec.Vector2(x=0, y=1)
vec.Vector2((0, 1))
vec.Vector2([0, 1])
vec.Vector2(iter([0, 1]))
vec.Vector2({'x':0, 'y':1})
vec.Vector2(types.SimpleNamespace(x=0, y=1))

All these define the same vector. That last example is there to demonstrate that vec.Vector2 can create a vector based on any object with x and y attributes.

Once you have a vector object, you can examine its attributes. Every vec.Vector2 object can be queried for both cartesian and polar coordinates:

v = vec.Vector2(0, 1)
print(v.theta, v.r)

prints 1.5707963267948966 1.0. That first number is π/2 (approximately).

Conversely, you can also define vec.Vector2 objects using polar coordinates, and then ask it for its cartesian coordinates:

v2 = vec.Vector2(r=1, theta=1.5707963267948966)
print(v2.x, v2.y)

This prints 6.123233995736766e-17 1.0. Conceptually this should print 0.0, 1.0--but math.pi is only an approximation, which means, sadly, that our result has an infinitesimal error.

Implementation Details

Internally vec.Vector2 objects are either "cartesian", "polar", or both. "cartesian" vector objects are defined in terms of x and y; "polar" vector objects are defined in terms of r and theta. All other attributes are lazily computed as needed.

vec.Vector2 objects use slots, and rely on __getattr__ to implement this lazy computation. Only the known values of the vector are set when it's created. If the user refers to an attribute that hasn't been computed yet, Python will call vec.Vector2.__getattr__(), which computes, caches, and returns that value. Future references to that attribute skip this mechanism and simply return the cached value, which is only as expensive as an attribute lookup on a conventional object.

Operations on vec.Vector2 objects compute their result using the cheapest approach. If you have a vec.Vector2 object defined using polar coordinates, and you call .rotate() or .scale() on it, all the math is done in the polar domain. On the other hand, adding vectors is almost always done in the cartesian domain, so if you add a polar vector to any other vector, its cartesian coordinates will likely be computed--and the resulting vector will always be defined using cartesian coordinates.

What's the exception? There's a special case for adding two polar vectors which have the exact same theta: just add their r values. That approach is much cheaper than converting to cartesian, and more precise as well, returning a vector defined using polar coordinates! vec.Vector2 takes advantage of many such serendipities, computing your vectors as cheaply and accurately as possible.

The API

vec.Vector2(x=None, y=None, *, r=None, theta=None, r_squared=None)

Constructs a vec.Vector2 object. You may pass in as many or as few of these arguments as you like; however, you must pass in either both x and y or both r and theta. Any attributes not passed in at construction time will be lazily computed at the time they are evaluated.

You can also pass in a single object which will initialize the vector. Supported objects include:

• an existing vec.Vector2 object (just returns that object),
• an object which has .x and .y attributes,
• a mapping object with exactly two keys, 'x' and 'y', and
• an ordered iterable object with exactly two elements.

vec.Vector2 only does some validation of its arguments. It ensures that r and theta are normalized. However, it doesn't check that (x, y) and (r, theta) describe the same vector. If you pass in x and y, and also pass in a theta and r that don't match, you'll get back the vec.Vector2 that you asked for. Good luck!

Attributes

vec.Vector2 objects support five attributes: x, y, r, theta, and r_squared. It doesn't matter whether the object was defined with cartesian or polar coordinates, they'll all work.

r_squared is equivalent to r*r, but it's much cheaper to compute based on cartesian coordinates. There are a lot of use cases where r_squared works just as well as r, for example in collision detection in a game.

Operators and protocols

vec.Vector2 objects support the iterator protocol. len() on a vec.Vector2 object will always return 2. You can also iterate over a vec.Vector2 object, which will yield the x and y attributes in that order.

vec.Vector2 objects support the sequence protocol. You can subscript them, which behaves as if the vec.Vector2 object is a tuple of length 2 containing the x and y attributes.

vec.Vector2 objects also support the boolean protocol; you may use them with boolean operators, and you may call bool() on them. When used in a boolean context, the zero vector evaluates to False, and all other vectors evaluate to True.

vec.Vector2 objects are hashable, but they're not ordered. (You can't ask if one vector is less than another.)

vec.Vector2 objects support the following operators:

• v1 + v2 adds the two vectors together.
• v1 - v2 subtracts the right vector from the left vector.
• v1 * scalar mulitplies the vector by a scalar amount, equivalent to v1.scale(scalar).
• v1 / scalar divides the vector by a scalar amount.
• +v1 is exactly the same as v1.
• -v1 returns the opposite of v1, such that v1 + (-v1) should be the zero vector. (This may not always be the case due to compounding floating-point errors.)
• v1 == v2 is True if the two vectors are exactly the same, and False otherwise. For consistency, this only compares cartesian coordinates. Note that floating-point imprecision may result in two vectors that should be the same failing an == check.
• v1 != v2 is False if the two vectors are exactly the same, and True otherwise. For consistency, this only compares cartesian coordinates. Note that floating-point imprecision may result in two vectors that should be the same passing an != check.
• v[0] == v.x
• v[1] == v.y
• list(v) == [v.x, v.y]

Class methods

vec.from_polar(r, theta)

Constructs a vec.Vector2 object from the two polar coordinates r and theta.

You can also pass in a single object which will be used to initialize the vector. Supported objects include:

• an existing vec.Vector2 object (just returns that object),
• an object which has .r and .theta attributes,
• a mapping object with exactly two keys, 'r' and 'theta', and
• an ordered iterable object with exactly two elements.

If r is 0, theta must be None, and from_polar will return the zero vector. If r is not 0, theta must not be None.

Methods

vec.Vector2 objects support the following methods:

vec.Vector2.almost_equal(other, places)

Returns True if the vector and other are the same vector, down to places decimal places. Like the Vector2 class's support for the == operator, the comparison is only done using cartesian coordinates, for consistency.

vec.Vector2.scaled(scalar)

Returns a new vec.Vector2 object, equivalent to the original vector multiplied by that scalar.

vec.Vector2.scaled_to_length(r)

Returns a new vec.Vector2 object, equivalent to the original vector with its length set to r.

vec.Vector2.normalized()

Returns a new vec.Vector2 object, equivalent to the original vector scaled to length 1.

vec.Vector2.rotated(theta)

Returns a new vec.Vector2 object, equal to the original vector rotated by theta radians.

vec.Vector2.dot(other)

Returns the "dot product" self • other. This result is a scalar value, not a vector.

vec.Vector2.cross(other)

Returns the "cross product" self ⨯ other. This result is a scalar value, not a vector.

Note: technically, there is no "cross product" defined for 2-dimensional vectors. In actuality this returns the "perpendicular dot product", or "perp dot product", of the two vectors, because that's what people actually want when they ask for the "cross product" of two 2D vectors.

vec.Vector2.polar()

Returns a 2-tuple of (self.r, self.theta).

vec.Vector2.lerp(other, ratio)

Returns a vector representing a linear interpolation between self and other, according to the scalar ratio ratio. ratio should be a value between (and including) 0 and 1. If ratio is 0, this returns self. If ratio is 1, this returns other. If ratio is 0.4, this returns (self * 0.6) + (other * 0.4).

vec.Vector2.slerp(other, ratio)

Returns a vector representing a spherical interpolation between self and other, according to the scalar ratio ratio. ratio should be a value between (and including) 0 and 1. If ratio is 0, this returns self. If ratio is 1, this returns other.

vec.Vector2.nlerp(other, ratio)

Returns a vector representing a normalized linear interpolation between self and other, according to the scalar ratio ratio. ratio should be a value between (and including) 0 and 1. If ratio is 0, this returns self. If ratio is 1, this returns other.

Constants

vec.vector2_zero

The immutable, eternal "zero" vec.Vector2 vector object. vec guarantees that every zero vector is a reference to this object:

>>> v = vec.Vector2(0, 0)
>>> v is vec.vector2_zero
True

Mathematically-speaking, the zero vector when expressed in polar coordinates doesn't have a defined angle. Therefore vec defines its zero vector as having an angle of None. The zero vector must have r set to zero and theta set to None, and any other vector must have a non-zero r and theta set to a value besides None.

Extending vec to handle other types

vec does some input verification on its inputs. Coordinates--x, y, r, theta--are required to be either int or long. (Technically theta can also be None.) This best serves the intended use case of vec as a 2D vector library for game programming in Python.

If you want to experiment with vec for other use cases, you may want vec to permit other types to be valid coordinates. vec provides a simple mechanism to allow this. Simply call:

    vec.permit_coordinate_type(T)

before creating your vector, passing in the type you want to use as a coordinate as T, and vec will now accept objects of that type as coordinates.

Note that the types you extend vec with in this manner should behave like numeric types, like int and float.

Changelog

0.6.2 2023/06/14

• Added Vector2.almost_equal, which supports testing for slightly-inexact equality.

0.6.1 2023/06/14

• Enhanced the Vector2 constructor: now it also accepts mappings. The mapping must have exactly two elements, x and y.
• Enhanced Vector2.from_polar. It now accepts all the same stuff as the Vector2 constructor: Vector2 objects, namespaces, mappings, and iterables. Where it examines names (attributes, keys) it naturally uses r and theta instead of x and y.

0.6 2023/06/14

A major improvement!

• vec now has a proper test suite.

• vec now passes its test suite with 100% coverage.

• vec explicitly supports Python 3.6+.

• Added more shortcut optimizations, e.g. rotating a cartesian vector by a multiple of pi/2.

• Tightened up the metaclass __call__ logic a great deal.

• Implemented vec.Vector2.slerp, and added vec.Vector2.nlerp.

• Allowed vec.permit_coordinate_type, to allow extending the set of permissible types for coordinates.

• Internal details:

  • Now cache _cartesian and _hash internally, as well as _polar. (A vector can have a complete set of both cartesian and polar coordinates, so it's nice to know everything that's available--that can make some operations faster.)

• Bugfix: vec.Vector2.dot() was simply wrong, it was adding where it should have been multiplying. Fixes #3.

0.5 2021/03/21

Initial version.