Mesher for trueSpace 5.x and 6.x
================================

Legalese
--------

This software is provided without warranty, and if your computer
against all odds would suddenly vanish into thin air I'd really
appreciate it if I wasn't held responsible in any way. I retain
copyright to all material contained within this archive, but do
allow for redistribution of the complete, unmodified archive as
long as it is not done for a fee (it is permissible to charge a
nominal fee to cover distribution costs).

What is it?
-----------

Mesher is a extension module for the trueSpace Python language that
is capable of creating objects based on a set of points and
faces. It also provides the ability to perform boolean operations
upon objects, either by name or by selection.

Installation Instructions
-------------------------

Make a directory named 'Lib' in your main trueSpace directory
and copy the Mesher.dll file into this location. That's all
there is to it.

Mesh Creation Usage
-------------------

Using the Mesher extension module is fairly simple. One only need
to create the set of points and faces according to the specification
below, and call the create() function to create a brand new object.

The create() function takes two or three parameters. If two parameters
are given the syntax is as follows:

	Mesher.create(points, faces)
	
The points need to be a list of the form

	[ [x1, y1, z1], ..., [xn, yn, zn] ]
	
with at least three points specified, and the faces need to be a
list of the form

	[ [p1, ..., pn], ..., [q1, ..., qm] ]
	
where the number of points for each face need to be at least three,
the offset into the point list is zero-based.

If three parameters are given for create()

	Mesher.create(points, faces, uv)

the list of points need to be given in the following form:

	[ [[p1, s1], ..., [pn, sn]], ..., [[q1, t1], ..., [qm, tm]] ]

where s1...sn and t1...tm are indices into the uv array. The UV array
itself takes the following form

	[ [u1, v1], ..., [un, vn] ]

Union, Intersection and Subtraction
-----------------------------------

This functionality is currently a bit dangerous to perform. Do
not use it if you happen to have any unsaved data (in trueSpace
or any other program!). Due to a lack of a proper Python API
for the exposed trueSpace functionality, there are restrictions
on how this can currently be implemented (I think), and error
checking is not quite up to par either. I've done what I can,
but it's not perfect. Save unsaved work! Please.

So, usage ...

	Mesher.union(["obj1", ..., "objn"])
	Mesher.intersect(["obj1", ..., "objn"])
	Mesher.subtract(["obj1", ..., "objn"])
	
	Mesher.union(["obj1", ..., "objn"], options)
	Mesher.intersect(["obj1", ..., "objn"], options)
	Mesher.subtract(["obj1", ..., "objn"], options)
	
	Mesher.union(["obj1", ..., "objn"], options, identity)
	Mesher.intersect(["obj1", ..., "objn"], options, identity)
	Mesher.subtract(["obj1", ..., "objn"], options, identity)
	
The argument to the three functions is a list of strings that
are names of objects in the current trueSpace scene. At least
two objects must be given. Order is not important, but for
subtraction the first object in the list is the object from
which the rest of the objects are subtracted from.

IMPORTANT: DO MAKE SURE ALL ITEMS IN THE LIST ARE STRINGS!
FAILURE ON THIS PART MAY CAUSE A CRASH OF TRUESPACE AND MIGHT
MAKE YOUR SYSTEM UNSTABLE!

[Update: No crashes have been reported by any user yet]

Union, intersection and subtraction can also be made based upon
multi-selection of objects. Simply shift-select all the objects
you wish to perform the operation upon and use one of the
following functions to perform the operation you desire:

	Mesher.unionselection()
	Mesher.intersectselection()
	Mesher.subtractselection()
	
	Mesher.unionselection(options)
	Mesher.intersectselection(options)
	Mesher.subtractselection(options)
	
	Mesher.unionselection(options, identity)
	Mesher.intersectselection(options, identity)
	Mesher.subtractselection(options, identity)
	
For subtraction the rule is that the first object selected in
the shift-select operation will be the object form which all
other objects are subtracted.

Boolean Options & Identity
--------------------------

The parameters for options and identity are optional. If neither
are specified the current settings in the trueSpace boolean
panel will be used. If you want to specify the identity parameter
you will also have to specify the options parameter (can't
have it both ways, unfortunately).

The identity parameter must be an integer greater than zero. The
options parameter is also an integer, which can be formed using
two constants

	Mesher.KEEP_DRILL
	Mesher.DELETE_EDGES

They can be used together like

	Mesher.KEEP_DRILL | Mesher.DELETE_EDGES
	
in which case both options will be turned on.

Specifying options and identity in a boolean call will not
change the setting in the trueSpace user interace.

Samples
-------

Simple square

	import Mesher
	import trueSpace
		
	points = [ [0, 0, 0], [0, 1, 0], [1, 0, 0], [1, 1, 0] ]
	faces = [ [0, 1, 3, 2] ]

	Mesher.create(points, faces)

	trueSpace.Stop()

Simple square with UV information

	import Mesher
	import trueSpace

	points = [ [0, 0, 0], [0, 1, 0], [1, 0, 0], [1, 1, 0] ]
	faces = [ [0, 0], [1, 1], [3, 3], [2, 2] ]
	uv = [ [0, 0], [0, 1], [1, 0], [1, 1] ]

	Mesher.create(points, faces, uv)
	
Wavy surface

	import Mesher
	import math
	import trueSpace
	
	resolution = 50

	pts = []
	faces = []

	def surface(x, y):
		return math.sin(x/5.0) * math.cos(y/5.0)

	def point(x, y):
		return x + y * resolution

	for x in range(0, resolution):
		for y in range(0, resolution):
			z = x + y
			pts.append([x/5.0-5, y/5.0-5, surface(x, y)])

	for x in range(0, resolution-1):
		for y in range(0, resolution-1):
			faces.append([point(x+1, y), point(x, y), point(x, y+1)])
			faces.append([point(x+1, y), point(x, y+1), point(x+1, y+1)])

	Mesher.create(pts, faces)

	trueSpace.Stop()

Union of two cubes just added

	import Mesher
	import trueSpace
	
	Mesher.union(["Cube", "Cube,1"])
	
	trueSpace.Stop()
	
Intersection of two cubes just added

	import Mesher
	import trueSpace
	
	Mesher.intersect(["Cube", "Cube,1"], Mesher.KEEP_DRILL)
	
	trueSpace.Stop()
	
Subtraction of two cubes from another cube

	import Mesher
	import trueSpace
	
	Mesher.subtract(["Cube", "Cube,1", "Cube,2"], Mesher.KEEP_DRILL|Mesher.DELETE_EDGES, 50)
	
	trueSpace.Stop()

BUGS
----

This extension is not bug-free. Really. :) Please feel free to contact
me regarding any problem, and I'll see what I can do about it.

Contact Information
-------------------

Lars Nilsson
chamaeleon@adelphia.net
http://chamaeleon.freeservers.com
