  ShellyLibV2.0
  Randolf Schultz rschultz@informatik.uni-rostock.de
  27 May 1996

  This is the documentation of ShellyLibV2.0, the ShellShapeGenerator.
  ______________________________________________________________________

  Table of Contents:

  1.      About this Document

  2.      Introduction

  3.      Changes

  4.      Using the Library

  4.1.    General Usage

  4.2.    Structures

  4.3.    Functions

  5.      Using shelly

  6.      Using the Shell Laboratory

  6.1.    Starting Up

  6.2.    The Main Window

  6.3.    The Menu

  6.4.    The 3D-View

  6.5.    File Selection Boxes

  6.6.    Slider Calibration

  6.7.    Notes about Entries

  7.      Parameters of the Shell Generator

  8.      Calculation Modi

  8.1.    The Nodule mode

  8.2.    The GenCurve mode

  8.2.1.  General Information

  8.2.2.  Creating Generation Curves

  9.      File Format

  10.     Compatibility

  11.     Output Formats

  12.     Known Bugs

  13.     Addresses, Pointers, Literature
  ______________________________________________________________________

  1.  About this Document

  This document has been written using the Linuxdoc-SGML system to
  generate files in a variety of text formats from one source file.
  There are plain ASCII, HTML and Postscript versions of this document
  prepared for you.

  In addition, you can use the provided SGML-source to generate other
  formats.

  Note, that the plain ASCII version probably misses a lot of formatting
  information.

  2.  Introduction

  ShellyLib is a small set of C-programs for generating seashell or
  snail shapes.  ShellyLib supports many common file formats, see
  section ``Output Formats'', and has been designed to be as portable as
  possible, see section ``Compatibility''.

  In contrast to Shelly (the ancestor), ShellyLib is not Freeware but
  Shareware.  Please read the file "License" for further information.

  ShellyLib contains a small library ("libshelly"), a simple frontend
  called "shelly" and a GUI called "Shell Laboratory".

  The frontend "shelly" behaves more or less just like the old Shelly,
  that is why it is still named this way.  The "Shell Laboratory" is
  partially written in Tcl/Tk and C, and uses OpenGL for immediate
  rendering of the shells.

  The algorithm used to generate the shells is an extended version of
  the algorithm by M.B. Cortie, found in Computer and Graphics, Vol. 17,
  No. 1, pp. 79-84, 1993, "Digital Seashells".

  3.  Changes

  A lot has changed from version 1.6 of Shelly (the ancestor of
  ShellyLib) to the current version 2.0:

  o  Legalities have changed, read the file "License"!

  o  Almost everything has been completely rewritten, therefore, I
     suggest to reread the whole documentation, even if you feel
     familiar with Shelly!

  o  Bezier output for POV-Ray creates really smooth surfaces now.

  o  Several new output formats, e.g. Truespace, RIB, SCED, have been
     added.

  o  The handling of scale factors has changed. There are file format
     dependant scale factors now, to ensure a unique size of the
     generated shells over the variety of output formats.

  o  ShellyLib has a really cool GUI now, unfortunately, it is not as
     nearly as portable as the library itself.

  o  The former "NewNod" mode is now called "Nodule" and has been
     improved in terms of speed and usability. The old "Nodule" mode is
     gone.

  o  The code has been split into several parts.  The shell generation
     is done by a small library called "libshelly".  Furthermore, there
     are two example frontends that use the library "shelly" and the
     "Shell Laboratory".

  o  The original algorithm of M.B. Cortie is limited to ellipsoid
     generation curves. ShellyLibV2.0 allows the user to define any
     generation curve in a special new calculation mode called
     "GenCurve".  This is useful for Cones or the "Miraculous
     Thatcheria", which were impossible to generate with the old
     algorithm.

  o  Some special keywords regarding POV-Ray are gone.

  o  Various other goodies have been included in the distribution, for
     instance displacement and surface shaders for RenderMan and a
     reference sheet that helps to understand the algorithm.

  4.  Using the Library

  This section contains a programmers guide to "libshelly".  If you do
  not plan to program with "libshelly" you may want to skip over to
  section ``Using shelly''.

  It would be handy if you would print a copy of "shellyl.h" or just
  open it for browsing.

  4.1.  General Usage

  If you want to use "libshelly" to create a shell, you have to fill an
  argument structure that contains all necessary parameters of the
  generator ("SLarguments") first.

  Then, one of the generating functions ("SLCalcShell",
  "SLCalcShellNodule", "SLCalcShellGC") may be called.  These functions
  will allocate memory for all points of the shell, fill the memory with
  coordinates and give you a pointer to it.

  The generated points are collected in lists. The lists of points are
  collected in another list (a list of lines).  There is no additional
  information available now, just the coordinates of the points.  For
  shells generated with "SLCalcShellNodule" (or for easier writing of
  some triangle based file formats) you might want to call functions
  that generate additional information.

  "SLTriangulate", for instance, assigns points of two lines to
  triangles.  This seems easy for two lines containing the same amount
  of points, but it is more complex if the points may be unevenly
  distributed and the numbers of points do not equal.  "SLTriangulate"
  uses the s-values stored in the points structures.  Since
  "SLCalcShellGC" does not store this information into the points,
  calling "SLTriangulate" on lists created with "SLCalcShellGC" is not
  possible. This means that not every output format is possible within
  the "GenCurve" mode.

  "SLCreateIndex" creates all index information for writing a file in a
  format that needs numbered points, lines and triangles, like T3D. You
  may want to take a look at "WriteT3DFile" in the file "src/rdwrt.c"
  for an example of how to use the indices.

  After writing the shell to hard-disk or displaying it you may free the
  occupied memory, using the various "SLFree"-functions.
  4.2.  Structures

  "SLarguments" is the structure that contains all parameters and some
  status information.

  "SLgcpoint" is a single point of a generating curve, used by the
  "GenCurve"-mode.

  "SLshell" is the basic structure of the shell.  Each shell is split
  into several lists (lines) of points. Each "SLshell" structure points
  to such a list.

  "SLpoint" is the structure that forms a list of coordinates.

  "SLpindex", "SLlindex", "SLtindex" contain index information.

  "SLtriangle" contains pointers to the three points of a triangle.

  4.3.  Functions

  "SLCalcShell", "SLCalcShellNodule" and "SLCalcShellGC" create a shell
  in the according mode ("Normal", "Nodule" or "GenCurve").

  "SLTriangulate" and "SLCreateIndex" create index information.

  The "SLFree"-functions free the associated items.

  For more in depth use of the library you might want to call
  "SLCalcLine", "SLCalcPoint" and their nodule-mode counterparts.  (If
  you want to change parameters randomly between the points to achieve a
  more realistically looking shell, for instance.)  These functions do
  not create shells, but lines or single points of a shell, according to
  the parameters. They will not be explained more deeply here. Take a
  look at the source.

  5.  Using shelly

  The program "shelly" is a small example frontend to "libshelly".  It
  simply reads a data file containing a set of parameters, then
  calculates a shell using "libshelly" and finally writes a 3D object to
  another file.

  Both files have to be specified as arguments to "shelly".  If called
  with a wrong number of arguments "shelly" will print a short help note
  onto the standard output. It does not accept any switches.

  Generally, you should run "shelly" this way:

       >shelly infile outfile

  Replace infile with the path and name of the file to be read, and
  outfile with the path and name of the file to be written.

  You may start "shelly" without arguments. It will ask for the two
  filenames, then.

  There are example data files in the "shy" subdirectory of the
  distribution.  For information on how to write data files to feed into
  "shelly", refer to section ``File Format''.

  6.  Using the Shell Laboratory

  The "Shell Laboratory" is a GUI for "libshelly".  It is mainly a
  Tcl/Tk script and some C-code to interface to OpenGL (via Togl) and
  "libshelly".

  The main goal of this GUI is to ease the process of parameterization
  through immediate display of the results.

  6.1.  Starting Up

  The "Shell Laboratory" consists of Tcl/Tk-code and C-code.  Therefore,
  after compiling the "Shell Laboratory" you have a Tcl-script "lab.tcl"
  and an executable "lab".  To start the "Shell Laboratory" you might
  use the provided shell-script "slab".

       >slab

  This script needs a "sh" installed in "/bin".  After installation of
  ShellyLib you have to edit the shell-script.  The complete path to the
  file "lab.tcl" has to be added to the last line ("source "lab.tcl"")
  of the file "slab".  Use of the tilde ("~") is allowed. If you didn't
  understand anything by now, read on.

  You might also start the lab this way:

       >lab lab.tcl

  Note that "lab" has to be in the search path of your shell.  And if
  "lab.tcl" is not in the current directory, you have to specify the
  full path to it.  Let us assume you installed "lab" in a way that it
  is in your current search path. If you unpacked the ShellyLib
  distribution in your home directory and did not move the file
  "lab.tcl" you may start the "Shell Laboratory" now with:

       >lab ~/ShellyLib-2.0/src/lab.tcl

  Using an alias for this might be a good idea.  The first thing you
  should do after startup is the tutorial, located in the "Help" menu.

  6.2.  The Main Window

  Each parameter of the shell generator is represented as a line,
  containing

  o  an entry (showing the value of that parameter)

  o  a configurable slider (it's minimum and maximum values are
     displayed in two labels to the right and left)

  o  a button to start the calibration of the slider.

  Since all those parameter-lines fit hardly on any screen, I put them
  into a scroll-able canvas.  You might want to maximize the window size
  to your full screen height.  You can cycle through the entries and
  sliders with <TAB> and <Shift+TAB>.

  Each change of a sliders value results in the following internal
  actions.  At first, a new shell is generated via "libshelly" in the
  mode selected in the "Shelly/Mode" sub menu. Then, the shell is
  displayed as wireframe or shaded polygonal model in the second window
  called "3D-View".

  6.3.  The Menu

  o  File

  o  Load: Loads a set of parameters (see "File Selection Box" section)

  o  Save: Saves a set of parameters

  o  Exit: Quits the application

     Shortcuts (accelerators) exist for these menu entries (<Ctrl+l>,
     <Ctrl+s> and <Ctrl+q>).

  o  Rendering: (Configuring the 3D-View)

  o  Mode:

  o  Wireframe: switches to wireframe display (default)

  o  FlatShaded: switches to a flat (constant) shaded representation

  o  SmoothShaded: switches to a smooth (Gourad) shaded representation

  o  DrawCoordsys: switches display of the small coordinate system on or
     off (default: on)

  o  AutoUpdate: If this is enabled, every change of a parameter results
     in an immediate update of the display.  Toggling the checkbox from
     "off" to "on" will not result in an updated display. (default: on)

  o  Shelly: (Configuring miscellaneous aspects of the "libshelly")

  o  Mode:

  o  Normal: (default)

  o  Nodule: see section ``Calculation Modi'' for help on this mode

  o  GenCurve: same here

  o  Write:

  o  POV-Ray

  o  etc. Write a file in the selected format to disk. See also section
     ``Output Formats''.

  o  Help: (A small online help)

  o  Tutorial: a gentle introduction to the "Shell Laboratory"

  o  Shell Laboratory: Just a pointer to the original docs.

  o  About Shell Laboratory: nice Nautilus, ehh?

  6.4.  The 3D-View

  This window uses Togl to interface to OpenGL and draw the shell.  The
  shell may be displayed as wireframe model or rendered using constant
  or smooth shading (Gourad-Shading).  You may configure this with the
  "Mode" sub-menu in the "Rendering" menu.

  You may rotate, zoom and move the shell (moving along z-axis only)
  with your mouse and keyboard.

  A coordinate system is drawn to help you to navigate. It might be
  helpful to estimate the size of the object, as each axis is exactly 1
  (whatever) long.  It can be switched off with the "DrawCoordsys"
  check-button in the "Rendering" menu.

  The view is updated every time you change the value of a parameter.
  You may change this behavior with the "AutoUpdate" check-button.

  The projection mode is always perspective. If you get annoyed by the
  perspective distortions that may occur when viewing large objects, use
  the "Scale" parameter to shrink the shell.

  If you are lost in space use <r> to reset to the default settings.

  Please note, that no setting of the 3D-View has any influence on any
  3D-objects written by the "Shell Laboratory".

  Here are all the key and mouse bindings:

  <Mouse-Button-1> (the left one) click and drag: rotate around x- and
  y-axis

  <Cursor-Left>, <Cursor-Right>: rotate around z-axis

  <Cursor-Up>, <Cursor-Down>: move along z-axis

  <+>: zoom in

  <->: zoom out

  <r>: reset all transformations

  Note that these key and mouse bindings are available in the 3D-View
  window only!

  6.5.  File Selection Boxes

  Some menu-entries open one of these monsters.  Seriously, when I
  switched from my beloved Amiga to a Linux-PC I felt lost after short
  time. I was used to standard "ASL" or "ReqTools" requesters, easy to
  use, functional and nice looking.  On X11 everyone does his own thing,
  one worse than the other.  So, I decided to reinvent the wheel too,
  and the result is a more or less Amiga-like file requester.

  Directories are marked with a trailing slash ("/").  Right mouse-
  button is bound to "cd ..".  Pressing <Return> in the list-box selects
  a file or changes the current directory.  Double-click on a file
  selects this file, on directory changes to this directory.

  Do I need to tell you more? Everything else should work as you expect.

  Note: Due to a bug in Tk4.0, double-clicking on a file will pop up an
  error box. But the file you have selected will be loaded!  It is just
  that little annoying box.  Use the "Ok!" button (or keyboard).
  Otherwise you have to update your Tcl/Tk to get rid of it.  Again, not
  my fault.

  6.6.  Slider Calibration

  The initial configuration of the sliders has been choosen to protect
  you from potentially dangerous parameter values, that may crash the
  lab, and to ensure greatest possible freedom in setting any parameter.

  From time to time it may be necessary to reconfigure a slider, so that
  other values than allowed by its initial configuration may be set.
  Each slider may be configured using the associated "Cal." button.
  This will open a modal dialog, where you can change minimum and
  maximum value and, important, the step-size or resolution of the
  slider.  Note, that you cannot set any other value than x = min + (n *
  step-size), (x <= max) with the slider.

  6.7.  Notes about Entries

  Normally, when you drag the slider the value of the entry is updated
  automatically. This could work vice versa but you would not be able to
  enter any other value than allowed by the configuration of the slider.
  You say you would not mind?  Imagine the following: The entry shows a
  value of 200, slider configuration is 100, 360, 10. You want to change
  the value manually to 300. You would not be able to delete the leading
  2 in the entry because the resulting value (0) does not fit into the
  slider! Editing would be a real nightmare.

  My solution: The entry is temporarily disconnected from the slider
  when the entry gets the focus (either by mouse-click, or by <TAB>
  key).  You may now edit the value freely. No update takes place,
  neither of the slider nor of the display.  Then press <TAB> or select
  another entry with the mouse.  The focus leaves the entry and the
  connection to the slider is established again. Slider and display are
  updated.

  7.  Parameters of the Shell Generator

  This section gives detailed information about the parameters of the
  shell generator. All explanations are very theoretical.  If you cannot
  understand them, print the "Reference Sheet" ("doc/reference.ps") and
  try to find the parameter in question there.  Playing around with the
  GUI for some time might also be a good idea.

  The basic idea of the algorithm is to simulate a shell shape by
  rotating a growing ellipse around the z-axis, and simultaneously
  displacing it from the z-axis. This results in a flat spiral.  If we
  move the ellipse along the z-axis while rotating, a shell like shape
  will appear. The curve determined by all centers of all ellipses is a
  so called helico-spiral.

  The parameters of this process are divided into 5 groups.  Parameters
  that need to be given in degrees are marked with an asterisk ("*").

     Angular Parameters:
        These parameters change the shape of the helico-spiral ("alpha"*
        and "beta"*) and the tilt of the ellipse against the axes of the
        local coordinate system of the ellipse ("phi"*, "my"*,
        "omega"*). Note, that "alpha"* does determine the growth rate of
        the ellipse too.

     Linear Parameters:
        They change the size (and shape) of the ellipse ("a", "b") and
        the distance of the first ellipses center from the z-axis ("A").

     Dimensional Parameters:
        They set how many ellipses are calculated ("omin"*, "omax"*,
        "od"*), and how many points on each ellipse are calculated
        ("smin"*, "smax"*, "sd"*).  Finally, a global scale-factor,
        independent from all file format specific scaling, might be
        applied using "Scale".

     Nodule Parameters:
        Change all aspects of nodules, position on the ellipse ("P"*),
        size ("W1"*, "W2"*), length ("L"), number of nodules per whorl
        ("N") and starting point on the spiral ("Nstart"*).

        There are three independent groups of nodules.  Add a "2" to
        each nodule parameter to set parameters of the second nodule
        group. Length of second nodule is therefore "L2".  Do the same
        for the third nodule, with a "3".  There are two more parameters
        to control an offset between the three groups of nodules,
        "Off2"* is the offset between nodule 1 and nodule 2 and "Off3"*
        is the offset between nodule 1 and nodule 3.

     Nodule-Mode Parameters:
        "Scano", "Scans", "Hdo", "Hds" refer to section ``Calculation
        Modi'' for information on this parameters.

  The most important parameters are "alpha", "beta", "A", "a" and "b".

  Here are some hints on how certain values change the shape of the
  shell.

  o  Alpha 90 means no growing of the ellipse and no spiral shape at
     all.  If beta is 90, too, this will produce a torus like shape. If
     alpha gets smaller the spiral will form and the ellipse will grow.

  o  Beta 90 means no moving of the ellipse along z-axis. This is fine
     for shells like "Nautilus", "Planorbis", "Ammonite" or several
     cockles. If you want to shape a "Turritella" or "Natalina" you have
     to decrease beta.
  o  The meaning of a certain value of A depends highly on a and b.
     Generally, A should be higher as a and b, otherwise the shell may
     look like a sphere.

  8.  Calculation Modi

  8.1.  The Nodule mode

  The parameters "od" and "sd" determine the resolution of the generated
  shell. But if the shell contains nodules that are thin and long you
  would have to use very small "od" and "sd" values in order to shape
  the nodules. This would lead to a real waste of memory, because
  between the nodules the high resolution is not necessary.  To minimize
  memory complexity, the special nodule calculation mode has been
  written. This mode adapts both "od" and "sd" while calculating the
  shell, so that small distances between the calculated points are only
  used when needed, in the nodules.  This process may be controlled with
  the parameters "Scano", "Scans", "Hdo" and "Hds".  "Scano" determines
  the smallest possible distance of two points in O direction, the same
  does "Scans" for the S direction.  "Hdo" defines the smallest possible
  difference in height between two points in O direction, the same does
  "Hds" for the S direction.  The difference in height is being
  calculated using the height of the nodule.  The nodule mode may be
  invoked by the "NODULE" keyword.

  "Hdo" and "Hds" are multiplied by the nodule height of the first
  nodule group, before they are passed to "libshelly", when using the
  example frontends.  The height difference value is now dependant from
  the nodule height.  It is now easier to estimate the effect of a
  certain value, e.g.  0.1 means a tenth of the nodule height, no matter
  how high the nodule actually is.  Note, that this multiplication is
  not done by "libshelly".

  Unfortunately, the result of this mode is of irregular structure.
  This means the only possible output type is triangles. No spline
  output, neither B-spline nor Bezier patches, may be generated using
  this mode.

  8.2.  The GenCurve mode

  8.2.1.  General Information

  The original algorithm of M.B. Cortie is limited to ellipsoid
  generation curves. ShellyLibV2.0 allows the user to define any
  generation curve, using the "GenCurve" mode.  This is useful for Cones
  or the "Miraculous Thatcheria", which were impossible to generate with
  the old algorithm.

  The curve needs to be specified as a sequential number of points with
  the "GCx:" and "GCy:" keywords. The parameters "a" and "b" still scale
  the curve as they do it in the other modes with the ellipse, and "A"
  moves the curve.  However, "smin","smax" and "sd" are out of function!
  The same applies for all nodule parameters. Nodules are not possible
  within this mode.

  Note, that the resolution of the shell depends directly on the list of
  points. The spaces between the points are not interpolated.  The
  curves provided in the "shy/gcurves" subdirectory are meant to be used
  with spline output formats like "RPL" or "RIB", because the curves
  contain only few points.  Note that not every output format is
  possible within this mode at present.  You may use: "RPL", "RIB",
  "BEZ", "SCB".

  You should switch from the default Catmull-Rom basis to the B-Spline
  basis, when using "RIB" output.

  Switch to this calculation mode with the "GCURVE" keyword.

  8.2.2.  Creating Generation Curves

  Generation curves might be created with the following steps:

  o  Grab a real shell or look up the desired shell in a shell
     compendium.

  o  We will need a view at the aperture of the shell now.

  o  Draw the shape of the aperture into a coordinate system. Use a fine
     grid! The shape should be located in quadrant IV: positive x,
     negative y.

  o  Digitize the curve into "GCx:", "GCy:" tupel (by hand), starting at
     the origin (or the nearest point).  Proceed in clockwise direction.
     If you want the shape to start/end at the first/last point, it
     could be handy to double the first/last tupel.  For a closed shape,
     end with the first tupel(s).

  o  You may now load the resulting file into another complete data
     file.

     The number of points you provide will be the number of points
     calculated per generation curve and  determine the resolution of
     the shell in the S direction. Unless you really have a lot of
     points in the generation curve, you should not try to generate
     triangle-based output!

  9.  File Format

  ShellyLib uses files in a simple format to store sets of parameters.
  You should use a characteristic filename extension like ".shy" for
  these files. However, this is not mandatory.

  Every line of the file is scanned for keywords.  Lines that start with
  an "#" are fully ignored.  If a line contains no keyword it is treated
  like a comment.

  Otherwise the number behind the keyword is copied into an internal
  variable or a flag is set. This implies, that there are two types of
  keywords, so called number-keywords and flag-keywords.  Number-
  keywords need to be combined with a number, flag-keywords have just to
  be there to set something. All names of the number-keywords correspond
  to parameters of the shell generator.

  Number-keywords contain a ":" to remind you to write a number behind
  them. Flag-keywords are written in capital letters.

  Keywords to change the so called "angular parameters" are "alpha:",
  "beta:", "phi:", "omega:", "my:".

  Keywords to change the "linear parameters" are "A:", "a:", "b:".

  Keywords for "dimension parameters" are "Scale:", "smin:", "smax",
  "sd:", "omin:", "omax:", "od:".

  The keywords for nodule 1 are: "P:", "L:", "W1:", "W2:", "N:".

  Nodule 2: "P2:", "L2:", "W12:", "W22:", "N2:", "Off2:".

  Nodule 3: "P3:", "L3:", "W13:", "W23:", "N3:", "Off3:".

  For an exact description of the parameters read section
  ``Parameters''.

  Keywords for switching output formats are "RPL", "T3D", "RAW", "X3D",
  "BEZ", "RIB", "SCD", "SCB", "TSP".  See section ``Output Formats'' for
  more information regarding the formats.

  Keywords for special calculation modi are "NORMAL", "NODULE",
  "Scano:", "Hdo:", "Scans:", "Hds:", "GCURVE", "GCx:", "GCy:".  See
  section ``Calculation Modi'' for more information.

  Some remarks: Everything is case sensitive ("rpl" is not the same as
  "RPL")!  Double use of the same keyword causes an overwriting of the
  last set value.  Only one keyword per line is allowed.

  10.  Compatibility

  This section covers compatibility issues regarding the use of
  ShellyLib on a certain machine or with certain software.

  Generally spoken, the library ("libshelly") should run on every
  computer with an ANSI-C capable C-compiler.

  This statement is not true for the example frontend ("shelly") and the
  GUI ("Shell Laboratory"), which use the "libshelly".

  The frontend "shelly" has been successfully ported to many
  machines/operating systems. It is not much less portable than the
  library itself.  But it needs a command line driven user interface.

  The GUI, "Shell Laboratory" is quite selective in terms of
  prerequisites.  You need a working Tcl/Tk, OpenGL and, last but not
  least, Togl.

  Tcl/Tk and OpenGL are ported to WinNT and Macintosh. OpenGL is even a
  part of WinNT.  But Togl has neither been ported to WinNT nor
  Macintosh at present.  If this changes the GUI will likely run on
  WinNT and/or Macintosh.  Otherwise you need a X11 and X11 based Tcl/Tk
  and OpenGL implementations in order to run the GUI.

  The following table shows some hardware/operating system
  configurations, the frontend "shelly" has been tested on.

  o  Hardware, OS, compiler, remarks:

  o  iP5-90, Linux 1.2.13 (Slack 3.0), gcc2.7.0, major development
     platform

  o  Amiga 4000, A-OS 3.0, gcc2.7.,

  o  SUN-Sparc, Solaris2.4, gcc2.7.?,

  o  SGI-Ind(y|igo), IRIX5.3, cc

     If you ported "shelly" to a platform not listed here, please
     contact me!

  The following table lists some hardware/operating system
  configurations, the GUI "Shell Laboratory" has been tested on.

  o  Hardware, OS, compiler, used versions of X11, Tcl/Tk, OpenGL, Togl:

  o  iP5-90, Linux 1.2.13 (Slack 3.0), gcc2.7.0, XFree86 3.1.2, Tcl7.4,
     Tk4.0, Mesa 1.2.7, Togl 1.0b1

  o  SGI-Ind(y|igo), IRIX5.3, cc, native X11 and OpenGL, Tcl 7.5, Tk
     4.1, Togl 1.0b1

     If you ported the "Shell Laboratory" to a platform not listed here,
     please contact me!

  11.  Output Formats

  ShellyLib is able to generate output for:

  o  Program, Output-Keyword, by, tested version, on OS, file type
     (content), remarks.

  o  Real3D, "RPL", RealSoft, V3.3, Win3.11, executable RPL-macro,
     creates a B-Spline-mesh in Normal-mode/GenCurve-mode or a Triset in
     Nodule-mode.

  o  T3DLib, "T3D", Glenn M. Lewis, V43, Linux, ASCII-File triangles, is
     able to output:

  o  DXF (AutoCAD Interchange Format), Tested with dxf2iv (IV - Open
     Inventor file format (SGI)) and 3DStudio V3

  o  T3D-binary (Imagine), Tested with Imagine V3

  o  NFF (Neutral File Format)

  o  OFF, Tested with Geomview V1.5

  o  POV-Ray (Persistence of Vision Raytracer)

  o  LOBJ (Lightwave Object File), Tested with LW 4.0 (WinNT 3.51)

  o  RAY (Rayshade)

  o  VORT

  o  X3D, "X3D", Mark Spychalla, V2.02, Linux, ASCII-File triangles, For
     fast previewing (wireframe), using X11.

  o  RAW2POV, "RAW", Steve Anger, V1.8, Linux, ASCII-File triangles, Is
     able to output:

  o  smooth triangles for POV-Ray V1.x/2.x, Tested with POV-Ray 2.2

  o  Vivid

  o  Polyray.

  o  POV-Ray, "BEZ" "POV", POV-Team, V2.2, Linux, ASCII-File
     BezierPatches, Not for Nodule-mode! For Nodule-mode use "RAW" and
     RAW2POV.  Also tested with V3.0! The patch parameters are a bit
     conservative, for custom settings you have to edit "rdwrt.h" and
     recompile.

  o  Truespace, "TSP", Caligari, V2.0(Demo), Win3.11, ASCII-File
     triangles, probably problems with texture coordinates (the demo
     expired...)

  o  SCED, "SCD" / "SCB", Stephen Chenney, V0.93, Linux, contains a
     triangle mesh ("SCD") - Normal/Nodule or Bezier patches ("SCB") -
     Normal/GenCurve, SCED, a powerful constraint based editor (X11),
     writes:

  o  POV-Ray

  o  Radiance

  o  RAY (Rayshade)

  o  RIB (RenderMan Interface Bytestream)

  o  VRML (Virtual Reality Modeling Language)

  o  BMRT - Blue Moon Rendering Tools, "RIB", Larry Gritz, V2.3.3,
     Linux, RenderMan Interface Bytestream creates Spline Meshes.
     Either CatmullRom or B-Spline type may be selected easily by
     editing the resulting file, default is CatmullRom.  Also tested
     with PhotoRealistic RenderMan V3.4c on IRIX5.3.

  12.  Known Bugs

  Bugs of the library ("libshelly"):

  o  The library does not check for any mathematical errors like
     division by zero. This may lead to crashes for certain combinations
     of parameters.  The following dangerous parameter values are known:

  o  "alpha" < 5: results in a crash

  o  "a" or "b" = 0: results in a crash

  o  "od" or "sd" = 0: infinite loop and malloc bomb, A complete lock of
     the machine is possible! (The same goes for all Nodule-mode
     parameters!)

  Bugs of "shelly":

  o  "shelly" does not check for forbidden combinations of calculation
     modes and output formats.

  Bugs of the "Shell Laboratory":

  o  Calculation of the surface normals for the shaded rendering modes
     is incorrect and slow.

  o  Saving of data files does not include calculation mode or output
     format settings.

  o  Loading of data files that switch calculation modes leaves the menu
     check-boxes in "Shelly/Mode" untouched.

  o  The lab might allocate all available colors of your display,
     leaving nothing for other applications. You should run it on a
     display with 16 or 24 bpp anyway.

  o  Double-clicks in the file requesters pop up an error box on Tk4.0.

  o  Loading of data files that contain values with higher resolution
     than the resolution of their slider does not work properly on
     Tk4.0.  The entry is displaying a wrong, rounded, value afterwards!
     Another good reason to update your Tcl/Tk.

     The GUI is my first Tcl/Tk - OpenGL project.  More errors or
     incompatibilities are likely. Do not hesitate to inform me of such
     errors or design flaws.

  13.  Addresses, Pointers, Literature

  The author may be contacted via e-mail:

  rschultz@informatik.uni-rostock.de

  or snail mail:

  Randolf Schultz
  Unter den Linden 51
  19079 Mirow
  Germany

  Newer versions and additional information may be obtained via the
  ShellyLib HomePage <http://www.informatik.uni-
  rostock.de/~rschultz/shellylh.html>.

  Other resources:

  o  Tcl/Tk:

     The Tcl/Tk home page <http://www.smli.com/research/tcl>

  o  Mesa (a 3D-library with an API similar to OpenGL, correct Brian?):

     The Mesa Home Page <http://www.ssec.wisc.edu/~brianp/Mesa.html>

  o  Togl (The missing link between OpenGL and Tcl/Tk):

     Togl Page <http://www.ssec.wisc.edu/~brianp/Togl.html>

  o  The Linuxdoc-SGML home page:

     Linuxdoc-SGML <http://www.informatik.tu-
     muenchen.de/~schwarz/linuxdoc-sgml/>

  The following literature has been of much help

  o  Digital Seashells, M.B. Cortie, Computer and Graphics, Vol. 17, No.
     1, pp. 79-84, 1993

  o  Shells, S. Peter Dance, Harper Collins Publishers 1992, ISBN 0 7322
     0067 9

  o  The Algorithmic Beauty of Sea Shells, Hans Meinhardt, Springer-
     Verlag Berlin Heidelberg 1995, ISBN 3 540 57842 0

