2010 October 12 / j|d|a|v|i|s|@|c|a|r|l|e|t|o|n|.|e|d|u

# Utility Functions

beginUserInterface()

Starts the user interface running. Call this after the initial scene is set up. After this, all user events are handled by the window(s).

nestSum(a, b)

Returns the sum a + b of two nested lists of numbers, assuming that they have the same structure.

nestDifference(a, b)

Returns the difference a - b of two nested lists of numbers, assuming that they have the same structure.

nestScaling(t, a)

Returns the scaling t * a of a nested list of numbers a by a scalar t.

nestCombination(a, t, b)

Returns the combination a + t * b of two nested lists of numbers, assuming that they have the same structure.

nestInterpolation(a, t, b)

Returns the interpolation a + t * (b - a) of two nested lists of numbers, assuming that they have the same structure.

nestDot(a, b)

Returns the dot product a.b of two nested lists of numbers, assuming that they have the same structure.

nestNorm(a)

Returns the square root of the dot product of the nested list of numbers with itself. For example, if the nest is a vector, then returns the length of the vector.

nestNormalized(a)

Returns the normalization of the nest a --- that is, the nest of the same structure, whose overall Euclidean norm is 1, and whose elements have the same signs as the elements of a do.

vectorSum(v, w)

Deprecated; use nest version. Returns the sum of 3-dimensional vectors.

vectorDifference(v, w)

Deprecated; use nest version. Returns the difference v - w of 3-dimensional vectors.

vectorScaling(v, s)

Deprecated; use nest version. Returns the 3-dimensional vector scaled by the given scalar.

vectorNorm(v)

Deprecated; use nest version. Returns the length of the 3-dimensional vector.

unitVector(v)

Deprecated; use nest version. Returns the 3-dimensional vector scaled to unit length, or the zero vector.

dotProduct(v, w)

Deprecated; use nest version. Returns the dot product of two 3-dimensional vectors.

crossProduct(v, w)

Returns the cross product of two 3-dimensional vectors.

arccos(x)

Clamps x to the interval [-1, 1], then takes the inverse cosine.

cartesianFromSpherical(rpt)

Returns Cartesian coordinates [x, y, z] for spherical coordinates rpt = (rho, phi, theta). Typically 0 <= rho, 0 <= phi <= pi, 0 <= theta <= 2 * pi.

sphericalFromCartesian(v)

Returns spherical coordinates [rho, phi, theta] for Cartesian coordinates v = (x, y, z). Satisfies 0 <= rho, 0 <= phi <= pi, 0 <= theta <= 2 * pi.

quaternionProduct(a, b)

Returns the product of two quaternions in rectangular [w, x, y, z] form.

quaternionFromAngleAxis(au)

Given an angle-axis rotation [a, [u1, u2, u3]], returns the rotation as a quaternion [w, x, y, z].

angleAxisFromQuaternion(wxyz)

Given a quaternion in the form [w, x, y, z], returns an angle-axis description [a, [u1, u2, u3]] of the same rotation.

angleFromAxisAndVectors(u, v, w)

Returns the angle in radians, such that a rotation about u takes v to w. All input vectors must be unit.

matrixInverse3(a)

Returns the inverse of the given 3x3 matrix a, or None if it is not invertible. All matrices are given as flat sequences in row-major order.

matrixTranspose(a, m, n)

Returns the nxm transpose of the given mxn matrix a. All matrices are given as flat sequences in row-major order. The entries in the matrix can be of any type, and of mixed types.

matrixProduct(a, b, m, n, p)

Returns the product of an mxn matrix a and an nxp matrix b, as an mxp matrix. All matrices are given as flat sequences in row-major order.

affineMatrixProduct(a, b)

Takes as input two 4x4 affine matrices --- that is, matrices with last row (0.0, 0.0, 0.0, 1.0) --- as length-16 sequences in row-major order. Returns their matrix product, in the same format.

perpendicularUnitVector(v)

Given a unit vector, returns a unit vector perpendicular to it.

angleAxisFromVectors(v, w)

Given two unit vectors v and w, returns the angle-axis rotation about v x w that takes v to w. If v and w are parallel, then v x w is ill-defined, and this function chooses it arbitrarily.

quaternionFromVectors(v, w)

Given two unit vectors v and w, returns the quaternion representing the rotation about v x w that takes v to w. If v and w are parallel, then v x w is ill-defined, and this function chooses it to be [0, 0, 1] arbitrarily.

vectorRotated(au, v)

Returns the vector v rotated by the angle-axis rotation au.

Returns the real solutions to the quadratic polynomial a t^2 + b t + c = 0. If a = b = c = 0 then all t are solutions; this is signaled by returning None. Otherwise a list of 0, 1, or 2 numbers is returned. If 2 are returned, then the first is less than the second.

lineSphereIntersection(a, v, c, rr, backside=False)

Intersects a line and a sphere. The line is described parametrically by a + t * v. The sphere is described by its center c and radius-squared rr. The backside parameter indicates whether the first (False) or second (True) solution is desired. If there is just one solution, then backside has no effect. If there is no solution, then None is returned.

linePlaneIntersection(a, v, c, n)

Intersects a line and a plane. The line is described parametrically by a + t * v. The plane is described by a point c and a normal vector n. If there is no solution, then None is returned.

cubicBijection(t)

A smooth, increasing, bijective function from the interval [0.0, 1.0] to itself, with derivative zero at both ends. Very similar to cubicCutoff. Useful for smooth animations.

cubicCutoff(d)

A smooth, decreasing, bijective function from the interval [0.0, 1.0] to itself, with derivative zero at both ends. Very similar to cubicBijection. Useful for cutting off nonzero functions.

cubicCutoffDerivative(d)

The derivative of cubicCutoff with respect to its argument.