[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Utility Classes


UT_Vector3

This is a class which implements a three dimmensional vector. It overloads the standard arthimatic operators to allow intuitive creation of vector valued expressions.


Methods

constructors

The default constructor does not assign any value to the vector.

Other constructors exist for creation from an array of floats, another vector, or to specify all coordinates explicitly.

int equalZero(float tol = 0.00001f) const

Returns one if the vector is within tol of zero in all coordinates.

int isEqual(const UT_Vector3 &vect, float tol = 0.00001f) const

Returns one if the vector is within tol of vect in all coordinates.

void clampZero(float tol = 0.00001f)

Sets each coordinate to zero if it is within tol of zero.

void negate()

Negates each coordinate of the vector

void multiply3(const UT_Matrix4 &mat)

Multiplies this vector by the given matrix, ignoring the 4th row and column.

void multiplyT(const UT_Matrix3 &mat)

Multiply this vector by the transpose of the matrix.

void multiply3(UT_Vector3 &dest, const UT_Matrix4 &mat) const

void multiplyT(UT_Vector3 &dest, const UT_Matrix3 &mat) const

void multiply(UT_Vector3 &dest, const UT_Matrix4 &mat) const

void multiply(UT_Vector3 &dest, const UT_Matrix3 &mat) const

These all multiply this by the matrix, placing the result int dest. Note that dest cannot be this. These may be faster than the operators, due to fewer assignments.

void rowVecMult(const UT_Matrix3 &m)

void rowVecMult(const UT_Matrix4 &m)

void colVecMult(const UT_Matrix4 &m)

void colVecMult(const UT_Matrix3 &m)

To right multiply this vector, use rowVecMult. Use colVecMult to left multiply this vector. The 4d versions will extend this to 4d by adding w = 1.0.

void cross(const UT_Vector3 &v)

void cross(const UT_Vector3 &v1, const UT_Vector3 &v2)

Finds the cross product, storing the result in this.

float dot(const UT_Vector3 &v) const

float dot(const UT_Vector3 &v1, const UT_Vector3 &v2) const

Find the dot product of this and v, or v1 and v2. Returns result.

float normalize (void)

Adjust this vector to be of unit length. Return the square of the original length. Degenerate vectors (0 length) may not be normalized.

void normal(const UT_Vector3 &a, const UT_Vector3 &b)

void normal(const UT_Vector4 &a, const UT_Vector4 &b)

Add a and b to the incremental calculation of a faces surface normal. Result is tracked in this.

float length(void) const

float length2(void) const

Find the respectively the Euclidean length and length squared of this.

UT_Vector3 project(const UT_Vector3 &u)

Returns the projection of u along this.

UT_Matrix3 project(int norm=1)

Creates a matrix to perform projection along this. If norm is non zero, this will first be normalized.

UT_Vector3 projection(const UT_Vector3 &p, const UT_Vector3 &v)

Returns the closest point on the line described by p and the direction vector v to this.

UT_Matrix3 symmetry(int norm=1)

Constructs the matrix to find the symmetry of a vector with this. Ie: two times the projection of v onto (*this) minus v.

int lineIntersect(const UT_Vector3 &p1, const UT_Vector3 &v1, const UT_Vector3 &p2, const UT_Vector3 &v2)

Sets this to the intersection of the lines p1, v1 and p2, v2. If the lines do not actual intersect, set to the closest point on the first line to the second line. If an intersection found, return 0. If none (ie: parallel) return -1. If the intersection occurs in the negative direction, return -2.

int segmentIntersect(const UT_Vector3 &a, const UT_Vector3 &b, const UT_Vector3 &p2, const UT_Vector3 &v2)

Finds the intersection of p2 + t*v2 and (a,b). If no intersection, find closest point on line (a,b) to p2 + t*v2. If intersection occurs within a and b, return 0. If parallel, return -1. If the intersection occurs before a, return -3, if after b, then -2.

float distance(const UT_Vector3 &p1, const UT_Vector3 &v1) const

float distance(const UT_Vector3 &p1, const UT_Vector3 &v1, const UT_Vector3 &p2, const UT_Vector3 &v2) const

Find the signed distance from this to the line, or between two lines.

float &x(void)

float x(void)

float &y(void)

float y(void)

float &z(void)

float z(void)

Access to specified coordinate.

const float *data(void) const

Returns a pointer to an array of floats consisting of the vectors coordinates.

void assign(float xx = 0., float yy = 0., float zz = 0.)

void assign(const float *v)

Set the values of the coordinates, either explicitly or from an array of floats.

void homogenize(void)

void dehomogenize(void)

Homogenize (multiply x and y by z) or dehomogenize (divide x and y by z) this.

int axisIndex(UT_Vector3::axis whichaxis) const

UT_Vector3::axis getAxis(int whichaxis) const

Conversion between axis enumerations and integers.


Operators

=

Assign one vector to another. Assign UT_Vector4 to UT_Vector3 through truncation. Assign all coordinates of this to one scalar.

+=

-=

Add/subtract a UT_Vector3 to this, or a scalar to all coordinates of this.

*=

/=

Multiply/divide a scalar to all coordinates of this.

==

!=

Perform exact equal/not equal test with another UT_Vector3.

()

[]

Access a coordinate of this. Neither () nor [] perform bounds checking.

*

Perform cross product of two UT_Vector3 or multiply a UT_Vector3 by a scalar.

/

Divide a UT_Vector3 by a scalar, or the scalar by the vector (Both result in a UT_Vector3).

+

-

Add/subtract a combination of UT_Vector3s and scalars.


UT_Vector4

The UT_Vector4 class provides easy handling of four dimmensional points. The coordinates are x, y, z, w, in that order. A large subset of UT_Vector3 functions are implemented, with the following exceptions:

project*, lineIntersection, symmetry, segmentIntersection, distance. 

Additional Methods

int equalZero3(float tol = 0.00001f)

void clampZero3(float tol = 0.00001f)

The same as the UT_Vector3 function, except only taking effect on the first three coordinates.

cross, the operator* between two vectors

These perform the cross product only taking into consideration the first three coordinates of the vectors.


UT_Matrix3

The UT_Matrix3 class handles computations of 3x3 floating point valued matrices.


Methods

constructors

The default construct does not initialize anything. A single float will cause the entire matrix to be given its value. An array of floating point values 3x3 in size can also be provided.

A copy constructor is also provided.

UT_Matrix3 copy(void) const

Returns a copy of this.

float coFactor(int k, int l) const

Returns the cofactor of the matrix: the determinant of the submatrix resulting from deleting the kth row and lth column.

float determinant(void) const

Computes and returns the determinant.

int invert(void)

int invert(UT_Matrix3 &m)const

int invertKramer(void)

int invertKramer(UT_Matrix3 &m)const

Inverts this, placing the result either in m or this if m not present. Returns 0 if success, or 1 if this is singular.

void transpose(void)

UT_Matrix3 transpose(void) const

Transposes this in place or return the transpose, not altering this.

void rotate(UT_Vector3 &axis, float theta, int norm=1)

UT_Matrix3 rotate(UT_Vector3 &axis, float theta, int norm=1) const

UT_Matrix3 rotationMat(UT_Vector3 &axis, float theta, int norm=1) const

void rotate(UT_Vector3::axis a, float theta)

UT_Matrix3 rotate(UT_Vector3::axis a, float theta) const

UT_Matrix3 rotationMat(UT_Vector3::axis a, float theta) const

Apply rotation to this around specified axis and angle. Theta is in radians.

void prerotate(UT_Vector3 &axis, float theta, int norm=1)

UT_Matrix3 prerotate(UT_Vector3 &axis, float theta, int norm=1) const

void prerotate(UT_Vector3::axis a, float theta)

UT_Matrix3 prerotate(UT_Vector3::axis a, float theta) const

Same as rotate, but pre-multiply the matrix as opposed to post-multiply.

void prerotate(float rx, float ry, float rz, const UT_XformOrder &order)

UT_Matrix3 prerotate(float rx, float ry, float rz, const UT_XformOrder &order) const

Pre-rotate by rx, ry, rz radians around the three axes in the order specified by order.

void rotate(float rx, float ry, float rz, const UT_XformOrder &ord)

UT_Matrix3 rotate(float rx, float ry, float rz, const UT_XformOrder &ord) const

Rotate matrix by rx, ry, rz radians around the three axes in the order specified by order.

void scale(float sx, float sy, float sz)

UT_Matrix3 scale(float sx, float sy, float sz) const

Scale this matrix by a diagonal matrix of diag(sx,sy,sz).

void prescale(float sx, float sy, float sz)

UT_Matrix3 prescale(float sx, float sy, float sz) const

Pre multiply this matrix by a diagonal matrix of diag(sx,sy,sz).

void translate(float dx, float dy)

UT_Matrix3 translate(float dx, float dy) const

Multiply this by the transform matrix described by dx, dy.

void pretranslate(float dx, float dy)

UT_Matrix3 pretranslate(float dx, float dy) const

Pre-Multiply this by the transform matrix described by dx, dy.

int crack(UT_Vector3 &rvec, const UT_XformOrder &order)

int crack(UT_Vector3 &rvec, const UT_XformOrder &order) const

Generate x, y, z rotation values from matrix. Returns 0 if success, 1 if not valid rotation matrix, 2 if rotOrder is invalid, and 3 for other errors. WARNING: The non-const method chanes the matrix!

int solve(float cx, float cy, float cz, UT_Vector3 &result) const

Solves the 3x3 system of equations whose parameters are held in this, and whose right hand side is cx, cy and cz. Returns 0 if the determinant is not 0, and 1 otherwise.

void changeSpace(UT_Vector3 &iSrc, UT_Vector3 &jSrc, UT_Vector3 &iDest,UT_Vector3 &jDest, int norm=1)

UT_Matrix3 changeSpace(UT_Vector3 &iSrc, UT_Vector3 &jSrc, UT_Vector3 &iDest,UT_Vector3 &jDest, int norm=1) const

Space change operation: right multiply this matrix by the 3x3 matrix of the transformation which moves the vector space defined by (iSrc, jSrc, cross(iSrc,jSrc)) into the space defined by (iDest, jDest, cross(iDest,jDest)). iSrc, jSrc, iDest, and jDest will be normalized before the operation if norm is 1. This matrix transforms iSrc into iDest, and jSrc into jDest.

void xform(const UT_XformOrder &order, float tx=0., float ty=0., float rz=0., float sx=1., float sy=1., float px=0., float py=0., int reverse=0)

UT_Matrix3 xform(const UT_XformOrder &order, float tx=0., float ty=0., float rz=0., float sx=1., float sy=1., float px=0., float py=0., int reverse=0) const

Multiply this matrix by the general transform matrix built from translations (tx,ty), degree rotation (rz), scales (sx,sy), and possibly a pivot point (px,py). The second methos leaves us unchanged, and returns a new (this*xform) instead. The order of the multiplies (SRT, RST, Rz, etc) is stored in 'order'. Normally you will ignore the 'reverse' parameter, which tells us to build the matrix from last to first xform, and to apply some inverses to txy, rz, and sxy.

void stretch(UT_Vector3 &v, float amount, int norm=1)

UT_Matrix3 stretch(UT_Vector3 &v, float amount, int norm=1) const

Right multiply this matrix by a 3x3 matrix which scales by a given amount along the direction of vector v. When applied to a vector w, the stretched matrix (*this) stretches w in v by the amount given. If norm is non-zero, v will be normalized prior to the operation.

int isNormalized() const

Returns 1 if a vector multiplied by this matrix will preserve its length.

float dot(unsigned i, unsigned j) const

Return the dot product between two rows i and j

void identity(void)

UT_Matrix3 identity(void)

Set the matrix to identity or return an identity matrix

void initialize(void)

Set the matrix to zero.


Operators

=

Assignment of matrix. If source is scalar, all elements set to that scalar. If source is a vector, it is extended to a full matrix by repeating it as a column vector.

==, !=

Exact equality/inequality check of two matrices.

*=, +=, -=

Add, multiply, or subtract a scalar/vector3/matrix3 from this.

/=

Divides the matrix by a scalar.

()

Access an element of the matrix. Does not do bounds checking. If only one parameter is provided, returns the entire row as a float *.

[]

Return a row as a UT_Vector3.

*, +, -

Multiplies, adds, subtracts, or divides a matrix from a matrix, float, or scalar. Division only defined for scalar. and multiplication for scalars and matrices.


UT_Matrix4

The UT_Matrix4 class provides support for 4x4 floating valued matrices. Most UT_Matrix3 functions are supported with the exceptions of:

isNormalized, crack (see explode), solve

Additional or Differing Methods

void translate(float dx, float dy, float dz = 0.)

UT_Matrix4 translate(float dx, float dy, float dz = 0.) const

Multiply this by a translation matrix constructed from (dx, dy, dz).

void xform(const UT_XformOrder &order, float tx=0., float ty=0., float tz=0., float rx=0., float ry=0., float rz=0., float sx=1., float sy=1., float sz=1., float px=0., float py=0., float pz=0., int reverse=0)

UT_Matrix4 xform(const UT_XformOrder &order, float tx=0., float ty=0., float tz=0., float rx=0., float ry=0., float rz=0., float sx=1., float sy=1., float sz=1., float px=0., float py=0., float pz=0., int reverse=0) const

Multiply this matrix by the general transform matrix built from translations (tx,ty,tz), degree rotations (rx,ry,rz), scales (sx,sy,sz), and possibly a pivot point (px,py,pz). The second methos leaves us unchanged, and returns a new (this*xform) instead. The order of the multiplies (SRT, RST, RxRyRz, etc) is stored in 'order'. Normally you will ignore the 'reverse' parameter, which tells us to build the matrix from last to first xform, and to apply some inverses to txyz, rxyz, and sxyz.

void xform(const UT_XformOrder &order, applyType type, char limit, float tx, float ty, float tz, float rx, float ry, float rz, float sx, float sy, float sz, float px, float py, float pz)

void rotate(const UT_XformOrder &order, applyType type, char limit, float rx, float ry, float rz);

These versions of xform and rotate can be used to apply selected parts of a transform. The applyType controls how far into the xform it should go. For example: applyXform(order, BEFORE_EQUAL, 'T', ...) will apply all the components of the transform up to and equal to the translates (depending on UT_XformOrder).
For xform char can be T, R, S, P, or p (P is for pivot)
For rotate char can be X, Y, or Z (P is for pivot)

int explode(const UT_XformOrder &order, UT_Vector3 &r, UT_Vector3 &s, UT_Vector3 &t) const

This is a super-crack that returns the translation, scale, and radian rotation vectors given a transformation order and a valid xform matrix. It returns 0 if succesful, and non-zero otherwise: 1 if the embedded rotation matrix is invalid, 2 if the rotation order is invalid, and 3 for other problems. If any of the scaling values is 0, the method returns all zeroes, and a 0 return value.


Table of Contents
Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
Material & Texture | Objects | Command and Expression | Render Output |
Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
Customizing UI | Questions & Answers

Copyright © 2004 Side Effects Software Inc.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7