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