	Heightfield Conversion Utilities -- beta test version
	10/17/95 John P. Beale <beale@jump.stanford.edu>

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, IBM,
and Pentium-DOS [djgpp]).

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).
	 GIF index, not color, is used. Interlaced GIF is not supported.

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.

joinhf -- more general version of copyx. Joins two heightfields together,
	stacked either vertically or horizontally. HFs do not need to be
	of the same dimension.

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. Can generate smoothed triangles, or use raw2pov for more
       control. 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.

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.2a which you can
download from   http://jumpjibe.stanford.edu:8080/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

  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.)
Have fun!

-john beale

----- <legal stuff> -----------------

These heightfield utilities are Copyright (C) 1995 John P. Beale
<beale@jump.stanford.edu>. Released under the GNU Public License version 2
(GPL). Freely redistributable. No fee is requested. No guarantee is given.


I have used Tom Boutell's gd (gifdraw) library for GIF I/O, which requires
the following notices. GD is

	Written by Tom Boutell, 5/94.
	Copyright 1994, Cold Spring Harbor Labs.
	Permission granted to use this code in any fashion provided
	that this notice is retained and any alterations are
	labeled as such. It is requested, but not required, that
	you share extensions to this module with us so that we
	can incorporate them into new versions.

	Tom Boutell, boutell@netcom.com
	http://sunsite.unc.edu/boutell/index.html
	116 14th Ave E Apt 2
	Seattle, WA 98102
-------------

The GIF encoder used in GD contains the following additional notices:

   Code drawn from ppmtogif.c, from the pbmplus package
   Based on GIFENCOD by David Rowley <mgardi@watdscu.waterloo.edu>. A
   Lempel-Zim compression based on "compress".
   Modified by Marcel Wijkstra <wijkstra@fwi.uva.nl>

   Copyright (C) 1989 by Jef Poskanzer.

   Permission to use, copy, modify, and distribute this software and its
   documentation for any purpose and without fee is hereby granted, provided
   that the above copyright notice appear in all copies and that both that
   copyright notice and this permission notice appear in supporting
   documentation.  This software is provided "as is" without express or
   implied warranty.

   The Graphics Interchange Format(c) is the Copyright property of
   CompuServe Incorporated.  GIF(sm) is a Service Mark property of
   CompuServe Incorporated.

/* +-------------------------------------------------------------------+ */
/* | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    | */
/* |   Permission to use, copy, modify, and distribute this software   | */
/* |   and its documentation for any purpose and without fee is hereby | */
/* |   granted, provided that the above copyright notice appear in all | */
/* |   copies and that both that copyright notice and this permission  | */
/* |   notice appear in supporting documentation.  This software is    | */
/* |   provided "as is" without express or implied warranty.           | */
/* +-------------------------------------------------------------------+ */
						

