Transforms and coordinates¶
Object-to-world transform¶
The matrix_world attribute of an Object contains the object-to-world transform that places the object in the 3D scene:
>>> o = bpy.context.active_object
>>> o
bpy.data.objects['Cube']
>>> o.matrix_world
Matrix(((1.3376139402389526, 0.0, 0.0, 0.3065159320831299),
(0.0, 1.3376139402389526, 0.0, 2.2441697120666504),
(0.0, 0.0, 1.3376139402389526, 1.2577730417251587),
(0.0, 0.0, 0.0, 1.0)))
Comparing this matrix with the values set in the Transform panel, you can see the Location value is stored in the right-most column of the matrix and the scaling along the diagonal. If there was a rotation set on this object some of these values would not be as recognizable anymore.
The location, rotation (in radians) and scale values can also be inspected and set separately:
>>> o.location
Vector((0.3065159320831299, 2.2441697120666504, 1.2577730417251587))
>>> o.rotation_euler
Euler((0.0, 0.0, 0.0), 'XYZ')
>>> o.scale
Vector((1.3376139402389526, 1.3376139402389526, 1.3376139402389526))
>>> o.location = (1, 2, 3)
# Rotations are set in radians
>>> o.rotation_euler.x = radians(45)
>>> o.scale = (2, 1, 1)
>>> o.matrix_world
Matrix(((2.0, 0.0, 0.0, 1.0),
(0.0, 0.7071067690849304, -0.7071067690849304, 2.0),
(0.0, 0.7071067690849304, 0.7071067690849304, 3.0),
(0.0, 0.0, 0.0, 1.0)))
See the section on parenting for some subtle effects on transformations in case object parenting is used.
Geometry coordinates¶
Mesh geometry in Blender stores vertex coordinates (and other geometric information) in object-space coordinates. But a mesh (or object in general) will usually get transformed to a specific position, scaling and orientation in the scene.
As described above the net transform from object-space to world-space coordinates, also called the object-to-world transform, is available through matrix_world. In cases where you need to have access to geometric data in world-space, say vertex coordinates, you need to apply the matrix_world transform manually.
For example, given the cube transformed as shown above, with only vertex 7 selected (visible in white the bottom-left of the image):
>>> o
bpy.data.objects['Cube']
>>> m = o.data
>>> o.matrix_world
Matrix(((1.3376139402389526, 0.0, 0.0, 0.3065159320831299),
(0.0, 1.3376139402389526, 0.0, 2.2441697120666504),
(0.0, 0.0, 1.3376139402389526, 1.2577730417251587),
(0.0, 0.0, 0.0, 1.0)))
# The object-space coordinate of this vertex
>>> m.vertices[7].co
Vector((-1.0, -1.0, -1.0))
# The world-space coordinate of this vertex, which matches
# what the Transform UI shows. Note the Global display mode
# select in the UI. If we would select Local the values shown
# would be (-1, -1, -1).
>>> o.matrix_world @ m.vertices[7].co
Vector((-1.0310980081558228, 0.9065557718276978, -0.07984089851379395))