From 67c15da97de7644fc4deb3ab1b03c3db22f1f647 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Mon, 17 Oct 2011 02:20:53 +0000
Subject: docs / clenup (no functional code changes) - added API examples for
 mathutils.Color/Euler/Quaternion/Matrix. - corrected own bad spelling
 matricies --> matrices. - minor pep8 edits. - update CMake ignore file list.

---
 doc/python_api/examples/mathutils.Color.py      | 30 ++++++++++++++++++++++++
 doc/python_api/examples/mathutils.Euler.py      | 31 ++++++++++++++++++++++++-
 doc/python_api/examples/mathutils.Matrix.py     | 27 ++++++++++++++++++++-
 doc/python_api/examples/mathutils.Quaternion.py | 22 +++++++++++++++++-
 doc/python_api/rst/bge.logic.rst                |  2 +-
 5 files changed, 108 insertions(+), 4 deletions(-)
 create mode 100644 doc/python_api/examples/mathutils.Color.py

(limited to 'doc')

diff --git a/doc/python_api/examples/mathutils.Color.py b/doc/python_api/examples/mathutils.Color.py
new file mode 100644
index 00000000000..a55f1195bf6
--- /dev/null
+++ b/doc/python_api/examples/mathutils.Color.py
@@ -0,0 +1,30 @@
+import mathutils
+
+# color values are represented as RGB values from 0 - 1, this is blue
+col = mathutils.Color((0.0, 0.0, 1.0))
+
+# as well as r/g/b attribute access you can adjust them by h/s/v
+col.s *= 0.5
+
+# you can access its components by attribute or index
+print("Color R:", col.r)
+print("Color G:", col[1])
+print("Color B:", col[-1])
+print("Color HSV: %.2f, %.2f, %.2f", col[:])
+
+
+# components of an existing color can be set
+col[:] = 0.0, 0.5, 1.0
+
+# components of an existing color can use slice notation to get a tuple
+print("Values: %f, %f, %f" % col[:])
+
+# colors can be added and subtracted
+col += mathutils.Color((0.25, 0.0, 0.0))
+
+# Color can be multiplied, in this example color is scaled to 0-255
+# can printed as integers
+print("Color: %d, %d, %d" % (col * 255.0)[:])
+
+# This example prints the color as hexidecimal
+print("Hexidecimal: %.2x%.2x%.2x" % (col * 255.0)[:])
diff --git a/doc/python_api/examples/mathutils.Euler.py b/doc/python_api/examples/mathutils.Euler.py
index bc7702c1d53..3f87cc0ab04 100644
--- a/doc/python_api/examples/mathutils.Euler.py
+++ b/doc/python_api/examples/mathutils.Euler.py
@@ -1,3 +1,32 @@
 import mathutils
+import math
 
-# todo
+# create a new euler with default axis rotation order
+eul = mathutils.Euler((0.0, math.radians(45.0), 0.0), 'XYZ')
+
+# rotate the euler
+eul.rotate_axis(math.radians(10.0), 'Z')
+
+# you can access its components by attribute or index
+print("Euler X", eul.x)
+print("Euler Y", eul[1])
+print("Euler Z", eul[-1])
+
+# components of an existing euler can be set
+eul[:] = 1.0, 2.0, 3.0
+
+# components of an existing euler can use slice notation to get a tuple
+print("Values: %f, %f, %f" % eul[:])
+
+# the order can be set at any time too
+eul.order = 'ZYX'
+
+# eulers can be used to rotate vectors
+vec = mathutils.Vector((0.0, 0.0, 1.0))
+vec.rotate(eul)
+
+# often its useful to convert the euler into a matrix so it can be used as
+# transformations with more flexibility
+mat_rot = eul.to_matrix()
+mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))
+mat = mat_loc * mat_rot.to_4x4()
diff --git a/doc/python_api/examples/mathutils.Matrix.py b/doc/python_api/examples/mathutils.Matrix.py
index bc7702c1d53..079070a5ec7 100644
--- a/doc/python_api/examples/mathutils.Matrix.py
+++ b/doc/python_api/examples/mathutils.Matrix.py
@@ -1,3 +1,28 @@
 import mathutils
+import math
 
-# todo
+# create a location matrix
+mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))
+
+# create an identitiy matrix
+mat_sca = mathutils.Matrix.Scale(0.5, 4, (0.0, 0.0, 1.0))
+
+# create a rotation matrix
+mat_rot = mathutils.Matrix.Rotation(math.radians(45.0), 4, 'X')
+
+# combine transformations
+mat_out = mat_loc * mat_rot * mat_sca
+print(mat_out)
+
+# extract components back out of the matrix
+loc, rot, sca = mat_out.decompose()
+print(loc, rot, sca)
+
+# it can also be useful to access components of a matrix directly
+mat = mathutils.Matrix()
+mat[0][0], mat[1][0], mat[2][0] = 0.0, 1.0, 2.0
+
+mat[0][0:3] = 0.0, 1.0, 2.0
+
+# each item in a matrix is a vector so vector utility functions can be used
+mat[0].xyz = 0.0, 1.0, 2.0
diff --git a/doc/python_api/examples/mathutils.Quaternion.py b/doc/python_api/examples/mathutils.Quaternion.py
index bc7702c1d53..d8c696e6ba6 100644
--- a/doc/python_api/examples/mathutils.Quaternion.py
+++ b/doc/python_api/examples/mathutils.Quaternion.py
@@ -1,3 +1,23 @@
 import mathutils
+import math
 
-# todo
+# a new rotation 90 degrees about the Y axis
+quat_a = mathutils.Quaternion((0.7071068, 0.0, 0.7071068, 0.0))
+
+# passing values to Quaternion's directly can be confusing so axis, angle
+# is supported for initializing too
+quat_b = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))
+
+print("Check quaternions match", quat_a == quat_b)
+
+# like matrices, quaternions can be multiplied to accumulate rotational values
+quat_a = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))
+quat_b = mathutils.Quaternion((0.0, 0.0, 1.0), math.radians(45.0))
+quat_out = quat_a * quat_b
+
+# print the quat, euler degrees for mear mortals and (axis, angle)
+print("Final Rotation:")
+print(quat_out)
+print("%.2f, %.2f, %.2f" % tuple(math.degrees(a) for a in quat_out.to_euler()))
+print("(%.2f, %.2f, %.2f), %.2f" % (quat_out.axis[:] +
+                                    (math.degrees(quat_out.angle), )))
diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index 798491b4710..82e69965840 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -106,7 +106,7 @@ There are also methods to access the current :class:`bge.types.KX_Scene`
 Matricies as used by the game engine are **row major**
 ``matrix[row][col] = float``
 
-:class:`bge.types.KX_Camera` has some examples using matricies.
+:class:`bge.types.KX_Camera` has some examples using matrices.
 
 *********
 Variables
-- 
cgit v1.2.3