-------- 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.
