Fugu Reference built on 25/01/2012

add_slider {...} adds a slider to the ui in fugu
	E.g., add_slider {var="x", value=1, low=0, high=10} creates a slider that 
	binds to the variable "x" in the active module's namespace.	 

R(rad,axis), R(rad,x,y,z) generates a matrix that will rotate a point a number of radians around the specified axis (vec3)

Rv(a:vec3,b:vec3) generates a matrix that will rotate vector a to align with vector b

S(s:vec3) generates a matrix that scales a point by the vector s

T(vec3), T(x,y,z) generates a matrix that translates a point by the given vector

scalef(poslist,center,amount): scales a list of faces around a specified point
	amount 	= 0 -> all vertices will be moved to the center point
   			= 1 -> all vertices will remain in place
   			in (0,1) -> faces will shrink
   			>1 -> faces will grow

transformf(poslist,T) applies transform T to each vertex in poslist

turtle() creates a turtle.
	A turtle can be used either:
	- as a navigation tool 
	- or to create generalised cylinders
	Check the examples for more info.
	
	Member functions:
	move(dist) 
	yaw(angle)
	roll(angle)
	pitch(angle)	
	set_frame(pos,heading,up) -- sets the turtles position heading and orientation
	set_stiffness(s1,s2) -- controls the shape of the generalised cylinder 
	set_scale(scale) -- controls the shape of the generalised cylinder
	set_cross_section(index) -- controls the shape of the generalised cylinder 	
	push -- record current state/position
	pop -- restore to old state/position	
	set_carrier_mode(cm) -- cm=0 use linear interpolation, cm=1 use bezier interpolation 	
	begin_cross_section 
	end_cross_section 	
	begin_cylinder
	end_cylinder
	add_point(n)	
	get_position
	get_heading
	get_up
	get_frame	
	mesh():mesh -- generate and return the generalised cylinder	

help(func) prints the documentation for a given object. Assign documentation with the document function.

show_commands() prints all documented commands

A meshnode is a node that references and transforms a mesh. Multiple meshnodes can reference the same mesh.
	Example usage:
	m = cube()
	n = meshnode(m)
	n:set_transform(R(half_pi,vec3(0,1,0))) -- rotate the mesh 45 degrees around the y axis
	m2 = dodecahedron()
	n:set_mesh(m2) -- change the mesh this node is referencing
	

A node is a positionable and orientable object in a universe.
	Example usage:
	n = node()
	n:set_transform(T(3,0,0)) -- translate by 3 units in the x direction	
	

A universe stores all nodes. 
	There is only one universe, called "fgu". Example usage:
	fgu:add(n) -- adds a node n to the universe
	fgu:make_child_of(parent,child) -- spatially links child to parent
	fgu.t -- returns the age of the universe (in seconds)   
	

abs(x) returns x if x>=0 and -x if x<0

acos(x) arc cosine

asin(x) arc sine

atan(x) arc tangent

atan2(v1,v2) arc tan v1/v2

bias(a,x) 1D bias function

ceil(x) smallest int >= x

clamp(x,a,b) clamps x between a and b

cos(rad) cosine

cosh(rad) hyperbolic cosine

cross(a,b) computes the cross product of vec3 a and b

deg(rad) rad to deg

distance(a,b) computes the distance between points (vec3) a and b

dot(a,b) computes the inner product of vec3 a and b

exp(v) e^v

floor(v) largest int <= v

fmod(x,y) remainder of x/y

fmod(x,y) remainder of x/y

frac_sum(x,y,z,n,falloff) computes n octaves of summed fractal noise

frexp(v) mantissa, exp

gain(g,x) gain control

gamma(g,x) standard gamma correct function

gauss(mean,var) returns a gaussian distributed random number

half_pi = 0.5*pi

huge is a constant larger than any numerical value

inv_sqrt(x) inverse square root

ldexp(v1,v2) v1*2^v2

length(v) computes the length of vec3 v

lerp(a,b,t) interpolates between a and b

log(x) natural log

log10(x) log 10

mat4 represents a 4d matrix. Example usage:
	creation: m = mat4()
	set to identity: m:set_basis(vec3(1,0,0),vec3(0,1,0),vec3(0,0,1))
	element access: m:get(row,col) row=0..3,col=0..3
	operators: m*2, m/3, m+n, m*n, m-n, -m
	make transformation matrix: 
		m:set_rotate_rad(angle,x,y,z)
		m:set_rotate_rad(angle,axis)
		m:set_translate(x,y,z)
		also see global functions R,Rv,T,S for shorthand

max(x,...) max of one or more values

min(x,...) min of one or more values

mix(a,b,t) mixes values a and b by amount t

modf(x) return ix,dx where x=ix+dx and ix is an integer

noise(x), noise(x,y), noise(x,y,z) computes 1D, 2D or 3D Perlin noise

normalise(v) returns vec3 v normlised

pi constant

polar(vec3), polar(x,y,z) convert cartesian to polar coordinates: r,theta,phi

pow(v1,v2) v1^v2

pulse(a,b,x) combines 2 steps: returns 1 if x is between a and b

quat represents a quaternion. It has a number of constructors:	
	quat(a,x,y,z) build component-wise
	quat(axis:vec3, radians) rotate around an axis
	quat(from:vec3, to:vec3) rotates a vector from to align with to
	quat(x_rot,y_rot,z_rot) rotation from euler angles
	quat(mat4) build from rotation matrix
	quat(xaxis:vec3,yaxis:vec3,zaxis:vec3) specify a basis to transform to
	

rad(deg) deg to rad

random(low=0,high=1) returns a random number between low and high inclusive 

random_vec3() is equivalent to vec3(random(),random(),random())
random_vec3(sc) is equivalent to vec3(sc*random(),sc*random(),sc*random())
random_vec3(low,high) is equivalent to vec3(random(low,high),random(low,high),random(low,high))

sign(f) = the sign of f

sin(rad) sine

sinh(rad) hyperbolic sine

slerp(a,b,t) spherically interpolates vec3 a and vec3 b

smoothstep(a,b,x) smooth interpolation using Horner's rule

sqr(x) = the square of x

sqrt(x) square root

step(a,x) = 0 when x < a, 1 otherwise

step_function(list) converts a list of (x,y) pairs into a step function. Example usage:
	local f = step_function {{0,0},{.5,1},{1,0}}
	f(0) -- returns 0
	f(.2) -- returns 0
	f(.5) -- returns 1
	f(.8) -- returns 1
	f(1.1) -- returns 0

tan(rad) tangent

tanh(rad) hyperbolic tangent

turbulence(x,y,z,n,falloff) computes n octaves of Perlin's turbulence function

two_pi = 2*pi

vec3 represents a 3d vector. Example usage:
	creation: v = vec3(1.5,0,4)
	element access: v.x, v.y, v.z (or alternatively v.r, v.g, v.b)
	operators: v*2, v/3, v+w, v-w, -v

capov(cap:poslist) returns the outermost vertices of a cap (a fan of pos'es)

cone(outer_radius,inner_radius,resolution) makes a cone mesh

cube() makes a cube mesh

cylinder(res) makes a cylinder mesh

dodecahedron() makes a dodecahedron mesh

extrude(m:mesh,v:vertex,[dir:vec3],magnitude)
	Extrudes all neighbouring faces in the direction given (or the normal if dir is omitted), and re-orients the
	faces to align perpendicularly along the extrusion axis
	Note: Assumes direction is normalised. 
	Returns the pos loop at the end of the extrusion

extrude_and_scale(m:mesh,v:vertex,dir:vec3,magnitude,scale) extrudes and scales the faces adjacent to v

a face is a triangle within a mesh.
	Attributes:
	n -- normal
	valid -- true if the face is still part of a mesh
	Member functions:
	calculate_normal -- recalculate the normal
	v(i) -- return the i'th vertex of this face (i = 0 to 2)

facelist(m:mesh) returns a list of all faces in the mesh m

flattenvl(m:mesh,vl:list,p:vec3,n:vec3) flattens a list of vertices, vl, so they align on the plane specified by p and n

foreachv(m:mesh,f:function) applies f to each vertex in m

icosahedron() makes an icosahedron mesh

ifaces(faces:poslist) returns an iterator over the faces in this poslist

inset(m:mesh,v:vertex,s:number) insets all the faces surrounding vertex v and scales them by s

iso(res,f) creates an isosurface from function f(x,y,z) within a 2x2x2 space of resolution res

load_mesh(file) loads a mesh from a file. supported formats: obj

loopp(v:vertex) returns the loop of pos'es surrounding v

loopv(v:vertex) returns the loop of vertices surrounding v

mesh is a triangular mesh. You construct a mesh as a primitive (cube,icosahedron,etc.) or with load_mesh().
	Member functions:
	subdivide(n) -- subdivide the mesh n times
	smooth_subdivide(n) -- smooth subdivide the mesh n times (Loop Subdivision)
	sync() -- recalculate all the vertex and face normals
	apply_transform(mtx) -- apply the transform matrix to the mesh vertices
	clone():mesh -- copy the mesh 		

nearbyv(m:mesh,v:vertex,n:integer) returns a list of vertices with edge distance n of v

octahedron() makes an octahedron mesh

a pos is a (vertex,edge,face) triple that uniquely identifies a position on a mesh.
	Constructors:
	pos(f,e,v) -- construct from a face, edge(int) and vertex
	pos(f,v) -- construct from a face and vertex	
	Attributes:
	v -- the vertex
	e -- the edge (an integer from 0 to 2)
	f -- the face
	Properties:
	flip_v, flip_e, flip_f -- navigate the mesh
	
	A pos can walk around a mesh by calling flip_v, flip_e or flip_f. 
	flip_v, for instance, changes the pos by selecting the pos that has the same e and f, but differs in v.	

sphere() makes a spherical mesh

split_edge(mesh,pos) splits the edge in pos into two and retriangulates the adjacent faces

tetrahedron() makes a tetrahedron mesh

tofaces(vl:list) returns a list of those faces adjacent to the vertices in vl

turtle() creates a turtle.
	A turtle can be used either:
	- as a navigation tool 
	- or to create generalised cylinders
	Check the examples for more info.
	
	Member functions:
	move(dist) 
	yaw(angle)
	roll(angle)
	pitch(angle)	
	set_frame(pos,heading,up) -- sets the turtles position heading and orientation
	set_stiffness(s1,s2) -- controls the shape of the generalised cylinder 
	set_scale(scale) -- controls the shape of the generalised cylinder
	set_cross_section(index) -- controls the shape of the generalised cylinder 	
	push -- record current state/position
	pop -- restore to old state/position	
	set_carrier_mode(cm) -- cm=0 use linear interpolation, cm=1 use bezier interpolation 	
	begin_cross_section 
	end_cross_section 	
	begin_cylinder
	end_cylinder
	add_point(n)	
	get_position
	get_heading
	get_up
	get_frame	
	mesh():mesh -- generate and return the generalised cylinder	

a vertex is a part of a mesh.
	Attributes:
	p -- position
	n -- normal	(read-only)
	c -- colour
	valid -- true if the vertex is still part of a mesh
	Member functions:
	calculate_normal -- recalculate the normal based on the adjacent faces	
	set_uv(u,v) -- set the uv coordinates
	get_adjacent_face -- returns an adjacent face	

vertexlist(m:mesh) returns a list of all vertices in the mesh m

sort(table [,comp])
	sorts table elements in a given order, in-place, from table[1] to table[n]
	comp is an optional comparison function s.t., comp(a,b) = true if a<b.

all(iter, [func]) Returns true if func(item) returns true for all item in items. (see http://mirven.github.com/underscore.lua/ for more info.)

any(iter, [func]) Returns true if func(item) returns true for any item in items. (see http://mirven.github.com/underscore.lua/ for more info.)

choose(list) returns a random element from list

collect is documented externally at http://mirven.github.com/underscore.lua/

compose(func1, func2, [...]) Returns the composition of a list of functions, where each function consumes the return value of the function that follows. In math terms, composing the functions f(), g(), and h() produces f(g(h())). (see http://mirven.github.com/underscore.lua/ for more info.)

concat(table [,sep [,i [,j]]]) returns table[i]..sep..table[i+1].. ..sep..table[j]

copy(table) returns a (deep) copy of a table

curry(func, arg) Creates a wrapper function substituing the supplied arg for the first argument in original function. (see http://mirven.github.com/underscore.lua/ for more info.)

detect(iter, func) Looks through a list returning the first element that matches a truth function. The function returns as soon as it finds an acceptable element. (see http://mirven.github.com/underscore.lua/ for more info.)

each(iter, func)  Passes each value to function(i) and returns the input. (see http://mirven.github.com/underscore.lua/ for more info.)

every is documented externally at http://mirven.github.com/underscore.lua/

extend(destination, source) Copy all of the properties in the source object over to the destination object. (see http://mirven.github.com/underscore.lua/ for more info.)

filter is documented externally at http://mirven.github.com/underscore.lua/

find(l,f) finds element v of l satisfying f(v)

first(array, [length]) Returns the first element of an array. Optionally it will return an array of the first n items. (see http://mirven.github.com/underscore.lua/ for more info.)

flatten(array) Flattens a nested array (the nesting can be to any depth). (see http://mirven.github.com/underscore.lua/ for more info.)

foldl is documented externally at http://mirven.github.com/underscore.lua/

for_each is documented externally at http://mirven.github.com/underscore.lua/

foreach(table, f) executes f on each element of table

head is documented externally at http://mirven.github.com/underscore.lua/

include is documented externally at http://mirven.github.com/underscore.lua/

inject is documented externally at http://mirven.github.com/underscore.lua/

insert(table, [pos,] value) inserts value at position pos in table

invoke(list_of_items, function_name) Calls a function with specified name on each item using the colon operator. (see http://mirven.github.com/underscore.lua/ for more info.)

is_empty(object) Returns true if object contains no values. (see http://mirven.github.com/underscore.lua/ for more info.)

is_equal is documented externally at http://mirven.github.com/underscore.lua/

join(array) Returns a string with all items in the array concatenated together with an optional separator. (see http://mirven.github.com/underscore.lua/ for more info.)

keys(object) Returns an array of all the property names in a table. (Note: order is not defined) (see http://mirven.github.com/underscore.lua/ for more info.)

map(iter, func) Produces a new array by mapping each value in iter through a transformation function. (see http://mirven.github.com/underscore.lua/ for more info.)

maxn(table) returns the largest positive numerical index of table

pluck(iter, property_name) An convenient version of the common use-case of mapextracting a list of properties. (see http://mirven.github.com/underscore.lua/ for more info.)

pop(array) Removes and returns the last item in an array (see http://mirven.github.com/underscore.lua/ for more info.)

push(array, item) Inserts item at the end of an array (see http://mirven.github.com/underscore.lua/ for more info.)

reduce(iter, memo, func) Boils down a list of values into a single value. Memo is the initial state of the reduction, and each successive step of it should be returned by func. (see http://mirven.github.com/underscore.lua/ for more info.)

reject(iter, func) Removes items that match the provided criteria. (see http://mirven.github.com/underscore.lua/ for more info.)

remove(table [,pos]) 
	removes the element at position pos from table, shifting down other elements to 
	close the space. returns the removed element. pos defaults to #table.

rest(array, [start_index]) Returns an array of all items except the first. Optionally it will start at start_index. (see http://mirven.github.com/underscore.lua/ for more info.)

reverse(iter, [comparison_func]) Iterates over all the items and returns a new array with the items in reverse order. (see http://mirven.github.com/underscore.lua/ for more info.)

select(iter, func) Removes items that do not match the provided criteria. (see http://mirven.github.com/underscore.lua/ for more info.)

set(l) converts list l to a set

shift(array) Removes and returns the first item in an array (see http://mirven.github.com/underscore.lua/ for more info.)

slice(array, start_index, length) Returns a section of an array starting with start_index of length items length. (see http://mirven.github.com/underscore.lua/ for more info.)

some is documented externally at http://mirven.github.com/underscore.lua/

sort(iter, [comparison_func]), Returns an array with all elements sorted by the comparison function, by default it uses the < operator. If an array is passed in it will sort the elements in place and not create a new array. (see http://mirven.github.com/underscore.lua/ for more info.)

tail is documented externally at http://mirven.github.com/underscore.lua/

to_array(iter) Collects all values into a new array. (see http://mirven.github.com/underscore.lua/ for more info.)

to_string(tbl) converts tbl to a human-readable string

unshift(array, item) Inserts item at the beginning of an array (see http://mirven.github.com/underscore.lua/ for more info.)

values(object) Returns an array of all the property values in a table. (Note: order is not defined) (see http://mirven.github.com/underscore.lua/ for more info.)

wrap(func, wrapper) Wraps the first function inside of the wrapper function, passing it as the first argument. This allows the wrapper to execute code before and after the function runs, adjust the arguments, and execute it conditionally. (see http://mirven.github.com/underscore.lua/ for more info.)

acentroidvl(vertex_list,n) computes the approximate centroid of a list of 
vertices defining a closed polygon (not necessarily planar).
The normalised vector, n, defines the plane on which the polygon approximately lies

centroid(point_list) computes the centroid of a 2d polygon defined by a list of vec3 (with z = 0)

  distribute_points_sphere(n) returns n equally distributed points on a sphere.

 "Distributing many points on a sphere" by E.B. Saff and A.B.J. Kuijlaars,
  Mathematical Intelligencer 19.1 (1997) 5--11

line_exp_point_dist(p1,p2,q) calculates the distance from q to the explicit line (p1,p2)

perp(v) returns a normalised vector perpendicular to vec3 v

project(a,b) projects vec3 a onto vec3 b and returns the result

segment_point_dist(p1,p2,q) calculates the distance from q to the explicit line segment (p1,p2)