Crate construct

Expand description

A library for higher order functional programming with homotopy maps to construct 3D geometry.

§What is a homotopy map?

A homotopy is a continuous deformation between two functions. Think about combining two functions f and g with a parameter in the range between 0 and 1 such that setting the parameter to 0 gives you f and setting it to 1 gives you g. With other words, it lets you interpolate smoothly between functions.

This library uses a simplified homotopy version designed for constructing 3D geometry:

/// A function of type `1d -> 3d`.
pub type Fn1<T> = Arc<Fn(T) -> [T; 3] + Sync + Send>;
/// A function of type `2d -> 3d`.
pub type Fn2<T> = Arc<Fn([T; 2]) -> [T; 3] + Sync + Send>;
/// A function of type `3d -> 3d`.
pub type Fn3<T> = Arc<Fn([T; 3]) -> [T; 3] + Sync + Send>;

In this library, these functions are called homotopy maps and usually satisfies these properties:

All inputs are assumed to be normalized, starting at 0 and ending at 1. This means that Fn1 forms a curved line, Fn2 forms a curved quad, and Fn3 forms a curved cube.
The Arc smart pointer makes it possible to clone closures.
The Sync and Send constraints makes it easier to program with multiple threads.
Basic geometric shapes are continuous within the range from 0 to 1.

A curved cube does not mean it need to look like a cube. Actually, you can create a variety of shapes that do not look like cubes at all, e.g. a sphere. What is meant by a “curved cube” is that there are 3 parameters between 0 and 1 controlling the generation of points. If you used an identity map, you would get a cube shape. The transformation to other shapes is the reason it is called a “curved cube”.

§Motivation

Constructing 3D geometry is an iterative process where the final design/need can be quite different from the first draft. In game engines there are additional needs like generating multiple models of various detail or adjusting models depending on the capacity of the target platform. This makes it desirable to have some tools where one can work with an idea without getting slowed down by a lot of technical details.

Homotopy maps have the property that the geometry can be constructed by need, without any additional instructions. This makes it a suitable candidate for combining them with higher order functional programming. Functions give an accurate representation while at the same time being lazy, such that one can e.g. intersect a curved cube to get a curved quad.

This library is an experiment to see how homotopy maps and higher order functional programming can be used to iterate on design. Function names are very short to provide good ergonomics.

Traits§

Cast: Casts into another type.
Float: Convenience trait for floats.
FromPrimitive: Trait for converting from different numeric types
Max: Maximum value.
Min: Minimum value.
One: Number 1.
Powf: Floating number power.
Radians: Useful constants for radians.
Signum: The sign of the number.
Sqrt: Square root.
Trig: Basic trigonometry functions
Zero: Number 0.

Functions§

add2: Adds two vectors.
add3: Adds two vectors.
cast2: Converts to another vector type.
cast3: Converts to another vector type.
cbez: Cubic bezier curve.
circle: Creates a circle located at a center and with a radius.
con: Concatenates two 1d -> 3d functions returning a new function.
contour: Gets the contour line of a curved quad.
conx2: Concatenates two 2d -> 3d functions at x-weight.
conx3: Concatenates two 3d -> 3d functions at x-weight.
cony2: Concatenates two 2d -> 3d functions at y-weight.
cony3: Concates two 3d -> 3d functions at y-weight.
conz3: Concates two 3d -> 3d functions at z-weight.
cquad: Constructs a curved quad by smoothing between boundary functions.
ext1: Extends a 1d shape into 2d by adding a vector to the result generated by a 1d shape.
ext2: Extends a 2d shape into 3d by adding a vector to the result generated by a 1d shape.
len2: Computes the length of vector.
len3: Computes the length of vector.
lin: Returns a linear function.
lin2: Creates a linear interpolation between two functions.
margin1: Adds a margin to input of a 1d -> 3d function.
margin2: Adds a margin to input of a 2d -> 3d function.
margin3: Adds a margin to input of a 3d -> 3d function.
mirx2: Bake mirror 2d -> 3d around yz-plane at x coordinate.
mirx3: Bake mirror 3d -> 3d around yz-plane at x coordinate.
miry2: Bake mirror 2d -> 3d around xz-plane at y coordinate.
miry3: Bake mirror 3d -> 3d around xz-plane at y coordinate.
mirz3: Bake mirror 3d -> 3d around xy-plane at z coordinate.
mx: Mirror shape 1d -> 3d around yz-plane at x coordinate.
my: Mirror shape 1d -> 3d around xz-plane at y coordinate.
mz: Mirror shape 1d -> 3d around xy-plane at z coordinate.
off: Offsets 3d -> 3d at position.
qbez: Quadratic bezier curve.
rev: Reverses input direction.
scale2: Multiplies the vector with a scalar.
scale3: Multiplies the vector with a scalar.
seg1: Uses a range to pick a segment of a curve.
sphere: Creates a sphere located at a center and with a radius.
sub2: Subtracts ‘b’ from ‘a’.
sub3: Subtracts ‘b’ from ‘a’.
x2: Intersects a curved quad at x-line.
x3: Intersects a curved cube at x-plane.
y2: Intersects a curved quad at y-line.
y3: Intersects a curved cube at y-plane.
z3: Intersects a curved cube at z-plane.

Type Aliases§

Fn1: A function of type 1d -> 3d.
Fn2: A function of type 2d -> 3d.
Fn3: A function of type 3d -> 3d.