Kludge3d - 3d modeler released by Andrew Sampson (ads4260@rit.edu)

homepage: kludge3d.sourceforge.net

Kludge3d is a simple 3d polygonal modeler, based on code harvested from
several other (presumably abandoned) projects.  Kludge3d is released under
the GPL, and requires GTK2 and gtkglext to work.

What it does:

- loads and saves 3d models in several formats, including AC3d, Wavefront,
  3ds (load only), Quake2 MD2 (load only), and Quake2 .map (save only).

- creates vertices and polygons.  No NURBS, splines, etc.

- organizes polygon meshes into a tree heirarchy

- applies textures to the meshes.

Kludge3d, as the name implies, is a kludge.  An ugly hack.  It will never
be the next 3d Studio MAX, or even the next Milkshape.  I set out to fashion
a usable GPL'ed level modeler, similar to AC3d, for creating game levels.
Rather than re-invent the wheel, I based my efforts on several existing
editors, and kludge3d is the result.  I hope you will find it useful.

Compilation instructions can be found in the INSTALL file.
The INSTALL file also has info on the ~/.kludge3d directory.
Usage instructions can be found on the kludge3d web page.

A NOTE FOR THOSE USING 3dfx CARDS:
If, like me, you're using a 3dfx card (such as the voodoo3, 4, or 5), then
you might run into problems using kludge3d.  Apparently, the DRI drivers for
the 3dfx cards suck, and won't allow a single application to open more than
one OpenGL surface at a time.  Multiple OpenGL applications can run
simultaneously, but a single application can open only one OpenGL window.  The
problem manifests itself as tootie-fruitie rainbow colors on all of the model
geometry, rather than the expected colors.  You can "fix" the problem by
falling back on software mode; run the following shell commands
(bash-specific, csh users are on their own) to do so:
	export LIBGL_ALWAYS_INDIRECT=1
	kludge3d


Creds:

In writing kludge3d, I took code from the following projects:

   - G3D by Blake Hegerle
        http://condor.stcloudstate.edu/~hebl9901/g3d
        laertes@stab.gemma.com
   - ME3D by Sam Revitch
        http://www.cs.washington.edu/homes/samr7/me3d
        samr7@cs.washington.edu
   - Orbit (space sim), which, in turn, took the code from ac_to_gl

Most of the interface was taken from G3D.  The opengl-preview was taken
from ME3D.  ME3D also provided the file-format-framework, and the Wavefront
loader.  Orbit provided much of the AC3D loading code.

Very little of either G3D or ME3D remain in the current version of kludge3d.
Most of the code has been rewritten at some point or another.  The vast
majority of the new code was written by Andrew Sampson, with some important
contributions from David Pinson (including the ground work for the Python
scripting interface, and much of the GTK2 porting work).

Using kludge3d's scripting features
===================================

Introduction
------------
In my opinion, the Python scripting capability of kludge3d is easily the most
interesting feature to be added in recent memory.  At the moment, the kludge3d
functions that can be accessed through scripts (the "scripting interface" or
"scripting API") are limited, as compared to other 3d modelers with Python
scripting (ex. Blender).  However, there is enough to create some interesting
tools.

Before going any further, let it be known that I assume that the reader is at
least a little familiar with Python.  If you are not, I suggest that you visit
the Python web site (www.python.org) and check out some of the tutorials.
Python is an easy language to learn.

The functions in kludge3d's scripting API are listed in the file
'src/pywrapper_wrap.doc'.  You can also check out the 'src/pywrapper.c' file
for more info.

Running Python code
-------------------
Running Python code in kludge3d is easy.  Once kludge3d is running, you can
type Python code into the text box at the bottom of the "Groups" notebook tab.
You can treat this the same as you would the command-line Python interpreter,
with the following exceptions:
	- Don't call any functions which expect input from stdin.  You won't be
	  able to send any input to them.
	- The command-line Python interpreter will print out the return value of
	  any statement you execute directly.  Kludge3d won't do that; you need to
	  use the 'print' keyword. (See the next item, also.)
	- You won't see the text output.  This is where kludge3d's log window
	  becomes handy.

About the log window
--------------------
Were it not for the log window, all of the text output generated by kludge3d
(including output from Python scripts) would be sent to the console.  If you
use your window manager to start kludge3d (rather than a command line), you
would never see such output.  To remedy this, the log window intercepts and
stores all of the text output by kludge3d.

There is a second Python text box at the bottom of the log window, for your
convenience.  You can use either one; they both do the same thing.

Writing re-usable tools
-----------------------
Using the Python text box, you can experiment with the scripting API.  However,
once you are ready to create a re-usable script, you will want to create a
script file to store it in.  See the README file for info on where to put your
script files.  Briefly, they should go in ~/.kludge3d, and you should put an
"import" entry in ~/.kludge3d/base.py for each of your modules.

Once you've done this, you can call your script by entering:

modulename.functionname( )

...in the Python text box, where modulename is the name of the file that you
stored your functions in, and functionname is the name of the function you want
to call.  Any arguments to your function go between the parenthesis, and are
separated by commas.  You can avoid all this typing (and can avoid having to
remember the arguments to your functions) by adding your functions to the
script-shortcut buttons in kludge3d's "Tools" notebook tab.

About the shortcut buttons in the "Tools" notebook tab
------------------------------------------------------
If you would like to create shortcut buttons for your scripts, you need to
add the following line to the end of your script file:

register_function( __name__, functionname )

You would obviously substitute your function's name for functionname.  You
need to call register_function once for each function you want to appear in
the Tools tab.

The next time you run kludge3d, a button with your function's name will appear
under the "Scripts" rollup in the "Tools" notebook tab.  If you click on the
button, a dialog will pop up showing the function's name, the "doc string"
for the function, and a prompt for each of the function's arguments.

Take a look at the example scripts
----------------------------------
If you're uncertain about where to start, take a look at the scripts I've
written.  They can be found in the 'scripts' directory.  The 'prefabs.py' file
is a good place to start.