1. Overview

1.1 Acknowledgements

I thank Prof. W. Barth (University Erlangen) for (en)forcing me to start this project. Hans Hülf, Rüdiger Örtel and Kai Schneider have spent lots of time on coding parts of surf. Some of the code has been copied from other places:

• Writing SUN rasterfiles and XWD files has been copied from Michael L. Mauldin's Fuzzy PixMap (fbm) library version 1.2.
• Writing a TIFF file has been copied from John Cristy's Image Magick version 3.0.
• The octree color reduction algorithm is copied from Ian Ashdown's article Octree Color Quantization in the C/C++ Users Journal Vol. 13, Number 3, pp. 31-43.

1.2 Copyright

surf is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

1.3 How to get surf

surf is available via http/ftp at the surf home page http://surf.sourceforge.net.

1.4 System requirements

To compile surf, the following software is needed:

• GNU gcc/g++ version 2.7.x or higher (any ISO C++ compiler should work..),
• make,
• GNU flex version 2.5 or higher (minor versions should work also, but lex does not suffice),
• Berkeley yacc (GNU bison should work also),
• GTK+ version 1.2.0 or later (only required if you want to compile surf with GUI support),
• POSIX threads (If you have Linux make sure you use glibc2),
• GNU MP (gmp) version 2 or later,

• 15 MB for a 1000x1000 pixel image,
• 60 MB for a 2000x2000 pixel image and
• 130 MB for a 3000x3000 pixel image (gobble!!).

1.5 Starting surf

surf is started by typing surf on the command line. Optional arguments are --no-gui (or -n) for starting surf without graphical user interface, --exec (or -x) to immediately execute the first passed script file and - when using surf with GUI - --progress-dialog which tells surf to use a progress dialog instead of a status bar, --auto-resize which forces the image windows to get automatically resized to the size of the image, and the usual GTK+ options. --help prints out the usage information:

    surf -n | --no-gui FILE...
    surf [GTK-OPTIONS] [-x | --exec] [--progress-dialog]
         [--auto-resize] [FILE]...
    surf --help

1.6 Scripts versus graphical user interface

surf is designed to visualize algebraic curves and surfaces. This can be done either by writing scripts in surf's command language and executing them interactively or from another program (for example make), or by using surf's graphical user interface. By using scripts one can draw series of pictures where each picture consists of several surfaces/curves at a high resolution.

1.7 Scripts

Scripts in surf's command language are stored in files with the suffix .pic. These files consist of descriptions of curves and/or surfaces and some commands. They can be invoked in two ways:

• by loading a script and pressing the button execute script or
• by starting surf with the name of a script file from the command line. If you compiled/started surf without GUI support, it automatically starts interpreting the script. Otherwise you have to press the execute script button.

1.8 Output

surf calculates both color and black & white images. Color images can currently be stored in the following formats:

• XWD,
• SUN rasterfile,
• PPM and
• JPEG

• Netscape 216 color cube (8 bit),
• optimized by an octree algorithm (8 bit) and
• true color (24 bit).

• Postscript,
• Encapsulated Postscript,
• TIFF,
• XBM,
• PGM and
• PBM.

1.9 Sample scripts

You will find some sample scripts together with surf's distribution. They are stored in the examples directory.

1.10 surf and make

surf can be invoked from make. This comes in quite handy when visualising a series of curves/surfaces. Suppose there are script files s1.pic, s2.pic, ... , sn.pic which create during execution images s1.xwd, s2.xwd, ... , sn.xwd. If for example gif is the desired image file format, an appropriate makefile might look like:

    #!/bin/bash
    #
    SURF    = surf
    RM      = /bin/rm -f
    CONVERT = convert
    #
    OBJS    = s1.gif s2.gif .... sn.gif
    #
    .SUFFIXES: .pic .gif
    #
    .pic.gif:
        ${SURF}    -n $<
        ${CONVERT} $*.xwd $*.gif
        ${RM}      $*.xwd
    #
    dummy:
        @echo ' '
        @echo 'usage:'
        @echo ' '
        @echo '    print this message:'
        @echo '        make'
        @echo ' '
        @echo '    build images:'
        @echo '        make all'
        @echo ' '
        @echo '    remove images:'
        @echo '        make clean'
        @echo ' '
    #
    all: ${OBJS}
    #
    clean:
        ${RM} *.gif
    #
    # end of makefile

1.11 Oddities, bugs and bug reports

In case you find any bug, please use the excellent Bug Tracking System on surf's project page at Sourceforge.