Mathutils

1 # Blender.Mathutils module and its subtypes 2 3 """ 4 The Blender.Mathutils submodule. 5 6 Mathutils 7 ========= 8 (when accessing it from the Game Engine use Mathutils instead of Blender.Mathutils) 9 10 This module provides access to matrices, eulers, quaternions and vectors. 11 12 Example:: 13 import Blender 14 from Blender import Mathutils 15 from Blender.Mathutils import * 16 17 vec = Vector([1,2,3]) 18 mat = RotationMatrix(90, 4, 'x') 19 matT = TranslationMatrix(vec) 20 21 matTotal = mat * matT 22 matTotal.invert() 23 24 mat3 = matTotal.rotationPart 25 quat1 = mat.toQuat() 26 quat2 = mat3.toQuat() 27 28 angle = DifferenceQuats(quat1, quat2) 29 print angle 30 31 @group Deprecated: CopyMat, CopyVec, CopyQuat, CopyEuler, RotateEuler, MatMultVec, VecMultMat, CrossVecs, DotVecs, CrossQuats, DotQuats 32 """ 33

34 -def Rand (low=0.0, high = 1.0):

35 """ 36 Return a random number within a range. 37 low and high represent are optional parameters which represent the range 38 from which the random number must return its result. 39 @type low: float 40 @param low: The lower range. 41 @type high: float 42 @param high: The upper range. 43 """

44

45 -def Intersect(vec1, vec2, vec3, ray, orig, clip=1):

46 """ 47 Return the intersection between a ray and a triangle, if possible, return None otherwise. 48 @type vec1: Vector object. 49 @param vec1: A 3d vector, one corner of the triangle. 50 @type vec2: Vector object. 51 @param vec2: A 3d vector, one corner of the triangle. 52 @type vec3: Vector object. 53 @param vec3: A 3d vector, one corner of the triangle. 54 @type ray: Vector object. 55 @param ray: A 3d vector, the orientation of the ray. the length of the ray is not used, only the direction. 56 @type orig: Vector object. 57 @param orig: A 3d vector, the origin of the ray. 58 @type clip: integer 59 @param clip: if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle. 60 @rtype: Vector object 61 @return: The intersection between a ray and a triangle, if possible, None otherwise. 62 """

63

64 -def TriangleArea(vec1, vec2, vec3):

65 """ 66 Return the area size of the 2D or 3D triangle defined. 67 @type vec1: Vector object. 68 @param vec1: A 2d or 3d vector, one corner of the triangle. 69 @type vec2: Vector object. 70 @param vec2: A 2d or 3d vector, one corner of the triangle. 71 @type vec3: Vector object. 72 @param vec3: A 2d or 3d vector, one corner of the triangle. 73 @rtype: float 74 @return: The area size of the 2D or 3D triangle defined. 75 """

76

77 -def TriangleNormal(vec1, vec2, vec3):

78 """ 79 Return the normal of the 3D triangle defined. 80 @type vec1: Vector object. 81 @param vec1: A 3d vector, one corner of the triangle. 82 @type vec2: Vector object. 83 @param vec2: A 3d vector, one corner of the triangle. 84 @type vec3: Vector object. 85 @param vec3: A 3d vector, one corner of the triangle. 86 @rtype: float 87 @return: The normal of the 3D triangle defined. 88 """

89

90 -def QuadNormal(vec1, vec2, vec3, vec4):

91 """ 92 Return the normal of the 3D quad defined. 93 @type vec1: Vector object. 94 @param vec1: A 3d vector, the first vertex of the quad. 95 @type vec2: Vector object. 96 @param vec2: A 3d vector, the second vertex of the quad. 97 @type vec3: Vector object. 98 @param vec3: A 3d vector, the third vertex of the quad. 99 @type vec4: Vector object. 100 @param vec4: A 3d vector, the fourth vertex of the quad. 101 @rtype: float 102 @return: The normal of the 3D quad defined. 103 """

104

105 -def LineIntersect(vec1, vec2, vec3, vec4):

106 """ 107 Return a tuple with the points on each line respectively closest to the other 108 (when both lines intersect, both vector hold the same value). 109 The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line. 110 @type vec1: Vector object. 111 @param vec1: A 3d vector, one point on the first line. 112 @type vec2: Vector object. 113 @param vec2: A 3d vector, another point on the first line. 114 @type vec3: Vector object. 115 @param vec3: A 3d vector, one point on the second line. 116 @type vec4: Vector object. 117 @param vec4: A 3d vector, another point on the second line. 118 @rtype: (Vector object, Vector object) 119 @return: A tuple with the points on each line respectively closest to the other. 120 """

121

122 -def CopyVec(vector):

123 """ 124 Create a copy of the Vector object. 125 @attention: B{DEPRECATED} use vector.copy() instead. 126 @type vector: Vector object. 127 @param vector: A 2d,3d or 4d vector to be copied. 128 @rtype: Vector object. 129 @return: A new vector object which is a copy of the one passed in. 130 """

131

132 -def CrossVecs(vec1, vec2):

133 """ 134 Return the cross product of two vectors. 135 @attention: B{DEPRECATED} use vector.cross(other) instead. 136 @type vec1: Vector object. 137 @param vec1: A 3d vector. 138 @type vec2: Vector object. 139 @param vec2: A 3d vector. 140 @rtype: Vector object. 141 @return: A new vector representing the cross product of 142 the two vectors. 143 """

144

145 -def DotVecs(vec1, vec2):

146 """ 147 Return the dot product of two vectors. 148 @attention: B{DEPRECATED} use vector.dot(other) instead. 149 @type vec1: Vector object. 150 @param vec1: A 2d,3d or 4d vector. 151 @type vec2: Vector object. 152 @param vec2: A 2d,3d or 4d vector. 153 @rtype: float 154 @return: Return the scalar product of vector muliplication. 155 """

156

157 -def AngleBetweenVecs(vec1, vec2):

158 """ 159 Return the angle between two vectors. Zero length vectors raise an error. 160 @type vec1: Vector object. 161 @param vec1: A 2d or 3d vector. 162 @type vec2: Vector object. 163 @param vec2: A 2d or 3d vector. 164 @rtype: float 165 @return: The angle between the vectors in degrees. 166 @raise AttributeError: When there is a zero-length vector as an argument. 167 """

168

169 -def MidpointVecs(vec1, vec2):

170 """ 171 Return a vector to the midpoint between two vectors. 172 @type vec1: Vector object. 173 @param vec1: A 2d,3d or 4d vector. 174 @type vec2: Vector object. 175 @param vec2: A 2d,3d or 4d vector. 176 @rtype: Vector object 177 @return: The vector to the midpoint. 178 """

179

180 -def VecMultMat(vec, mat):

181 """ 182 Multiply a vector and matrix (pre-multiply) 183 Vector size and matrix column size must equal. 184 @type vec: Vector object. 185 @param vec: A 2d,3d or 4d vector. 186 @type mat: Matrix object. 187 @param mat: A 2d,3d or 4d matrix. 188 @rtype: Vector object 189 @return: The row vector that results from the muliplication. 190 @attention: B{DEPRECATED} You should now multiply vector * matrix direcly 191 Example:: 192 result = myVector * myMatrix 193 """

194

195 -def ProjectVecs(vec1, vec2):

196 """ 197 Return the projection of vec1 onto vec2. 198 @type vec1: Vector object. 199 @param vec1: A 2d,3d or 4d vector. 200 @type vec2: Vector object. 201 @param vec2: A 2d,3d or 4d vector. 202 @rtype: Vector object 203 @return: The parallel projection vector. 204 """

205

206 -def RotationMatrix(angle, matSize, axisFlag, axis):

207 """ 208 Create a matrix representing a rotation. 209 @type angle: float 210 @param angle: The angle of rotation desired. 211 @type matSize: int 212 @param matSize: The size of the rotation matrix to construct. 213 Can be 2d, 3d, or 4d. 214 @type axisFlag: string (optional) 215 @param axisFlag: Possible values: 216 - "x - x-axis rotation" 217 - "y - y-axis rotation" 218 - "z - z-axis rotation" 219 - "r - arbitrary rotation around vector" 220 @type axis: Vector object. (optional) 221 @param axis: The arbitrary axis of rotation used with "R" 222 @rtype: Matrix object. 223 @return: A new rotation matrix. 224 """

225

226 -def TranslationMatrix(vector):

227 """ 228 Create a matrix representing a translation 229 @type vector: Vector object 230 @param vector: The translation vector 231 @rtype: Matrix object. 232 @return: An identity matrix with a translation. 233 """

234

235 -def ScaleMatrix(factor, matSize, axis):

236 """ 237 Create a matrix representing a scaling. 238 @type factor: float 239 @param factor: The factor of scaling to apply. 240 @type matSize: int 241 @param matSize: The size of the scale matrix to construct. 242 Can be 2d, 3d, or 4d. 243 @type axis: Vector object. (optional) 244 @param axis: Direction to influence scale. 245 @rtype: Matrix object. 246 @return: A new scale matrix. 247 """

248

249 -def OrthoProjectionMatrix(plane, matSize, axis):

250 """ 251 Create a matrix to represent an orthographic projection 252 @type plane: string 253 @param plane: Can be any of the following: 254 - "x - x projection (2D)" 255 - "y - y projection (2D)" 256 - "xy - xy projection" 257 - "xz - xz projection" 258 - "yz - yz projection" 259 - "r - arbitrary projection plane" 260 @type matSize: int 261 @param matSize: The size of the projection matrix to construct. 262 Can be 2d, 3d, or 4d. 263 @type axis: Vector object. (optional) 264 @param axis: Arbitrary perpendicular plane vector. 265 @rtype: Matrix object. 266 @return: A new projeciton matrix. 267 """

268

269 -def ShearMatrix(plane, factor, matSize):

270 """ 271 Create a matrix to represent an orthographic projection 272 @type plane: string 273 @param plane: Can be any of the following: 274 - "x - x shear (2D)" 275 - "y - y shear (2D)" 276 - "xy - xy shear" 277 - "xz - xz shear" 278 - "yz - yz shear" 279 @type factor: float 280 @param factor: The factor of shear to apply. 281 @type matSize: int 282 @param matSize: The size of the projection matrix to construct. 283 Can be 2d, 3d, or 4d. 284 @rtype: Matrix object. 285 @return: A new shear matrix. 286 """

287

288 -def CopyMat(matrix):

289 """ 290 Create a copy of the Matrix object. 291 @type matrix: Matrix object. 292 @param matrix: A 2d,3d or 4d matrix to be copied. 293 @rtype: Matrix object. 294 @return: A new matrix object which is a copy of the one passed in. 295 @attention: B{DEPRECATED} Use the matrix copy funtion to make a copy. 296 Example:: 297 newMat = myMat.copy() 298 """

299

300 -def MatMultVec(mat, vec):

301 """ 302 Multiply a matrix and a vector (post-multiply) 303 Vector size and matrix row size must equal. 304 @type vec: Vector object. 305 @param vec: A 2d,3d or 4d vector. 306 @type mat: Matrix object. 307 @param mat: A 2d,3d or 4d matrix. 308 @rtype: Vector object 309 @return: The column vector that results from the muliplication. 310 @attention: B{DEPRECATED} You should use direct muliplication on the arguments 311 Example:: 312 result = myMatrix * myVector 313 """

314

315 -def CopyQuat(quaternion):

316 """ 317 Create a copy of the Quaternion object. 318 @type quaternion: Quaternion object. 319 @param quaternion: Quaternion to be copied. 320 @rtype: Quaternion object. 321 @return: A new quaternion object which is a copy of the one passed in. 322 @attention: B{DEPRECATED} You should use the Quaterion() constructor directly 323 to create copies of quaternions 324 Example:: 325 newQuat = Quaternion(myQuat) 326 """

327

328 -def CrossQuats(quat1, quat2):

329 """ 330 Return the cross product of two quaternions. 331 @attention: B{DEPRECATED} use quat.cross(other) instead. 332 @type quat1: Quaternion object. 333 @param quat1: Quaternion. 334 @type quat2: Quaternion object. 335 @param quat2: Quaternion. 336 @rtype: Quaternion object. 337 @return: A new quaternion representing the cross product of 338 the two quaternions. 339 """

340

341 -def DotQuats(quat1, quat2):

342 """ 343 Return the dot product of two quaternions. 344 @attention: B{DEPRECATED} use quat.dot(other) instead. 345 @type quat1: Quaternion object. 346 @param quat1: Quaternion. 347 @type quat2: Quaternion object. 348 @param quat2: Quaternion. 349 @rtype: float 350 @return: Return the scalar product of quaternion muliplication. 351 """

352

353 -def DifferenceQuats(quat1, quat2):

354 """ 355 Returns a quaternion represting the rotational difference. 356 @type quat1: Quaternion object. 357 @param quat1: Quaternion. 358 @type quat2: Quaternion object. 359 @param quat2: Quaternion. 360 @rtype: Quaternion object 361 @return: Return a quaternion which which represents the rotational 362 difference between the two quat rotations. 363 """

364

365 -def Slerp(quat1, quat2, factor):

366 """ 367 Returns the interpolation of two quaternions. 368 @type quat1: Quaternion object. 369 @param quat1: Quaternion. 370 @type quat2: Quaternion object. 371 @param quat2: Quaternion. 372 @type factor: float 373 @param factor: The interpolation value 374 @rtype: Quaternion object 375 @return: The interpolated rotation. 376 """

377

378 -def CopyEuler(euler):

379 """ 380 Create a new euler object. 381 @type euler: Euler object 382 @param euler: The euler to copy 383 @rtype: Euler object 384 @return: A copy of the euler object passed in. 385 @attention: B{DEPRECATED} You should use the Euler constructor directly 386 to make copies of Euler objects 387 Example:: 388 newEuler = Euler(myEuler) 389 """

390

391 -def RotateEuler(euler, angle, axis):

392 """ 393 Roatate a euler by an amount in degrees around an axis. 394 @type euler: Euler object 395 @param euler: Euler to rotate. 396 @type angle: float 397 @param angle: The amount of rotation in degrees 398 @type axis: string 399 @param axis: axis to rotate around: 400 - "x" 401 - "y" 402 - "z" 403 """

404

405 -class Vector:

406 """ 407 The Vector object 408 ================= 409 This object gives access to Vectors in Blender. 410 @group Axises: x, y, z, w 411 @ivar x: The x value. 412 @ivar y: The y value. 413 @ivar z: The z value (if any). 414 @ivar w: The w value (if any). 415 @ivar length: The magnitude of the vector. 416 @ivar magnitude: This is a synonym for length. 417 @ivar wrapped: Whether or not this item is wrapped data 418 @note: Comparison operators can be done on Vector classes: 419 - >, >=, <, <= test the vector magnitude 420 - ==, != test vector values e.g. 1,2,3 != 1,2,4 even if they are the same length 421 @note: Math can be performed on Vector classes 422 - vec + vec 423 - vec - vec 424 - vec * float/int 425 - vec * matrix 426 - vec * vec 427 - vec * quat 428 - -vec 429 @note: You can access a vector object like a sequence 430 - x = vector[0] 431 - vec_a[:] vec_b 432 - vec2d[:] vec3d[:2] 433 @note: Vectors support 'swizzle' operations 434 - vec.xyz = vec.zyx 435 - vec.xy = vec.zw 436 - vec.xxy = vec.wzz 437 - vec.yzyz = vec.yxyx 438 439 See U{http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)} 440 441 @attention: Vector data can be wrapped or non-wrapped. When a object is wrapped it 442 means that the object will give you direct access to the data inside of blender. Modification 443 of this object will directly change the data inside of blender. To copy a wrapped object 444 you need to use the object's constructor. If you copy and object by assignment you will not get 445 a second copy but a second reference to the same data. Only certain functions will return 446 wrapped data. This will be indicated in the method description. 447 Example:: 448 wrappedObject = Object.getAttribute() #this is wrapped data 449 print wrappedObject.wrapped #prints 'True' 450 copyOfObject = wrappedObject.copy() #creates a copy of the object 451 secondPointer = wrappedObject #creates a second pointer to the same data 452 print wrappedObject.attribute #prints '5' 453 secondPointer.attribute = 10 454 print wrappedObject.attribute #prints '10' 455 print copyOfObject.attribute #prints '5' 456 """ 457

458 - def __init__(list = None):

459 """ 460 Create a new 2d, 3d, or 4d Vector object from a list of floating point numbers. 461 @note: that python uses higher precission floating point numbers, so values assigned to a vector may have some rounding error. 462 463 464 Example:: 465 v = Vector(1,0,0) 466 v = Vector(myVec) 467 v = Vector(list) 468 @type list: PyList of float or int 469 @param list: The list of values for the Vector object. Can be a sequence or raw numbers. 470 Must be 2, 3, or 4 values. The list is mapped to the parameters as [x,y,z,w]. 471 @rtype: Vector object. 472 @return: It depends wheter a parameter was passed: 473 - (list): Vector object initialized with the given values; 474 - (): An empty 3 dimensional vector. 475 """

476

477 - def copy():

478 """ 479 Returns a copy of this vector 480 @return: a copy of itself 481 """

482

483 - def zero():

484 """ 485 Set all values to zero. 486 @return: an instance of itself 487 """

488

489 - def normalize():

490 """ 491 Normalize the vector, making the length of the vector always 1.0 492 @note: Normalize works for vectors of all sizes, however 4D Vectors w axis is left untouched. 493 @note: Normalizing a vector where all values are zero results in all axis having a nan value (not a number). 494 @return: an instance of itself 495 """

496

497 - def negate():

498 """ 499 Set all values to their negative. 500 @return: an instance of its self 501 """

502

503 - def resize2D():

504 """ 505 Resize the vector to 2d. 506 @return: an instance of itself 507 """

508

509 - def resize3D():

510 """ 511 Resize the vector to 3d. New axis will be 0.0. 512 @return: an instance of itself 513 """

514

515 - def resize4D():

516 """ 517 Resize the vector to 4d. New axis will be 0.0. 518 The last component will be 1.0, to make multiplying 3d vectors by 4x4 matrices easier. 519 @return: an instance of itself 520 """

521

522 - def toTrackQuat(track, up):

523 """ 524 Return a quaternion rotation from the vector and the track and up axis. 525 @type track: String. 526 @param track: Possible values: 527 - "x - x-axis up" 528 - "y - y-axis up" 529 - "z - z-axis up" 530 - "-x - negative x-axis up" 531 - "-y - negative y-axis up" 532 - "-z - negative z-axis up" 533 @type up: String. 534 @param up: Possible values: 535 - "x - x-axis up" 536 - "y - y-axis up" 537 - "z - z-axis up" 538 @rtype: Quaternion 539 @return: Return a quaternion rotation from the vector and the track and up axis. 540 """

541

542 - def reflect(mirror):

543 """ 544 Return the reflection vector from the mirror vector argument. 545 @type mirror: Vector object 546 @param mirror: This vector could be a normal from the reflecting surface. 547 @rtype: Vector object matching the size of this vector. 548 @return: The reflected vector. 549 """

550

551 - def cross(other):

552 """ 553 Return the cross product of this vector and another. 554 @note: both vectors must be 3D. 555 @type other: Vector object 556 @param other: The other vector to perform the cross product with. 557 @rtype: Vector 558 @return: The cross product. 559 """

560

561 - def dot(other):

562 """ 563 Return the dot product of this vector and another. 564 @note: both vectors must be the same size. 565 @type other: Vector object 566 @param other: The other vector to perform the dot product with. 567 @rtype: float 568 @return: The dot product. 569 """

570

571 -class Euler:

572 """ 573 The Euler object 574 ================ 575 This object gives access to Eulers in Blender. 576 @group Axises: x, y, z 577 @ivar x: The heading value in degrees. 578 @ivar y: The pitch value in degrees. 579 @ivar z: The roll value in degrees. 580 @ivar wrapped: Whether or not this object is wrapping data directly 581 @note: You can access a euler object like a sequence 582 - x = euler[0] 583 @note: Comparison operators can be done: 584 - ==, != test numeric values within epsilon 585 @attention: Euler data can be wrapped or non-wrapped. When a object is wrapped it 586 means that the object will give you direct access to the data inside of blender. Modification 587 of this object will directly change the data inside of blender. To copy a wrapped object 588 you need to use the object's constructor. If you copy and object by assignment you will not get 589 a second copy but a second reference to the same data. Only certain functions will return 590 wrapped data. This will be indicated in the method description. 591 Example:: 592 wrappedObject = Object.getAttribute() #this is wrapped data 593 print wrappedObject.wrapped #prints 'True' 594 copyOfObject = wrappedObject.copy() #creates a copy of the object 595 secondPointer = wrappedObject #creates a second pointer to the same data 596 print wrappedObject.attribute #prints '5' 597 secondPointer.attribute = 10 598 print wrappedObject.attribute #prints '10' 599 print copyOfObject.attribute #prints '5' 600 """ 601

602 - def __init__(list = None):

603 """ 604 Create a new euler object. 605 606 Example:: 607 euler = Euler(45,0,0) 608 euler = Euler(myEuler) 609 euler = Euler(sequence) 610 @type list: PyList of float/int 611 @param list: 3d list to initialize euler 612 @rtype: Euler object 613 @return: Euler representing heading, pitch, bank. 614 @note: Values are in degrees. 615 """

616

617 - def zero():

618 """ 619 Set all values to zero. 620 @return: an instance of itself 621 """

622

623 - def copy():

624 """ 625 @return: a copy of this euler. 626 """

627

628 - def unique():

629 """ 630 Calculate a unique rotation for this euler. Avoids gimble lock. 631 @return: an instance of itself 632 """

633

634 - def toMatrix():

635 """ 636 Return a matrix representation of the euler. 637 @rtype: Matrix object 638 @return: A 3x3 roation matrix representation of the euler. 639 """

640

641 - def toQuat():

642 """ 643 Return a quaternion representation of the euler. 644 @rtype: Quaternion object 645 @return: Quaternion representation of the euler. 646 """

647 - def makeCompatible(eul_compat):

648 """ 649 Make this euler compatible with another, so interpolating between them works as expected. 650 @rtype: Euler object 651 @return: an instance of itself 652 """

653

654 -class Quaternion:

655 """ 656 The Quaternion object 657 ===================== 658 This object gives access to Quaternions in Blender. 659 @group Axises: x, y, z, w 660 @ivar w: The w value. 661 @ivar x: The x value. 662 @ivar y: The y value. 663 @ivar z: The z value. 664 @ivar wrapped: Wether or not this object wraps data directly 665 @ivar magnitude: The magnitude of the quaternion. 666 @ivar axis: Vector representing the axis of rotation. 667 @ivar angle: A scalar representing the amount of rotation 668 in degrees. 669 @note: Comparison operators can be done: 670 - ==, != test numeric values within epsilon 671 @note: Math can be performed on Quaternion classes 672 - quat + quat 673 - quat - quat 674 - quat * float/int 675 - quat * vec 676 - quat * quat 677 @note: You can access a quaternion object like a sequence 678 - x = quat[0] 679 @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it 680 means that the object will give you direct access to the data inside of blender. Modification 681 of this object will directly change the data inside of blender. To copy a wrapped object 682 you need to use the object's constructor. If you copy and object by assignment you will not get 683 a second copy but a second reference to the same data. Only certain functions will return 684 wrapped data. This will be indicated in the method description. 685 Example:: 686 wrappedObject = Object.getAttribute() #this is wrapped data 687 print wrappedObject.wrapped #prints 'True' 688 copyOfObject = wrappedObject.copy() #creates a copy of the object 689 secondPointer = wrappedObject #creates a second pointer to the same data 690 print wrappedObject.attribute #prints '5' 691 secondPointer.attribute = 10 692 print wrappedObject.attribute #prints '10' 693 print copyOfObject.attribute #prints '5' 694 """ 695

696 - def __init__(list, angle = None):

697 """ 698 Create a new quaternion object from initialized values. 699 700 Example:: 701 quat = Quaternion(1,2,3,4) 702 quat = Quaternion(axis, angle) 703 quat = Quaternion() 704 quat = Quaternion(180, list) 705 706 @type list: PyList of int/float 707 @param list: A 3d or 4d list to initialize quaternion. 708 4d if intializing [w,x,y,z], 3d if used as an axis of rotation. 709 @type angle: float (optional) 710 @param angle: An arbitrary rotation amount around 'list'. 711 List is used as an axis of rotation in this case. 712 @rtype: New quaternion object. 713 @return: It depends wheter a parameter was passed: 714 - (list/angle): Quaternion object initialized with the given values; 715 - (): An identity 4 dimensional quaternion. 716 """

717

718 - def identity():

719 """ 720 Set the quaternion to the identity quaternion. 721 @return: an instance of itself 722 """

723

724 - def copy():

725 """ 726 make a copy of the quaternion. 727 @return: a copy of itself 728 """

729

730 - def negate():

731 """ 732 Set the quaternion to its negative. 733 @return: an instance of itself 734 """

735

736 - def conjugate():

737 """ 738 Set the quaternion to its conjugate. 739 @return: an instance of itself 740 """

741

742 - def inverse():

743 """ 744 Set the quaternion to its inverse 745 @return: an instance of itself 746 """

747

748 - def normalize():

749 """ 750 Normalize the quaternion. 751 @return: an instance of itself 752 """

753

754 - def toEuler(eul_compat):

755 """ 756 Return Euler representation of the quaternion. 757 @type eul_compat: L{Euler} 758 @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. 759 @rtype: Euler object 760 @return: Euler representation of the quaternion. 761 """

762

763 - def toMatrix():

764 """ 765 Return a matrix representation of the quaternion. 766 @rtype: Matrix object 767 @return: A 3x3 rotation matrix representation of the quaternion. 768 """

769

770 - def cross(other):

771 """ 772 Return the cross product of this quaternion and another. 773 @type other: Quaterion object 774 @param other: The other quaternion to perform the cross product with. 775 @rtype: Vector 776 @return: The cross product. 777 """

778

779 - def dot(other):

780 """ 781 Return the dot product of this quaternion and another. 782 @type other: Quaterion object 783 @param other: The other quaternion to perform the dot product with. 784 @rtype: float 785 @return: The dot product. 786 """

787

788 -class Matrix:

789 """ 790 The Matrix Object 791 ================= 792 This object gives access to Matrices in Blender. 793 @ivar rowSize: The row size of the matrix. 794 @ivar colSize: The column size of the matrix. 795 @ivar wrapped: Whether or not this object wrapps internal data 796 @note: Math can be performed on Matrix classes 797 - mat + mat 798 - mat - mat 799 - mat * float/int 800 - mat * vec 801 - mat * mat 802 @note: Comparison operators can be done: 803 - ==, != test numeric values within epsilon 804 @note: You can access a quaternion object like a 2d sequence 805 - x = matrix[0][1] 806 - vector = matrix[2] 807 @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it 808 means that the object will give you direct access to the data inside of blender. Modification 809 of this object will directly change the data inside of blender. To copy a wrapped object 810 you need to use the object's constructor. If you copy and object by assignment you will not get 811 a second copy but a second reference to the same data. Only certain functions will return 812 wrapped data. This will be indicated in the method description. 813 Example:: 814 wrappedObject = Object.getAttribute() #this is wrapped data 815 print wrappedObject.wrapped #prints 'True' 816 copyOfObject = wrappedObject.copy() #creates a copy of the object 817 secondPointer = wrappedObject #creates a second pointer to the same data 818 print wrappedObject.attribute #prints '5' 819 secondPointer.attribute = 10 820 print wrappedObject.attribute #prints '10' 821 print copyOfObject.attribute #prints '5' 822 """ 823

824 - def __init__(list1 = None, list2 = None, list3 = None, list4 = None):

825 """ 826 Create a new matrix object from initialized values. 827 828 Example:: 829 matrix = Matrix([1,1,1],[0,1,0],[1,0,0]) 830 matrix = Matrix(mat) 831 matrix = Matrix(seq1, seq2, vector) 832 833 @type list1: PyList of int/float 834 @param list1: A 2d,3d or 4d list. 835 @type list2: PyList of int/float 836 @param list2: A 2d,3d or 4d list. 837 @type list3: PyList of int/float 838 @param list3: A 2d,3d or 4d list. 839 @type list4: PyList of int/float 840 @param list4: A 2d,3d or 4d list. 841 @rtype: New matrix object. 842 @return: It depends wheter a parameter was passed: 843 - (list1, etc.): Matrix object initialized with the given values; 844 - (): An empty 3 dimensional matrix. 845 """

846

847 - def zero():

848 """ 849 Set all matrix values to 0. 850 @return: an instance of itself 851 """

852 853

854 - def copy():

855 """ 856 Returns a copy of this matrix 857 @return: a copy of itself 858 """

859

860 - def identity():

861 """ 862 Set the matrix to the identity matrix. 863 An object with zero location and rotation, a scale of 1, will have an identity matrix. 864 865 See U{http://en.wikipedia.org/wiki/Identity_matrix} 866 @return: an instance of itself 867 """

868

869 - def transpose():

870 """ 871 Set the matrix to its transpose. 872 873 See U{http://en.wikipedia.org/wiki/Transpose} 874 @return: None 875 """

876

877 - def determinant():

878 """ 879 Return the determinant of a matrix. 880 881 See U{http://en.wikipedia.org/wiki/Determinant} 882 @rtype: float 883 @return: Return a the determinant of a matrix. 884 """

885

886 - def invert():

887 """ 888 Set the matrix to its inverse. 889 890 See U{http://en.wikipedia.org/wiki/Inverse_matrix} 891 @return: an instance of itself. 892 @raise ValueError: When matrix is singular. 893 """

894

895 - def rotationPart():

896 """ 897 Return the 3d submatrix corresponding to the linear term of the 898 embedded affine transformation in 3d. This matrix represents rotation 899 and scale. Note that the (4,4) element of a matrix can be used for uniform 900 scaling, too. 901 @rtype: Matrix object. 902 @return: Return the 3d matrix for rotation and scale. 903 """

904

905 - def translationPart():

906 """ 907 Return a the translation part of a 4 row matrix. 908 @rtype: Vector object. 909 @return: Return a the translation of a matrix. 910 """

911

912 - def scalePart():

913 """ 914 Return a the scale part of a 3x3 or 4x4 matrix. 915 @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. 916 @rtype: Vector object. 917 @return: Return a the scale of a matrix. 918 """

919

920 - def resize4x4():

921 """ 922 Resize the matrix to by 4x4 923 @return: an instance of itself. 924 """

925

926 - def toEuler(eul_compat):

927 """ 928 Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only). 929 @type eul_compat: L{Euler} 930 @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. 931 @rtype: Euler object 932 @return: Euler representation of the rotation matrix. 933 """

934

935 - def toQuat():

936 """ 937 Return a quaternion representation of the rotation matrix 938 @rtype: Quaternion object 939 @return: Quaternion representation of the rotation matrix 940 """

941

Source Code for Module Mathutils