### From BlenderWiki

# Mathutils API Update

Recently a patch was submitted [#25747], which highlights some problems with the mathutils API which I have also noticed from my use of mathutils for testing tools and import/exporters.

I ran these changes by Uncle_Entity, dougal2 & z0r on IRC before writing up the proposal for initial feedback and have now written down the proposed changes in detail.

--Ideasman42 10:51, 3 February 2011 (UTC)

## Coerce Method Arguments

At the moment passing fixed values to a function is annoying because you must use mathutils constructors, or assign a value beforehand for reuse.

>>> myvec.cross(Vector((0, 0, 1)))

... but we could also accept

>>> myvec.cross((0, 0, 1))

Same with vec.angle(other), quat.difference((...))

This will **NOT** extend to operators

>>> Vector(...) + (1,2,3) >>> Vector(...) + Euler(...)

Seems convenient but introduces ambiguity as to what is the return type, and confuses which operators have special behavior such as Vector() * Matrix().

It also means the first value:

>>> (x, y, z, x) * Matrix()

Could be treated as a 4d vector or a quaternion.

## Separate Modify In-Place Methods

Clear separation between methods which modify in-place and ones which return new values.

At the moment this backfires in common cases when modifying wrapped data is not intended:

>>> imat = obj.matrix_world.invert() * othermat # edits object. >>> imat = obj.matrix_world.copy().invert() * othermat # ok.

mathutils wrapped types are used in the GameEngine and for many RNA types so I think its worth avoiding confusion here.

I propose to have 2 methods in cases such as this.

>>> matrix.invert() # Inverts in-place, returns None >>> matrix.inverted() # Returns a new, inverted matrix.

Same with normalize / normalized, transpose / transposed... etc.

## Rename Methods

- matrix/euler.to_quat() --> to_quaternion()
*This abbreviation isnt used anywhere else in mathutils.* - matrix.rotation_part() --> matrix.to_3x3()
*rotation_part() also contains scale which is misleading.* - matrix.translation_part() --> to_translation()
- scale_part() --> to_scale()
*At the moment we have matrix methods rotation_part() / scale_part() / translation_part().*

The method naming implies that together they will decompose the matrix, but as noted above this is not the case.

Since these methods were written I have added...

>>> loc, rot, scale = matrix.decompose()

*So I'm proposing to drop the *_part() suffix and have this in keeping with: matrix.to_euler(), to_quat(), to_3x3()*

- matrix.resize3x3 --> resize_3x3(), better matches to_3x3().

## Consistent Matrix Constructor Argument order

At the moment Matrix constructor order is mixed.

>>> mathutils.Matrix.Rotation(angle, matrix_size, axis) >>> mathutils.Matrix.Scale(factor, matrix_size, axis) >>> mathutils.Matrix.Shear(plane, factor, matrix_size) # <-- Odd one out >>> mathutils.Matrix.OrthoProjection(plane, matrix_size, axis) >>> mathutils.Matrix.Translation(vector)