Math Module at a Glance

This page provides a structured overview of the Box2D math classes. The math module is designed with several key principles:

  • Immutable objects: Most classes (Vec2, Rot, Transform, AABB) are immutable - operations return new instances rather than modifying existing ones

  • Vector-like compatibility: Functions accepting vector arguments can take any iterable with 2 floats (tuples, lists, Vec2, etc.)

  • Pythonic interfaces: Classes support Python protocols like operators, iteration, and unpacking

  • Box2D integration: All classes provide seamless conversion to and from Box2D’s native types

Vec2

An immutable 2D vector class representing points and vectors in 2D space. Supports Python unpacking and can be used anywhere a sequence of 2 floats is expected.

Creation

  • Vec2(x, y) - Create a vector with given components

  • Vec2.zero() - Create a zero vector (0,0)

  • Vec2.up() - Unit vector pointing up (0,1)

  • Vec2.down() - Unit vector pointing down (0,-1)

  • Vec2.left() - Unit vector pointing left (-1,0)

  • Vec2.right() - Unit vector pointing right (1,0)

  • Vec2.from_angle(angle) - Create a unit vector from an angle

  • Vec2.from_b2Vec2(b2_vec) - Create from Box2D’s native vector

Properties

  • x, y - Component access

  • as_tuple - Get components as tuple (x, y)

  • length - Get vector magnitude

  • length_squared - Get squared magnitude (faster)

  • angle - Get angle in radians

  • normalized - Get unit vector in same direction

  • inverse - Get vector with negated components (-x, -y)

  • b2Vec2 - Get Box2D’s native vector equivalent

  • is_finite - Check if vector has finite components

Vector Operations

  • v1 + v2 - Vector addition

  • v1 - v2 - Vector subtraction

  • v1 * scalar - Scalar multiplication

  • v1 / scalar - Scalar division

  • -v - Negation

  • x, y = vec - Unpacking into components

  • tuple(vec) - Convert to tuple

  • list(vec) - Convert to list

  • normalize() - Normalize vector in-place

  • dot(other) - Dot product

  • cross(other) - Cross product (scalar result)

  • cross_scalar(s, direction) - Cross product with scalar

  • perpendicular(direction) - Get perpendicular vector

  • rotate(angle) - Rotate vector by angle

  • lerp(other, t) - Linear interpolation

  • project(other) - Project onto another vector

  • reject(other) - Reject component from another vector

  • distance_to(other) - Distance between vectors

Utility Methods

  • is_close(other, tolerance) - Check if vectors are close

  • min(other) - Component-wise minimum

  • max(other) - Component-wise maximum

  • clamp(min_value, max_value) - Clamp components to range

  • multiply_componentwise(other) - Component-wise multiplication

Rot

Immutable representation of 2D rotation using sine/cosine components for efficient calculations. All rotation operations create new instances rather than modifying existing ones.

Creation

  • Rot(angle) - Create from angle in radians

  • Rot.identity() - Create identity (zero) rotation

  • Rot.zero() - Alias for identity

  • Rot.from_degrees(degrees) - Create from angle in degrees

  • Rot.from_sincos(s, c) - Create from sine and cosine values

  • Rot.from_b2Rot(b2_rot) - Create from Box2D’s native rotation

Properties

  • s, c - Sine and cosine components

  • angle - Rotation angle in radians

  • angle_radians - Alias for angle

  • angle_degrees - Rotation angle in degrees

  • as_tuple - Get components as tuple (s, c)

  • b2Rot - Get Box2D’s native rotation equivalent

  • x_axis - Get rotated X axis as Vec2

  • y_axis - Get rotated Y axis as Vec2

  • inverse - Get inverse rotation

Rotation Operations

  • r1 * r2 - Compose rotations

  • r * v - Rotate vector

  • rotate_vector(v) - Rotate vector (alternative syntax)

  • normalize() - Normalize rotation components

  • interpolate(other, t, ccw) - Interpolate between rotations

Transform

Immutable transformation combining position and rotation. Performs rotation followed by translation when applied to points.

Creation

  • Transform(position, rotation) - Create with position and rotation (accepts any vector-like object and angle/Rot)

  • Transform.from_b2Transform(b2_transform) - Create from Box2D’s native transform

Properties

  • position - Translation vector (Vec2)

  • rotation - Rotation component (Rot)

  • inverse - Get inverse transformation

  • b2Transform - Get Box2D’s native transform equivalent

Operations

  • t(point) - Apply transform to point (calling the transform)

  • t * point - Apply transform to point (multiplication syntax)

  • t1 * t2 - Compose transforms

ScaledTransform

Extended transform with scaling support, primarily for visualization purposes. Applies transformations in the order: Scale → Rotate → Translate.

Creation

  • ScaledTransform(position, rotation, scale) - Create with position, rotation and scale

  • ScaledTransform.from_transform(transform, scale) - Create from Transform and scale

Properties

  • position - Translation vector

  • rotation - Rotation component

  • scale - Scale vector (x and y scale)

  • inverse - Get inverse transformation

Operations

  • st(point) - Apply scaled transform to point (calling the transform)

  • st * point - Apply scaled transform to point (multiplication syntax)

Mat22

A 2x2 matrix for linear transformations. Used for rotations, scaling, and linear systems.

Creation

  • Mat22(*args) - Create from components

  • Mat22.identity() - Create identity matrix

  • Mat22.from_angle(angle) - Create rotation matrix

  • Mat22.from_columns(col1, col2) - Create from column vectors

  • Mat22.from_rows(row1, row2) - Create from row vectors

  • Mat22.from_b2Mat22(b2_mat22) - Create from Box2D’s native matrix

Properties

  • columns - Get column vectors tuple

  • rows - Get row vectors tuple

  • determinant - Get matrix determinant

  • inverse - Get inverse matrix

  • b2Mat22 - Get Box2D’s native matrix equivalent

Operations

  • m * v - Apply matrix to vector

  • m1 * m2 - Matrix multiplication

  • transpose() - Get transposed matrix

  • solve(b) - Solve linear system A*x = b

AABB

Immutable Axis-Aligned Bounding Box for collision detection and spatial queries. Used extensively in the physics engine for broadphase collision detection.

Creation

  • AABB(lower, upper) - Create with lower and upper bounds (accepts any vector-like objects)

  • AABB.from_points(points) - Create from collection of points

  • AABB.from_b2AABB(b2_aabb) - Create from Box2D’s native AABB

Properties

  • lower - Lower bound (minimum point)

  • upper - Upper bound (maximum point)

  • center - Center point

  • half_size - Half dimensions

  • width - Width (x-span)

  • height - Height (y-span)

  • is_valid - Check if upper ≥ lower

  • b2AABB - Get Box2D’s native AABB equivalent

Operations

  • contains(other) - Check if contains AABB or point

  • overlaps(other) - Check if overlaps with another AABB

  • merge(other) - Create union with AABB or point

  • expanded(margin) - Create expanded/contracted AABB

  • translated(offset) - Create translated AABB