Current installation

3dpalign is currently installed on the "gem" machines located in 56 Jorgensen. The binary is "~dazuma/3dpalign/bin/3dpalign". Source code is available in the directory "~dazuma/3dpalign/src/".

Installing elsewhere

3dpalign can theoretically be installed on any computer with OpenGL and GLUT libraries, though in practice I've only tried compiling on SGI Indy and Indigo machines.

To install on a different system, first copy all the source files and the Makefile into a directory. Next, you will need to make modifications to the Makefile describing the location of your OpenGL and GLUT headers and libraries.

1. On the line that begins with "LIBS=", replace "../lib/libglut.a" with the path of your glut library.
2. On the line that begins with "CFLAGS=", replace "-I/usr/ug/include" with the search path where the "GL/gl.h" and "GL/glut.h" headers can be found.

Finally, you can build the application using "gmake". Note that, on some systems, the generic "make" utility is not compatible with this Makefile, so you should normally use the GNU make utility.

To clear out the dependency files, object files and executable, you can "gmake clean".

The following are notes on using the volume carving and mesh generation tools written by Emil Praun. This information is based only on what I've been able to find out through experimentation. You'd best direct specific questions to Emil.

After you have finished using 3dpalign, generating a mesh is a three-step process. First, you need to use fit2vol to normalize the volume and fit it into the unit cube. Second, you should run volcarve to generate a signed distance function describing the model. Third, you should run mCubes to generate the mesh. Soft links to the appropriate binaries are located on the gems in the directory "~dazuma/3dpalign/bin/".

Running fit2vol

The first step is to run fit2vol. Give it the name of your .3dp file as an argument. It will ask you if you want to manually specify the volume to fit; normally, you should answer "n". fit2vol will then generate a new set of .params files for you, with the malign matrices modified to fit into the proper volume for the carver. Your old .params files will be renamed with the addition of the suffix ".old". This process should take just a few moments.

Running volcarve

The next step is to run volcarve. Give it the name of your .3dp file as an argument. You will see an inventor window, which will probably appear blank to start off.

Your first trick is to get something to show up in the window. Select the arrow tool, and hit the "b" key to display the object boundaries. Then, select the hand tool and try to move (rotate) the image around until something shows up. It will probably appear as a blocky volume that bears little, if any, resemblance to your object. If nothing appears, repeat the process. If, at any time while you're moving the view, the program says "finding connected component", it means you were using the arrow tool instead of the hand tool. To get out of that mode, press "f" then "b" (with the arrow tool still selected), then select the hand tool and try again.

Once you actually see an object, you are ready to begin refining the carve. With the arrow tool selected, hit the "r" key to refine the carve. The program should quickly run through some processing, display something to the effect of "resolving boundaries at resolution 16", and redisplay the object with a little more detail.

You should repeat this process several times. By the time you reach resolution 32 or 64, you should be able to recognize the volume being displayed. Your object will be present, and there probably will also be several other "extra" volumes. Don't worry about this-- it's normal. Also, by that time, you should be noticing that each time you repeat the process, it takes much longer to complete. Resolution 128 will probably take as much as a few minutes, and higher resolution refinements will be even more time-consuming. Typically, you will want to stop after 128, 256, or 512.

Next, you need to isolate the volume that corresponds to your object. To do this, rotate the view so you get a clear view of your object, then click on it. Then be prepared to wait. I'm not sure exactly what the program is doing at this point, but it's probably walking the volume and identifying the voxels that you have selected. This process may take a very long time. Expect several minutes for resolution 128, up to 15-20 minutes running at resolution 256, or up to several hours for 512.

Once this processing has finished, you should see only a display of your object. If it looks correct, hit the "k" key (again, making sure the arrow tool is selected) to keep only that volume. The program will print out a warning that further refinement will no longer have any effect. Finally, hit "s" to save the signed distance function describing the object as "signedD.volume", and you're done. Press "q" to quit.

If the volume you selected in the previous step turns out to be only part of your object, you'll need to use a different method to isolate your volume. Instead of pressing "k", press "f" then "b" to get the entire volume back. Next, click on all the volumes that look like they're NOT part of your object, and hit "d" to delete each one. Keep doing this until only your object is left. You can then save the volume.

Running mCubes

The final step is to generate the mesh. This can be done using the mCubes tool. Simply run "mCubes" without any arguments in the same directory as your "signedD.volume" file. It will take anywhere from a few seconds to several minutes to run, depending on the resolution you ended with, and will spit out a file "volume.iv".

The caveat with mCubes is that it may require a LOT of temporary disk space. Resolution 512 will require up to 100 megabytes of space for the temporary file, and the final output will require between 30 and 40 megabytes. Resolution 256 requires only around 30 megabytes temporary space, and up to 10 megabytes for the output. Lower resolutions will have lower disk space requirements.