-------- HeightField Lab ------------------ 1997 - 2015 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. HF-Lab 0.91 does work (in a DOS window) under Windows XP. ----- Quickstart (Windows): 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. ======================================================================= ----------------------------- 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 by 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 [ contributed CRATER code ] Michael Lamertz [ high/truecolor X 'show' ] Robert Bertram [ input ASCII .OCT files ] ------- and many thanks to: ---------------- * Original author of ppmforge.c: John Walker (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: * 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.