    Height fields are fast, efficient objects that are generally used to
 create mountains or other raised surfaces out of hundreds of triangles in a
 mesh.

    A height field is essentially a 1 unit wide by 1 unit long box with a
 mountainous surface on top.  The height of the mountain at each point is
 taken from the color number (palette index) of the pixels in a graphic image
 file.
                    ________     <---- image index 255
                  /        /|
            +1y  ---------- |
                 |        | |
                 |        | |+1z <- Image upper-right
                 |        | /
            0,0,0---------- +1x
                 ^
                 |____ Image lower-left

    NOTE: Image resolution is irrelevant to the scale of the heightfield.

    The mesh of triangles corresponds directly to the pixels in the image
 file.  In fact, there are two small triangles for every pixel in the image
 file.  The Y (height) component of the triangles is determined by the pal-
 ette index number stored at each location in the image file.  The higher the
 number, the higher the triangle.  The maximum height of an unscaled height
 field is 1 unit.

    The higher the resolution of the image file used to create the height
 field, the smoother the height field will look.  A 640 X 480 GIF will create
 a smoother height field than a 320 x 200 GIF.  The size/resolution of the
 image does not affect the size of the height field.  The unscaled height
 field size will always be 1x1.  Higher resolution image files will create
 smaller triangles, not larger height fields.

    There are three types files which can define a height field as follows:
       height_field { gif 'filename.gif' }
       height_field { tga 'filename.tga' }
       height_field { pot 'filename.pot' }

    The image file used to create a height field can be a GIF, TGA or POT
 format file.  The GIF format is the only one that can be created using a
 standard paint program.

    In a GIF file, the color number is the palette index at a given point.
 Use a paint program to look at the palette of a GIF image.  The first color
 is palette index zero, the second is index 1, the third is index 2, and so
 on.  The last palette entry is index 255.  Portions of the image that use
 low palette entries will be lower on the height field.  Portions of the ima-
 ge that use higher palette entries will be higher on the height field.  For
 example: an image that was completely made up of entry 0 would be a flat 1x1
 square.  An image that was completely made up of entry 255 would be a 1x1x1
 cube.

    The maximum number of colors in a GIF are 256, so a GIF height field can
 have any number of triangles but they will only 256 different height values.

    The color of the palette entry does not affect the height of the pixel.
 Color entry 0 could be red, blue, black, or orange, but the height of any
 pixel that uses color entry 0 will always be 0.  Color entry 255 could be
 indigo, hot pink, white, or sky blue, but the height of any pixel that uses
 color entry 255 will always be 1.

    You can create height field GIF images with a paint program or a fractal
 program like 'Fractint'.  If you have access to an IBM-PC, you can get
 Fractint from most of the same sources as POV-Ray.

    A POT file is essentially a GIF file with a 16-bit palette.  The ma ximum
 number of colors in a POT file is greater than 32,000.  This means a POT
 height field can have over 32,000 possible height values.  This makes it
 possible to have much smoother height fields.

    NOTE: The maximum height of the field is still 1 even though more inter-
 mediate values are possible.

    At the time of this writing, the only program that created POT files was
 a freeware IBM-PC program called Fractint.  POT files generated with this
 fractal program create fantastic landscapes.  If you have access to an IBM-
 PC, you can get Fractint from most of the same sources as POV-Ray.

    The TGA file format may be used as a storage device for 16-bit numbers
 rather than an image file.  The TGA format uses the red and green bytes of
 each pixel to store the high and low bytes of a height value.  TGA files are
 as smooth as POT files, but they must be generated with special custom-made
 programs.  Currently, this format is of most use to programmers, though you
 may see TGA height field generator programs arriving soon.  There is example
 C source code included with the POV-Ray source archive to create a TGA file
 for use with a height field.

    It is nearly impossible to take advantage of the 16 bits of resolution
 offered by the use of tga files in height fields when the tga file is cre-
 ated in a paint program.  A gif file is a better choice for paint created
 height fields in 8 bits.  Also see Appendix B.5 for a tip on creating tga
 files for height fields.

    An optional 'water_level' parameter may be added after the file name and
 It consists of the keyword 'water_level' followed by a float value tells the
 program not to look for the height field below that value.  Default value is
 0 and legal values are between 0 and 1.  For example: 'water_level .5' tells
 POV-Ray to only render the top half of the height field.  The other half is
 'below the water' and couldn't be seen anyway.  This term comes from the po-
 pular use of height fields to render landscapes.  A height field would be
 used to create islands and another shape would be used to simulate water
 around the islands.  A large portion of the height field would be obscured
 by the 'water' so the 'water_level' parameter was introduced to allow the
 ray tracer to ignore the unseen parts of the height field.  Water_level is
 also used to 'cut away' unwanted lower values in a height field.  For exam-
 ple: if you have an image of a fractal on a solid colored background, where
 the back ground color is palette entry 0, you can remove the background in
 the height field by specifying, 'water_level .001'

    Normally height fields have a rough, jagged look because they are made of
 lots of flat triangles.  Adding the keyword 'smooth' causes POV-Ray to modi-
 fy the surface normal vectors of the triangles in such a way that the light-
 ing and shading of the triangles will give a smooth look.  This may allow
 you to use a lower resolution file for your height field than would other-
 wise be needed.

    Height fields can be used in CSG shapes and they can be scaled, rotated
 and translated.  Because they are finite they respond to automatic bounding.

    Here are a notes and helpful hints on height fields from their creator,
 Doug Muir:
       'The height field is mapped to the x-z plane, with its lower left
       corner sitting at the origin.  It extends to 1 in the positive x
       direction and to 1 in the positive z direction.  It is maximum 1
       unit high in the y direction.  You can translate it, scale it, and
       rotate it to your heart's content.'

    When deciding on what water_level to use, remember, this applies to the
 untransformed height field.  If you are a Fractint user, the water_level
 should be used just like the water_level parameter for 3d projections in
 Fractint.

    Here's a detailed explanation of how the ray-tracer creates the height
 field.  You can skip this if you aren't interested in the technical side of
 ray tracing.  This information is not needed to create or use height fields.

    To find an intersection with the height field, the ray tracer first
 checks to see if the ray intersects the box which surrounds the height
 field.  Before any transformations, this box's two opposite vertexes are at
 (0, water_level, 0) and (1, 1, 1).  If the box is intersected, the ray
 tracer figures out where, and then follows the line from where the ray
 enters the box to where it leaves the box, checking each pixel it crosses
 for an intersection.

    It checks the pixel by dividing it up into two triangles.  The height
 vertex of the triangle is determined by the color index at the corresponding
 position in the GIF, POT, or TGA file.

    If your file has a uses the color map randomly, your height field is go-
 ing to look pretty chaotic, with tall, thin spikes shooting up all over the
 place.  Not every GIF will make a good height field.

    If you want to get an idea of what your height field will look like, I
 recommend using the IBM-PC program Fractint's 3d projection features to do a
 sort of preview.  If it doesn't look good there, the ray tracer isn't going
 to fix it.  For those of you who can't use Fractint, convert the image pal-
 ette to a gray scale from black at entry 0 to white at entry 255 with smooth
 steps of gray.  The dark parts will lower than the brighter parts, so you
 can get a feel for how the image will look as a height field.
