Caltech Multi-Res Modeling Group - Progressive Geometry Compression Software

Introduction

This package is part of an implementation of "Progressive Geometry Compression" as described in Siggraph 2000 paper of the same name. It includes wavelet transform code, a zerotree coder, file conversion tools, and a mesh viewer which can progressively read encoded files. The tools provide many options which are likely of interest only for researchers who wish to compare results. Note that we do not include any remeshing tools nor the Touma Gotsman (TG) coder in this package. A complete application would require these tools. All tools included are compiled for Win32 platform (Windows NT/9x).

The overall process of encoding consists of applying a wavelet transform to a semi-regular mesh followed by zerotree coding of the resulting coefficients. The resulting files can then either be viewed directly with a supplied viewer or further manipulated with other tools. For example, decompression is performed by running the zerotree coder to decode wavelet coefficients which can then be followed by an inverse wavelet transform.

A simple example run consists of several steps and would proceed as follows

lw ..\models\rabbit.dat

This will produce a file rabbit.lw which contains the Loop wavelet transform of the input mesh. Subsequently these coefficients must be encoded

code rabbit.lw

This results in two files rabbit.pgc and rabbit.pgz. The former contains the coarsest level connectivity information which would typically be encoded with a TG coder (not included), while the rabbit.pgz file contains the actual zerotree coefficients. As a result of this the actual filesize of rabbit.pgc is larger than what one would get after proper coding of it, though the rabbit.pgz file is the properly coded zerotree file. Now the result can be viewed

mview rabbit.pgz

(note that although we only specified rabbit.pgz here mview quietly also looks for rabbit.pgc.)

Other examples can be run with different input files such as venus.dat etc. These files can be found in the models directory. Note that all executables rely on a .dll file which must be in the current directory or in the system path.

The following paragraphs contain much more detailed information on these tools which allow them to be used in scripts with a variety of settings.

Wavelet Transform

We support two wavelet transforms: Loop and lifted Butterfly, which are implemented by lw.exe and bw.exe respectively. These tools require two parameters: source and destination files. For the forward transform the input file must be a .dat file. The output file produced (regardless of filename extension) has the same internal layout, but contains the wavelet coeffcients. Such a file is suitable as input for the inverse transform.

Example

forward transform

lw sourceFile targetFile
bw sourceFile targetFile
inverse transform

lw sourceFile targetFile -u
bw sourceFile targetFile -u

Reconstruction is adaptive: only faces with nonzero wavelet coefficients are subdivided. At low bit rates this results in a very coarse approximation. More precisely the actual output produced is a control mesh for a subdivision patch surface. To visualize the actual surface subdivision is performed until a user controllable flatness threshold is met.

Example

Inverse transform with refinement (flatness threshold 0.01)

lw sourceFile targetFile -u -U0.01
bw sourceFile targetFile -u -U0.01

Notes:

There is an option to turn off lifting in the Butterfly transform. Use the -n switch for nonlifted Butterfly. Make sure to use consistent switches for both forward and backward transforms. The layout of the input and output files is identical. The only distinction is that one contains wavelet coefficients while the other contains actual vertex positions.
The wavelet coefficients are expressed in local coordinate frames. The switch -l turns off the local frame transform.
The forward Loop transform is relatively slow since it requires the solution of a linear system. Use the -v switch to get a verbose report on the solver progress.
This implementation does not support crease tags.

Zerotree Coder

The zerotree coder is code.exe. It requires three parameters: a wavelet file, a coarse file, and an archive file. When these files are explicitly specified their names or extensions do not matter. Compare this to the example we provided at the very beginning in which only one name is specified and all others are inferred. In encoding mode the coder reads the wavelet file, writes the coarse level information to the coarse output file (without any compression), and encodes the wavelet coefficients into an archive. In decoding mode it reads the coarse file, decodes the archive, and writes a wavelet file.

Example

Encoding a file

code waveletFile coarseFile ArchiveFile
Decoding a file
code waveletFile coarseFile ArchiveFile -u

Progressivity can be controlled by either setting the target rate (archive file size) or by setting the number of bitplanes (default 12) to encode or decode.

Examples

Encode 10 bitplanes

code waveletFile coarseFile ArchiveFile -d10
Encode to archive size of 1000 bytes

code waveletFile coarseFile ArchiveFile -s1000
Decode first 7 bitplanes (archive must contain at least 7 bitplanes)

code waveletFile coarseFile ArchiveFile -u -d7
Decode first 900 bytes of the archive
code waveletFile coarseFile ArchiveFile -u -s900

The zerotree coder decodes the mesh adaptively. It subdivides triangles only when it decodes corresponding nonzero coefficients. The -f switch can force the coder to reconstruct a uniform mesh.

Example

Uniform reconstruction

code waveletFile coarseFile ArchiveFile -u -f

By default code.exe does not encode any coarsest level information. The -T switch forces encoding of the coarsest level geometry. In such a case some number of bitplanes (default 5) of the coarsest geometry is stored directly behind the archive header. All following refinement bitplanes are stored as the zerotree coder descends a given bitplane of wavelet coefficients. In this mode the zerotree coder writes to the coarseFile only the connectivity and zeroes out all geometry information.

Examples

Encode coarsest level geometry

code waveletFile coarseFile ArchiveFile -T
Encode coarsest level geometry with 4 leading bitplanes
code waveletFile coarseFile ArchiveFile -T4

Information about which wavelet transform was used can be stored into the archive header using -w switch

-w2 - Butterfly
-w6 - nonlifted Butterfly,
-w3 - Loop

This information is used by the mesh viewer to choose the appropriate wavelet transform. Again, in the example mentioned at the very beginning of this document the transform type was assumed so no such flag had to be given. Here we explicitly give the user control over this to facilitate experimentation. As before consistent use of flags then becomes the user's reponsibility.

Example

Store Loop scheme number

code waveletFile coarseFile ArchiveFile -w3

Note: We do not do any compression of the coarsest level connectivity. A single rate coder must be used to encode this information. For this purpose we used the coder of Touma and Gotsman (TG) and the numbers reported in the paper reflect the use of the TG coder for the coarsest level connectivity. Since we do not own the TG coder, it is not included in this distribution and we have chosen a standard ascii description of the coarsest level connectivity which takes up considerably more space than what the TG encoded version of the file would require. WARNING! The TG coder does not preserve the order of faces in the mesh which is essential for the zerotree coder. However, a second encoding does not change this order. Therefore, if one wishes to use the TG coder with our files the data file must first be preprocessed (before the wavelet transform) to adjust the order of faces to one which is reproduced by the TG coder. We include the fixcon.exe tool for this purpose. Here is an example of its usage:

Dump coarsest mesh in wrl format

fixcon dataFile coarseFile -c
Encode and then decode coarseFile using the TG coder
Adjust connectivity
fixcon dataFile fixedDataFile decodedCoarseFile

File Conversion

We use our own multiresolution format to represent data. This format is used both for the original input mesh (.dat) and the files produced by the wavelet transform. In the latter case the numerical values are interpreted as wavelet coefficients, not as vertex positions. It is the user's reponsibility to use them accordingly. The included dat2iv.exe tool can be used to convert data to some other formats.

Examples

Conversion to Inventor format

dat2iv srcFile dstFile
Conversion to VRML format

dat2iv srcFile dstFile -Dw
Conversion to our ASCII multires format

dat2iv srcFile dstFile -Da
Conversion to our binary multires format
dat2iv srcFile dstFile -Db

Note that conversion from an Inventor or VRML to a multires format creates a single resolution file. Therefore, any conversion from a multires format is not invertable.

This tool can also be used to dump hierarchy information into a text file. This works with original meshes as well as their wavelet transforms since they both use the same format. The tool picks one coarsest level triangle and one of its neighbors and represents all children of these faces as entries of a square matrix. Then it writes the matrix to a text file. By default it writes the Z vertex component of the first face.

Example

Dump Z components of the first triangle

dat2iv multiresFile txtFile -Dt
Dump Z components of 20th triangle

dat2iv multiresFile txtFile -Dt19
Dump X components of 20th triangle

dat2iv multiresFile txtFile -Dt"19 0"
Dump Y components of 20th triangle

dat2iv multiresFile txtFile -Dt"19 1"

Mesh Viewer

The mesh viewer mview.exe can progressively read encoded meshes as well as uncompressed files in multires format. While it is in progressive mode (started by opening any encoded mesh) it shows a progressive load slider. The position of the slider determines how much of the file is to be decoded (the right most position corresponds to the whole archive). Also, the user can control a reconstruction flatness threshold. During inverse wavelet transform mview does adaptive subdivision until it meets this flatness threshold (the value 0 corresponds to uniform subdivision to some maximal depth). The mesh viewer always assumes that the coarsest mesh file has the same name as the archive and the extension .pgc. For example, when specifying rabbit.pgz on the commandline the tool will automatically look for rabbit.pgc in the same directory and will fail if such a file is not found. Also, it tries to find a wavelet scheme number in the archive header. Use code with the -w switch to store the scheme number into the header.

With this package release we also include compressed files for a few models. They were encoded with the Loop transform and have 12 bitplanes of wavelet coefficients. The coarsest level geometry was also encoded with 5 leading bitplanes. We also include the same models encoded using the lifted butterfly transform. The wavelet files were encoded with the same settings as the corresponding Loop wavelet files. The compressed files are located in the models\buttefly directory. One can compare reconstruction quality of the transforms using commands like

mview venus.pgz

mview butterfly\venus.pgz

Acknowledgments

The code was written by Andrei Khodakovsky. It contains elements of earlier codes contributed to by Denis Zorin, Igor Guskov, Wim Sweldens, and Peter Schröder. Our implementation uses an arithmetic coder written by Geoff Davis and John Danskin.

To get the distribution you need to download the executables and the models directory. If you want to compress your own multiresolution models you need to convert them to our DAT format. For comparison purposes you may be interested in the original finest level irregular meshes. The horse, rabbit, and Venus head models are courtesy of Cyberware, the bunny model is courtesy of Stanford University.