
   May 18 1996  ver 1.3                                             gforge(1)



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

     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
          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 mtn.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
          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. 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  Images,
          New York: Springer Verlag, 1988.

     [3]  Walker, John, "ppmforge.c" in Jef Poskanzer's PBMPLUS raster toolk-
          it, 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, ver-
     sion 2.  For more details, see the GPL.

