Overview

This is a guide to the Misfit Model 3D scripting language. It includes only functions that are specific to Misfit Model 3D. Standard lua control structures and functions are not documented here.

For more information on using the scripting language, you may also want to review the Scripting Guide.

Contents

General

modelGetName

Descritption: Get the filename of the model

Arguments: Returns:

Notes: If the model does not have a filename this function will return an empty string.

modelSaveAs

Descritption: Save the model as a specified format.

Arguments: Returns:

Notes: Existing files will not be over-written. If writing the file in the specified format would cause an over-write, a number is added to the filename and incremented until the filename is unique.

modelGetVertexCount

Descritption: Get the number of vertices in the model.

Arguments: Returns:

Notes: None

modelGetFaceCount

Descritption: Get the number of faces (polygons (triangles)) in the model.

Arguments: Returns:

Notes: None

modelGetGroupCount

Descritption: Get the number of polygon

MD3 Limits

The MD3 file format has several limits that you should consider when making a model for this format. These are outlined below. If your model has more that the MD3 limit, the file will not be saved correctly and you should get a error message dialog.
[ Contents | Using | Tools | Commands ]
Copyright © 2004-2007, Kevin Worcester
./usr/share/doc/mm3d/html/olh_rgbawin.html0000644000000000000000000000356111330145376017366 0ustar rootroot Misfit Model 3D Help - RGBA Window

RGBA Window

This window is no longer in use. Use the RGBA sliders in the Materials Window instead.

The RGBA Window is used to change light properties for a texture. It is made up of four sliders and four text entry boxes for the three colors (red, green, and blue) and an alpha value. This window is accessible from the Materials Window.

The four lighting types that use the RGBA Window are:

Each color value ranges from -1.0 to 1.0. You can drag the slider left to decrease a color's value, or drag it right to increase a color's value. You can also change a value by typing a new value into the text box next to the slider.

Press Ok to keep your changes to the color values or press Cancel to ignore any changes.

[ Contents | Using | Tools | Commands ]
Copyright © 2004-2007, Kevin Worcester
./usr/share/doc/mm3d/html/olh_scriptguide.html0000644000000000000000000001242311330145376020254 0ustar rootroot Misfit Model 3D Help - Scripting Guide

Scripting Guide

Overview

Misfit Model scripts provide a way to quickly manipulate several models in a uniform manner. Scripts can apply matrix transformations, create new primitives, apply textures, and create or manipulate animations.

Misfit Model 3D uses a lua-based scripting system. For general lua programming information, go to http://www.lua.org/docs.html. For functions specifically added to lua for model manipulation, see the Scripting Reference page.

The lua language for Misfit Model is restricted to the standard control structures, the math library, and the model manipulation functions.

A the time of this writing, the scripting system was tested against Lua 5.0.3. Other 5.x versions should work fine.

Script files

Script files are text files with functions that perform operations on models. The open script dialog box will look for files with a .lua extension by default, so you will probably want to use .lua as the script extension. A script run from the Misfit Model 3D UI is run on a single model at a time.

Scripts work similarly to the UI in that some operations work on the base model and some work on the current animation (if you are in animation mode). Functions like selectedRotate and selectedTranslate will work on the model itself or on animation frames if you have used setAnimByIndex and animSetFrame.

A simple example script is included below. Lines beginning with "--" are comments. They are marked in blue below for the sake of clarity. This script is included in the Misfit Model 3D distribution in the scripts directory. There are a few other scripts that are also included for reference. 

x1 = -1.0
y1 = -1.0
z1 = -1.0
x2 =  1.0
y2 =  1.0
z2 =  1.0

-- front
modelCreateMeshRectangle( x2, y1, z2, x1, y1, z2,
   x1, y2, z2, x2, y2, z2 )

-- back
modelCreateMeshRectangle( x1, y1, z1, x2, y1, z1,
   x2, y2, z1, x1, y2, z1 )

-- right
modelCreateMeshRectangle( x2, y1, z1, x2, y1, z2,
   x2, y2, z2, x2, y2, z1 )

-- left
modelCreateMeshRectangle( x1, y1, z2, x1, y1, z1,
   x1, y2, z1, x1, y2, z2 )

-- top
modelCreateMeshRectangle( x1, y2, z2, x1, y2, z1,
   x2, y2, z1, x2, y2, z2 )

-- bottom
modelCreateMeshRectangle( x1, y1, z1, x1, y1, z2,
   x2, y1, z2, x2, y1, z1 )

modelSelectAllVertices()
selectedWeldVertices()

User interface

To run a script in the graphical user interface, select "Run Script..." from the "File" menu. This will allow you to chose a script file to run on the current model. The result of the script will be displayed in the status bar.

If there was an error running the script the error will be displayed in the status bar. Long errors may be truncated. In these cases the entire error may be visible by hovering the mouse over the status bar to see a tool tip.

Once you have run a script, you can run it again by selecting the script name from the "Recent scripts" submenu in the "File" menu.

Command line

To run a script from the command line, use the --script option. The --script option requires a script filename as an argument.

The script will run on every model file specified on the command line. If no model files are specified, a new model will be created. After the script has been run on every model file, Misfit Model 3D will continue processing as usual. If no other command line options are specified, the modified model files will each be opened in a view window.

If you wish to do command-line processing only without opening a view window in the User Interface, see the --save and --batch options in the Command Line documentation. There may be other options that are useful in batch processing as well.

[ Contents | Using | Tools | Commands ]
Copyright © 2004-2007, Kevin Worcester
./usr/share/doc/mm3d/html/olh_scriptref.html0000644000000000000000000007427111330145376017744 0ustar rootroot Misfit Model 3D Help - Scripting Reference

Overview

This is a guide to the Misfit Model 3D scripting language. It includes only functions that are specific to Misfit Model 3D. Standard lua control structures and functions are not documented here.

For more information on using the scripting language, you may also want to review the Scripting Guide.

Contents

General

modelGetName

Descritption: Get the filename of the model

Arguments: Returns:

Notes: If the model does not have a filename this function will return an empty string.

modelSaveAs

Descritption: Save the model as a specified format.

Arguments: Returns:

Notes: Existing files will not be over-written. If writing the file in the specified format would cause an over-write, a number is added to the filename and incremented until the filename is unique.

modelGetVertexCount

Descritption: Get the number of vertices in the model.

Arguments: Returns:

Notes: None

modelGetFaceCount

Descritption: Get the number of faces (polygons (triangles)) in the model.

Arguments: Returns:

Notes: None

modelGetGroupCount

Descritption: Get the number of polygon

MD3 Limits

The MD3 file format has several limits that you should consider when making a model for this format. These are outlined below. If your model has more that the MD3 limit, the file will not be saved correctly and you should get a error message dialog.
[ Contents | Using | Tools | Commands ]
Copyright © 2004-2007, Kevin Worcester
./usr/share/doc/mm3d/html/olh_rgbawin.html0000644000000000000000000000356111330145376017366 0ustar rootroot Misfit Model 3D Help - RGBA Window

RGBA Window

This window is no longer in use. Use the RGBA sliders in the Materials Window instead.

The RGBA Window is used to change light properties for a texture. It is made up of four sliders and four text entry boxes for the three colors (red, green, and blue) and an alpha value. This window is accessible from the Materials Window.

The four lighting types that use the RGBA Window are:

Each color value ranges from -1.0 to 1.0. You can drag the slider left to decrease a color's value, or drag it right to increase a color's value. You can also change a value by typing a new value into the text box next to the slider.

Press Ok to keep your changes to the color values or press Cancel to ignore any changes.

[ Contents | Using | Tools | Commands ]
Copyright © 2004-2007, Kevin Worcester
./usr/share/doc/mm3d/html/olh_scriptguide.html0000644000000000000000000001242311330145376020254 0ustar rootroot Misfit Model 3D Help - Scripting Guide

Scripting Guide

Overview

Misfit Model scripts provide a way to quickly manipulate several models in a uniform manner. Scripts can apply matrix transformations, create new primitives, apply textures, and create or manipulate animations.

Misfit Model 3D uses a lua-based scripting system. For general lua programming information, go to http://www.lua.org/docs.html. For functions specifically added to lua for model manipulation, see the Scripting Reference page.

The lua language for Misfit Model is restricted to the standard control structures, the math library, and the model manipulation functions.

A the time of this writing, the scripting system was tested against Lua 5.0.3. Other 5.x versions should work fine.

Script files

Script files are text files with functions that perform operations on models. The open script dialog box will look for files with a .lua extension by default, so you will probably want to use .lua as the script extension. A script run from the Misfit Model 3D UI is run on a single model at a time.

Scripts work similarly to the UI in that some operations work on the base model and some work on the current animation (if you are in animation mode). Functions like selectedRotate and selectedTranslate will work on the model itself or on animation frames if you have used setAnimByIndex and animSetFrame.

A simple example script is included below. Lines beginning with "--" are comments. They are marked in blue below for the sake of clarity. This script is included in the Misfit Model 3D distribution in the scripts directory. There are a few other scripts that are also included for reference. 

x1 = -1.0
y1 = -1.0
z1 = -1.0
x2 =  1.0
y2 =  1.0
z2 =  1.0

-- front
modelCreateMeshRectangle( x2, y1, z2, x1, y1, z2,
   x1, y2, z2, x2, y2, z2 )

-- back
modelCreateMeshRectangle( x1, y1, z1, x2, y1, z1,
   x2, y2, z1, x1, y2, z1 )

-- right
modelCreateMeshRectangle( x2, y1, z1, x2, y1, z2,
   x2, y2, z2, x2, y2, z1 )

-- left
modelCreateMeshRectangle( x1, y1, z2, x1, y1, z1,
   x1, y2, z1, x1, y2, z2 )

-- top
modelCreateMeshRectangle( x1, y2, z2, x1, y2, z1,
   x2, y2, z1, x2, y2, z2 )

-- bottom
modelCreateMeshRectangle( x1, y1, z1, x1, y1, z2,
   x2, y1, z2, x2, y1, z1 )

modelSelectAllVertices()
selectedWeldVertices()

User interface

To run a script in the graphical user interface, select "Run Script..." from the "File" menu. This will allow you to chose a script file to run on the current model. The result of the script will be displayed in the status bar.

If there was an error running the script the error will be displayed in the status bar. Long errors may be truncated. In these cases the entire error may be visible by hovering the mouse over the status bar to see a tool tip.

Once you have run a script, you can run it again by selecting the script name from the "Recent scripts" submenu in the "File" menu.

Command line

To run a script from the command line, use the --