sandey/blender
1
0
Fork 0
forked from bartvdbraak/blender
Code Pull Requests Activity

copy of docs from 2.4x for python modules that have been kept

Browse Source
This commit is contained in:
Campbell Barton 2010-01-24 12:58:38 +00:00
commit 2cfd3b6586
5 changed files with 3009 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1779
source/blender/python/doc/epy/BGL.py Normal file
View File

File diff suppressed because it is too large Load Diff

112
source/blender/python/doc/epy/Geometry.py Normal file
View File

@ -0,0 +1,112 @@
# Blender.Geometry module and its subtypes
"""
The Blender.Geometry submodule.
Geometry
========
(when accessing it from the Game Engine use Geometry instead of Blender.Geometry)
This new module provides access to a geometry function.
"""
def PolyFill(polylines):
"""
Takes a list of polylines and calculates triangles that would fill in the polylines.
Multiple lines can be used to make holes inside a polyline, or fill in 2 seperate lines at once.
@type polylines: List of lists containing vectors, each representing a closed polyline.
@rtype: list
@return: a list if tuples each a tuple of 3 ints representing a triangle indexing the points given.
@note: 2D Vectors will have an assumed Z axis of zero, 4D Vectors W axis is ignored.
@note: The order of points in a polyline effect the direction returned triangles face, reverse the order of a polyline to flip the normal of returned faces.
I{B{Example:}}
The example below creates 2 polylines and fills them in with faces, then makes a mesh in the current scene::
import Blender
Vector= Blender.Mathutils.Vector
# Outline of 5 points
polyline1= [Vector(-2.0, 1.0, 1.0), Vector(-1.0, 2.0, 1.0), Vector(1.0, 2.0, 1.0), Vector(1.0, -1.0, 1.0), Vector(-1.0, -1.0, 1.0)]
polyline2= [Vector(-1, 1, 1.0), Vector(0, 1, 1.0), Vector(0, 0, 1.0), Vector(-1.0, 0.0, 1.0)]
fill= Blender.Geometry.PolyFill([polyline1, polyline2])
# Make a new mesh and add the truangles into it
me= Blender.Mesh.New()
me.verts.extend(polyline1)
me.verts.extend(polyline2)
me.faces.extend(fill) # Add the faces, they reference the verts in polyline 1 and 2
scn = Blender.Scene.GetCurrent()
ob = scn.objects.new(me)
Blender.Redraw()
"""
def LineIntersect2D(vec1, vec2, vec3, vec4):
"""
Takes 2 lines vec1, vec2 for the 2 points of the first line and vec2, vec3 for the 2 points of the second line.
@rtype: Vector
@return: a 2D Vector for the intersection or None where there is no intersection.
"""
def ClosestPointOnLine(pt, vec1, vec2):
"""
Takes 2 lines vec1, vec2 for the 2 points of the first line and vec2, vec3 for the 2 points of the second line.
@rtype: tuple
@return: a tuple containing a vector and a float, the vector is the closest point on the line, the float is the position on the line, between 0 and 1 the point is on the line.
"""
def PointInTriangle2D(pt, tri_pt1, tri_pt2, tri_pt3):
"""
Takes 4 vectors (one for the test point and 3 for the triangle)
This is a 2d function so only X and Y are used, Z and W will be ignored.
@rtype: int
@return: 1 for a clockwise intersection, -1 for counter clockwise intersection, 0 when there is no intersection.
"""
def PointInQuad2D(pt, quad_pt1, quad_pt2, quad_pt3):
"""
Takes 5 vectors (one for the test point and 5 for the quad)
This is a 2d function so only X and Y are used, Z and W will be ignored.
@rtype: int
@return: 1 for a clockwise intersection, -1 for counter clockwise intersection, 0 when there is no intersection.
"""
def BoxPack2D(boxlist):
"""
Takes a list of 2D boxes and packs them into a square.
Each box in boxlist must be a list of at least 4 items - [x,y,w,h], after running this script,
the X and Y values in each box will be moved to packed, non overlapping locations.
Example::
# Make 500 random boxes, pack them and make a mesh from it
from Blender import Geometry, Scene, Mesh
import random
boxes = []
for i in xrange(500):
boxes.append( [0,0, random.random()+0.1, random.random()+0.1] )
boxsize = Geometry.BoxPack2D(boxes)
print 'BoxSize', boxsize
me = Mesh.New()
for x in boxes:
me.verts.extend([(x[0],x[1], 0), (x[0],x[1]+x[3], 0), (x[0]+x[2],x[1]+x[3], 0), (x[0]+x[2],x[1], 0) ])
v1= me.verts[-1]
v2= me.verts[-2]
v3= me.verts[-3]
v4= me.verts[-4]
me.faces.extend([(v1,v2,v3,v4)])
scn = Scene.GetCurrent()
scn.objects.new(me)
@note: Each boxlist item can be longer then 4, the extra items are ignored and stay untouched.
@rtype: tuple
@return: a tuple pair - (width, height) of all the packed boxes.
"""
def BezierInterp(vec_knot_1, vec_handle_1, vec_handle_2, vec_knot_2, resolution):
"""
Takes 4 vectors representing a bezier curve and returns a list of vector points.
@note: any vector size is supported, the largest dimension from the input will be used for all returned vectors/
@rtype: list
@return: a list of vectors the size of resolution including the start and end points (vec_knot_1 and vec_knot_2)
"""

132
source/blender/python/doc/epy/IDProp.py Normal file
View File

@ -0,0 +1,132 @@
class IDGroup:
"""
The IDGroup Type
================
This type supports both iteration and the []
operator to get child ID properties.
You can also add new properties using the [] operator.
For example::
group['a float!'] = 0.0
group['an int!'] = 0
group['a string!'] = "hi!"
group['an array!'] = [0, 0, 1.0, 0]
group['a subgroup!] = {"float": 0.0, "an int": 1.0, "an array": [1, 2],
"another subgroup": {"a": 0.0, "str": "bleh"}}
Note that for arrays, the array type defaults to int unless a float is found
while scanning the template list; if any floats are found, then the whole
array is float. Note that double-precision floating point numbers are used for
python-created float ID properties and arrays (though the internal C api does
support single-precision floats, and the python code will read them).
You can also delete properties with the del operator. For example:
del group['property']
To get the type of a property, use the type() operator, for example::
if type(group['bleh']) == str: pass
To tell if the property is a group or array type, import the Blender.Types module and test
against IDGroupType and IDArrayType, like so::
from Blender.Types import IDGroupType, IDArrayType.
if type(group['bleghr']) == IDGroupType:
(do something)
@ivar name: The name of the property
@type name: string
"""
def pop(item):
"""
Pop an item from the group property.
@type item: string
@param item: The item name.
@rtype: can be dict, list, int, float or string.
@return: The removed property.
"""
def update(updatedict):
"""
Updates items in the dict, similar to normal python
dictionary method .update().
@type updatedict: dict
@param updatedict: A dict of simple types to derive updated/new IDProperties from.
@rtype: None
@return: None
"""
def keys():
"""
Returns a list of the keys in this property group.
@rtype: list of strings.
@return: a list of the keys in this property group.
"""
def values():
"""
Returns a list of the values in this property group.
Note that unless a value is itself a property group or an array, you
cannot change it by changing the values in this list, you must change them
in the parent property group.
For example,
group['some_property'] = new_value
. . .is correct, while,
values = group.values()
values[0] = new_value
. . .is wrong.
@rtype: list of strings.
@return: a list of the values in this property group.
"""
def iteritems():
"""
Implements the python dictionary iteritmes method.
For example::
for k, v in group.iteritems():
print "Property name: " + k
print "Property value: " + str(v)
@rtype: an iterator that spits out items of the form [key, value]
@return: an iterator.
"""
def convert_to_pyobject():
"""
Converts the entire property group to a purely python form.
@rtype: dict
@return: A python dictionary representing the property group
"""
class IDArray:
"""
The IDArray Type
================
@ivar type: returns the type of the array, can be either IDP_Int or IDP_Float
"""
def __getitem__(index):
pass
def __setitem__(index, value):
pass
def __len__():
pass

941
source/blender/python/doc/epy/Mathutils.py Normal file
View File

@ -0,0 +1,941 @@
# Blender.Mathutils module and its subtypes
"""
The Blender.Mathutils submodule.
Mathutils
=========
(when accessing it from the Game Engine use Mathutils instead of Blender.Mathutils)
This module provides access to matrices, eulers, quaternions and vectors.
Example::
import Blender
from Blender import Mathutils
from Blender.Mathutils import *
vec = Vector([1,2,3])
mat = RotationMatrix(90, 4, 'x')
matT = TranslationMatrix(vec)
matTotal = mat * matT
matTotal.invert()
mat3 = matTotal.rotationPart
quat1 = mat.toQuat()
quat2 = mat3.toQuat()
angle = DifferenceQuats(quat1, quat2)
print angle
@group Deprecated: CopyMat, CopyVec, CopyQuat, CopyEuler, RotateEuler, MatMultVec, VecMultMat, CrossVecs, DotVecs, CrossQuats, DotQuats
"""
def Rand (low=0.0, high = 1.0):
"""
Return a random number within a range.
low and high represent are optional parameters which represent the range
from which the random number must return its result.
@type low: float
@param low: The lower range.
@type high: float
@param high: The upper range.
"""
def Intersect(vec1, vec2, vec3, ray, orig, clip=1):
"""
Return the intersection between a ray and a triangle, if possible, return None otherwise.
@type vec1: Vector object.
@param vec1: A 3d vector, one corner of the triangle.
@type vec2: Vector object.
@param vec2: A 3d vector, one corner of the triangle.
@type vec3: Vector object.
@param vec3: A 3d vector, one corner of the triangle.
@type ray: Vector object.
@param ray: A 3d vector, the orientation of the ray. the length of the ray is not used, only the direction.
@type orig: Vector object.
@param orig: A 3d vector, the origin of the ray.
@type clip: integer
@param clip: if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle.
@rtype: Vector object
@return: The intersection between a ray and a triangle, if possible, None otherwise.
"""
def TriangleArea(vec1, vec2, vec3):
"""
Return the area size of the 2D or 3D triangle defined.
@type vec1: Vector object.
@param vec1: A 2d or 3d vector, one corner of the triangle.
@type vec2: Vector object.
@param vec2: A 2d or 3d vector, one corner of the triangle.
@type vec3: Vector object.
@param vec3: A 2d or 3d vector, one corner of the triangle.
@rtype: float
@return: The area size of the 2D or 3D triangle defined.
"""
def TriangleNormal(vec1, vec2, vec3):
"""
Return the normal of the 3D triangle defined.
@type vec1: Vector object.
@param vec1: A 3d vector, one corner of the triangle.
@type vec2: Vector object.
@param vec2: A 3d vector, one corner of the triangle.
@type vec3: Vector object.
@param vec3: A 3d vector, one corner of the triangle.
@rtype: float
@return: The normal of the 3D triangle defined.
"""
def QuadNormal(vec1, vec2, vec3, vec4):
"""
Return the normal of the 3D quad defined.
@type vec1: Vector object.
@param vec1: A 3d vector, the first vertex of the quad.
@type vec2: Vector object.
@param vec2: A 3d vector, the second vertex of the quad.
@type vec3: Vector object.
@param vec3: A 3d vector, the third vertex of the quad.
@type vec4: Vector object.
@param vec4: A 3d vector, the fourth vertex of the quad.
@rtype: float
@return: The normal of the 3D quad defined.
"""
def LineIntersect(vec1, vec2, vec3, vec4):
"""
Return a tuple with the points on each line respectively closest to the other
(when both lines intersect, both vector hold the same value).
The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line.
@type vec1: Vector object.
@param vec1: A 3d vector, one point on the first line.
@type vec2: Vector object.
@param vec2: A 3d vector, another point on the first line.
@type vec3: Vector object.
@param vec3: A 3d vector, one point on the second line.
@type vec4: Vector object.
@param vec4: A 3d vector, another point on the second line.
@rtype: (Vector object, Vector object)
@return: A tuple with the points on each line respectively closest to the other.
"""
def CopyVec(vector):
"""
Create a copy of the Vector object.
@attention: B{DEPRECATED} use vector.copy() instead.
@type vector: Vector object.
@param vector: A 2d,3d or 4d vector to be copied.
@rtype: Vector object.
@return: A new vector object which is a copy of the one passed in.
"""
def CrossVecs(vec1, vec2):
"""
Return the cross product of two vectors.
@attention: B{DEPRECATED} use vector.cross(other) instead.
@type vec1: Vector object.
@param vec1: A 3d vector.
@type vec2: Vector object.
@param vec2: A 3d vector.
@rtype: Vector object.
@return: A new vector representing the cross product of
the two vectors.
"""
def DotVecs(vec1, vec2):
"""
Return the dot product of two vectors.
@attention: B{DEPRECATED} use vector.dot(other) instead.
@type vec1: Vector object.
@param vec1: A 2d,3d or 4d vector.
@type vec2: Vector object.
@param vec2: A 2d,3d or 4d vector.
@rtype: float
@return: Return the scalar product of vector muliplication.
"""
def AngleBetweenVecs(vec1, vec2):
"""
Return the angle between two vectors. Zero length vectors raise an error.
@type vec1: Vector object.
@param vec1: A 2d or 3d vector.
@type vec2: Vector object.
@param vec2: A 2d or 3d vector.
@rtype: float
@return: The angle between the vectors in degrees.
@raise AttributeError: When there is a zero-length vector as an argument.
"""
def MidpointVecs(vec1, vec2):
"""
Return a vector to the midpoint between two vectors.
@type vec1: Vector object.
@param vec1: A 2d,3d or 4d vector.
@type vec2: Vector object.
@param vec2: A 2d,3d or 4d vector.
@rtype: Vector object
@return: The vector to the midpoint.
"""
def VecMultMat(vec, mat):
"""
Multiply a vector and matrix (pre-multiply)
Vector size and matrix column size must equal.
@type vec: Vector object.
@param vec: A 2d,3d or 4d vector.
@type mat: Matrix object.
@param mat: A 2d,3d or 4d matrix.
@rtype: Vector object
@return: The row vector that results from the muliplication.
@attention: B{DEPRECATED} You should now multiply vector * matrix direcly
Example::
result = myVector * myMatrix
"""
def ProjectVecs(vec1, vec2):
"""
Return the projection of vec1 onto vec2.
@type vec1: Vector object.
@param vec1: A 2d,3d or 4d vector.
@type vec2: Vector object.
@param vec2: A 2d,3d or 4d vector.
@rtype: Vector object
@return: The parallel projection vector.
"""
def RotationMatrix(angle, matSize, axisFlag, axis):
"""
Create a matrix representing a rotation.
@type angle: float
@param angle: The angle of rotation desired.
@type matSize: int
@param matSize: The size of the rotation matrix to construct.
Can be 2d, 3d, or 4d.
@type axisFlag: string (optional)
@param axisFlag: Possible values:
- "x - x-axis rotation"
- "y - y-axis rotation"
- "z - z-axis rotation"
- "r - arbitrary rotation around vector"
@type axis: Vector object. (optional)
@param axis: The arbitrary axis of rotation used with "R"
@rtype: Matrix object.
@return: A new rotation matrix.
"""
def TranslationMatrix(vector):
"""
Create a matrix representing a translation
@type vector: Vector object
@param vector: The translation vector
@rtype: Matrix object.
@return: An identity matrix with a translation.
"""
def ScaleMatrix(factor, matSize, axis):
"""
Create a matrix representing a scaling.
@type factor: float
@param factor: The factor of scaling to apply.
@type matSize: int
@param matSize: The size of the scale matrix to construct.
Can be 2d, 3d, or 4d.
@type axis: Vector object. (optional)
@param axis: Direction to influence scale.
@rtype: Matrix object.
@return: A new scale matrix.
"""
def OrthoProjectionMatrix(plane, matSize, axis):
"""
Create a matrix to represent an orthographic projection
@type plane: string
@param plane: Can be any of the following:
- "x - x projection (2D)"
- "y - y projection (2D)"
- "xy - xy projection"
- "xz - xz projection"
- "yz - yz projection"
- "r - arbitrary projection plane"
@type matSize: int
@param matSize: The size of the projection matrix to construct.
Can be 2d, 3d, or 4d.
@type axis: Vector object. (optional)
@param axis: Arbitrary perpendicular plane vector.
@rtype: Matrix object.
@return: A new projeciton matrix.
"""
def ShearMatrix(plane, factor, matSize):
"""
Create a matrix to represent an orthographic projection
@type plane: string
@param plane: Can be any of the following:
- "x - x shear (2D)"
- "y - y shear (2D)"
- "xy - xy shear"
- "xz - xz shear"
- "yz - yz shear"
@type factor: float
@param factor: The factor of shear to apply.
@type matSize: int
@param matSize: The size of the projection matrix to construct.
Can be 2d, 3d, or 4d.
@rtype: Matrix object.
@return: A new shear matrix.
"""
def CopyMat(matrix):
"""
Create a copy of the Matrix object.
@type matrix: Matrix object.
@param matrix: A 2d,3d or 4d matrix to be copied.
@rtype: Matrix object.
@return: A new matrix object which is a copy of the one passed in.
@attention: B{DEPRECATED} Use the matrix copy funtion to make a copy.
Example::
newMat = myMat.copy()
"""
def MatMultVec(mat, vec):
"""
Multiply a matrix and a vector (post-multiply)
Vector size and matrix row size must equal.
@type vec: Vector object.
@param vec: A 2d,3d or 4d vector.
@type mat: Matrix object.
@param mat: A 2d,3d or 4d matrix.
@rtype: Vector object
@return: The column vector that results from the muliplication.
@attention: B{DEPRECATED} You should use direct muliplication on the arguments
Example::
result = myMatrix * myVector
"""
def CopyQuat(quaternion):
"""
Create a copy of the Quaternion object.
@type quaternion: Quaternion object.
@param quaternion: Quaternion to be copied.
@rtype: Quaternion object.
@return: A new quaternion object which is a copy of the one passed in.
@attention: B{DEPRECATED} You should use the Quaterion() constructor directly
to create copies of quaternions
Example::
newQuat = Quaternion(myQuat)
"""
def CrossQuats(quat1, quat2):
"""
Return the cross product of two quaternions.
@attention: B{DEPRECATED} use quat.cross(other) instead.
@type quat1: Quaternion object.
@param quat1: Quaternion.
@type quat2: Quaternion object.
@param quat2: Quaternion.
@rtype: Quaternion object.
@return: A new quaternion representing the cross product of
the two quaternions.
"""
def DotQuats(quat1, quat2):
"""
Return the dot product of two quaternions.
@attention: B{DEPRECATED} use quat.dot(other) instead.
@type quat1: Quaternion object.
@param quat1: Quaternion.
@type quat2: Quaternion object.
@param quat2: Quaternion.
@rtype: float
@return: Return the scalar product of quaternion muliplication.
"""
def DifferenceQuats(quat1, quat2):
"""
Returns a quaternion represting the rotational difference.
@type quat1: Quaternion object.
@param quat1: Quaternion.
@type quat2: Quaternion object.
@param quat2: Quaternion.
@rtype: Quaternion object
@return: Return a quaternion which which represents the rotational
difference between the two quat rotations.
"""
def Slerp(quat1, quat2, factor):
"""
Returns the interpolation of two quaternions.
@type quat1: Quaternion object.
@param quat1: Quaternion.
@type quat2: Quaternion object.
@param quat2: Quaternion.
@type factor: float
@param factor: The interpolation value
@rtype: Quaternion object
@return: The interpolated rotation.
"""
def CopyEuler(euler):
"""
Create a new euler object.
@type euler: Euler object
@param euler: The euler to copy
@rtype: Euler object
@return: A copy of the euler object passed in.
@attention: B{DEPRECATED} You should use the Euler constructor directly
to make copies of Euler objects
Example::
newEuler = Euler(myEuler)
"""
def RotateEuler(euler, angle, axis):
"""
Roatate a euler by an amount in degrees around an axis.
@type euler: Euler object
@param euler: Euler to rotate.
@type angle: float
@param angle: The amount of rotation in degrees
@type axis: string
@param axis: axis to rotate around:
- "x"
- "y"
- "z"
"""
class Vector:
"""
The Vector object
=================
This object gives access to Vectors in Blender.
@group Axises: x, y, z, w
@ivar x: The x value.
@ivar y: The y value.
@ivar z: The z value (if any).
@ivar w: The w value (if any).
@ivar length: The magnitude of the vector.
@ivar magnitude: This is a synonym for length.
@ivar wrapped: Whether or not this item is wrapped data
@note: Comparison operators can be done on Vector classes:
- >, >=, <, <= test the vector magnitude
- ==, != test vector values e.g. 1,2,3 != 1,2,4 even if they are the same length
@note: Math can be performed on Vector classes
- vec + vec
- vec - vec
- vec * float/int
- vec * matrix
- vec * vec
- vec * quat
- -vec
@note: You can access a vector object like a sequence
- x = vector[0]
- vec_a[:] vec_b
- vec2d[:] vec3d[:2]
@note: Vectors support 'swizzle' operations
- vec.xyz = vec.zyx
- vec.xy = vec.zw
- vec.xxy = vec.wzz
- vec.yzyz = vec.yxyx
See U{http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)}
@attention: Vector data can be wrapped or non-wrapped. When a object is wrapped it
means that the object will give you direct access to the data inside of blender. Modification
of this object will directly change the data inside of blender. To copy a wrapped object
you need to use the object's constructor. If you copy and object by assignment you will not get
a second copy but a second reference to the same data. Only certain functions will return
wrapped data. This will be indicated in the method description.
Example::
wrappedObject = Object.getAttribute() #this is wrapped data
print wrappedObject.wrapped #prints 'True'
copyOfObject = wrappedObject.copy() #creates a copy of the object
secondPointer = wrappedObject #creates a second pointer to the same data
print wrappedObject.attribute #prints '5'
secondPointer.attribute = 10
print wrappedObject.attribute #prints '10'
print copyOfObject.attribute #prints '5'
"""
def __init__(list = None):
"""
Create a new 2d, 3d, or 4d Vector object from a list of floating point numbers.
@note: that python uses higher precission floating point numbers, so values assigned to a vector may have some rounding error.
Example::
v = Vector(1,0,0)
v = Vector(myVec)
v = Vector(list)
@type list: PyList of float or int
@param list: The list of values for the Vector object. Can be a sequence or raw numbers.
Must be 2, 3, or 4 values. The list is mapped to the parameters as [x,y,z,w].
@rtype: Vector object.
@return: It depends wheter a parameter was passed:
- (list): Vector object initialized with the given values;
- (): An empty 3 dimensional vector.
"""
def copy():
"""
Returns a copy of this vector
@return: a copy of itself
"""
def zero():
"""
Set all values to zero.
@return: an instance of itself
"""
def normalize():
"""
Normalize the vector, making the length of the vector always 1.0
@note: Normalize works for vectors of all sizes, however 4D Vectors w axis is left untouched.
@note: Normalizing a vector where all values are zero results in all axis having a nan value (not a number).
@return: an instance of itself
"""
def negate():
"""
Set all values to their negative.
@return: an instance of its self
"""
def resize2D():
"""
Resize the vector to 2d.
@return: an instance of itself
"""
def resize3D():
"""
Resize the vector to 3d. New axis will be 0.0.
@return: an instance of itself
"""
def resize4D():
"""
Resize the vector to 4d. New axis will be 0.0.
The last component will be 1.0, to make multiplying 3d vectors by 4x4 matrices easier.
@return: an instance of itself
"""
def toTrackQuat(track, up):
"""
Return a quaternion rotation from the vector and the track and up axis.
@type track: String.
@param track: Possible values:
- "x - x-axis up"
- "y - y-axis up"
- "z - z-axis up"
- "-x - negative x-axis up"
- "-y - negative y-axis up"
- "-z - negative z-axis up"
@type up: String.
@param up: Possible values:
- "x - x-axis up"
- "y - y-axis up"
- "z - z-axis up"
@rtype: Quaternion
@return: Return a quaternion rotation from the vector and the track and up axis.
"""
def reflect(mirror):
"""
Return the reflection vector from the mirror vector argument.
@type mirror: Vector object
@param mirror: This vector could be a normal from the reflecting surface.
@rtype: Vector object matching the size of this vector.
@return: The reflected vector.
"""
def cross(other):
"""
Return the cross product of this vector and another.
@note: both vectors must be 3D.
@type other: Vector object
@param other: The other vector to perform the cross product with.
@rtype: Vector
@return: The cross product.
"""
def dot(other):
"""
Return the dot product of this vector and another.
@note: both vectors must be the same size.
@type other: Vector object
@param other: The other vector to perform the dot product with.
@rtype: float
@return: The dot product.
"""
class Euler:
"""
The Euler object
================
This object gives access to Eulers in Blender.
@group Axises: x, y, z
@ivar x: The heading value in degrees.
@ivar y: The pitch value in degrees.
@ivar z: The roll value in degrees.
@ivar wrapped: Whether or not this object is wrapping data directly
@note: You can access a euler object like a sequence
- x = euler[0]
@note: Comparison operators can be done:
- ==, != test numeric values within epsilon
@attention: Euler data can be wrapped or non-wrapped. When a object is wrapped it
means that the object will give you direct access to the data inside of blender. Modification
of this object will directly change the data inside of blender. To copy a wrapped object
you need to use the object's constructor. If you copy and object by assignment you will not get
a second copy but a second reference to the same data. Only certain functions will return
wrapped data. This will be indicated in the method description.
Example::
wrappedObject = Object.getAttribute() #this is wrapped data
print wrappedObject.wrapped #prints 'True'
copyOfObject = wrappedObject.copy() #creates a copy of the object
secondPointer = wrappedObject #creates a second pointer to the same data
print wrappedObject.attribute #prints '5'
secondPointer.attribute = 10
print wrappedObject.attribute #prints '10'
print copyOfObject.attribute #prints '5'
"""
def __init__(list = None):
"""
Create a new euler object.
Example::
euler = Euler(45,0,0)
euler = Euler(myEuler)
euler = Euler(sequence)
@type list: PyList of float/int
@param list: 3d list to initialize euler
@rtype: Euler object
@return: Euler representing heading, pitch, bank.
@note: Values are in degrees.
"""
def zero():
"""
Set all values to zero.
@return: an instance of itself
"""
def copy():
"""
@return: a copy of this euler.
"""
def unique():
"""
Calculate a unique rotation for this euler. Avoids gimble lock.
@return: an instance of itself
"""
def toMatrix():
"""
Return a matrix representation of the euler.
@rtype: Matrix object
@return: A 3x3 roation matrix representation of the euler.
"""
def toQuat():
"""
Return a quaternion representation of the euler.
@rtype: Quaternion object
@return: Quaternion representation of the euler.
"""
def makeCompatible(eul_compat):
"""
Make this euler compatible with another, so interpolating between them works as expected.
@rtype: Euler object
@return: an instance of itself
"""
class Quaternion:
"""
The Quaternion object
=====================
This object gives access to Quaternions in Blender.
@group Axises: x, y, z, w
@ivar w: The w value.
@ivar x: The x value.
@ivar y: The y value.
@ivar z: The z value.
@ivar wrapped: Wether or not this object wraps data directly
@ivar magnitude: The magnitude of the quaternion.
@ivar axis: Vector representing the axis of rotation.
@ivar angle: A scalar representing the amount of rotation
in degrees.
@note: Comparison operators can be done:
- ==, != test numeric values within epsilon
@note: Math can be performed on Quaternion classes
- quat + quat
- quat - quat
- quat * float/int
- quat * vec
- quat * quat
@note: You can access a quaternion object like a sequence
- x = quat[0]
@attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
means that the object will give you direct access to the data inside of blender. Modification
of this object will directly change the data inside of blender. To copy a wrapped object
you need to use the object's constructor. If you copy and object by assignment you will not get
a second copy but a second reference to the same data. Only certain functions will return
wrapped data. This will be indicated in the method description.
Example::
wrappedObject = Object.getAttribute() #this is wrapped data
print wrappedObject.wrapped #prints 'True'
copyOfObject = wrappedObject.copy() #creates a copy of the object
secondPointer = wrappedObject #creates a second pointer to the same data
print wrappedObject.attribute #prints '5'
secondPointer.attribute = 10
print wrappedObject.attribute #prints '10'
print copyOfObject.attribute #prints '5'
"""
def __init__(list, angle = None):
"""
Create a new quaternion object from initialized values.
Example::
quat = Quaternion(1,2,3,4)
quat = Quaternion(axis, angle)
quat = Quaternion()
quat = Quaternion(180, list)
@type list: PyList of int/float
@param list: A 3d or 4d list to initialize quaternion.
4d if intializing [w,x,y,z], 3d if used as an axis of rotation.
@type angle: float (optional)
@param angle: An arbitrary rotation amount around 'list'.
List is used as an axis of rotation in this case.
@rtype: New quaternion object.
@return: It depends wheter a parameter was passed:
- (list/angle): Quaternion object initialized with the given values;
- (): An identity 4 dimensional quaternion.
"""
def identity():
"""
Set the quaternion to the identity quaternion.
@return: an instance of itself
"""
def copy():
"""
make a copy of the quaternion.
@return: a copy of itself
"""
def negate():
"""
Set the quaternion to its negative.
@return: an instance of itself
"""
def conjugate():
"""
Set the quaternion to its conjugate.
@return: an instance of itself
"""
def inverse():
"""
Set the quaternion to its inverse
@return: an instance of itself
"""
def normalize():
"""
Normalize the quaternion.
@return: an instance of itself
"""
def toEuler(eul_compat):
"""
Return Euler representation of the quaternion.
@type eul_compat: L{Euler}
@param eul_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.
@rtype: Euler object
@return: Euler representation of the quaternion.
"""
def toMatrix():
"""
Return a matrix representation of the quaternion.
@rtype: Matrix object
@return: A 3x3 rotation matrix representation of the quaternion.
"""
def cross(other):
"""
Return the cross product of this quaternion and another.
@type other: Quaterion object
@param other: The other quaternion to perform the cross product with.
@rtype: Vector
@return: The cross product.
"""
def dot(other):
"""
Return the dot product of this quaternion and another.
@type other: Quaterion object
@param other: The other quaternion to perform the dot product with.
@rtype: float
@return: The dot product.
"""
class Matrix:
"""
The Matrix Object
=================
This object gives access to Matrices in Blender.
@ivar rowSize: The row size of the matrix.
@ivar colSize: The column size of the matrix.
@ivar wrapped: Whether or not this object wrapps internal data
@note: Math can be performed on Matrix classes
- mat + mat
- mat - mat
- mat * float/int
- mat * vec
- mat * mat
@note: Comparison operators can be done:
- ==, != test numeric values within epsilon
@note: You can access a quaternion object like a 2d sequence
- x = matrix[0][1]
- vector = matrix[2]
@attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
means that the object will give you direct access to the data inside of blender. Modification
of this object will directly change the data inside of blender. To copy a wrapped object
you need to use the object's constructor. If you copy and object by assignment you will not get
a second copy but a second reference to the same data. Only certain functions will return
wrapped data. This will be indicated in the method description.
Example::
wrappedObject = Object.getAttribute() #this is wrapped data
print wrappedObject.wrapped #prints 'True'
copyOfObject = wrappedObject.copy() #creates a copy of the object
secondPointer = wrappedObject #creates a second pointer to the same data
print wrappedObject.attribute #prints '5'
secondPointer.attribute = 10
print wrappedObject.attribute #prints '10'
print copyOfObject.attribute #prints '5'
"""
def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
"""
Create a new matrix object from initialized values.
Example::
matrix = Matrix([1,1,1],[0,1,0],[1,0,0])
matrix = Matrix(mat)
matrix = Matrix(seq1, seq2, vector)
@type list1: PyList of int/float
@param list1: A 2d,3d or 4d list.
@type list2: PyList of int/float
@param list2: A 2d,3d or 4d list.
@type list3: PyList of int/float
@param list3: A 2d,3d or 4d list.
@type list4: PyList of int/float
@param list4: A 2d,3d or 4d list.
@rtype: New matrix object.
@return: It depends wheter a parameter was passed:
- (list1, etc.): Matrix object initialized with the given values;
- (): An empty 3 dimensional matrix.
"""
def zero():
"""
Set all matrix values to 0.
@return: an instance of itself
"""
def copy():
"""
Returns a copy of this matrix
@return: a copy of itself
"""
def identity():
"""
Set the matrix to the identity matrix.
An object with zero location and rotation, a scale of 1, will have an identity matrix.
See U{http://en.wikipedia.org/wiki/Identity_matrix}
@return: an instance of itself
"""
def transpose():
"""
Set the matrix to its transpose.
See U{http://en.wikipedia.org/wiki/Transpose}
@return: None
"""
def determinant():
"""
Return the determinant of a matrix.
See U{http://en.wikipedia.org/wiki/Determinant}
@rtype: float
@return: Return a the determinant of a matrix.
"""
def invert():
"""
Set the matrix to its inverse.
See U{http://en.wikipedia.org/wiki/Inverse_matrix}
@return: an instance of itself.
@raise ValueError: When matrix is singular.
"""
def rotationPart():
"""
Return the 3d submatrix corresponding to the linear term of the
embedded affine transformation in 3d. This matrix represents rotation
and scale. Note that the (4,4) element of a matrix can be used for uniform
scaling, too.
@rtype: Matrix object.
@return: Return the 3d matrix for rotation and scale.
"""
def translationPart():
"""
Return a the translation part of a 4 row matrix.
@rtype: Vector object.
@return: Return a the translation of a matrix.
"""
def scalePart():
"""
Return a the scale part of a 3x3 or 4x4 matrix.
@note: This method does not return negative a scale on any axis because it is not possible to obtain this data from the matrix alone.
@rtype: Vector object.
@return: Return a the scale of a matrix.
"""
def resize4x4():
"""
Resize the matrix to by 4x4
@return: an instance of itself.
"""
def toEuler(eul_compat):
"""
Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).
@type eul_compat: L{Euler}
@param eul_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.
@rtype: Euler object
@return: Euler representation of the rotation matrix.
"""
def toQuat():
"""
Return a quaternion representation of the rotation matrix
@rtype: Quaternion object
@return: Quaternion representation of the rotation matrix
"""

45
source/blender/python/doc/epy/testbgl.py Normal file
View File

@ -0,0 +1,45 @@
# Testing the BGL module
import Blender
from Blender.BGL import *
from Blender import Draw
R = G = B = 0
A = 1
instructions = "Hold mouse buttons to change the background color."
quitting = " Press ESC or q to quit."
def show_win():
glClearColor(R,G,B,A) # define color used to clear buffers
glClear(GL_COLOR_BUFFER_BIT) # use it to clear the color buffer
glColor3f(1,1,1) # change default color
glRasterPos2i(50,100) # move cursor to x = 50, y = 100
Draw.Text("Testing BGL + Draw") # draw this text there
glRasterPos2i(350,20) # move cursor again
Draw.Text(instructions + quitting) # draw another msg
glBegin(GL_LINE_LOOP) # begin a vertex-data list
glVertex2i(46,92)
glVertex2i(120,92)
glVertex2i(120,115)
glVertex2i(46,115)
glEnd() # close this list
glColor3f(0.35,0.18,0.92) # change default color again
glBegin(GL_POLYGON) # another list, for a polygon
glVertex2i(315, 292)
glVertex2i(412, 200)
glVertex2i(264, 256)
glEnd()
Draw.Redraw(1) # make changes visible.
def ev(evt, val): # this is a callback for Draw.Register()
global R,G,B,A # it handles input events
if evt == Draw.ESCKEY or evt == Draw.QKEY:
Draw.Exit() # this quits the script
elif evt == Draw.LEFTMOUSE: R = 1 - R
elif evt == Draw.MIDDLEMOUSE: G = 1 - G
elif evt == Draw.RIGHTMOUSE: B = 1 - B
else:
Draw.Register(show_win, ev, None)
Draw.Register(show_win, ev, None) # start the main loop