Documentation (such as it is) for six programs. 8/30/96 jpb Thanks to Cees (cvdmark@xs4all.nl) for organizing. ------------------------------------------------------------------------- Fcolor -- Convert experimental-Fractint-count output to truecolor TGA file Gforge -- Generate fractal landscapes, command-line program HF-Lab -- Generate and manipulate landscapes, text-mode interface (newer) Hutil -- Individual heightfield utilities (older; HF-Lab includes them) Hslcom -- Add individual Hue, Sat, Lum files to generate a standard TGA Sparkl -- Add "sparkle" glint-effects to a TGA image ------------------------------------------------------------------------- FCOLOR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 nonstandard 24-bit TGA format . . . . . . . . . . . . . . . . . 2 standard 24-bit color Gforge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 synopsis. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 descryption . . . . . . . . . . . . . . . . . . . . . . . . . . 3 generation of a landscape . . . . . . . . . . . . . . . . . . . 3 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 -dimension . . . . . . . . . . . . . . . . . . . . . . 4 -adim ad ascale. . . . . . . . . . . . . . . . . . . . 4 bpfilter . . . . . . . . . . . . . . . . . . . . . . . 4 brfilter . . . . . . . . . . . . . . . . . . . . . . . 4 lpfilter . . . . . . . . . . . . . . . . . . . . . . . 5 hpfilter . . . . . . . . . . . . . . . . . . . . . . . 5 -power . . . . . . . . . . . . . . . . . . . . . . . . 5 -limit . . . . . . . . . . . . . . . . . . . . . . . . 5 -crater. . . . . . . . . . . . . . . . . . . . . . . . 5 -wrapoff . . . . . . . . . . . . . . . . . . . . . . . 5 -peak. . . . . . . . . . . . . . . . . . . . . . . . . 5 -seed. . . . . . . . . . . . . . . . . . . . . . . . . 5 -name. . . . . . . . . . . . . . . . . . . . . . . . . 6 -type. . . . . . . . . . . . . . . . . . . . . . . . . 6 BUGS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 tiling . . . . . . . . . . . . . . . . . . . . . . . . 6 fixed output sizes . . . . . . . . . . . . . . . . . . 6 HF-Lab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Setup: (PC DOS/Windows3.1/Windows95). . . . . . . . . . . . . . 8 Using HF-Lab. . . . . . . . . . . . . . . . . . . . . . . . . . 8 Fourier Filters. . . . . . . . . . . . . . . . . . . . 9 lpf. . . . . . . . . . . . . . . . . . . . . . . . . . 10 Warping and Twisting . . . . . . . . . . . . . . . . . 10 twist. . . . . . . . . . . . . . . . . . . . . 11 bloom. . . . . . . . . . . . . . . . . . . . . 11 cwarp. . . . . . . . . . . . . . . . . . . . . 11 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 HSLCOM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Hutil Heightfield Conversion Utilities. . . . . . . . . . . . . . . . 14 hcon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 composit. . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 double. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 copyx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 slopegen. . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 smooth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 orb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 cyl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 hslcom. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Input filetypes. . . . . . . . . . . . . . . . . . . . 15 Output filetypes . . . . . . . . . . . . . . . . . . . 15 Sparkl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Add "sparkles". . . . . . . . . . . . . . . . . . . . . . . . . 17 --------------------------------------------------------------------------- FCOLOR -2- The "fcolor" program is intended to take read in a file of 24-bit integers in a nonstandard 24-bit TGA format, and write out a standard 24-bit color TGA file by converting each input pixel count value into Hue, Saturation, and Luminance values, and thence to R,G,B bytes. The nine optional parameters control the conversion. Each of the hue, saturation, and luminosity values has three parameters which control the exponential scaling, the range, and the offset. Normally the full range of each of H,S,L runs from [0..1]. Hue wraps around both for values less than 0 and greater than 1. Luminosity and Saturation wrap for values greater than one, and negative values are forced to zero. For each pixel: fiter = iter / maxiter; /* normalized iteration value */ hue = pow(fiter,h1) * h2 + h3; sat = pow(fiter,s1) * s2 + s3; lum = lum(fiter,l1) * l2 + l3; -------------------------------------------------------------------------------- Gforge(1) -3- NAME gforge - fractal forgery of landscapes and textures SYNOPSIS gforge [-mesh size] [-dimension dim [-adim dim scale]] [-power factor] [-limit low high] [-peak xpos ypos] [-craters [density height]] [-seed seed] [-name filename] [-type TGA|PGM|PG8|OCT|MAT|PNG] [-bpfilter centfreq Q] [-brfilter centfreq Q] [-lpfilter cutfreq Order] [-hpfilter cutfreq Order] [-version] DESCRIPTION gforge generates a landscape texture by "random fractal forgery," the term coined by Richard F. Voss of the IBM Thomas J. Watson Research Center for seemingly realistic pictures of natural objects generated by simple algorithms embodying randomness and fractal self-similarity. The techniques used by gforge are essentially those given by Voss[1], par- ticularly the technique of spectral synthesis explained in more detail by Dietmar Saupe[2]. The source code (and this man page) was mostly tak- en from the "ppmforge" module[3] in the PBMPLUS package of graphics utilities. The gforge "crater" option was contributed by Heiko Eissfeldt . The generation of a landscape begins with the preparation of an array of random data in the frequency domain. The size of this array, the "mesh size," can be set with the -mesh option; the larger the mesh the more realistic the pictures but the calculation time and memory requirement increases as the square of the mesh size. The degree of roughness, which you can specify with the -dimension option, determines whether the resulting terrain is rolling hills or jagged mountins. As the dimension value is increased, more high frequency components are added into the random mesh. (Note that this number does NOT directly correspond to a conventional 'fractal' dimension, eg. a Hausdorff- Besicovich dimension. All gforge surfaces have a 'fractal dimension' near 2.0.) You may apply a band-pass and/or band-reject filter to the frequency data, specifying the normalized [0..1] center frequency and Q (sharp- ness) of each filter. Lowpass and highpass filters are also available. Then an inverse Fourier transform is performed upon it, which converts the original random frequency domain data into spatial amplitudes. We scale the real components that result from the Fourier transform into numbers from 0 to 1 associated with each point on the mesh. You can further modify this number by applying a "power law scale" to it with the -power option. Unity scale leaves the numbers unmodified; a power scale of 0.5 takes the square root of the numbers in the mesh, while a power scale of 3 replaces the numbers in the mesh with their cubes. Powers less than 1 yield landscapes with vertical scarps that look like glacially-carved valleys (with -limit -1.0 1.0); powers greater than one make fairy-castle spires (which require large mesh sizes for best results). Craters, if that option is selected, are added at this point. After these calculations, we have an array of the specified size con- taining numbers that range from 0 to 1. Six output formats are available as described below. ------------------------------------------------------------------------------- -4- Invoking the program with no options writes a 128x128 TGA file called "output.tga" which looks like a somewhat bumpy hillside (in POV any- way... being a special format, it will look like green speckled noise in a standard viewer). "gforge -help" tells you briefly what options are available. You can abbreviate keywords also. Try gforge -t pg8 -pow 1 -dim 4 -n sand.pgm for an image of sand, or gforge -type tga -pow 1.8 -dim 2.4 -m 400 -n mountain.tga for a mountain range to render with POV. Getting your landscape to look just right will require playing around with the -dimension and -power specs. OPTIONS -mesh meshsize The size of the (n x n) IFFT (inverse fast-fourier transform) ma- trix. To prevent the IFFT from becoming a slow fourier transform, it is suggested that the mesh size be a power of two, but you can choose any number you want. If it happens to have a large prime factor, or be itself a prime number, the IFFT calcula- tion will be considerably slowed. The default meshsize is 128. Note that a mesh size of 1024 will require just over 8 megabytes of memory. -dimension dim Sets the dimension to the specified dim, which may be any floating point value between 0 and 3. Higher dimensions create more ``chaotic'' images, which require higher resolution output and a larger FFT mesh size to look good. If no dimension is specified, 2.15 is used. To be precise, the initial mesh is filled with gaus- sian noise of amplitude (1/f)^(4 - dim). Accordingly, dim=4 would give you pure white noise. -adim ad ascale Adds an additional component of noise in the frequency domain with the dimension ad and amplitude (scaled relative to the first speci- fied dimension) of ascale. You can add up to nine additional di- mensions, although one or two is almost certainly enough. Often you don't need any at all. An example might be to have large rolling hills of dim 1.7, with a touch of higher frequencies for a rougher texture: gforge -dim 1.7 -adim 2.0 0.1 -pow 1.8 -bpfilter center-freq Q -brfilter center-freq Q Apply a band-pass (bpfilter) and/or band-reject (brfilter) to the frequency data before the inverse FFT. Center-frequency should be -------------------------------------------------------------------------------- -5- between 0.0 and 1.0. A band-pass filter at f=0 is just a low-pass filter, and at f=1.0 it is a high-pass filter. Q ("quality factor") = 0.5 is a broad filter, Q=20 is narrow. Try these options to see their effects. -lpfilter cut-freq Order -hpfilter cut-freq Order Apply a low-pass or high-pass filter to the frequency data. Cutoff-frequency, between 0 and 1, is the frequency at which the response drops by half. Order may be any positive value; 1 is a soft filter, 1000 is a brick-wall filter. -power exponent Raise the elevation powers to the specified exponent, giving a non- linear scaling effect, useful for some purposes. -limit min max Only relevant if a -power exponent other than 1.0 is selected. Scales terrain to the range [ min- max ] prior to raising to a power. Default is [0.0 - 1.0]. See the sample script/batch file for example usages. -crater density height Add craters to the landscape. The optional density parameter con- trols how many there are. The default 1.0 gives you moderate cratering, but you can specify any positive value. Crater height defaults to 1.0, for what I felt were reasonable looking craters. This is the vertical crater height relative to the underlying landscape scale, and will need to be changed depending on how you scale the vertical axis of your heightfield when you render it. As height goes to zero, the craters dwindle in height and disappear. Crater radius follows a power law distribution. -wrapoff Turn off the default wraparound of craters. The underlying landscape is always tilable, but with this option it will become farther and farther from being tilable as more craters are added. I'm not sure if this is actually useful. Note: cannot be used with the "peak" option. -peak xpos ypos You can specify the location of the largest value (highest peak) in the image as a fraction of the image height and width. For example, gforge -dim 1.5 -pow 3 -peak 0.5 0.5 -name lonelymountain.tga puts the highest peak in the center of the image. This is most use- ful for lower values of dim where there is only one or a few broad maxima; at -dim 2 or above it tends to make less difference. If you don't specify it, it's somewhere random. -seed seed You can give it a random number seed, otherwise it chooses one based on the current time from the system clock. If you use the same seed, you get the same image every time. ------------------------------------------------------------------------------- -name filename -6- If you don't specify it, it's "output.tga" (or "output.xxx", the extension depending on which file type is being written). Existing files with that name are overwritten without warning. -type TGA|PGM|PG8|OCT|MAT|PNG Six options, default is TGA. TGA and PGM are 16-bit formats, and PG8 is just PGM 8-bit binary format. PG8 , will produce a standard PGM file suitable for viewing in a standard graphic viewer to check out what the options are doing to your landscape. OCT produces an ascii file compatible with Octave v1.1.1, a matrix-math package similar in function to Matlab. MAT produces a 32-bit floating- point file in the Matlab binary format. PNG generates 16-bit PNG (portable network graphics) greyscale, which at the time of this writing is a very new format, but gaining in support. Flags may be abbreviated. BUGS tiling 'feature' Because the FFT operates on periodic functions, the opposite edges of the image will always match up. If it turns out you want to cov- er a large area by tiling these textures together, this is just what you want (ie, it's a FEATURE... in fact one way to generate useful tilable textures is by taking the FFT of any interesting picture, filtering a bit, and doing the inverse transform.) If you don't want periodicity, just generate a larger image than you need and use some smaller fraction of it. The "-wrapoff" option applies only to craters crossing the page edge. The "-peak" and "-wrapoff" options cannot be used simultaneously. fixed output sizes The output is always a square grid. If you want a different aspect ratio, you should use another image processing package to crop or rescale as appropriate. Unfortunately most of them don't support 16 bits of precision. John Cristy's ImageMagick 3.6.5 can be compiled to support 16-bit PNG, and Andreas Dilger's patch to POV-Ray 2.2 supports PNG input, output, imagemaps, and heightfields: http://www.wizards.dupont.com/cristy/ImageMagick.html http://www-mddsp.enel.ucalgary.ca/People/adilger/povray/pngpov.html SEE ALSO ppmforge(1), ppm(5), POV-Ray docs [1] Voss, Richard F., ``Random Fractal Forgeries,'' in Earnshaw et. al., Fundamental Algorithms for Computer Graphics, Berlin: Springer-Verlag, 1985. [2] Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images, New York: Springer Verlag, 1988. [3] Walker, John, "ppmforge.c" in Jef Poskanzer's PBMPLUS raster toolk- it, 1991. ------------------------------------------------------------------------------- -7- What's New in Gforge version 1.2b? ---------------------- 12/16/95 jpb -- Bugfix for default random -seed timebomb. Ooops! A date-dependent integer overflow condition in the random number seed was fixed. What's New in Gforge version 1.2a? ---------------------- 9/20/95 jpb -- New -seed behavior. Now, if you specify a different resolution and use the same -seed value as before, the image will look the same (but, obviously, at a different resolution). Good for quickly roughing out the shape you want and then generating at high quality later. -- Beginnings of a Tcl/Tk graphical interface, tenatively named Xforge. (so far, useful only on X-Windows on Unix systems) What's New in Gforge version 1.1f? ---------------------- 8/8/95 jpb -- New format: output to 16-bit greyscale PNG format, using the included pnglib and zlib compression libraries. Source is now 4x larger; sorry! Thanks to G.E. Schalnat at Group 42 Inc. for PNGLIB, and J-l Gailly and Mark Adler for ZLIB. -- Filtering options: bandpass, bandreject:
Center frequency is normalized, ranges from 0.0 to 1.0 Q values in the range 0.5-50 are typical. for lowpass, highpass: The filters tend to give you very UNrealistic landscapes, but then again that might be what you're looking for. -- Returned crater creation to Heiko's original bigger-craters-overlay- smaller-ones structure, minor cosmetic code clean-ups What's New in Gforge version 1.1? ------------------------ 7/27/95 jpb -- New -crater option, takes two optional arguments and , gives you great looking lunar landscapes. Thanks to Heiko Eissfeldt for this contribution! -- Better control of nonlinear height scaling with the -limit option. Good for lake basins, valleys, and plateau forms. -- Better random number generator eliminates diagonal streaks at higher dimensions and meshsizes. Now that the generator is internal, the same -seed value will give you identical results on any machine gforge can be compiled on (well, if you've got at least 24 bits matissa in your floating point type, which doesn't exclude much). -- Better FFT routine can handle any meshsize, not just powers of 2. What's New in Gforge version 1.0f? --------------------------------- -- Output to OCT and MAT types, the latter being Matlab binary-compatible giving you 32 bit floating-point values for the highest accuracy. OCT is the Octave ascii floating-point type. ------------------------------------------------------------------------------- -8- -------- HeightField Lab ------------------ April 27 1996 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 Unix workstations using X Windows. ----- 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. --------------------------------------------------------------------------- -9- 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: ------------------------------------------------------------------------------- -10- 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. ------------------------------------------------------------------------------ -11- 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. 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). ------------------------------------------------------------------------------- -12- 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.) ------------------------------------------------------------------------------- -13- HSLCOM is a small utility program which combines three grayscale image maps in GIF, POT, PGM, or POV-Ray style TGA (NOT standard TGA) formats, into a single standard 24-bit TGA file. This is one way to get "truecolor" fractal images; you'd generate three GIF or POT files in Fractint and then combine them with HSLCOM. The three input files are taken to be hue, saturation, and luminosity (intensity or brightness) values for the respective pixels. You can specify the subranges of each H,S,L on the command line as optional parameters (type HSLCOM with no options for usage instruction). An example: hslcom frac1.gif frac2.gif frac3.gif 0.0 1.0 0.0 1.0 0.0 1.0 hue saturation luminosity This gives you an output TGA file comprising the full range of hue, sat, and luminosity values (each ranges from 0..1). Or another example, hslcom f1.pot f2.pot f3.pot 0.1 0.3 0.6 1.0 0.4 0.8 Which gives you a medium lightness (.4-.8), more saturated (.6-1) reddish (.1-.3) image. The ranges are described as follows: HUE: 0.0=Red 0.4=Yellow-Green 0.8=Blue etc. etc. SAT: 0.0=Grey 1.0=fully saturated LUM: 0.0=Black 1.0=White IMPORTANT: hslcom requires GO32.EXE (the DJGPP 32-bit DOS extender) to be present in in your search path. It should be available in the same place you got hslcom. You can get the entire DJGPP compiler environment, free, for FTP from many places including ftp://oak.oakland.edu/ . ------------------------------------------------------------------------------- -14- Heightfield Conversion Utilities -- beta test version Nov.30, 1995 John P. Beale Here are some utilities useful for those working with Heightfields (also called displacement maps or elevation maps or depth maps), especially those using the POV-Ray raytracer to render them. I decided to release these early; hence, they may have bugs. However I have run the code sucessfully using gcc 2.6.3 on at least five different machines (Sparc, SGI, DEC, Pentium-DOS and Pentium-Linux). This is the binary-only archive. You may obtain the source code as hutil01a.tar.gz from the same site as you got this, or various archive sites on the web (try "archie") or my homepage http://www-leland.stanford.edu/~beale/land/gforge/. The "production" release will have more documentation. This is just a brief description. Run each program with no arguments for an option list. hcon -- converts between heightfield formats. NOT a general-purpose converter, only deals with greyscales. The only TGA type supported is the POV 16-bit heightfield (24bit, blue bytes zero). composit -- combines heightfields with several different arithmatic operations. Good for generating heterogenous terrain using exponent operation. Hint: output might be negative or large; use .mat floating point format for output, then convert later with hcon ... -rescale. double -- doubles x and y dimensions of heightfield, some smoothing also. copyx -- adds a copy of input heightfield onto the right-hand side, so, output file is 2x wider and same height. slopegen -- generate a heightfield with a y gradient (from the top down) useful for subtracting off a landscape profile to simulate a more gradual horizon, assuming you are viewing from the +y direction. smooth -- smooth a .mat format file, using flag.pgm as a mask if it exists. Not command-line driven. Input, output is .mat binary only. Use hcon to convert to/from .mat format. flag.pgm should be 8-bit (PG8). orb -- generates triangular-mesh spherical 'heightfield' in .raw or POV .inc format. You select radial scaling value and tesselation recursion level. Note: level 5=190k, 6=780k, 7=3meg, 8=13meg, 9=40meg file cyl -- generates triangular-mesh cylindrical 'heightfield' in .raw or .inc format. Args: inner radius, outer radius, length, num_circ, num_high Last two args specify the number of vertices around and up cylinder. NOTE: If you want to use ORB or CYL, you'd probably be happier doing it "right", that is, using Polyray 1.8 instead of POV-Ray 2.2. Why? Because Polyray can do spherical and cylindrical heightfields directly! With 8 meg of memory in my PC, I can do a 600x600 spherical heightfield, which I couldn't dream of doing with ORB. Polyray is generally similar to POV-Ray, but in some ways more powerful. Get it from http://ftp.povray.org/pub/polyray/ ------------------------------------------------------------------------------- -15- hslcom- unlike the other programs, this generates a full-color TGA imagemap rather than a 16-bit heightfield type. The input is three same-sized heightfield-type files (GIF,POT,TGA,etc.) which are taken to be the hue, saturation, and luminosity of each corresponding pixel. Nothing to do with heightfields really, but can make a cool imagemap. Look in the 'examples' directory for some sample .POV scenes and a script demonstrating some of the utilities. Notes: all of these utilities, with the exception of 'smooth', operate on a variety of heightfield types. For example, type 'hcon' with no parameters. It displays a usage message saying it can read files of type PGM MAT GIF POT TGA and write PGM PG8 MAT OCT GIF POT TGA. To explain: Input filetypes: ----------------- PGM ascii or binary PGM (NOT PNM). This is a single-value-per-pixel file. MAT Matlab binary 32 or 64-bit floating point, IEEE little-endian. GIF GIF87a or GIF89a. NOTE: uses index value, ignores color map POT Fractint/POV-Ray style .pot 16-bit files (GIF89a variant) TGA POV-Ray's HF format: 24-bit TGA holding 16-bit gray information Output filetypes: ------------------ PGM 16-bit ascii PGM (Portable Grey Map) PG8 8-bit binary PGM MAT 32-bit binary floating-point Matlab format OCT 32-bit (roughly) ascii float-pnt. Octave (like Matlab) format GIF 8-bit gray colormap, standard Compuserve GIF87a POT 16-bit gray. can be read by POV-Ray, but not Fractint TGA 16-bit values in 24-bit file (1/3 wasted). POV-Ray's HF format. And where do you get heightfields in these formats to convert in the first place, you may ask yourself? I'd recommend my own program, naturally. Gforge generates PGM,MAT,OCT, and TGA format heightfields. As of this writing the current version is gforge v1.1f which you can download from an Internet archive site near you. Check 'archie'. Or, go to my homepage http://www-leland.stanford.edu/~beale/land/gforge/. My utilities can read the GIF and POT files generated by Fractint, although the reverse is not true. Fractint and Gforge are the only 16-bit heightfield generators I know of at this time. There are a great many 8-bit generators, though, usually giving you GIF output. Hint: if you use 'composit' to combine several heightfields in more than one step, use the "MAT" format as an intermediate format, because it can represent negative numbers and large numbers. The other formats are treated as representing values from 0.0 to 1.0, and will wrap around if you exceed those bounds. When converting back from MAT to say, GIF, you can do one of two things: rescale all values to fit the GIF range: hcon topo.mat topo.gif -rescale Or, you may want to clip the values somewhere. Supposing you had used ------------------------------------------------------------------------------- -16- composit mul fract001.pot fract002.pot image.mat 8.0 -4.0 to generate an interesting combination of two POT files from Fractint, for instance. This example takes each pixel value from 'fract002.pot' (which ranges from 0.0 to 1.0), multiplies by eight, subtracts four, and multiplies the result by the corresponding pixel in fract001.pot. (Composit requires the two input files to be of exactly the same size.) You now may have a MAT file with values running from -3.8 to 2.7 (for instance). You want to create a POT representing just the range -1 to +2, and clip numbers less than -1 to black and greater than +2 to white. You would then type this: hcon image.mat image.pot -1.0 2.0 but now, you discover you'd rather have the image inverted. Type this: hcon image.pot image.pot -negate (Input files are read in and closed before any output, so this works.) ------------------------------------------------------------------------------- -17- Sparkl -- Add "sparkles" simulating diffraction spikes to an image. This is a small utility to add those glint or sparkle-type effects you may have seen to your own images. It doesn't add sparkles arbitrarily, but works by painting in radial spikes or rays around what are already the brightest pixels in an image. The number of spokes, their intensity and length, and overall rotation angle is adjustable through command-line parameters. Also adjustable is the brightest-pixels-percentile cutoff value, ie, what fraction of brightest pixels should be enhanced with glints? The default value of 0.001 (ie 0.1 percentile) seems to work pretty well. Much more than that and you'll have the entire picture looking sparkly. This percentile value is then translated into an absolute brightness level by taking a histogram of the image and adding up the numbers of brightest pixels. IMPORTANT: Not all images are good candidates for "sparkle" treatment. You want a fairly dark image, with a few bright points. The effect of the program on all bright, or low-contrast images is difficult or impossible to see. If you aren't getting the result you want, try first darkening the image and making sure there are a few small bright points in it. Initial image contrast is critical for best results. Caution: too many sparkles will probably make your image look like a home-shopping-network advertisement for cheap jewlery. Note that the only image file format used by this program is the 24-bit ("type 2") uncompressed, top-down, TGA (Targa) format file. This format is very common in the DOS/PC world, less so for Unix boxes but you can convert other formats to it with "xv" version 3.1, or ImageMagick, or the pbmplus tools. UNIX: type "make" and the program should compile. DOS: zip file includes .exe, you'll also need DJGPP GO32.EXE DOS extender which should be available from same FTP site. Dec. 15th 1995 -- John P. Beale