     gforge(1)                                                         gforge(1)
                                May 18 1996  ver 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 cent_freq Q] [-brfilter
                   cent_freq Q] [-lpfilter cut_freq Order] [-hpfilter cut_freq
                   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],
          particularly the technique of spectral synthesis explained in more de-
          tail by Dietmar Saupe[2]. The source code  (and  this  man  page)  was
          mostly  taken  from the "ppmforge" module[3] in the PBMPLUS package of
          graphics utilities. The gforge  "crater"  option  was  contributed  by
          Heiko Eissfeldt <heiko@colossus.escape.de>.

          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 re-
          quirement increases as the square of the mesh  size.   The  degree  of
          roughness,  which  you  can specify with the -dimension option, deter-
          mines whether the resulting terrain is rolling hills or  jagged  moun-
          tins.  As  the  dimension value is increased, more high frequency com-
          ponents 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

                                        - 1 -           Formatted:  May 10, 2000

     gforge(1)                                                         gforge(1)
                                May 18 1996  ver 1.3

          point.  After  these  calculations,  we have an array of the specified
          size containing numbers that range from 0 to 1. Six output formats are
          available as described below.

          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  calcu-
               lation 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  float-
               ing  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
               gaussian  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
               specified dimension) of ascale.  You can add up to nine addition-
               al  dimensions,  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 frequen-

                                        - 2 -           Formatted:  May 10, 2000

     gforge(1)                                                         gforge(1)
                                May 18 1996  ver 1.3

               cies 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
               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 fac-
               tor") = 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
               nonlinear 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 disap-
               pear.  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.

                                        - 3 -           Formatted:  May 10, 2000

     gforge(1)                                                         gforge(1)
                                May 18 1996  ver 1.3

          -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 ex-
               ample,

               gforge -dim 1.5 -pow 3 -peak 0.5 0.5 -name mtn.tga

               puts the highest peak in the center of the image.  This  is  most
               useful  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  differ-
               ence. 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
               If you don't specify it, it's "output.tga" (or "output.xxx",  the
               extension  depending on which file type is being written). Exist-
               ing 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 stan-
               dard 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  gen-
               erates 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 cover a large area by tiling these textures together, this  is
               just what you want (ie, it's a FEATURE... in fact one way to gen-
               erate useful tilable textures is by taking the  FFT  of  any  in-
               teresting  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  as-

                                        - 4 -           Formatted:  May 10, 2000

     gforge(1)                                                         gforge(1)
                                May 18 1996  ver 1.3

               pect  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 height-
               fields. POV-Ray 3.0 supports PNG.

               http://www.wizards.dupont.com/cristy/ImageMagick.html
               http://www-mddsp.enel.ucalgary.ca/People/adilger/povray

     SEE ALSO
          ppmforge(1), ppm(5), povray(1)

          [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  Im-
               ages, New York: Springer Verlag, 1988.

          [3]  Walker, John, "ppmforge.c"  in  Jef  Poskanzer's  PBMPLUS  raster
               toolkit, 1991.  <kelvin@fourmilab.ch>  <http://www.fourmilab.ch/>

     AUTHORS
               John Beale                            Heiko Eissfeldt
               1745 Webster St.                 <heiko@colossus.escape.de>
               Palo Alto, CA 94301
               -----------------------------------------------------------------
               beale@best.com               http://jump.stanford.edu:8080/~beale
               http://www.best.com/~beale   http://chomsky.stanford.edu/~beale

          The gforge program is copyright (c) 1995 by John  P.  Beale,  and  the
          crater  code is copyright (c) 1995 Heiko Eissfeldt. 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.

                                        - 5 -           Formatted:  May 10, 2000