Goulib.geom module

Inheritance diagram of Goulib.geom

2D geometry

class Goulib.geom.Geometry(*args)[source]

Bases: object

The following classes are available for dealing with simple 2D geometry. The interface to each shape is similar; in particular, the connect and distance methods are defined identically for each.

For example, to find the closest point on a line to a circle:

>>> circ = Circle(Point2(3., 2.), 2.)
>>> line = Line2(Point2(0., 0.), Point2(-1., 1.))
>>> line.connect(circ).p1
Point2(0.50, -0.50)

To find the corresponding closest point on the circle to the line:

>>> line.connect(circ).p2
Point2(1.59, 0.59)

this constructor is called by descendant classes at copy it is replaced to copy some graphics attributes in module drawings

__init__(*args)[source]

this constructor is called by descendant classes at copy it is replaced to copy some graphics attributes in module drawings

point(u)[source]
Returns:Point2 or Point3 at parameter u
tangent(u)[source]
Returns:Vector2 or Vector3 tangent at parameter u
intersect(other)[source]
connect(other)[source]
Returns:Geometry shortest (Segment2 or Segment3) that connects self to other
distance(other)[source]
__contains__(pt)[source]
__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

Goulib.geom.argPair(x, y=None)[source]

Process a pair of values passed in various ways.

class Goulib.geom.Vector2(*args)[source]

Bases: object

Mutable 2D vector:

Construct a vector in the obvious way:

>>> Vector2(1.5, 2.0)
Vector2(1.50, 2.00)

>>> Vector3(1.0, 2.0, 3.0)
Vector3(1.00, 2.00, 3.00)

Element access

Components may be accessed as attributes (examples that follow use Vector3, but all results are similar for Vector2, using only the x and y components):

>>> v = Vector3(1, 2, 3)
>>> v.x
1
>>> v.y
2
>>> v.z
3

Vectors support the list interface via slicing:

>>> v = Vector3(1, 2, 3)
>>> len(v)
3
>>> v[0]
1
>>> v[:]
(1, 2, 3)

You can also “swizzle” the components (a la GLSL or Cg):

>>> v = Vector3(1, 2, 3)
>>> v.xyz
(1, 2, 3)
>>> v.zx
(3, 1)
>>> v.zzzz
(3, 3, 3, 3)

Operators

Addition and subtraction are supported via operator overloading (note that in-place operators perform faster than those that create a new object):

>>> v1 = Vector3(1, 2, 3)
>>> v2 = Vector3(4, 5, 6)
>>> v1 + v2
Vector3(5.00, 7.00, 9.00)
>>> v1 -= v2
>>> v1
Vector3(-3.00, -3.00, -3.00)

Multiplication and division can be performed with a scalar only:

>>> Vector3(1, 2, 3) * 2
Vector3(2.00, 4.00, 6.00)
>>> v1 = Vector3(1., 2., 3.)
>>> v1 /= 2
>>> v1
Vector3(0.50, 1.00, 1.50)

The magnitude of a vector can be found with abs:

>>> v = Vector3(1., 2., 3.)
>>> abs(v)
3.7416573867739413

A vector can be normalized in-place (note that the in-place method also returns self, so you can chain it with further operators):

>>> v = Vector3(1., 2., 3.)
>>> v.normalize()
Vector3(0.27, 0.53, 0.80)
>>> v
Vector3(0.27, 0.53, 0.80)

The following methods do not alter the original vector or their arguments:

magnitude()

Returns the magnitude of the vector; equivalent to abs(v). Example:

>>> v = Vector3(1., 2., 3.)
>>> v.magnitude()
3.7416573867739413
magnitude_squared()

Returns the sum of the squares of each component. Useful for comparing the length of two vectors without the expensive square root operation. Example:

>>> v = Vector3(1., 2., 3.)
>>> v.magnitude_squared()
14.0
normalized()

Return a unit length vector in the same direction. Note that this method differs from normalize in that it does not modify the vector in-place. Example:

>>> v = Vector3(1., 2., 3.)
>>> v.normalized()
Vector3(0.27, 0.53, 0.80)
>>> v
Vector3(1.00, 2.00, 3.00)
dot(other)

Return the scalar “dot” product of two vectors. Example:

>>> v1 = Vector3(1., 2., 3.)
>>> v2 = Vector3(4., 5., 6.)
>>> v1.dot(v2)
32.0
cross() and cross(other)

Return the cross product of a vector (for Vector2), or the cross product of two vectors (for Vector3). The return type is a vector. Example:

>>> v1 = Vector3(1., 2., 3.)
>>> v2 = Vector3(4., 5., 6.)
>>> v1.cross(v2)
Vector3(-3.00, 6.00, -3.00)

In two dimensions there can be no argument to cross:

>>> v1 = Vector2(1., 2.)
>>> v1.cross()
Vector2(2.00, -1.00)
reflect(normal)

Return the vector reflected about the given normal. In two dimensions, normal is the normal to a line, in three dimensions it is the normal to a plane. The normal must have unit length. Example:

>>> v = Vector3(1., 2., 3.)
>>> v.reflect(Vector3(0, 1, 0))
Vector3(1.00, -2.00, 3.00)
>>> v = Vector2(1., 2.)
>>> v.reflect(Vector2(1, 0))
Vector2(-1.00, 2.00)
rotate_around(axes, theta)

For 3D vectors, return the vector rotated around axis by the angle theta.

>>> v = Vector3(1., 2., 3.)
>>> axes = Vector3(1.,1.,0)
>>> v.rotate_around(axes,math.pi/4)
Vector3(2.65, 0.35, 2.62)

Constructor. :param *args: x,y values

__init__(*args)[source]

Constructor. :param *args: x,y values

xy
Returns:tuple (x,y)
__repr__()[source]
__hash__()[source]
__eq__(other)[source]

Tests for equality include comparing against other sequences:

>>> v2 = Vector2(1, 2)
>>> v2 == Vector2(3, 4)

False >>> v2 != Vector2(1, 2) False >>> v2 == (1, 2) True

>>> v3 = Vector3(1, 2, 3)
>>> v3 == Vector3(3, 4, 5)
False
>>> v3 != Vector3(1, 2, 3)
False
>>> v3 == (1, 2, 3)
True
__len__()[source]
__iter__()[source]
__add__(other)[source]
__radd__(other)
__iadd__(other)[source]
__sub__(other)[source]
__rsub__(other)[source]

Point2 - Vector 2 substraction :param other: Point2 or (x,y) tuple :return: Vector2

__mul__(other)[source]
__rmul__(other)
__imul__(other)[source]
__div__(other)[source]
__rdiv__(other)[source]
__floordiv__(other)[source]
__rfloordiv__(other)[source]
__truediv__(other)[source]
__rtruediv__(other)[source]
__neg__()[source]
__pos__()[source]
__abs__()[source]
mag()
length
mag2()[source]
normalize()[source]
normalized()[source]
dot(other)[source]
cross()[source]
reflect(normal)[source]
angle(other=None, unit=False)[source]

angle between two vectors. :param unit: bool True if vectors are unit vectors. False increases computations :return: float angle in radians to the other vector, or self direction if other=None

project(other)[source]

Return the projection (the component) of the vector on other.

__class__

alias of type

__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

class Goulib.geom.Point2(*args)[source]

Bases: Goulib.geom.Vector2, Goulib.geom.Geometry

A point on a 2D plane. Construct in the obvious way:

>>> p = Point2(1.0, 2.0)
>>> p

Point2(1.00, 2.00)

Point2 subclasses Vector2, so all of Vector2 operators and methods apply. In particular, subtracting two points gives a vector:

>>> Point2(2.0, 3.0) - Point2(1.0, 0.0)

Vector2(1.00, 3.00)

connect(other)
Returns a Segment2 which is the minimum length line segment that can connect the two shapes. other may be a Point2, Line2, Ray2, Segment2 or Circle.

Constructor. :param *args: x,y values

distance(other)[source]

absolute minimum distance to other object :param other: Point2, Line2 or Circle :return: float positive distance between self and other

__contains__(pt)[source]
Returns:True if self and pt are the same point, False otherwise

needed for coherency

intersect(other)[source]

Point2/object intersection :return: Point2 copy of self if on other object, None if not

connect(other)[source]
__abs__()
__abstractmethods__ = frozenset()
__add__(other)
__class__

alias of ABCMeta

__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__div__(other)
__eq__(other)

Tests for equality include comparing against other sequences:

>>> v2 = Vector2(1, 2)
>>> v2 == Vector2(3, 4)

False >>> v2 != Vector2(1, 2) False >>> v2 == (1, 2) True

>>> v3 = Vector3(1, 2, 3)
>>> v3 == Vector3(3, 4, 5)
False
>>> v3 != Vector3(1, 2, 3)
False
>>> v3 == (1, 2, 3)
True
__floordiv__(other)
__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__()
__iadd__(other)
__imul__(other)
__init__(*args)

Constructor. :param *args: x,y values

__iter__()
__le__

Return self<=value.

__len__()
__lt__

Return self<value.

__mul__(other)
__ne__

Return self!=value.

__neg__()
__new__()

Create and return a new object. See help(type) for accurate signature.

__pos__()
__radd__(other)
__rdiv__(other)
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__()
__rfloordiv__(other)
__rmul__(other)
__rsub__(other)

Point2 - Vector 2 substraction :param other: Point2 or (x,y) tuple :return: Vector2

__rtruediv__(other)
__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

__sub__(other)
__truediv__(other)
angle(other=None, unit=False)

angle between two vectors. :param unit: bool True if vectors are unit vectors. False increases computations :return: float angle in radians to the other vector, or self direction if other=None

cross()
dot(other)
length
mag()
mag2()
normalize()
normalized()
point(u)
Returns:Point2 or Point3 at parameter u
project(other)

Return the projection (the component) of the vector on other.

reflect(normal)
tangent(u)
Returns:Vector2 or Vector3 tangent at parameter u
xy
Returns:tuple (x,y)
Goulib.geom.Polar(mag, angle)[source]
class Goulib.geom.Line2(*args)[source]

Bases: Goulib.geom.Geometry

A Line2 is a line on a 2D plane extending to infinity in both directions; a Ray2 has a finite end-point and extends to infinity in a single direction; a Segment2 joins two points.

All three classes support the same constructors, operators and methods, but may behave differently when calculating intersections etc.

You may construct a line, ray or line segment using any of:

  • another line, ray or line segment
  • two points
  • a point and a vector
  • a point, a vector and a length

For example:

>>> Line2(Point2(1.0, 1.0), Point2(2.0, 3.0))
Line2(<1.00, 1.00> + u<1.00, 2.00>)
>>> Line2(Point2(1.0, 1.0), Vector2(1.0, 2.0))
Line2(<1.00, 1.00> + u<1.00, 2.00>)
>>> Ray2(Point2(1.0, 1.0), Vector2(1.0, 2.0), 1.0)
Ray2(<1.00, 1.00> + u<0.45, 0.89>)

Internally, lines, rays and line segments store a Point2 p and a Vector2 v. You can also access (but not set) the two endpoints p1 and p2. These may or may not be meaningful for all types of lines.

The following methods are supported by all three classes:

intersect(other)

If other is a Line2, Ray2 or Segment2, returns a Point2 of intersection, or None if the lines are parallel.

If other is a Circle, returns a Segment2 or Point2 giving the part of the line that intersects the circle, or None if there is no intersection.

connect(other)
Returns a Segment2 which is the minimum length line segment that can connect the two shapes. For two parallel lines, this line segment may be in an arbitrary position. other may be a Point2, Line2, Ray2, Segment2 or Circle.
distance(other)
Returns the absolute minimum distance to other. Internally this simply returns the length of the result of connect.

Segment2 also has a length property which is read-only.

__init__(*args)[source]
__eq__(other)[source]

lines are “equal” only if base points and vector are strictly equal. to compare if lines are “same”, use line1.distance(line2)==0

__repr__()[source]
point(u)[source]
Returns:Point2 at parameter u
tangent(u)[source]
Returns:Vector2 tangent at parameter u. Warning : tangent is generally not a unit vector
intersect(other)[source]
connect(other)[source]
__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__contains__(pt)
__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

distance(other)
class Goulib.geom.Ray2(*args)[source]

Bases: Goulib.geom.Line2

__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__contains__(pt)
__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__eq__(other)

lines are “equal” only if base points and vector are strictly equal. to compare if lines are “same”, use line1.distance(line2)==0

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__init__(*args)
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__()
__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

connect(other)
distance(other)
intersect(other)
point(u)
Returns:Point2 at parameter u
tangent(u)
Returns:Vector2 tangent at parameter u. Warning : tangent is generally not a unit vector
class Goulib.geom.Segment2(*args)[source]

Bases: Goulib.geom.Line2

p1
p2
__repr__()[source]
__abs__()[source]
mag2()[source]
length
swap()[source]
midpoint()[source]
bisect()[source]
__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__contains__(pt)
__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__eq__(other)

lines are “equal” only if base points and vector are strictly equal. to compare if lines are “same”, use line1.distance(line2)==0

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__init__(*args)
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

connect(other)
distance(other)
intersect(other)
point(u)
Returns:Point2 at parameter u
tangent(u)
Returns:Vector2 tangent at parameter u. Warning : tangent is generally not a unit vector
class Goulib.geom.Circle(*args)[source]

Bases: Goulib.geom.Geometry

Circles are constructed with a center Point2 and a radius:

>>> c = Circle(Point2(1.0, 1.0), 0.5)
>>> c

Circle(<1.00, 1.00>, radius=0.50)

Internally there are two attributes: c, giving the center point and r, giving the radius.

The following methods are supported:

connect(other)
Returns a Segment2 which is the minimum length line segment that can connect the two shapes. other may be a Point2, Line2, Ray2, Segment2 or Circle.
distance(other)
Returns the absolute minimum distance to other. Internally this simply returns the length of the result of connect.
Parameters:args – can be
  • Circle
  • center, point on circle
  • center, radius
__init__(*args)[source]
Parameters:args – can be
  • Circle
  • center, point on circle
  • center, radius
__eq__(other)[source]
__repr__()[source]
__abs__()[source]
Returns:float perimeter
length
point(u)[source]
Returns:Point2 at angle u radians
tangent(u)[source]
Returns:Vector2 tangent at angle u. Warning : tangent has magnitude r != 1
__contains__(pt)[source]
Returns:True if pt is ON or IN the circle
intersect(other)[source]
Parameters:other – Line2, Ray2 or Segment2**, Ray2 or Segment2, returns

a Segment2 giving the part of the line that intersects the circle, or None if there is no intersection.

connect(other)[source]
swap()[source]
__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

distance(other)
Goulib.geom.circle_from_3_points(a, b, c)[source]

constructs Circle passing through 3 distinct points :param a,b,c: Point2 :return: the unique Circle through the three points a, b, c

Goulib.geom.arc_from_3_points(a, b, c)[source]

constructs Arc2 starting in a, going through b and ending in c :param a,b,c: Point2 :return: the unique Arc2 starting in a, going through b and ending in c

class Goulib.geom.Arc2(center, p1=0, p2=6.283185307179586, r=None, dir=1)[source]

Bases: Goulib.geom.Circle

Parameters:
  • center – Point2 or (x,y) tuple
  • p1 – starting Point2 or angle in radians
  • p2 – ending Point2 or angle in radians
  • r – float radius, needed only if p1 or p2 is an angle
  • dir – arc direction. +1 is trig positive (CCW) and -1 is Clockwise
__init__(center, p1=0, p2=6.283185307179586, r=None, dir=1)[source]
Parameters:
  • center – Point2 or (x,y) tuple
  • p1 – starting Point2 or angle in radians
  • p2 – ending Point2 or angle in radians
  • r – float radius, needed only if p1 or p2 is an angle
  • dir – arc direction. +1 is trig positive (CCW) and -1 is Clockwise
angle(b=None)[source]
Returns:float signed arc angle
__abs__()[source]
Returns:float arc length
point(u)[source]
Returns:Point2 at parameter u
tangent(u)[source]
Returns:Vector2 tangent at parameter u
__eq__(other)[source]
__repr__()[source]
swap()[source]
__contains__(pt)[source]
Returns:True if pt is ON the Arc
intersect(other)[source]
__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

connect(other)
distance(other)
length
class Goulib.geom.Ellipse(*args)[source]

Bases: Goulib.geom.Circle

Parameters:args – can be
  • Ellipse
  • center, corner point
  • center, r1,r2,angle
__init__(*args)[source]
Parameters:args – can be
  • Ellipse
  • center, corner point
  • center, r1,r2,angle
__repr__()[source]
__eq__(other)[source]
__abs__()
Returns:float perimeter
__abstractmethods__ = frozenset()
__class__

alias of ABCMeta

__contains__(pt)
Returns:True if pt is ON or IN the circle
__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

connect(other)
distance(other)
intersect(other)
Parameters:other – Line2, Ray2 or Segment2**, Ray2 or Segment2, returns

a Segment2 giving the part of the line that intersects the circle, or None if there is no intersection.

length
point(u)
Returns:Point2 at angle u radians
swap()
tangent(u)
Returns:Vector2 tangent at angle u. Warning : tangent has magnitude r != 1
class Goulib.geom.Matrix3(*args)[source]

Bases: object

Two matrix classes are supplied, Matrix3, a 3x3 matrix for working with 2D affine transformations, and Matrix4, a 4x4 matrix for working with 3D affine transformations.

The default constructor intializes the matrix to the identity:

>>> Matrix3()
Matrix3([    1.00     0.00     0.00
             0.00     1.00     0.00
             0.00     0.00     1.00])
>>> Matrix4()
Matrix4([    1.00     0.00     0.00     0.00
             0.00     1.00     0.00     0.00
             0.00     0.00     1.00     0.00
             0.00     0.00     0.00     1.00])

Element access

Internally each matrix is stored as a set of attributes named a to p. The layout for Matrix3 is:

# a b c
# e f g
# i j k

and for Matrix4:

# a b c d
# e f g h
# i j k l
# m n o p

If you wish to set or retrieve a number of elements at once, you can do so with a slice:

>>> m = Matrix4()
>>> m[:]
[1.0, 0, 0, 0, 0, 1.0, 0, 0, 0, 0, 1.0, 0, 0, 0, 0, 1.0]
>>> m[12:15] = (5, 5, 5)
>>> m
Matrix4([    1.00     0.00     0.00     5.00
             0.00     1.00     0.00     5.00
             0.00     0.00     1.00     5.00
             0.00     0.00     0.00     1.00])

Note that slices operate in column-major order, which makes them suitable for working directly with OpenGL’s glLoadMatrix and glGetFloatv functions.

Class constructors

There are class constructors for the most common types of transform.

new_identity

Equivalent to the default constructor. Example:

>>> m = Matrix4.new_identity()
>>> m
Matrix4([    1.00     0.00     0.00     0.00
             0.00     1.00     0.00     0.00
             0.00     0.00     1.00     0.00
             0.00     0.00     0.00     1.00])
new_scale(x, y) and new_scale(x, y, z)

The former is defined on Matrix3, the latter on Matrix4. Equivalent to the OpenGL call glScalef. Example:

>>> m = Matrix4.new_scale(2.0, 3.0, 4.0)
>>> m
Matrix4([    2.00     0.00     0.00     0.00
             0.00     3.00     0.00     0.00
             0.00     0.00     4.00     0.00
             0.00     0.00     0.00     1.00])
new_translate(x, y) and new_translate(x, y, z)

The former is defined on Matrix3, the latter on Matrix4. Equivalent to the OpenGL call glTranslatef. Example:

>>> m = Matrix4.new_translate(3.0, 4.0, 5.0)
>>> m
Matrix4([    1.00     0.00     0.00     3.00
             0.00     1.00     0.00     4.00
             0.00     0.00     1.00     5.00
             0.00     0.00     0.00     1.00])
new_rotate(angle)

Create a Matrix3 for a rotation around the origin. angle is specified in radians, anti-clockwise. This is not implemented in Matrix4 (see below for equivalent methods). Example:

>>> import math
>>> m = Matrix3.new_rotate(math.pi / 2)
>>> m
Matrix3([    0.00    -1.00     0.00
             1.00     0.00     0.00
             0.00     0.00     1.00])

The following constructors are defined for Matrix4 only.

new_rotatex(angle), new_rotatey(angle), new_rotatez(angle)

Create a Matrix4 for a rotation around the X, Y or Z axis, respectively. angle is specified in radians. Example:

>>> m = Matrix4.new_rotatex(math.pi / 2)
>>> m
Matrix4([    1.00     0.00     0.00     0.00
             0.00     0.00    -1.00     0.00
             0.00     1.00     0.00     0.00
             0.00     0.00     0.00     1.00])
new_rotate_axis(angle, axis)

Create a Matrix4 for a rotation around the given axis. angle is specified in radians, and axis must be an instance of Vector3. It is not necessary to normalize the axis. Example:

>>> m = Matrix4.new_rotate_axis(math.pi / 2, Vector3(1.0, 0.0, 0.0))
>>> m
Matrix4([    1.00     0.00     0.00     0.00
             0.00     0.00    -1.00     0.00
             0.00     1.00     0.00     0.00
             0.00     0.00     0.00     1.00])
new_rotate_euler(heading, attitude, bank)

Create a Matrix4 for the given Euler rotation. heading is a rotation around the Y axis, attitude around the X axis and bank around the Z axis. All rotations are performed simultaneously, so this method avoids “gimbal lock” and is the usual method for implemented 3D rotations in a game. Example:

>>> m = Matrix4.new_rotate_euler(math.pi / 2, math.pi / 2, 0.0)
>>> m
Matrix4([    0.00    -0.00     1.00     0.00
             1.00     0.00    -0.00     0.00
            -0.00     1.00     0.00     0.00
             0.00     0.00     0.00     1.00])
new_perspective(fov_y, aspect, near, far)

Create a Matrix4 for projection onto the 2D viewing plane. This method is equivalent to the OpenGL call gluPerspective. fov_y is the view angle in the Y direction, in radians. aspect is the aspect ration width / height of the viewing plane. near and far are the distance to the near and far clipping planes. They must be positive and non-zero. Example:

>>> m = Matrix4.new_perspective(math.pi / 2, 1024.0 / 768, 1.0, 100.0)
>>> m
Matrix4([    0.75     0.00     0.00     0.00
             0.00     1.00     0.00     0.00
             0.00     0.00    -1.02    -2.02
             0.00     0.00    -1.00     0.00])

Operators

Matrices of the same dimension may be multiplied to give a new matrix. For example, to create a transform which translates and scales:

>>> m1 = Matrix3.new_translate(5.0, 6.0)
>>> m2 = Matrix3.new_scale(1.0, 2.0)
>>> m1 * m2
Matrix3([    1.00     0.00     5.00
             0.00     2.00     6.00
             0.00     0.00     1.00])

Note that multiplication is not commutative (the order that you apply transforms matters):

>>> m2 * m1
Matrix3([    1.00     0.00     5.00
             0.00     2.00    12.00
             0.00     0.00     1.00])

In-place multiplication is also permitted (and optimised):

>>> m1 *= m2
>>> m1
Matrix3([    1.00     0.00     5.00
             0.00     2.00     6.00
             0.00     0.00     1.00])

Multiplying a matrix by a vector returns a vector, and is used to transform a vector:

>>> m1 = Matrix3.new_rotate(math.pi / 2)
>>> m1 * Vector2(1.0, 1.0)
Vector2(-1.00, 1.00)

Note that translations have no effect on vectors. They do affect points, however:

>>> m1 = Matrix3.new_translate(5.0, 6.0)
>>> m1 * Vector2(1.0, 2.0)
Vector2(1.00, 2.00)
>>> m1 * Point2(1.0, 2.0)
Point2(6.00, 8.00)

Multiplication is currently incorrect between matrices and vectors – the projection component is ignored. Use the Matrix4.transform method instead.

Matrix4 also defines transpose (in-place), transposed (functional), determinant and inverse (functional) methods.

A Matrix3 can be multiplied with a Vector2 or any of the 2D geometry objects (Point2, Line2, Circle, etc).

A Matrix4 can be multiplied with a Vector3 or any of the 3D geometry objects (Point3, Line3, Sphere, etc).

For convenience, each of the matrix constructors are also available as in-place operators. For example, instead of writing:

>>> m1 = Matrix3.new_translate(5.0, 6.0)
>>> m2 = Matrix3.new_scale(1.0, 2.0)
>>> m1 *= m2

you can apply the scale directly to m1:

>>> m1 = Matrix3.new_translate(5.0, 6.0)
>>> m1.scale(1.0, 2.0)
Matrix3([    1.00     0.00     5.00
             0.00     2.00     6.00
             0.00     0.00     1.00])
>>> m1
Matrix3([    1.00     0.00     5.00
             0.00     2.00     6.00
             0.00     0.00     1.00])

Note that these methods operate in-place (they modify the original matrix), and they also return themselves as a result. This allows you to chain transforms together directly:

>>> Matrix3().translate(1.0, 2.0).rotate(math.pi / 2).scale(4.0, 4.0)
Matrix3([    0.00    -4.00     1.00
             4.00     0.00     2.00
             0.00     0.00     1.00])

All constructors have an equivalent in-place method. For Matrix3, they are identity, translate, scale and rotate. For Matrix4, they are identity, translate, scale, rotatex, rotatey, rotatez, rotate_axis and rotate_euler. Both Matrix3 and Matrix4 also have an in-place transpose method.

The copy method is also implemented in both matrix classes and behaves in the obvious way.

__init__(*args)[source]
__repr__()[source]
__iter__()[source]
__getitem__(key)[source]
__setitem__(key, value)[source]
__eq__(other)[source]
__sub__(other)[source]
__imul__(other)[source]
__mul__(other)[source]
__call__(other)[source]
identity()[source]
scale(x, y=None)[source]
__class__

alias of type

__delattr__

Implement delattr(self, name).

__dir__() → list

default dir() implementation

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__ = None
__le__

Return self<=value.

__lt__

Return self<value.

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

offset()[source]
angle(angle=0)[source]
Parameters:angle – angle in radians of a unit vector starting at origin
Returns:float bearing in radians of the transformed vector
mag(v=None)[source]

Return the net (uniform) scaling of this transform.

translate(*args)[source]
Parameters:*args

x,y values

rotate(angle)[source]
classmethod new_identity()[source]
classmethod new_scale(x, y)[source]
classmethod new_translate(x, y)[source]
classmethod new_rotate(angle)[source]
mag2()[source]
__abs__()[source]
transpose()[source]
transposed()[source]
determinant()[source]
inverse()[source]
orientation()[source]
Returns:1 if matrix is right handed, -1 if left handed