Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Python Scripting

Blender mathutils: Vectors, Matrices, Quaternions and Euler

Use Blender's mathutils module: Vector dot and cross products, normalization, Euler angles, Quaternion rotation and 4x4 Matrix transforms with worked examples.

Almost every script that places, aims or measures things needs 3D maths. Blender includes the mathutils module with Vector, Matrix, Euler, Quaternion and Color. Object locations, rotations and transforms are already mathutils types, so learning them makes scripts shorter and less error-prone.

Blender is not available on this site. The mathutils code is shown read-only, and each idea has a runnable pure-Python stand-in with the same formulas (plus math), so you can check results by hand. The stand-ins are written to give the same numbers as mathutils, but they are not the real module.

Vectors

Python
from mathutils import Vector

a = Vector((1, 2, 3))
b = Vector((4, 0, -1))

print(a + b)            # <Vector (5.0000, 2.0000, 2.0000)>
print(a - b)
print(a * 2)            # scalar multiply
print(a.length)         # 3.7416...
print(a.normalized())   # length 1, same direction
print(a.dot(b))         # 1 (scalar)
print(a.cross(b))       # perpendicular vector
print((a - b).length)   # distance between two points
print(a.lerp(b, 0.5))   # midpoint
print(a.angle(b))       # radians

Important facts:

  • a * b between two vectors is an element-wise product, not dot. Use .dot(), .cross() explicitly (Blender 2.8+ uses @ for matrix multiplication).
  • normalize() changes the vector in place, normalized() returns a copy.
  • obj.location is a live Vector: obj.location.x += 1 moves the object, but v = obj.location is not a copy. Use v = obj.location.copy() to keep a snapshot.

Dot and cross products

The dot product a . b = |a||b| cos(angle) measures how much two directions agree: 1 for the same direction (unit vectors), 0 for perpendicular, -1 for opposite. Use it for "is this face looking at the camera?" or the angle between two directions.

The cross product gives a vector perpendicular to both, with length |a||b| sin(angle). Use it for surface normals: for a triangle (p0, p1, p2) the normal is (p1 - p0).cross(p2 - p0).normalized().

Python Stand-in: vector math, normals and angles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Euler angles and quaternions

Rotation can be stored in several ways:

  • Euler (obj.rotation_euler): three angles in radians (X, Y, Z) applied in an order ('XYZ' by default). Easy to read and animate. Weakness: gimbal lock (two axes line up and one degree of freedom disappears) and awkward interpolation.
  • Quaternion (obj.rotation_quaternion): four numbers (w, x, y, z). No gimbal lock and smooth interpolation (slerp). Hard to read.
  • Axis-angle: an axis and an angle.

Switch with obj.rotation_mode = 'QUATERNION'. Convert with .to_quaternion() and .to_euler():

Python
from mathutils import Euler, Quaternion, Vector
import math

e = Euler((0, 0, math.radians(90)), 'XYZ')
q = e.to_quaternion()
v = Vector((1, 0, 0))
v.rotate(q)                       # rotates in place
print(v)                          # approximately (0, 1, 0)

q2 = Quaternion((0, 0, 1), math.radians(90))   # axis, angle
print(q2.to_euler())
print(q.slerp(Quaternion(), 0.5)) # halfway back to identity rotation

The stand-in creates a quaternion from an axis and angle and rotates a point with it, using the same formula that Blender uses.

Python Stand-in: quaternion from axis and angle, rotate a point

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Matrices and transforms

A 4 x 4 Matrix stores location, rotation and scale together. Every object has obj.matrix_world (object to world space) and obj.matrix_local.

Python
from mathutils import Matrix, Vector
import math

T = Matrix.Translation((2, 0, 0))
R = Matrix.Rotation(math.radians(90), 4, 'Z')
S = Matrix.Diagonal((2, 2, 2, 1))     # scale (uniform 2)

M = T @ R @ S                         # applied right to left: scale, then rotate, then move
print(M @ Vector((1, 0, 0)))          # a point to world space
print(M.to_translation(), M.to_euler(), M.to_scale())
print(M.inverted())                   # world -> local

Remember: matrix multiplication is not commutative: T @ R is not R @ T. The matrix to the right happens first. To get the world position of a vertex: obj.matrix_world @ vertex.co. To convert a world point to local space: obj.matrix_world.inverted() @ point. A point (Vector) with three components is multiplied as a location, while directions should ignore translation (use to_3x3()).

Python Stand-in: order of transforms (scale, rotate, translate)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical recipes

  1. Distance between objects: (a.location - b.location).length.
  2. Look at a target (rotate an object to face a point): direction = target - obj.location; obj.rotation_euler = direction.to_track_quat('-Z', 'Y').to_euler().
  3. World position of a bone tip: armature.matrix_world @ pose_bone.tail.
  4. Mirror a point across X: Vector((-v.x, v.y, v.z)).
  5. Random point on a sphere: normalize a vector of three Gaussian random numbers and scale it by the radius.

Common mistakes

  • Using degrees instead of radians.
  • Forgetting .copy() when keeping a position that is later changed.
  • Using * instead of @ for matrix multiplication.
  • Using obj.location when you need the world position of a parented object: use matrix_world.translation.
  • Euler order surprises: rotating X then Y differs from Y then X.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the dot product of two perpendicular unit vectors?

    dot = cos(angle); cos(90 degrees) = 0.
  2. 2. Which operator multiplies matrices in Blender's Python?

    Matrix multiplication uses @. A scalar or element-wise product uses * for vectors.
  3. 3. What is the main advantage of quaternions over Euler angles?

    Quaternions have no gimbal lock and slerp gives smooth rotation, but they use four numbers.
  4. 4. How do you get the world position of a mesh vertex vertex.co on object obj?

    matrix_world transforms local coordinates into world space.

Summary

  • mathutils gives Vector, Matrix, Euler and Quaternion types used by all object transforms.
  • Dot products measure alignment, cross products give normals.
  • Matrix order matters: the rightmost transform is applied first.
  • Use .copy() for snapshots and matrix_world for world space.

Next: Operators and Add-ons