Java MD3 Model Viewer

The Java MD3 Model Viewer is a windowed Java program that uses OpenGL to display a Quake 3 .md3 model file on the screen.

The Java source code (which is provided under the GNU General Public License), together with its javadoc documentation, is included! You can find it in the sources.zip file that comes with the distribution.

The latest version of this program and tips and tricks for efficient use can be found on the Java MD3 Model Viewer Home Page (http://fragland.net/md3view).

What's New?

• New in version 1.2.2
  • There's a new splash screen and icon, made by David 'dines' Durrenberger.
  • The apply submenu of the file menu moved to the model menu.
  • Added export to the Alias Wavefront .obj file format. This also exports the vertex normals and texture coordinates.
  • The different parts of a player model are now automatically assembled when you open one part. This makes viewing of player models much easier: just open "lower.md3"! You can disable this function in the options.
  • Added detach part functionality to model menu.
  • Made some animation names more verbose.
  • Fixed bug where textures cannot be viewed before a model has been opened. Also, texture modes no longer affect the texture viewer.
  • Added apply texture to mesh functionality. A menu will allow you to apply a texture (.jpg or .tga) to a particular mesh of a model (i.s.o. to the entire model, as is the case with the old apply texture function).
  • Textures are now exported to the same directory as the .wrl file when exporting a model to VRML97, unless this option is turned off in the options panel. Thus it is no longer necessary to manually extract the textures from the pak and edit the .wrl to update the texture URLs!
  • Line breaks are added as needed in the mesh names list of the model properties.
  • The program is now 'officially' distributed under the GNU General Public License. This was allready the case in the past (because the program builds on GL4Java - which is LGPL - and the Mental Vortex MD3View - which is GPL -). The GPL itself is accessible from the help menu.
  • Fixed bug in VRML97 exporter that caused generation of corrupt .wrl files when a model with missing textures was exported.
  • Donald Gray contributed to the project by writing a Autocad DXF exporter.
• New in version 1.2.1
  • Fixed bone frames having all kinds of colors. Also, the position data member of a boneframe is now drawn. The boneframes are green, the model itself white, the boneframe position red and the vertex normals yellow.
  • Garbage characters are now filtered from the tag, mesh, model and texture names.
  • Added animation properties button to the animation control panel.
  • The default 'All Frames' animation, which plays all available animation frames, is now allways present, also when the animation.cfg file is found. (Easy when debugging your animation.cfg file).
  • MD3 loader is more robust: it now correctely deals with non-default offsets for the different data parts of the file.
  • Changed some animation names based on info from Paul Steed.
  • Added show vertex normals function to view menu.
  • Added PLG export function.
  • Added support for sex, headoffset and footsteps in animation.cfg loader. Also fixed TORSO_OFFSET compensation code in CFGIO.
  • The meaning of the unknown bytes in the MD3 format is now known and the md3.md3model package was modified accordingly (Big thanks to HK Developments!).
  • JPG textures are now supported (they're used from the Q3DemoTest on).
  • Added option panel, accessible from the options item in the file menu, which lets you control the display of error messages, auto skin loading and jpg texture loading.
  • Default rendering mode is now FLAT_TEXTURED (i.s.o. SHADED_TEXTURED).
  • Model properties output now contains mesh names.
  • Added close model function to file menu.
  • Reorgenized menus: there's now a model menu, which contains the tags menu. When you use the 'Attach File' submenu of the model menu you can attach a file to a certain tag position of the current model.
  • Animation control panel moved to tab on right side of viewer. Also, it's now in a seperate class: MD3ViewAnimationControl.
  • Lots of small code changes all over the program to provide pak file support (i.e. in the searchForPath method).
  • Added full featured pak file browser: you can view text files, apply skins, view textures, load models, ... directely from a .pk3 file! Right click on a node in the pak file tree for a popup menu with lots of new functions!
  • Changed float[] in Vec3 to 3 seperate floats. This lead to a 25% performance improvement during interpolated animation. However, the cost is less elegant code.
  • Fixed bug in blending code: glDepthMask(GL_FALSE) needed for transparent meshes.
  • Command line support is back. The first command line argument, if present, will be intepreted as the name of an .md3 file that should be opened.
  • Fixed small mistake in light source setup.
  • Cleaned up OpenGL code a bit which led to some performance improvements.
  • Last directory from which a file was opened and last directory to which a file was saved are now maintained independently.
  • Added save screenshot function to the file menu. This will save the viewport to a Targa file.
  • Fixed some NullPointer bugs (in MD3GLModelFactory and MD3View).
• New in version 1.2
  • Added crude filename filtering to open-file dialog boxes and default save-filename to save-file dialog boxes.
  • Added import skin function to file menu. This allows you to import a .skin file (they come with player models).
  • Added show bone frame box function to view menu. This allows you to display the bounding boxes of the models for each animation frame.
  • The properties function now also lists the number of tags. Also changed layout of output.
  • Changed MD3 loader. It now also supports the hand models, i.e. shotgun_hand.md3. These hand models contain no meshes (and thus no vertex and triangle data), only animation frames to animate the use and changing of the weapon in question. Load one and attach a weapon to the weapon tag and you'll understand...
  • Added transparency. Transparency is processed on a per mesh bases, so some meshes in a model can be transparent while other meshes in the same model are not. Currently transparency is determined based on the mesh name stored in the .md3 files (hack :).
  • Restructured the code: the general MD3 model classes are now in a package md3.md3model, the viewer specific ones are in md3.md3view and general utility classes reside in the md3.util package.
  • Completely redid animation system. The animation config files (animation.cfg), that accompany the player models, are now parsed and the information in them is used to enable you to play the different animations defined for the player models. Interpolation between key frames was also added and can be toggled on and off.
  • Added gray scale and 24 bit color map support to the TGA file loader. This was necessary because a new texture in Q3T 1.07 (pole.tga) is an 8 bit gray scale Targa image.
  • Added quick manipulations function to view menu. This will switch the view to wire frame mode while the user manipulates the model (rotate, scale, ...). If you have a slow GL card you'll like this!
• New in version 1.1
  • Fixed textures displaying strange bug.
  • Improved model and texture loading performance using buffers.
  • Added panning of model using shift + drag with first mouse button.
  • Added reset view function to view menu to reset manipulations (scale, rotate and pan) of view.
  • Added properties function to file menu to display some stats about the model (nr. of triangles, vertices, ...).
  • Kicked out command line argument support.

Installation

Upgrading a previous version

Upgrading a (old) working version of the Java MD3 Model viewer is very simple: just replace your old md3view.jar file with the new one (make sure you're not running the viewer while doing this)!

Installing it as an application

Easy Win32 installation instructions

On Win32, follow these simple required-software-installation-steps:

1. Install the Java Runtime by executing the installer exe. In the following steps I assume that you install this to C:\Program Files\JavaSoft\JRE\1.2.
2. Unzip libGL4Java2.X.Y.Z-Win32-x86.zip to C:\Program Files\JavaSoft\JRE\1.2\bin.
3. Unzip gl4java2.X.Y.Z-jar.zip to C:\Program Files\JavaSoft\JRE\1.2\lib\ext (You'll have to create the ext subdirectory!).
4. Download the Java MD3 Model Viewer and unzip the distribution to a directory of your choice.

General installation instructions (mostly for non Win32 users)

Any OpenGL capable system (Linux, Solaris, WinNT, SGI, ...) should suffice to run the viewer. Most people will use the program as a normal application. If you want to do that, follow these instructions (If you're new to Java, you might want to read the Java Newbie Tips first):

1. Get and install Java 1.2.x. You need either the Java SDK or Runtime. Both are available from Sun at: http://java.sun.com.
2. Get and install GL4Java, the Java OpenGL binding. You will need at least version 2.0.1.1 of GL4Java! You can get it at http://www.jausoft.com. (You need 2 files: for version 2.0.1.2 on a Win32 system these would be gl4java2.0.1.2.zip and libgl4java2.0.1.2-win32-x86.zip. Unzip the first one into the 'ext' directory of your Java Runtime. Extract the libraries in the second file into the 'bin' directory of your Java runtime.)
3. Unzip the Java MD3 Model Viewer distribution zip file into a directory of your choice.
4. When on a Windows system, start the md3view.bat file. On Unix machines, type the content of the mdview.bat file directely into your command line.
   

Common Installation Problems

• Error message: "Execption in thread "main" java.lang.NoClassDefFoundError: gl4java/awt/GLCanvas"
  This is because Java can't find the 'gl4java.jar' file. Make sure you have C:\Program Files\JavaSoft\JRE\1.2\lib\ext\gl4java.jar (Note that you might have to create the 'ext' dir yourself!).
• Error message: "bad command of file name" Edit the md3view.bat file to include the directory where java.exe resides on your system, eg. 'c:\windows\system\java -jar md3view.jar'.

Tips

• I recommend that you use the hotspot JVM (you can also get this from Sun at http://java.sun.com) because it will greatly improve performance!
• An easy way to bring the full 3d glory of your new skin to the web is by exporting your model, with the skin applied to it, to VRML97. Now convert all textures that you use to jpg format (if necessary), and once that's done, edit the VRML file that was generated (normally has extension .wrl) with a text editor and change the references to the original textures to point to your .jpg textures (The references are allready correct if your model only contained jpg textures!). The last step is to include the following in an HTML page (I assume the HTML page is in the same directory as the .jpg files and your .wrl file): <embed src="mygeneratedfile.wrl" width="99%" height="88%" vrml_dashboard="TRUE"></embed> Note: I don't know how legal this would be....I take no responsibility whatsowever...

If you're new to Java, here are a few tips that might help you in getting Java programs, like the Java MD3 Model Viewer, to work:

• Java is case sensitive, like C/C++ (also on systems that are not, like Windows 98)!
• Java programs can't be executed directely by your machine. You'll need a JVM (Java Virtual Machine), aka Java Runtime, to execute a Java program.
• The Java CLASSPATH is an environment variable similar to the well known PATH environment variable. PATH is used to tell the OS where to find executables. CLASSPATH is used to tell the Java runtime where to find .class files, that is, Java executables.
• A Java application is a stand-alone Java program. A Java applet is a Java program that runs inside of your Web browser. The Java MD3 Model viewer is a Java application.

Todo

• get applet stuff working properly and easily
• real filename filtering in file dialogs (AWT bug 4031440)
• add shader file support
• support for multiple .pk3 files open at the same time
• Recent models/recent pak files list
• Save settings on exit
• ...

Known Bugs/Strange Things

• sensitive mouseDragged(), reacts when double clicking in file dialog
• debug output ("gc=0;"), this is done by the gl4java libs...has something to do with gljFree()...only happens with some OpenGL drivers...
• crash when you do resises of OpenGL canvas (on G400, ATI 3D Rage)...probably a problem in GL4Java...
• artefacts during interpolated animation (i.e. shrinking of models)...probably float rounding problem during quaternion slerp...
• saved screenshots have strange deformations from time to time...probably some sync problem in the GL driver when reading the frame buffer...
• textures are not shown when model is opened using command line argument...for some strange reason GL_TEXTURE_2D is not enabled when texture data is uploaded?!?...probably synchronization problem between threads...
• strange transparency artefacts (e.g. head not blended behind flash of weapon with Anarki model)...this is a known bug :-/

Credits

• Mental Vortex for creating the original MD3View!
• David 'dines' Durrenberger for creating the cool art: splash screen and icon (versions up to 1.2.1 used art by casManG)!
• HK Developments for some MD3 model format info and help in debugging!
• Donald Gray for the DXF exporter!

Contact

If you have any comments, suggestions or bug reports, let me know: Erwin 'KLR8' Vervaet.

Enjoy!