Toposcope source files - version 961022.
PLESE READ THE COPYRIGHT NOTICE AT THE END OF THIS FILE

CONTENTS

This directory tree contains the sources for the "toposcope", a set of
programs for the visualization of 2D cellular complexes.

For a description of the problem and how the programs do, see

  @inproceedings{ros-sto-96-vis,
    title = "Automatic Visualization of Two-Dimensional Cellular Complexes",
    author = "Rober M. Rosi and Jorge Stolfi",
    booktitle = "Proceedings of Graph Drawing '96",
    pages = "13 pp.",
    note = "To appear.",
    month = sep,
    address = "Berkeley, Calif.",
    year = 1996
  }

  @techreport{ros-sto-96-vistr,
    title = "Automatic Visualization of Two-Dimensional Cellular Complexes",
    author = "Rober Marcone Rosi and Jorge Stolfi",
    institution = "Institute of Computing, University of Campinas",
    number = "IC-96-02",
    month = may,
    year = 1996
  }

  @masterthesis{mac-95-thesis,
    title =  {Visualiza\c{c}\~ao Autom\'atica de Complexos Celulares Arbitr\'arios}, 
    author = {Rober Marcone Rosi},
    school = "Departamento de Ci\^encia da Computa\c{c}\~ao, IMECC, Universidade
                    de Campinas",
    month = dez,
    year = 1995
  }

This tar file was quickly put together on 96-10-22, in response to
external requests.  We hope it contains all necessary libraries and
modules, but we haven't tested for that.  

The tools are written in Modula-3, and have been tested with release
3.5.3 of the DEC SRC compiler and libraries. 

The main programs are

  MakeShape 
    Generates the topological tructures for several simple complexes
    (torus, klein bottle, tritorus, star, etc.)  with random vertex
    coordinates.
               
  SmoothShape
    The initial smoothing heuristics.
  
  OptShape
    The energy optimizer.
  
  RefineTriang
    Refines an existing triangular mesh.

  TriangToX3D
    Converts a configuration file to the format understood by "x3d",
    an interactive wireframe viewer.

  TriangToPOV
    Converts a configuration file to the format understood by POV-Ray,
    a popular raytracer.
  
Other auxiliary programs are:

  MakeRawCube, MakeRawCylinder, MakeSquare
    Build complexes with fixed topology and geometry:
    a cube, a cylinder, a flat square.
  
  RandomShapes
    Randomizes the coordinates of a given mesh.
  
  TestEnergy, EnergySlice
    Generate "gnuplot" data files showing a cross-section of the
    energy function along a specified subspace of the configuration
    space.  TestEnergy 1-D slices (for the "plot" command), whereas 
    EnergySlice generates 2D slices (for the "plot3d" command).
                 
The programs communicate via ASCII files. The main file type is the
".top" format, which describes the topology of a triangular mesh, its
geometric configuration, plus colors, edge thicknesses, etc.  The
format is described in the comments inside file sample.top The module
libm3marcone/src/Triang.{i3,m3} has routines for parsing and writing
".top" files.

A typical run involves
                                        -> TriangToX3D -> hull -> x3d
                                       /
  MakeShape -> SmoothShape -> OptShape 
                                       \
                                        -> TriangToPov -> POV-Ray

Typically one would run SmoothShape some 5-20 times with different
random seeds, check the results with TriangToX3D and x3d, pick the
best one, and run OptShape once or twice on it, with varying
parameters.

There are several shell scripts scattered throughout the directory tree.
They should be viewed merely as possible sources of inspiration.
It is highly unlikely that they will work in your environment without
extensive modifications.

J. Stolfi
96-10-22

***************** START OF COPYRIGHT AND AUTHORSHIP NOTICE **********

All files in this directory tree are Copyright 1996 by Jorge Stolfi,
Rober Marcone Rosi, and Universidade Estadual de Campinas, Brazil---
unless stated otherwise in the files themselves.

THESE FILES ARE DISTRIBUTED WITH NO GUARANTEE OF ANY KIND.  Neither
the authors nor their employers may be held responsible for any losses
or damages attributed to their use.

These files may be freely copied, distributed, modified, and used for
any purpose; provided that any subtantial excerpt of these files that
is redistributed or incorporated in other software packages is
accompanied by this copyright and authorship notice, and is made freely
available under these same terms.
***************** END OF COPYRIGHT AND AUTHORSHIP NOTICE ************