floodfilling and distance map generation for 3d surfaces
Dan Morris - Stanford University Haptics Lab

overview | using voxelizer interactively | using the voxelizer .ini file | output format
download | sample meshes | technical information | contact

overview This program floodfills a surface mesh (which must be very nearly watertight) to produce a voxel array, optionally computing a distance field in the process (the distance from each voxel to the surface and the corresponding closest surface point). The program can also compute shortest distances for each voxel to a series of additional meshes (up to 5). It can load models in 3ds, obj, and ply formats, and the .node/.face format used by TetGen. The output format is a ".voxels" file, which is a binary format described in voxel_file_format.h . The program can also output tetrahedral meshes in TetGen format; the floodfilling process is identical to that used for voxelization, and each voxel is simply split into five tets (so the mesh is not conformal). Voxelization can be initiated interactively or from an .ini file. The application was developed in C++ and is based on CHAI and WinMeshView.
- using voxelizer interactively When voxelizer starts up, you'll see the GUI pictured at the right. To voxelize a model, click "load model" and choose the model you want to voxelize. Before voxelizing an object, you may want to click "test voxelization" just to confirm that the floodfill is successful and that the mesh is watertight (if it's not, the whole bounding box of the mesh will get filled). When you're ready to voxelize, just click "voxelize". If the object is "hello.obj", you'll get a file called "hello.v[nn].voxels", where "nn" indicates the resolution of voxelization (see below). Other parameters you can change: You can change the resolution of voxelization (or tetrahedralization) in the "voxel resolution" box. This is the number of voxels along the longest axis of the bounding box of your object. Larger voxels produce a coarser mesh and also may lead to problems getting through "tight spots" in your mesh. Voxels are isotropic, so the long-axis resolution determines the resolution on the other two axes. Sometimes the seed voxel for the floodfilling is a bad choice. You can change the seed (where the flood-fill begins) by clicking any triangle in the mesh. You can load "subtractor" and "modifier" models _after_ you load the model you want to voxelize. A "subtractor" model is used to put "holes" in your voxelized object; it blocks off space that should be considered _outside_ the object. A "modifier" model is used for distance-field computation; every voxel is output along with its shortest distance to each of the modifiers. Use the "compute distance field" check to determine whether the program computes a distance field when it computes a voxel array. This takes about 10 times longer than flood-filling alone, so if you just want a voxel array, you should leave this un-checked. You can rotate and move the model in the viewport to examine it; these transformations will _not_ affect the output. Use the following mouse-drag operations to manipulate the object (inherited from winmeshview):
  Left-drag | rotate the object
  Shift-left-drag | move the object
  Right-drag | pan the camera
  Shift-right-drag | zoom the camera
  Middle-drag | rotate the camera
using the voxelizer .ini file When voxelizer starts up, the program will look for a file called voxelizer.ini. The supplied .ini file looks like:
    LONG_AXIS_RESOLUTION 120
    COMPUTE_DISTANCE_FIELD 0

    # OBJECT_TO_VOXELIZE bunny.capped.obj
    # SEED_TRIANGLE 5

    # OBJECT_TO_VOXELIZE gear.obj
    # SEED_TRIANGLE 5

    # OBJECT_TO_VOXELIZE happy_vrip_res4.ply
    # SEED_TRIANGLE 500

    OBJECT_TO_VOXELIZE dragon_vrip_res2.ply
    SEED_TRIANGLE 10000

    VOXELIZE_IMMEDIATELY 0
Blank lines and lines beginning with '#' are ignored. The available options in this file are:
LONG_AXIS_RESOLUTION | same as the corresponding dialog box, explained above
COMPUTE_DISTANCE_FIELD | same as the corresponding check box, explained above
OBJECT_TO_VOXELIZE | the mesh to load at startup. only one meshes will be processed; if more than one OBJECT_TO_VOXELIZE entry is present, all but the last will be ignored.
SEED_TRIANGLE | a seed triangle to start the flood-fill
VOXELIZE_IMMEDIATELY | If this is 0, the program will load the specified model and start the GUI. If this is 1, the program will immediately voxelize the specified model and quit.
output format Voxel files are stored in a binary format, specified in detail in voxel_file_format.h
sample models Four sample models are included with the voxelizer zipfile. They don't all voxelize well with the default seed; load them using the provided .ini file (which contains commented-out entries with seeds for each model), or click somewhere near the core of the model before voxelizing. Models were obtained from the Stanford 3D Scanning Repository, except for the gear, which came from the INRIA mesh repository.
bunny | happy | dragon | gear
downloading voxelizer The voxelizer zipfile contains the voxelizer binary plus required dll's, sample models, the default .ini file, and this .html file.
technical information Technical information about this application can be found in the following: Morris D. Automated Preparation, Calibration, and Simulation of Deformable Objects. Stanford University Department of Computer Science Technical Report 2006-07. Morris D. Algorithms and Data Structures for Haptic Rendering: Curve Constraints, Distance Maps, and Data Logging. Stanford University Department of Computer Science Technical Report 2006-06.
contact Feel free to send comments, suggestions, bug reports, or indications that this was useful software to dmorris@cs.stanford.edu.