### hf_lab-0.90 README file

    -------- HeightField Lab   ------------------      July 24 1997 jpb

    HF-Lab is designed to generate heightfields for use as landscapes or other
    surfaces in a computer-generated image.  It can generate, manipulate,
    display, load and save heightfields.  The display functions are greyscale
    previews only; it is intended that a raytracer such as the freeware
    POV-Ray be used to generate the final output image. The program runs on
    PCs under DOS and on Unix workstations using X Windows. Many people report
    graphics conflicts when running the DOS version under Windows 3.1 or '95.

    ----- Quickstart (DOS):   Type "demo" to see an example of HF-Lab at work.

    ----- Quickstart (Unix):  Refer to the "unix.txt" file, then skip forward
                              to "Using HF-Lab", below.

    ----- Setup: (PC DOS/Windows3.1/Windows95) --------------------------

    You need these files to run HF-Lab:

      HL.EXE       the program executable
      HF-LAB.HLP   data for the on-line help function
      CWSDPMI.EXE  the DPMI host (DOS only, not needed for Windows)

    HL.EXE (and CWSDPMI.EXE for DOS) must be present somewhere in your path.

    Put the help file in some convenient place and then set the environment
    variable accordingly. For instance if you had it in c:/hflab you would then
    add this to your

    AUTOEXEC.BAT file:

      set HFLHELP=C:/hflab/hf-lab.hlp

    Either reboot for this variable to be set, or type the "set" command at the DOS
    prompt for it to take effect. Now you are ready to run HF-Lab.

    =======================================================================

    ----------------------------- Using HF-Lab ----------------------------

    HF-Lab is a tool for generating heightfields.  A heightfield (HF) is just a
    two-dimensional matrix or array of values representing elevation at each
    point ('HF' and 'matrix' are used interchangeably in the documentation).
    HF-Lab commands fall into several categories: those for generating
    heightfields (HFs), combining or transforming them, and viewing them are the
    three most important. Then there are other 'housekeeping' commands to move
    HFs around on the internal stack, load and save them on the disk, and set
    various internal variables. Type "help" or "?" for a command summary, or
    "help gforge" for specific help on the 'gforge' command, for instance.

    HF-Lab is based on the idea of a stack for storing HFs. Those familiar with
    the Hewlett-Packard calculators or the FORTH language will be used to
    this. The stack is like a pile of plates: the last plate (or HF) you put on
    the stack will be on top, and also the first one you get when you go to use
    one.

    If you want to use the second-from-top HF, just use the "swap" operator to
    exchange the position of the top two HFs. The "rot3" operator moves the
    third HF down to the top, and pushes the top two down by one. The "rot"
    operation moves the bottom one to the top (no matter how many items are on
    the stack), and the rest down one.

    The usual approach is to generate one or two heightfields with the 'gforge'
    command, modifying them with the POW (raise to exponent) or CRATER (add
    craters) commands, and after each operation using SHOW (view as 2D greyscale)
    or VIEW (view as 3D image) to see the results. Note that most commands may be
    abbreviated and the most often used ones go to a single letter; for example:

      l    list the heightfields now on the stack
      s    show the 2D HF
      v    show a 3D perspective

    Have a look at the provided HF-Lab command scripts ("test1.scr", etc.) to
    give you an idea of how to use HF-Lab.  You can use these in batch mode as

       hl test1.scr       (DOS version)
       hlx test1.scr	(X version)

    or from within a HF-Lab session by typing at the prompt:

    HL> run test1.scr

    The latter command will execute the script and then return you to the
    prompt in interactive mode where you can continue manipulations.

    --- Math operations ---

    A number of mathematical manipulations may be performed on HFs; type "help"
    for a full list. I find that interesting effects may be obtained for example
    by the "exp" operator which takes each element of one HF to a power or
    exponent specified by the corresponding element of another HF.  Note that by
    default, "gforge" will produce a HF with elements ranging between 0.0 and
    1.0. You will often want to scale the HF to have a different range; one way
    to do this is NORM -3.14 3.14 for instance, which will scale the HF to have
    the specified minimum and maximum values. You might use that command prior to
    SIN which takes the trigonometric sine of each value. Note that the SHOW
    command always prescales the matrix to use eactly the full grey-scale range,
    but VIEW does not; so you may want to renormalize to the default 0..1 with
    NORM prior to using VIEW (with a large elevation range, the HF will be so
    tall it will not fit on the screen).

    You can get a histogram of the matrix values with HIST. The histogram
    equalization function which may be familiar from 2D image processing programs
    is available, though more often you only want a "little bit" of equalization
    rather than complete, so you can specify for instance EQ 0.1 which will move
    you 10% of the way toward a fully equalized matrix.

    --- Fourier Filters ---

    I'd like to point out the fourier filter options offer a wide range of
    possibilities. For instance generate or load in a heightfield and try out
    the lowpass filter command:

       lpf 0.3 1.0

    This smooths out the surface somewhat. The first argument specifies
    the frequency threshold above which the amplitude is reduced.  The possible
    range is [0.0 ... 1.0], so had you typed

       lpf 1.0 1.0

    there would have been almost no effect, since there are no frequencies
    above 1.0, the maximum frequency (technically, the "Nyquist limit
    frequency"). I say "almost no effect" here because the second argument
    determines the sharpness of the filter, and 1 is a "soft" filter. (More
    exactly, the second example sets a one-pole filter with the half-power
    point at the Nyquist limit).  If you wanted a sharp or "brick wall"
    filter, use a large number for the second argument like

      lpf 0.05 1000

    which will remove essentially all frequencies above the 0.05 fraction.
    There may not be much left of your landscape after that.

    The highpass filter function works just like the lowpass, but with the
    opposite effect of reducing the large rolling features. This is good for
    generating the effect of a large range of mountains, for example, rather
    than just a few.  Try

      gforge 200
      view 3
      hpf 0.1 1
      view 3

    to see the difference the filter makes.  ("view" puts you into the
    interactive viewing mode which you have to quit from later. "view 3" shows
    you the view for three seconds and then returns to the HL> prompt.)

    The bandpass and bandreject filters acts more specifically on a single
    range of frequencies with the specified center value. Experiment with them
    to see their effects.

    Complex matrix type: most HF-Lab operators work on "real" matrices, that
    is, a simple array of <xsize> by <ysize> floating point numbers. However
    there is also a "complex" matrix type which has two float values for
    each (x,y) point: a real and imaginary value. HF-Lab does not implement
    the full set of arithmetic for complex numbers; mostly the two parts are
    used as horizontal and vertical components of a displacement vector in
    the "cwarp" operation. See the "csplit" and "cjoin" operators to convert
    between the complex or composit matrix and two separate matrices or HFs
    on the stack.

    --- Warping and Twisting operations -------------

    There are three commands in this category; 'twist', 'bloom', and
    'cwarp'. Each requires there be two HFs on the stack, a "control" matrix in
    the top (X) position and the original, "source" matrix in the second-to-top
    (Y) position. The result matrix will be left on the top of the stack when
    the operation is finished.

    TWIST rotates each point from the source matrix about its center (or other
    specified point) by an amount specified in the control matrix. If the
    control matrix is a constant 1.00 everywhere, for instance, then this
    results in a simple overall rotation by 1 radian (57 degrees). With a
    control matrix having varying values (eg. a GFORGE surface) one can obtain
    interesting ridge structures.

    BLOOM is similar to TWIST but instead translates each point radially
    outward from the center (or other specified point). Unless the control
    matrix is zero at the center (or other point), there will be a visible
    discontinuity there.

    CWARP is a more general operation which takes a "complex" (or composit)
    matrix as the control matrix, which specifies a vector displacement for
    each point in the source matrix as X and Y (horizontal/vertical)
    displacements. Try running movie2.scr to see an example of this operation
    applied repeatedly.

    ------- Erosion -----------------------

    Realistic fluvial erosion (caused by flow of water, eg river valleys and
    canyons) is mathematically difficult to accurately simulate. However I have
    written a stand-alone program called "erode" and available as "er1u.zip" or
    "er1u.tar.gz" which does (or attempts to do) erosion on heightfields.  This
    program takes overnight (at least) to do anything visually interesting. It
    is also a command-line utility which is pretty difficult to use and even
    harder to understand.

    You can do essentially what the "erode" program does in HF-Lab, but you
    have do each step individually and then repeat them many times. Here
    is where a script file (see example *.scr files) comes in handy. The
    following is an example:

    # ========= Example Erosion script      ================
    # --------- by John Beale Nov. 11/30/96 ----------------

    gforge 200    ;# generate a random 200x200 surface
    peak .5 .5    ;# position the highest point in the middle
    fillbasin 100 ;# iteratively fill in lowest points, take 100 steps
    flow          ;# generate a river-flow map using a downhill-flow algorithm
    norm 0 0.1    ;# scale flow map to have value ranges in [0...0.1]
    sub           ;# subtract this matrix from landscape
                   # It is this subtraction which "carves out" the rivers
    smooth 0.1    ;# smooth off edges a bit to simulate landslips, weathering

    # Do all of this again. And again. And... eventually, it looks like something.
    # (Once you've filled in the basins in the first step, you don't need to
    #  refill them so much, and the algorithm is very slow. Should be improved.)

    fillb 10; flow; norm 0 0.1; sub; smooth 0.1
    fillb 10; flow; norm 0 0.1; sub; smooth 0.1
    fillb 10; flow; norm 0 0.1; sub; smooth 0.1

    # ========= end of erosion script =============================

    There is much more to HF-Lab than I have covered here. Experiment with the
    commands to see what they do. Remember you can get help on any command
    with the 'help' function.

    --- Out of Memory?  ------

    After a number of HF operations you may find HF-Lab reports that you are
    out of memory even when you used to be able to have more HFs of the same
    size on the stack. This is due to a "memory fragmentation" problem exactly
    analagous to hard disk fragmentation; I believe it is present only in the
    DOS version of HF-Lab. The only solution at this point is to save each HF
    in a file (use .MAT unless you lack disk space), then exit the program and
    restart; this will restore all your memory for use. Buying more memory
    will only delay the problem, not eliminate it. This bug will hopefully be
    fixed in a future release.

    ----- Notes ----------------------

    HF-Lab combines several utilities I released earlier in separate form:
    gforge, hutils, and xgrid. It is similar in some ways to the Lee Crocker's
    PICLAB program, although it is different in that it adds a more general
    stack structure, but does not deal with multi-channel (ie, color) images.
    HF-Lab also shares some capabilities with the much more powerful (and
    expensive) Matlab program. However HF-Lab is designed only for working with
    heightfields.

    HF-Lab stores each heightfield 'pixel' element as a single-precision
    (4-byte) floating point number. This gives you seven decimal places, which
    is enough accuracy to store the elevation of Mt. Everest (29028 ft) to
    within the thickness of a grain of sand. This seems adequate for most
    heightfield applications, without taking the additional memory that
    double-precision floats would require.

    Since the 'gforge' algorithm uses real and imaginary parts prior to the
    IFFT step, it requires eight bytes per pixel so a 1000x1000 mesh needs 8
    million bytes to generate.  The heightfield stack is initially set at four
    elements but if you're running low on memory you may want to reduce this
    ('set stack 3', for example).

    Note that the 'double' fractal-interpolation command offers an alternative
    to 'gforge' not only for increasing the resolution of existing HFs (eg from
    a DEM) but for entirely synthesizing them too (see test3.scr). This method
    takes only half the memory that 'gforge' requires, since it doesn't use a
    complex-part matrix. (Personally I think the output isn't quite as good, but
    it's your option.)

    -----------------------------------------------------------------------
                                  HF-Lab Credits
    -----------------------------------------------------------------------

    main author:   John P. Beale
    email:         beale@best.com
    WWW Homepages:
    	       http://www.best.com/~beale
                   http://chomsky.stanford.edu/~beale/

    ------ contributing authors: ------------

      Heiko Eissfeldt <heiko@colossus.escape.de>     [ contributed CRATER code ]
      Michael Lamertz <mlamertz@odars.de>		 [ high/truecolor X 'show' ]
      Robert Bertram  <robertrb@umich.edu>		 [ input ASCII .OCT files  ]

    ------- and many thanks to: ----------------

      *  Original author of ppmforge.c:   John Walker <kelvin@fourmilab.ch>
         (I based Gforge on ppmforge, and HF-Lab is based on Gforge.)

      *  The authors of Lab-3D: T.Hruz, I. Povazan,R. Gosiorovsky

       Lab-3D is a reasonably small X-Windows program which demonstrates a
       number of 3D rendering algorithms. It is also useful for reference
       if you're just starting X programming. You can get Lab-3D from
       ftp://dec50.vm.stuba.sk/        email:  <lab-3d@vm.stuba.sk>

      *  The author of GDLIB, Thomas Boutell.  http://www.boutell.com/
       (I use gdlib for GIF file format I/O, although it can do much more.)

      *  Andreas Dilger, who immediately solved a PNG problem I'd spent many
    	hours on, and is a really nice guy too.

      * The HF-Lab beta-testers

      * enthusiastic readers of comp.graphics.rendering.raytracing

    -------------------------------
       gd is copyright 1994, 1995, Quest Protein Database Center, Cold
       Spring Harbor Labs. Permission granted to copy and distribute this
       work provided that this notice remains intact. Credit for the library
       must be given to the Quest Protein Database Center, Cold Spring Harbor
       Labs, in all derived works.

    -------------------------------

      The HF-Lab program is copyright (C) 1995 by John P. Beale.  This program
      comes with ABSOLUTELY NO WARRANTY. Permission is granted to redistribute
      the full source code under the terms of the GNU General Public License,
      version 2.  For more details, see the GPL.