
vgfractal(1)                 Khoros                  vgfractal(1)

PROGRAM
     vgfractal - Creates a fractal image with a desired fractal
     dimension.

SYNTAX
     vgfractal

     -o             Output image filename

     [-trigger]     trigger input

     [-r]           Number of recursions

     [-h]           Hurst coefficient

     [-d]           Standard deviation

     [-s]           Seed

     [-c]           Coastlines

     [-m]           Random additions

     [-V]           Gives the version for vgfractal

     [-U]           Gives the usage for vgfractal

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called vgfractal.ans
                    or file1

     [-a [file1]]   Uses vgfractal.ans or file1 as the answer
                    file

DESCRIPTION
     vgfractal creates a fractal image with a desired fractal
     dimension.  A fractal image is created using the midpoint
     displacement algorithm, which uses a recursive generation
     technique.  Numerous types of fractal images may be created
     by varying the input parameters.

     The output image, which corresponds to the -o argument, is
     stored as data type FLOAT, and will be a single band image.
     The size of the resulting image will be determined by the
     maximum number of recursions.  That is, the resulting image
     will be square, with dimensions (2^recursions +1) by
     (2^recursions +1).

     The input parameters include: maximum number of recursions,
     desired hurst coefficient, standard deviation of random
     numbers, seed, coastlines, and random additions.  Descrip-
     tions on the use of these parameters follow.

     The maximum number of recursions (iterations) is specified
     by the -r recursive iteration argument.  The recursive
     iteration argument must be an integer ranging from 2 to 10.
     The size of the image will be a power of two of the recur-
     sive iteration argument.  That is, it will create an image
     with sizes ranging from (5 by 5) to (1025 by 1025).  The
     default number of recursions is 6, which will result in an
     image of size 65 by 65 pixels.

     The hurst coefficient of the generated image may be altered
     with the -h argument.  This allows the user to change the
     fractal dimension of the generated image.  Since the hurst
     coefficient is a measure of the slope of window size vs
     range in pixel values, the valid range for the hurst coeffi-
     cient is  0 < H < 1.

     The fractal dimension is calculated from the hurst coeffi-
     cient as follows:

                              D = 3 - H
         where,
                  D is the fractal dimension
                  H is the hurst coefficient.

     The parameter 3 reflects the 3-dimensional Euclidean
     geometry of the system (ie. X, Y, and Z or pixel value).

     The standard deviation of the randomly generated numbers
     used to create the fractal image may be altered using the -s
     argument.  Increasing the standard deviation will permit a
     wider range of values to be generated by the random number
     generator.  This will have the same effect as scaling the
     values that are generated.

     A seed may be entered to allow the same image to be gen-
     erated, or the system time may be used to set the seed
     (default).

     The coastline argument (-c) can be toggled on (default is
     off), which will effectively generate a "coastline" by set-
     ting all generated values that fall below zero to be equal
     to zero.  This creates the effect of a body of water running
     up against a landform, or a "coastline".

     The random additions argument (-m) can be toggled on, which
     will allow random elements to be added to each point,
     whereas with random additions turned off (default), random
     elements are added only to the new midpoints generated in
     each stage.

     Note that in order to display the image as a three dimen-
     sional relief plot, the data can be plotted in Xprism3.

     Theory - The midpoint displacement algorithm constructs the
     image using a recursive generation technique.  This method
     works with square lattices of points or pixels.  Given a
     resolution (w) of such a lattice or grid, another square
     grid is obtained with a resolution of w/sqrt(2) by adding
     the midpoints of all squares.  The orientation of the new
     lattice is rotated by 45 degrees, and adding the midpoints
     of all squares yields the next lattice with a resolution of
     w/2 and the same orientation as the first.  This is illus-
     trated as follows:

           o   x   o            o   o   o           o x o x o
                                  x   x             x o x o x
           x   o   x    ---->   o   o   o   ---->   o x o x o
                                  x   x             x o x o x
           o   x   o            o   o   o           o x o x o

           where,      o = old points
                       x = new points

     The trigger input can be used to cause vgfractal to re-
     execute when used inside cantata. No image is read from this
     input.

REQUIRED ARGUMENTS
     -o     type: outfile
            desc: Output image filename

OPTIONAL ARGUMENTS
     -trigger
            type: infile
            desc: trigger input

     -r     type: integer
            desc: Number of recursions
            default: 6
            bounds: 2 < [-r] < 10

     -h     type: float
            desc: Hurst coefficient
            default: 0.5
            bounds: 0.000000 < [-h] < 1.000000

     -d     type: float
            desc: Standard deviation
            default: 1
            bounds: value > 0.0

     -s     type: integer
            desc: Seed
            default: 0
            bounds: value >= 0

     -c     type: boolean
            desc: Coastlines
            default: false

     -m     type: boolean
            desc: Random additions
            default: false

EXAMPLES
     vgfractal -o output_image.xv -r 5 -h 0.7 -d 2.0 -s 1359 -m 1

     the selected number of recursions is 5 (2^5 +1 or a 33 x 33
     image).  The hurst coefficient selected is 0.7, which
     results in an image with a fractal dimension of 2.3.  The
     standard deviation is 2.0 (slightly wider range of values
     generated).  The seed for the random number generator is
     entered as 1359.  The random additions flag is toggled on.

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lvgfractal(3)
     vfractal(1)

RESTRICTIONS
     The resulting output image will be of type FLOAT.

COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

