graphmath v2.4.0 Graphmath.Vec3

This is the 3D mathematics library for graphmath.

This submodule handles 3D vectors using tuples of floats.

Link to this section Summary

Functions

add( a, b) adds two vec3s

create() creates a zeroed vec3

create(vec) creates a vec3 from a list of 3 or more floats

create(x,y,z) creates a vec3 of value (x,y,z)

cross( a, b) finds the cross productof one vec3 with another vec3

dot( a, b) finds the dot (inner) product of one vec3 with another vec3

equal(a, b) checks to see if two vec3s a and b are equivalent

equal(a, b, eps) checks to see if two vec3s a and b are equivalent within some tolerance

length(a) finds the length (Eucldiean or L2 norm) of a vec3

length_manhattan(a) finds the Manhattan (L1 norm) length of a vec3

length_squared(a) finds the square of the length of a vec3

lerp(a,b,t) linearly interpolates between one vec3 and another vec3 along an interpolant

multiply( a, b) multiplies element-wise a vec3 by another vec3

near(a,b, distance) checks whether two vec3s are within a certain distance of each other

negate(v) creates a vector whose elements are opposite in sign to v

normalize(a) finds the unit vector with the same direction as a vec3

random_ball() gives a point at or within unit distance of the origin, using the last algo here

random_box() gives a point on or in the unit box [0,1]x[0,1]x[0,1]

random_sphere() gives a point at or within unit distance of the origin, using this polar method. Another really nice exploration of this is here

rotate( v, k, theta) rotates a vector (v) about a unit vector (k) by theta radians

scalar_triple(a,b,c) returns the scalar triple product of three vectors

scale( a, scale) uniformly scales a vec3

subtract(a, b) subtracts one vec3 from another vec3

weighted_sum(a, v1, b, v2) returns the sum of vectors v1 and v2 having been scaled by a and b, respectively

Link to this section Types

Link to this type

vec3()
vec3() :: {float(), float(), float()}

Link to this section Functions

Link to this function

add(a, b)
add(vec3(), vec3()) :: vec3()

add( a, b) adds two vec3s.

a is the first vec3.

b is the second vec3.

It returns a vec3 of the form { ax + bx, ay + by, az + bz }.

Link to this function

create()
create() :: vec3()

create() creates a zeroed vec3.

It takes no arguments.

It returns a vec3 of the form { 0.0, 0.0, 0.0 }.

Link to this function

create(vec)
create([float()]) :: vec3()

create(vec) creates a vec3 from a list of 3 or more floats.

vec is a list of 3 or more floats.

It returns a vec3 of the form {x,y,z}, where x, y, and z are the first three elements in vec.

Link to this function

create(x, y, z)
create(float(), float(), float()) :: vec3()

create(x,y,z) creates a vec3 of value (x,y,z).

x is the first element of the vec3 to be created.

y is the second element of the vec3 to be created.

z is the third element of the vec3 to be created.

It returns a vec3 of the form {x,y,z}.

Link to this function

cross(a, b)
cross(vec3(), vec3()) :: vec3()

cross( a, b) finds the cross productof one vec3 with another vec3.

a is the first vec3.

b is the second vec3.

It returns a float of the value ( aybz - azby, azbx - axbz, axby - aybx).

The cross product of two vectors is a vector perpendicular to the two source vectors. Its magnitude will be the area of the parallelogram made by the two souce vectors.

Link to this function

dot(a, b)
dot(vec3(), vec3()) :: float()

dot( a, b) finds the dot (inner) product of one vec3 with another vec3.

a is the first vec3.

b is the second vec3.

It returns a float of the value (axbx + ayby + azbz).

Link to this function

equal(arg1, arg2)
equal(vec3(), vec3()) :: boolean()

equal(a, b) checks to see if two vec3s a and b are equivalent.

a is the vec3.

b is the vec3.

It returns true if the vectors have equal elements.

Note that due to precision issues, you may want to use equal/3 instead.

Link to this function

equal(arg1, arg2, eps)
equal(vec3(), vec3(), float()) :: boolean()

equal(a, b, eps) checks to see if two vec3s a and b are equivalent within some tolerance.

a is the vec3.

b is the vec3.

eps is the tolerance, a float.

It returns true if the vectors have equal elements within some tolerance.

Link to this function

length(a)
length(vec3()) :: float()

length(a) finds the length (Eucldiean or L2 norm) of a vec3.

a is the vec3 to find the length of.

It returns a float of the value (sqrt( ax2 + ay2 + az2)).

Link to this function

length_manhattan(a)
length_manhattan(vec3()) :: float()

length_manhattan(a) finds the Manhattan (L1 norm) length of a vec3.

a is the vec3 to find the Manhattan length of.

It returns a float of the value (ax + ay + az).

The Manhattan length is the sum of the components.

Link to this function

length_squared(a)
length_squared(vec3()) :: float()

length_squared(a) finds the square of the length of a vec3.

a is the vec3 to find the length squared of.

It returns a float of the value ax2 + ay2 + az2.

In many cases, this is sufficient for comparisons and avoids a square root.

Link to this function

lerp(a, b, t)
lerp(vec3(), vec3(), float()) :: vec3()

lerp(a,b,t) linearly interpolates between one vec3 and another vec3 along an interpolant.

a is the starting vec3.

b is the ending vec3.

t is the interpolant float, on the domain [0,1].

It returns a vec3 of the form (1-t)a - (t)b.

The interpolant t is on the domain [0,1]. Behavior outside of that is undefined.

Link to this function

multiply(a, b)
multiply(vec3(), vec3()) :: vec3()

multiply( a, b) multiplies element-wise a vec3 by another vec3.

a is the vec3 multiplicand.

b is the vec3 multiplier.

It returns a vec3 of the form { axbx, ayby, azbz }.

Link to this function

near(a, b, distance)
near(vec3(), vec3(), float()) :: boolean()

near(a,b, distance) checks whether two vec3s are within a certain distance of each other.

a is the first vec3.

b is the second vec3.

distance is the distance between them as a float.

Link to this function

negate(arg)
negate(vec3()) :: vec3()

negate(v) creates a vector whose elements are opposite in sign to v.

Link to this function

normalize(a)
normalize(vec3()) :: vec3()

normalize(a) finds the unit vector with the same direction as a vec3.

a is the vec3 to be normalized.

It returns a vec3 of the form {normx, normy, normz}.

This is done by dividing each component by the vector's magnitude.

Link to this function

random_ball()
random_ball() :: vec3()

random_ball() gives a point at or within unit distance of the origin, using the last algo here.

It returns a vec3 within at most unit distance of the origin.

Link to this function

random_box()
random_box() :: vec3()

random_box() gives a point on or in the unit box [0,1]x[0,1]x[0,1].

It returns a vec3.

Link to this function

random_sphere()
random_sphere() :: vec3()

random_sphere() gives a point at or within unit distance of the origin, using this polar method. Another really nice exploration of this is here.

It returns a vec3 within at most unit distance of the origin.

Link to this function

rotate(v, k, theta)
rotate(vec3(), vec3(), float()) :: vec3()

rotate( v, k, theta) rotates a vector (v) about a unit vector (k) by theta radians.

v is the vec3 to be rotated.

k is the vec3 axis of rotation. It must be of unit length.

theta is the angle in radians to rotate as a float.

This uses the Formula of Rodriguez:

Vrot = Vcos(theta) + (K x V)sin(theta) + K(K dot V)(1-cos(theta))

Link to this function

scalar_triple(arg1, arg2, arg3)
scalar_triple(vec3(), vec3(), vec3()) :: float()

scalar_triple(a,b,c) returns the scalar triple product of three vectors.

We're using the a*(b x c) form.

Link to this function

scale(a, scale)
scale(vec3(), float()) :: vec3()

scale( a, scale) uniformly scales a vec3.

a is the vec3 to be scaled.

scale is the float to scale each element of a by.

It returns a tuple of the form { axscale, ayscale, azscale }.

Link to this function

subtract(a, b)
subtract(vec3(), vec3()) :: vec3()

subtract(a, b) subtracts one vec3 from another vec3.

a is the vec3 minuend.

b is the vec3 subtrahend.

It returns a vec3 of the form { ax - bx, ay - by, az - bz }.

(the terminology was found here).

Link to this function

weighted_sum(a, arg1, b, arg2)
weighted_sum(number(), vec3(), number(), vec3()) :: vec3()

weighted_sum(a, v1, b, v2) returns the sum of vectors v1 and v2 having been scaled by a and b, respectively.