Heightfield Conversion Utilities -- beta test version 10/17/95 John P. Beale 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 ----- ----------------- These heightfield utilities are Copyright (C) 1995 John P. Beale . 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 . A Lempel-Zim compression based on "compress". Modified by Marcel Wijkstra 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. | */ /* +-------------------------------------------------------------------+ */