View Source Graphmath.Vec3 (graphmath v2.6.0)

This is the 3D mathematics.

This submodule handles 3D vectors using tuples of floats ex: {1.0, 2.0, 3.0}.

Summary

Functions

add( a, b) adds two vec3s.

chebyshev_distance(a,b) returns the Chebyshev distance between two points a and b.

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.

minkowski_distance(a,b,order) returns the Minkowski distance between two points a and b of order order.

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.

p_norm(v,order) returns the P-norm of vector v of order order.

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.

Types

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

Functions

@spec 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 { a<sub>x</sub> + b<sub>x</sub>, a<sub>y</sub> + b<sub>y</sub>, a<sub>z</sub> + b<sub>z</sub> }.

Link to this function

chebyshev_distance(arg1, arg2)

View Source
@spec chebyshev_distance(vec3(), vec3()) :: number()

chebyshev_distance(a,b) returns the Chebyshev distance between two points a and b.

@spec create() :: vec3()

create() creates a zeroed vec3.

It takes no arguments.

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

@spec 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.

@spec 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}.

@spec 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 ( a<sub>y</sub>b<sub>z</sub> - a<sub>z</sub>b<sub>y</sub>, a<sub>z</sub>b<sub>x</sub> - a<sub>x</sub>b<sub>z</sub>, a<sub>x</sub>b<sub>y</sub> - a<sub>y</sub>b<sub>x</sub>).

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.

@spec 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 (a<sub>x</sub>b<sub>x</sub> + a<sub>y</sub>b<sub>y</sub> + a<sub>z</sub>b<sub>z</sub>).

@spec 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.

@spec 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.

@spec 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( a<sub>x</sub><sup>2</sup> + a<sub>y</sub><sup>2</sup> + a<sub>z</sub><sup>2</sup>)).

@spec 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 (a<sub>x</sub> + a<sub>y</sub> + a<sub>z</sub>).

The Manhattan length is the sum of the components.

@spec 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 a<sub>x</sub><sup>2</sup> + a<sub>y</sub><sup>2</sup> + a<sub>z</sub><sup>2</sup>.

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

@spec 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

minkowski_distance(arg1, arg2, order)

View Source
@spec minkowski_distance(vec3(), vec3(), number()) :: number()

minkowski_distance(a,b,order) returns the Minkowski distance between two points a and b of order order.

order needs to be greater than or equal to 1 to define a metric space.

order 1 is equivalent to manhattan distance, 2 to Euclidean distance, otherwise all bets are off.

@spec 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 { a<sub>x</sub>b<sub>x</sub>, a<sub>y</sub>b<sub>y</sub>, a<sub>z</sub>b<sub>z</sub> }.

Link to this function

near(arg1, arg2, distance)

View Source
@spec 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.

@spec negate(vec3()) :: vec3()

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

@spec 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.

@spec p_norm(vec3(), number()) :: number()

p_norm(v,order) returns the P-norm of vector v of order order.

order needs to be greater than or equal to 1 to define a metric space.

order 1 is equivalent to manhattan distance, 2 to Euclidean distance, otherwise all bets are off.

@spec 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.

@spec 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.

@spec 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.

@spec 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:

V<sub>rot</sub> = Vcos(theta) + (K x V)sin(theta) + K(K dot V)(1-cos(theta))

Link to this function

scalar_triple(arg1, arg2, arg3)

View Source
@spec 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.

@spec 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 { a<sub>x</sub>scale, a<sub>y</sub>scale, a<sub>z</sub>scale }.

@spec 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 { a<sub>x</sub> - b<sub>x</sub>, a<sub>y</sub> - b<sub>y</sub>, a<sub>z</sub> - b<sub>z</sub> }.

(the terminology was found here).

Link to this function

weighted_sum(a, arg1, b, arg2)

View Source
@spec 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.