A 2dimensional vector class designed to be convenient
Project description
vec
A reasonable, performant 2D vector object for games
Copyright 20192023 by Larry Hastings
Overview
vec
is a module currently publishing one class: Vector2
, a 2D
vector object designed for game development.
Features:
Vector2
objects are immutable.Vector2
support all the usual vector object features, including operator overloading. Attributes of
Vector2
objects are lazilycomputed 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 four PyWeek gaming challenges. And twice, midweek, 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 immutableit just makes sense from an API perspective. What if you set the position of some gameengine pawn to be a particular vector object, then modify that vector object? Should the pawn update its position automaticallyand if so, how would it 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 inand translate back and forthis
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 designit 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 secondclass 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's Vector2
avoids all these problems:
Vector2
objects are immutable, they make polar and cartesian coordinates both firstclass citizens, and
 they strictly use radians for polar coordinates.
The Conceptual Model
Vector2
objects conceptually represent a vector. They can be
defined using either cartesian or polar coordinates, and any Vector2
can be queried for both its cartesian and polar coordinates.
Most vector objects in games are defined using cartesian coordinates.
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:
Vector2(0, 1)
Vector2(x=0, y=1)
Vector2((0, 1))
Vector2([0, 1])
Vector2(iter([0, 1]))
Vector2({'x':0, 'y':1})
Vector2(types.SimpleNamespace(x=0, y=1))
All these define the same vector. That last example is there to demonstrate
that Vector2
can create a vector based on any object with x
and y
attributes.
Every Vector2
object supports both cartesian and polar coordinates.
You can define a Vector2
using cartesian coordinates, then examine
its polar coordinates. This:
v = vec.Vector2(0, 1)
print(v.theta, v.r)
prints 1.5707963267948966 1.0
. That first number is π/2 (approximately).
Conversely, you can define a Vector2
object using polar
coordinates, then examine its cartesian coordinates:
v2 = vec.Vector2(r=1, theta=math.pi/2)
print(v2.x, v2.y)
This prints 6.123233995736766e17 1.0
. Conceptually this should
print 0.0, 1.0
but math.pi
is only an approximation, which sadly
means our result has an infinitesimal error.
Implementation Details
To define a valid Vector2
object, you must have a complete
set of either cartesian or polar coordinateseither is sufficient.
All other attributes will be lazily computed on demand.
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 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 Vector2
objects compute their result
using the cheapest approach. If you have a 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 computedand 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! Vector2
takes advantage of many such serendipities,
performing your vector math as cheaply and accurately as possible.
The API
Vector2(x=None, y=None, *, r=None, theta=None, r_squared=None)

Constructs a `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
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.
Vector2
only does some validation of its arguments. It ensures thatr
andtheta
are normalized. However, it doesn't check that(x, y)
and(r, theta)
describe the same vector. If you pass inx
andy
, and also pass in atheta
andr
that don't match, you'll get back theVector2
that you asked for. Good luck!  an existing
Attributes
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 if you have
a Vector2
object defined with cartesian coordinates,
it's much cheaper to compute r_squared
than r
.
And there are many use cases where r_squared
works
just as well as r
.
For example, consider collision detection in a game. One way to decide whether two objects are colliding is to measure the distance between themif it's less than a certain distance R, the two objects are colliding. But computing the actual distance is expensiveit requires a timeconsuming square root. It's much cheaper to compute the distancesquared between the two points. If that's less than R^{2}, the two objects are colliding.
Operators and protocols
Vector2
objects support the iterator protocol.
len()
on a Vector2
object will always return 2.
You can also iterate over a Vector2
object,
which will yield the x
and y
attributes in that order.
Vector2
objects support the sequence protocol. You can subscript
them, which behaves as if the Vector2
object is a tuple of length
2 containing the x
and y
attributes.
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
.
Vector2
objects are hashable, but they're not ordered.
(You can't ask if one vector is less than another.)
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 tov1.scale(scalar)
.v1 / scalar
divides the vector by a scalar amount.+v1
is exactly the same asv1
.v1
returns the opposite ofv1
, such thatv1 + (v1)
should be the zero vector. (This may not always be the case due to compounding floatingpoint errors.)v1 == v2
isTrue
if the two vectors are exactly the same, andFalse
otherwise. For consistency, this only compares cartesian coordinates. Note that floatingpoint imprecision may result in two vectors that should be the same failing an==
check. Consider using thealmost_equal
method, which allows for some imprecision in its comparison.v1 != v2
isFalse
if the two vectors are exactly the same, andTrue
otherwise. For consistency, this only compares cartesian coordinates. Note that floatingpoint imprecision may result in two vectors that should be the same passing an!=
check. Again, consider using thealmost_equal
method and negating the results.v[0]
andv.x
evaluate to the same number.v[1]
andv.y
evaluate to the same number.list(v)
is the same as[v.x, v.y]
.
Class methods
vec.from_polar(r, theta)

Constructs a `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
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
is0
,theta
must beNone
, andfrom_polar
will return the zero vector. Ifr
is not0
,theta
must not beNone
.  an existing
Methods
Vector2
objects support the following methods:
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.
Vector2.scaled(scalar)
 Returns a new `Vector2` object, equivalent to the original vector multiplied by that scalar.
Vector2.scaled_to_length(r)
 Returns a new `Vector2` object, equivalent to the original vector with its length set to `r`.
Vector2.normalized()
 Returns a new `Vector2` object, equivalent to the original vector scaled to length 1.
Vector2.rotated(theta)
 Returns a new `Vector2` object, equal to the original vector rotated by `theta` radians.
Vector2.dot(other)
 Returns the "dot product" `self` • `other`. This result is a scalar value, not a vector.
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 2dimensional 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.
Vector2.polar()
 Returns a 2tuple of `(self.r, self.theta)`.
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 between `0` and `1` noninclusive, this returns a point on the line segment
defined by the two endpoints `self` and `other`, with the point being `ratio` between `self`
and `other`. For example, if `ratio` is `0.4`, this returns `(self * 0.6) + (other * 0.4)`.
Note that it's not an error to specify a
ratio
less than0
or greater than1
, andratio
is not clamped to this range.
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`.
Note that it's not an error to specify a
ratio
less than0
or greater than1
, andratio
is not clamped to this range.
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`.
Note that it's not an error to specify a
ratio
less than0
or greater than1
, andratio
is not clamped to this range.
Constants
vector2_zero

The "zero" `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
Mathematicallyspeaking, the zero vector when expressed in polar coordinates doesn't have a defined angle. Therefore
vec
defines its zero vector as having an angle ofNone
. The zero vector must haver
set to zero andtheta
set toNone
, and any other vector must have a nonzeror
andtheta
set to a value besidesNone
.
vector2_1_0

A predefined `Vector2` vector object, equivalent to `Vector2(1, 0)`.
When constructing a `Vector2` object that is exactly equivalent to this
vector, the `Vector2` constructor will always return a reference to this
vector:
>>> v = vec.Vector2(1, 0) >>> v is vec.vector2_1_0 True >>> v2 = vec.Vector2(r=1, theta=0) >>> v2 is vec.vector2_1_0 True
vector2_0_1

A predefined `Vector2` vector object, equivalent to `Vector2(0, 1)`.
When constructing a `Vector2` object that is exactly equivalent to this
vector, the `Vector2` constructor will always return a reference to this
vector:
>>> v = vec.Vector2(0, 1) >>> v is vec.vector2_0_1 True >>> v2 = vec.Vector2(r=1, theta=pi/2) >>> v2 is vec.vector2_0_1 True
vector2_1_1

A predefined `Vector2` vector object, equivalent to `Vector2(1, 1)`.
When constructing a `Vector2` object that is exactly equivalent to this
vector, the `Vector2` constructor will always return a reference to this
vector:
>>> v = vec.Vector2(1, 1) >>> v is vec.vector2_1_1 True >>> v2 = vec.Vector2(r=2 ** 0.5, theta=pi/4) >>> v2 is vec.vector2_1_1 True
Extending vec to handle other types
vec
does some input verification on its inputs.
Coordinatesx
, 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.3 2023/10/26

Added three new predefined vectors:
vector2_1_0
isVector2(1, 0)
vector2_0_1
isVector2(0, 1)
vector2_1_1
isVector2(1, 1)
Any expression that results in a vector that would be exactly equal to one of these vectors is guaranteed to return the predefined vector.
Vector2(1, 0) is vector2_1_0
evaluates toTrue
.
0.6.2 2023/06/14
 Added
Vector2.almost_equal
, which supports testing for slightlyinexact equality.
0.6.1 2023/06/14
 Enhanced the
Vector2
constructor: now it also accepts mappings. The mapping must have exactly two elements,x
andy
.  Enhanced
Vector2.from_polar
. It now accepts all the same stuff as theVector2
constructor:Vector2
objects, namespaces, mappings, and iterables. Where it examines names (attributes, keys) it naturally usesr
andtheta
instead ofx
andy
.
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
Vector2.slerp
, and addedVector2.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 availablethat can make some operations faster.)
 Now cache

Bugfix:
Vector2.dot()
was simply wrong, it was adding where it should have been multiplying. Fixes #3.
0.5 2021/03/21
Initial version.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.