Typical aesthe screen
Aesthe is 3D scripting development environment controlled by command line with built-in 3D modeller, allowing you to create interactive script-driven 3D simulations or animations.
Copyleft (ↄ) 2008 by Tomáš Darmovzal
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/> .
You can download sources of Aesthe from SourceForge.Net
SourceForge.net Logo
Running Aesthe
Usage: ./aesthe [-h] [-v] [-d<width>x<height>] [-s<scriptname>]
-h --- prints usage help
-v --- prints version
-d<width>x<height> --- specifies initial console window dimensions
-s<scriptname> --- specifies script name to run after aesthe starts
cd bin ./aesthe -d1024x768 -sexample1
Command shown above runs demo application - robot arm simulation.
Robot arm simulation
Default control bindings
By default mouse and keyboard events are bounded as follows (see script/event.lua for more precise description):
Mouse events
left button drag - rotates camera around camera point
middle button drag - shifts Y coordinate of camera point (moves camera vertically)
right button drag - shifts X-Z coordinates of camera points (moves camera in horizontal plane)
wheel up/down - increments/decrements distance of camera from camera point
CTRL + left button drag - (un)marks vertices and faces of current object
CTRL + left button pointed - places new vertex in plane parallel to camera view vector and intersecting camera point
SHIFT + left button drag - rotates marked vertices around camera view vector
SHIFT + middle button drag - scales uniformly marked vertices with respect to current camera point
SHIFT + right button drag - moves marked vertices in plane parallel to camera view vector
Keyboard events
F1 - change camera to top orthographic projection
F2 - change camera to front orthographic projection
F3 - change camera to side orthographic projection
F4 - change camera to last used perspective projection
F5 - switches between solid and wireframe render
F6 - switches between mark view (current object gray, others green, marked elements colored) and material view (shows textures and materials)
F11 - loads scene from model file named "checkpoint"
F12 - saves whole scene into model file named "checkpoint"
Terrain flood simulation
Aesthe is assembled of several modules:
kernel - lightweight interface for all kinds of scene graph operations including creating/destroying basic scene elements, reading/changing their attributes or traversing them. This module is written in ANSI C and does not depends on any other library (excluding stdlib for malloc) and thus can be used separately.
render - its primary function is to render kernel scene graph. Current implementation uses OpenGL.
engine - scripting language engine bound to all other modules allowing full control over their functionality. Currently is used Lua language v. 5.1 ( www.lua.org )
console - serves as graphical interface for other modules with user. Creates graphical window which combines command line console for command execution with 3D scene rendered at background. Current implementation depends on SDL library.
eximport - module used as (de)serializer of selected branch of scene tree into persistent state (export/import scene to/from file).
Kernel is aesthe module, which holds scene graph and exports simple interface for its manipulation. Kernel interface is designed to allow only primitive-type values passing, thus application developer cannot break scene content with invalid pointer. This interface allows developer to create and destroy basic elements of scene (vertices, faces, objects and textures), set or read element's attributes, traversal through scene graph and some more. Kernel module is written with respect to keep no dependency to any external library (excluding libc, of course), thus you can use it separately in any other 3D GPL project.
Kernel is designed as finite automaton, which has set of variables - one for each basic element type - which can be used to store reference to current basic elements passed as parameters to other operations (eg. setting/getting attributes). This set of variables is furthermore provided as stack - that means, you can save current state of variables by push() operation (which duplicates top of the stack) and then again restore previously saved state by calling pop() . Furthermore, you can use concept of registry (similar to processor registry), which serves as array of basic scene elements with user-defined length. You can use this registry as temporary array of elements, which are accessible by numerical index. Registry are bounded to current state, that means if you call pop(), you lose along with current variables also current registry.
In C, struct AeKernel is the most important kernel data structure - it holds root of scene graph as well as current variable state stack and registry. This structure has several methods for scene manipulation:
C: void aekCreate(AeKernel * kernel, AeType type);
Lua: kernel.create(kernel.AET_*)
enum AeType
AET_VERTEX - vertex
AET_FACE - polygon
AET_TEXTURE - texture
AET_OBJECT - node of scene tree containing its own faces, vertices and transformation matrix
Creates new element of provided type and sets it as current. All attribute values are reset to its default values.
AeType enumeration parameter is provided for chosing type of created element.
C: void aekDestroy(AeKernel * kernel, AeType type);
Lua: kernel.destroy(kernel.AET_*)
Destroys element set as current value of provided element type.
C: void aekSet(AeKernel * kernel, AeType type, AeAttribute attribute, void * value); void aekGet(AeKernel * kernel, AeType type, AeAttribute attribute, void * value, int maxlength);
Lua: kernel.set(kernel.AET_*, kernel.AEA_*, value) value = kernel.get(kernel.AET_*, kernel.AEA_*)
Methods for setting/reading attribute values of elements which are set as current.
In C, parameter value must reference to value of correct data type (see following list of attribute types).
Parameter maxlength states maximal length of read attribute value. It has sense only while reading attribute of variable length (currently only char */string). In other cases is value of this parameter ignored.
enum AeAttribute:
AEA_ID - int/number - unique identifier of element
AEA_MARK - int/number - mark of element
AEA_TEMP - int/number - temporary value of element
AEA_POSITION - V3/ae.v3 - position of vertex
AEA_NORMAL - V3/ae.v3 - normal vector of surface at vertex (only applicable for already bound vertex)
AEA_TEXUV - V2/ae.v2 - texture coordinate for vertex (only applicable for already bound vertex)
AEA_SHININESS - float/number - material shininess coefficient (only applicable for already bound vertex)
AEA_COLOR - V3/ae.v3 - material color (only applicable for already bound vertex)
AEA_AMBIENT - V3/ae.v3 - material ambient RGB reflection (only applicable for already bound vertex)
AEA_DIFFUSE - V3/ae.v3 - material diffuse RGB reflection (only applicable for already bound vertex)
AEA_SPECULAR - V3/ae.v3 - material specular RGB reflection (only applicable for already bound vertex)
AEA_EMISSION - V3/ae.v3 - material emission color (only applicable for already bound vertex)
AEA_FILE - char */string - texture file name (applicable for texture only)
AEA_TRANSFORM - Matrix/ae.matrix - object transformation (applicable for object only)
AEA_NAME - char */string - object name (applicable for object only)
AEA_VISIBLE - int/boolean - object visibility flag (applicable for object only)
C: typedef int (* AeFindCallback)(AeKernel * kernel, int index, void * userdata); int aekFind(AeKernel * kernel, AeType type, AeRule rule, int param, AeFindCallback callback, void * userdata);
Lua: count = kernel.find(kernel.AET_*, kernel.AER_*, param, [callback(index)], [userdata])
Find() is multi-purpose method for any kind of scene elements traversal. First parameter specifies type of basic element for traversal, second and third specifies traversal rule and its optional integer parameter (see AeRule table below). Fourth parameter is optional, if set specifies callback which will be called for every found element. Found element is before invoking callback set as current, so it is often useful to surround find() call with push() and pop() brackets. Optional last parameter is userdata used for callback.
Callback prototype takes integer parameter index, which represents index of each found element incremented from zero. Callback returns integer flag used as indicator of premature stop of search loop (zero means continue, nonzero means stop search immediately).
Find method returns number of found elements. If callback is not specified (is set to NULL in C), this method can be used to count number of searched elements and/or set last (sometimes only) searched element as current.
enum AeRule
AER_ALL - traverse all elements
AER_BY_ID - traverse only element with ID attribute equal to param
AER_BY_MARK - traverse only elements with MARK attribute equal to param
AER_BY_MARK_MASK_ALL - traverse only elements for which MARK attribute value has set ALL bits specified by bitmask param
AER_BY_MARK_MASK_ANY - traverse only elements for which MARK attribute value has set ANY bits specified by bitmask param
AER_BY_TEMP - traverse only elements with TEMP attribute equal to param
AER_BY_TEMP_MASK_ALL - traverse only elements for which TEMP attribute value has set ALL bits specified by bitmask param
AER_BY_TEMP_MASK_ANY - traverse only elements for which TEMP attribute value has set ANY bits specified by bitmask param
AER_BY_PARENT - traverse objects whose parent is current object (traverse all childs of current object)
AER_BY_CHILD - traverse object whose child is current object (traverse parent of current object)
AER_BY_FACE - traverse textures or vertices which are bound to current face
AER_BY_VERTEX - traverse faces which are bound to current vertex
AER_BY_TEXTURE - traverse faces which are bound to current texture
C: void aekBind(AeKernel * kernel, AeType type1, AeType type2, int order1, int order2); void aekUnbind(AeKernel * kernel, AeType type1, AeType type2);
Lua: kernel.bind(kernel.AET_*, kernel.AET_*, [order1], [order2]) kernel.unbind(kernel.AET_*, kernel.AET_*)
These functions are used to (un)bind vertices with faces and faces with textures. Faces-vertices as well as faces-textures has many-to-many relationship, so if you wish to eg. add vertex to 3rd index in face, you must set desired face and vertex as current and call bind(AET_VERTEX, AET_FACE, 3, 0).
C: void aekPush(AeKernel * kernel); void aekPop(AeKernel * kernel);
Lua: kernel.push() kernel.pop()
Function push() duplicates current state at the top of state stack excluding registry values. Function pop() removes top of the state stack (call is successfull only if stack size is > 1).
C: void aekClear(AeKernel * kernel, AeType type);
Lua: kernel.clear(kernel.AET_*)
This method clears current element of chosen type in top of state stack. It does not destroy the element, only clears its reference in current state.
C: void aekRegistry(AeKernel * kernel, AeType type, int size); void aekLoad(AeKernel * kernel, AeType type, int index); void aekStore(AeKernel * kernel, AeType type, int index);
Lua: kernel.registry(kernel.AET_*, size) kernel.load(kernel.AET_*, index) kernel.store(kernel.AET_*, index)
Call registry(type, size) allocates in current state registry array of specified type and size. If size is 0, registry are cleared, if size is larger then previous registry size, then all previous items are preserved. Call load(type, index) replaces current state element of specified type by item in registry array at specified index. Calling of store(type, index) sets current state element reference of specified type into registry at specified index. Indices parameters in load() and store() are boundary-checked.
Modelling in aesthe
Shortcut commands documentation
:box [width] [height] [depth] [cx] [cy] [cz] --- Builds box with specified sizes and center point
:c [x] [y] [z] --- Moves camera to position <x, y, z>
:ck [steps] --- Adds camera key-frame
:ckr --- Resets (removes) all camera keyframes
:clr --- Clears screen
:cm [x] [y] [z] --- Moves camera relatively by vector <x, y, z>
:cn [smooth] --- Correct normals on marked vertices and faces. <smooth> is boolean flag specifying creation of flat/smooth normals
:col [color] --- Set color <color> to marked face-vertices
:con [height] [radius] [slices] [cx] [cy] [cz] --- Builds cone
:cr --- Replays remembered camera keyframes
:cyl [height] [radius] [slices] [cx] [cy] [cz] --- Build cylinder
:d --- Delete marked faces and vertices of current object
:df --- Deletes marked faces of current object
:dv --- Deletes marked vertices of current object
:emi [color] --- Sets emission color to marked face-vertices
:ext [segments] [dx] [dy] [dz] [connect] [beginCap] [endCap] --- Extrude marked vertices
:fill --- Fills marked vertices with face (in natural order)
:flood [mark] --- Recursively spreads faces marked with <mark> (defaults to 1) to adjacent faces
:help [command] --- Prints shortcut command info
:helpapi [member] --- Prints API member info
:lat [segments] [dx] [dy] [dz] [cx] [cy] [cz] [join] [connect] [begin] [_end] --- Lathe marked vertices
:lo --- Lists complete object tree
:load [name] --- Imports whole scene from model file <name> (defaults to previously saved <name>)
:ma --- Marks all (sets to one) all vertices and faces of current object
:mc --- Removes marks (sets to zero) from all vertices and faces of current object
:ml --- List all marks used in current object
:mov [x] [y] [z] --- Moves marked vertices relatively by vector <x, y, z>
:o [ident] --- Sets object by id or name <ident> as current. If <ident> is not set sets root scene as current object.
:oc --- Clears all vertices and faces of current object
:oh --- Hides current objects (sets to non-visible)
:on [name] --- Creates new object with <name>
:os --- Show current object (sets to visible)
:q --- Exits Aesthe
:ref [ambient] [diffuse] [specular] --- Sets reflectances to marked face-vertices
:rot angle [dx] [dy] [dz] [cx] [cy] [cz] --- Rotates marked vertices by <angle> degrees in axis <dx, dy, dz> around center <cx, cy, cz>
:save [name] --- Exports whole scene into model file <name> (defaults to previously saved <name>)
:sca [sx] [sy] [sz] [cx] [cy] [cz] --- Scales marked vertices by factors <sx, sy, sz> from center <cx, cy, cz>
:shi [shininess] --- Sets shininess to marked face-vertices
:sph [radius] [slices] [stacks] [cx] [cy] [cz] --- Builds sphere
:stop --- Stops timer
:sub [factor] --- Subdivides marked faces by factor <factor>
:tor [radius1] [radius2] [slices1] [slices2] [cx] [cy] [cz] --- Builds torus
:tp --- Moves current object pointer to parent of current object
:trot angle [dx] [dy] [dz] [cx] [cy] [cz] --- Rotates current object (changes transformation) by <angle> degrees in axis <dx, dy, dz> around center <cx, cy, cz>
Lua API documentation
Global functions
clone (value)
Creates clone of <value>
dump (value, [output])
Dumps content of <value> using print-function <output> (defualts to print())
eval (exp)
Evaluates expression exp and returns its value
exit ()
Shorthand for console.stop()
print (...)
Prints arguments with default print-color
printc (r, g, b, ...)
Color-prints arguments with color <r, g, b>
run (scriptFile)
Shorthand for engine.execFile(scriptFile)
trace ()
Prints current stack trace
Package of functions to provide 3D algorithms for scene manipulation
extrude ([direction], [segments], [connect], [beginCap], [endCap])
Extrudes marked points (in natural order) in <direction> (defaults to <0, 1, 0>) by <segments> (defaults to 1). <beginCap> and <endCap> indicates presence of ending cap faces. If <connect> is true, than first and last vertices are connected.
fill ()
Fills marked vertices with face (in natural order)
lathe ([segments], [direction], [center], [join], [connect], [begin], [_end])
Lathes marked vertices around axis <direction> (defaults to <0, 1, 0>) with center at <center> (defaults to <0, 0, 0>) by several <segments> (defaults to 10). <begin> and <_end> specifies caps of resulting lathe - "vertex" means first/last vertex will become pole, "face" means planar face cap, "none" means no cap.
Package of functions for event handling
add (name, func)
Adds hook <func> to the list of hook for event <name>
fail (name, ...)
This function is called whenever any unregistered event with <name> occures
Table of function tables used as hooks for events
Must be set to nil or function - in that case function is called for every event with string argument containing runnable Lua command which can be used to reinvoke the event
requestUserInput (prompt)
Prints <prompt> and sets flag announcing next single "input" event will be raised as "userinput"
set (name, func)
Sets hook <func> as the only hook for event <name>
Table of standard hooks
Package of function for scene branch export/import (saving and loading scene to/from file). Standard supported formats (engines) are "aexi" (default) and "wf" (Wavefront obj)
export (filename, [engine])
Exports (serialize) scene branch determined by current object to file models/<filename>.suffix using specified <engine> (defaults to "aexi")
import (filename, [engine])
Imports (deserialize) scene branch from file models/<filename>.suffix into branch determined by current object using specified <engine> (defaults to "aexi")
register (name, suffix, export, import)
Registers new <export> and/or <import> routines for symbolic format <name> with file suffix <suffix>. Export and import functions takes single argument <file> and return error code (0 means OK).
Package of mathematic functions - see Lua documentation
band (a, b)
Bitwise AND on integers
bor (a, b)
Bitwise OR on integers
bxor (a, b)
Bitwise XOR on integers
todeg (rad)
Converts from radians to degrees
torad (deg)
Converts from degrees to radians
Userdata data type representing 4x3 affine transformation matrix (last row is always [0, 0, 0, 1]). Supports operator * as matrix-to-matrix or vector-to-matrix multiplication
get (matrix)
Gets matrix elements in line-by-line form m11, m12, ..., m33, m34
new ()
Creates new unit matrix
set (matrix, m11, m12, ..., m33, m34)
Sets matrix elements
setRotation (matrix, angle, ax, ay, az, [cx], [cy], [cz])
Sets matrix elements to rotation matrix specified by <angle> around axis <ax, ay, az> with center at <cx, cy, cz>
setScale (matrix, sx, [sy], [sz])
Sets matrix elements to scale matrix with coefficients <sx, sy, sz> (or <sx, sx, sx> if <sy> an <sz> is not specified)
setTranslation (matrix, tx, ty, tz)
Sets matrix elements to translation matrix in direction <tx, ty, tz>
Simple UDP networking
_close (index)
Raw socket close. <index> is socket index returned by net._open() method call.
_open (host, port)
Raw socket open. If <host> is not defined, local server socket is created, otherwise client socket is created. Returns socket index used for net._write() or net._close() methods.
_write (index, data)
Raw socket <data> send. <index> is socket index returned by net._open() method call.
List of active connections
open ([host], port, recvcallback)
Opens server or client UDP socket. If <host> is undefined then local server socket is created. Otherwise client socket aiming to <host>:<port> machine is created. <recvcallback> is a function used as callback for incoming packet notification. Method returns connection instance `conn' contains methods conn:write(data) for sending a packet and conn:close() for closing connection.
send (host, port, data)
Sends single UDP packet containing <data> to specified <port> at <host> machine.
startrc (port)
Starts remote-control server at specified <port>. Each packet delivered to this local port is executed as command string
stoprc ()
Stops remote-control server
Package of functions for building 3D primitives
box ([va], [vb])
Builds a box with corners at <va> (defaults to <-1, -1, -1>) and <vb> (defaults to <1, 1, 1>)
cone ([height], [radius], [slices], [center])
Build cone with <height> (defaults to 1) and <radius> (defaults to 1) with <slices> count (defaults to 10) and center at <center> (defaults to <0, 0, 0>)
cube ([a], [c])
Builds cube with edge <a> (defaults to 1) and center <c> (defaults to <0, 0, 0>)
cylinder ([height], [radius], [slices], [center])
Build cylinder with <height> (defaults to 1) and <radius> (defaults to 1) with <slices> count (defaults to 10) and center at <center> (defaults to <0, 0, 0>)
heightField (heights, rows, cols, [rowdist], [coldist], [center])
Builds height field using height values in <heights> (could be table or function(row, col)) with number of <rows> and <cols>. <rowdist> and <coldist> specifies width of row and column (both defaults to 1) and <center> specifies center of height field (defaults to <0, 0, 0>).
sphere ([radius], [slices], [stacks], [center])
Builds sphere with <radius> (defaults to 1) at <center> (defaults to <0, 0, 0>) with number of <slices> (defaults to 16) and <stacks> (defaults to 8)
torus ([radius1], [radius2], [slices1], [slices2], [center])
Builds torus with outer radius <radius1> (defaults to 2), inner radius <radius2> (defaults to 0.5), count of outer slices <slices1> (defaults to 20) and inner slices <slices2> (defaults to 10)
Package of string manipulation functions - see Lua documentation
endsWith (str, suffix)
Returns true iff string <str> ends with substring <suffix>
split (str, sep)
Returns table of segments from string <str> that were separated by <sep>
startsWith (str, prefix)
Returns true iff string <str> starts with substring <prefix>
Package of utility functions
Camera parameters saved using util.setCamera()
Storage for tables of camera parameters used for camera fly-throughs
bindTexture (file)
Creates texture with <file> (if does not exist) and binds it to all marked faces
cameraDumpKeyframes ()
Prints all saved camera parameters
cameraKeyframe ([count])
Saves current camera parameters into table util.CAMERA_KEYFRAMES
cameraKeyframeReset ()
Resets all saved camera parameters
cameraMove ([x], [y], [z])
Moves camera relatively by vector <x, y, z>
cameraReplay ([millis])
Replays all saved camera parameters using linear interpolation with delay <millis>
cameraSwitch ()
Switches between perspective and orthogonal camera view
clearScreen ()
Clears screen
getFaceCenter ()
Returns center point of current face or nil if it is not bound to any vertices yet
getFaceNormal ()
Returns normal vector for current face
getObjectName ()
Returns name of current object
getWorldTransform ()
Returns matrix representing absolute transformation in world coordinate system
interpolate (callback, [count], [millis], [after])
Interpolates values from 0 to 1 in <count> steps (defaults to 10) and calls callback() with each value. Between each two steps is <millis> delay (defaults to 40). After reaching value 1 is called callback <after>() (if specified).
linearInterpolate (callback, [count], [millis], [after], [from], [to])
Process linear interpolation between <from> and <to> (defaults to 0 and 1) using util.interpolate(). Parameters <from> or <to> can be either scalars (numbers) or tables of numbers, in which case callback is called with table parameter instead of scalar number. Other parameters are passed directly to util.interpolate().
listObjects ()
Print object hierarchy tree to screen
load ([name])
Loads whole scene from model file <name> (defaults to previously saved model name)
markFlood (mark)
Recursively spreads faces marked with <mark> to adjacen faces
materialColor ([V3 color])
Sets material <color> (defaults to white) of marked vertex-faces
materialEmission ([V3 emission])
Sets material <emission> color (defaults to black) of marked vertex-faces
materialReflectance ([V3 ambient], [V3 diffuse], [V3 specular])
Sets material reflectances of marked vertex-faces
materialShininess ([F shininess])
Sets material <shininess> coefficient (defaults to 0) of marked vertex-faces
newObject ([name])
Creates new object with name <name> as child of current object and set it as current
newVertex (x, y, z)
Creates new vertex at position <x, y, z> and marks it
objectClear ()
Removes all faces and vertices from current object
objectVisible ([on])
Sets current object visibility <on>
restoreCamera ()
Restores camera previously stored in util.CAMERA
save ([name])
Saves whole scene into model file <name> (defaults to previously saved model name)
setCamera ([V3 position], [F azimuth], [F zenith], [F distance], [B perspective])
Sets camera parameters - value of either parameter is unchanged if not set or nil. Saves camera parameters to util.CAMERA
setFaceNormal (normal)
Sets <normal> as normal to all vertices of current face
setObjectName (name)
Sets <name> of current object
setTransform (m)
Sets transformation matrix of current object to <m>
tempClear ()
Resets temp attribute to 0 for all vertices and faces of current object
tempFaceSet ([temp])
Sets temp attribute to <temp> (defaults to 0) for all faces
tempSet (type, [temp])
Sets temp attribute to <temp> (defaults to 0) for all elements of specified <type>
tempVertexSet ([temp])
Sets temp attribute to <temp> (defaults to 0) for all vertices
toObject ([ident])
Finds object with ID or name equals to <ident> and sets it as current object. If <ident> is omitted, than root scene is set as current object.
toParentObject ()
Sets parent object of current object as current
toTopObject ()
Sets top object of scene (object with ID = 1) as current object
Userdata data type representing 2D vector. Supports operators + (vector addition), * (scalar multiplication or dot product), / (scalar division), unary - (vector negation)
angle (v2)
Returns clockwise angle between <v2> and vector <1, 0>
get (v2)
Returns coordinate in form X, Y
new ()
Creates new zero vector
set (v2, x, y)
Sets coordinates
unit (v2)
Change vector length to 1
X coordinate or U texture coordinate
Y coordinate or V texture coordinate
Userdata data type representing 3D vector. Supports operators + (vector addition), * (scalar multiplication, dot product or matrix multiplication), / (scalar division), unary - (vector negation)
cross (u, v)
Counts cross product of vectors <u> and <v>
get (v3)
Returns coordinate in form X, Y, Z
new ()
Creates new zero vector
random ([max], [v3])
Generates random vector (or sets random position on existing vector) inside interval <-max, +max> in all dimensions. <max> defaults to 1.
set (v3, x, y, z)
Sets coordinates
unit (v3)
Change vector length to 1
X coordinate or red color component
Y coordinate or green color component
Z coordinate or blue color component
Author: Tomáš Darmovzal tomas dot darmovzal at gmail dot you-know-what
Generated by DocumentPreProcessor (dpp) - DPP source