	          TerraConv
	          =========

	Copyright (c) 2004-2007, Pauli Lindgren
	e-mail:    pauli.lindgren@mbnet.fi
	     or	   pauli0212@yahoo.com
	web page:  http://koti.mbnet.fi/pkl/


TerraConv converts Terragen terrain files into TIFF or PGM image file
and TIFF/PGM files back to terrain files. You can use TerraConv for
exampe for editing terrain with on an image manipulation program, or
to use Terragen terrain in some other geographical program.

TerraConv supports 16 bit color depth, so that you will not lose any
resolution in the conversion process.

TerraConv supports following file formats:
  - Terragen Terrains			R/W
  - TIFF,	 8 bit grayscale	R
  - TIFF,	16 bit grayscale	R/W
  - TIFF,	32 bit HDR grayscale	R/W
  - TIFF,	24 bit RGB color	R
  - TIFF,	48 bit RGB color	R
  - GeoTIFF	  (as TIFF)
  - PGM,	 8 bit binary		R
  - PGM,	16 bit binary		R/W
  - PGM,	ASCII          		R/W

8 bit palette color images can be loaded, but the palette information
is ignored.

Only non-compressed TIFF files are supported. When the file is read, it is
converted into grayscale. When writing a TIFF file, 16 bit grayscale
or 32 bit floating point (HDR) grayscale mode is used. When writing
PGM file, 16 bit resolution is used, either as binary or ASCII.

-----------------------------------------------------------------------------

	INSTALLING

TerraConv works on Windows 95/98/2000/NT4/XP operating system.
To instal TerraConv, just unzip the files into any directory.
You can then start the program by typing "tconv" on DOS command prompt.

Alternatively, you can create a shortcut on your Windows desktop: 
 1. Click tconv.exe with right mouse button, drag it into your
    desktop and release mouse button.
 2. From the pop-up menu, select "Create Shortcuts Here".
 3. Rename the icon to "TerraConv" or whatever you like.


-----------------------------------------------------------------------------

	USER INTERFACE

TerraConv user interface has 6 buttons:
  Load Terrain	- load a Terragen terrain file into memory
  Save Terrain  - save Terragen terrain file
  Import	- load a TIFF or PGM file and convert it into grayscale
  Export	- save terrain as TIFF or PGM image file
  Restore	- restore last terrain scaling data
  Exit		- exit the program

Left part of the display contains the header data from the terrain
file that was last loaded or saved. The right part of the display contains
header data from the last TIFF or PGM file loaded or saved.

Middle part of the display shows the terrain as a grayscale image.


-----------------------------------------------------------------------------

	USING TerraConv

To convert terrain file into TIFF or PGM file:
  1. Click "Load Terrain", select a file you want to convert and click OK.
  2. Click "Export".
  3. In Export Options dialog box, select the file type and other
     options (see below), then click OK.
  4. Select filename/location for the TIF file to save. Default
     filename is the name of terrain file with extension changed
     for the selected file type. Note: you may change the extension,
     but that does not change the type of saved file.

To convert TIFF or PGM file into Terragen terrain:
  1. Click "Import", select a file you want to convert and click OK.
     The file type is recognized by the extension.
  2. You may now restore the scaling data of previously loaded
     terrain file by clicking "Restore".
  3. Click "Save Terrain" and select filename/location for the terrain
     file to save.


	Export Options dialog

Export options dialog is displayed when you click Export button.

"Save as" list box allows you to select file type: TIF or PGM.
The default is TIF, which is supported by most image editing
programs.

"Pixel data format" radio buttons selects the format pixel data is
saved in the file. In most cases, 16 bit binary should be selected.
Use other format if required by the target program.

"Include GeoTIFF data" tickbox: tick this to create a GeoTIFF file.
This can be used to export terrain into a geographical program that
supports GeoTIFF files (such as 3DEM). Usually, you should also
select "32 bit floating point" as pixel data format.



	DRAG AND DROP

You can drag a file from Windows Explorer or a folder and drop it on
the TerraConv icon. TerraConv will then start and load that file. The
file type is identified by the extension.

When TerraConv application window is open, you can drag a file into
the application window. The file is then loaded into TerraConv.

You may create a special icon on your desktop so that when you drag
and drop a file on that icon, it is converted immediatelly from
.TER to .TIF or from other formats to .TER, without opening the
application window (see COMMAND LINE below). To create the icon:

 1. Create a new desktop icon as described in INSTALLING above.
 2. Click the icon with right mouse button and select "Properties"
 3. In the Target field on the Shortcut tab, add command line switch
    -b at the end of the text (outside any quotes), for example:
    "C:\Program Files\Terragen\TConv.exe" -b -s



	KEYBOARD SHORTCUTS

In addition to clicking with mouse, you can activate a button
by pressing the key that is underlined in the button text.
For example, to load terrain file, press L.

Alt-X exits the program.

If Esc is pressed while file load operation is running, the
operation is canceled.



	COMMAND LINE

You can start TerraConv from DOS prompt by typing tconv. This will
open the TerraConv application window.

You may enter a filename on the command line:
  tconv example.ter

TerraConv will then start and load the specified file. The file type
is recognized by the extension.

If you enter two filenames, for example:
  tconv example.ter example.tif
the conversion from the input file (example.ter) to the output file
(example.tif) is done silently without opening TerraConv application
window.

Alternatively, you can use the -B flag (Batch mode). If you give the
-B flag with only one filename, then the destination filename is created
from source filename by changing the extension. If source file has
the extension .ter, the destination file will have extenstion (and file
type of) .tif, otherwise destination file will have extension .ter.

Note: TerraConv runs as a separate process. Therefore, the conversion
is not yet ready when the DOS prompt is displayed again. TerraConv gives
a short beep sound when the conversion has been done. Use option -s
if you do not want the beep sound.

If the file exists, confirm overwrite dialog appears. However, if you
enter the command line option -o, the file is overwritten without prompting.

The summary of command line syntax:

   tconv [-o] [-s] [-b] [inputfile [outputfile]]

where:
   infputfile	= name of file to read (source)
   outputfile	= name of file to write (destination)
   -o		= Overwrite destination file without prompt
   -s		= Silent (no beep sound when done)
   -b		= Batch mode even if just one filename

Items in [square braces] are optional.
The option letters can be preceded either by character '-' or '/'
and they may be entered in upper or lower case.

Examples:

   tconv -o test.ter test.tif
   tconv /o /b test.ter



	BATCH PROCESSING

You can process multiple files in a directory by creating a .BAT file.

For example, to convert all .TER files in a directory into .TIF files,
create a file "ter2tif.bat" which contains the following line:

  for %%F in (*.ter) do d:\path\tconv -b -o %%F

Replace "d:\path\" above with the actual path to your TerreConv directory.

Then go to the directory that contains your .TER files and just execute
the command ter2tif (with full path if necessary). That will convert all
the .TER files into .TIF files. The names of the files created will be
the same as .TER file but with extension .TIF. Note that Windows may
run multiple copies of tconv.exe in parallel, so the memory space may
limit the number of files that can be converted.



-----------------------------------------------------------------------------

	NOTES ON FILE TYPES


	Tagged Image File Format (TIFF)

This is a standard format supported by most image editing programs.
However, TIFF standard allows very much variations in the format, and
therefore it is not uncommon that one program can not read the file
created by another program.

TerraConv can only read uncompressed TIFF files. Thus, when saving TIFF file
from your image editor, make sure to select "no compression" option.


	HDR TIFF files

HDR TIFF is a TIFF file where pixel data is stored as floating point
numbers. This allows very large brightness range to be used, or
in case of altitude data, a large altitude range.
Some geographical programs (such as 3DEM) require HDR data, that is
why this option has been included in TerraConv.

HDR TIFF files have extension .TIF just like an ordinary TIFF file.
When loading TIF, TerraConv automatically detects if the data is
in HDR format, and scales and converts it into 16 bit integer data
suitable for Terragen.

When saving TIFF, you can select from Export Options dialog box
if the data is to be saved as normal 16-bit binary or as 32-bit
floating point (=HDR). HDR data is often used in combinaton with
GeoTIFF data (see below).


	GeoTIFF files

GeoTIFF files are TIFF files with some additional information for
storing geographical data. GeoTIFF file may contain terrain altitude
data, but it can be used for many other purposes, too (for example:
maps, aerial photographs). Naturally, only GeoTIFF that contains
altitude data is suitable to be converted into Terragen terrain.

GeoTIFF files have extension .TIF just like an ordinary TIFF file.
When loading TIF, TerraConv automatically detects if GeoTIFF data
is included, and uses it to set Terrain scaling. (In this case
you do not need to use the Restore button to restore previous
scaling.) However, GeoTIFF data may be stored in many various
formats. TerraConv can use the scaling data only if the coordinates
have been stored in degrees and altitude data in metres (which
is the most common format). If unknown format causes totally
wrong values for altitude scaling, you may reset the values into
sensible range by clicking the Restore button. You can then adjust
the altitude scaling in Terragen.

When saving TIFF, you can select from Export Options dialog box
if GeoTIFF data is to be saved.


	Portable Grayscale Map (PGM) files

PGM is a simple file format used as intermediate format for file
type conversions, especially in Unix/Linux world.

PGM may store data either in binary or ASCII format. ASCII format
creates much larger files, but you may need to use it when
converting files to/from computers that use Big Endian byte order
(e.g. Macintosh).

Note that 16 bit PGM format is relatively new, and older programs
may only support 8 bit data (in which case you can not export
terrain data to such program).


-----------------------------------------------------------------------------

	BUGS AND LIMITATIONS
 
- Maximum terrain size is 8193 x 8193 pixels.
- Compressed TIFF files not supported.
- Not all coordinate systems of GeoTIFF supported.
- The program runs on bytecode interpreter, so it is a bit slow.


-----------------------------------------------------------------------------

	REVISION HISTORY

V1.23  14.08.2007
 - Added keyboard commands Esc (break) and Alt-X (exit)
 - Resizeable File Open/Save dialog boxes
 - Fix: Did not save any more scaling data after Restore had been pressed
 - Compiled with new runtime library (hopefully this reduces the number
   of false virus alarms given by some virus scanners)

V1.22  28.07.2005
 - Added command line option -b (batch mode)
 - Keyboard shortcuts for buttons
 - Fix: Command line conversion from .ter to .tif corrected
 - Fix: Windows XP compatibility for Conversion Ready sound

V1.21  15.03.2005
 - Max terrain size increased from 2049 to 8193
 - Some memory optimization
 - Some speed enhancement for larger files

V1.20  24.11.2004
 - Added HDR TIFF support (floating point data)
 - Added GeoTIF support
 - Added PGM file support
 - Added drag and drop support
 - Added command line parameters
 - Fix: now correctly loads grayscale TIF with Alpha channel
 - Fix: now correctly loads TIF with only 1 strip and no offset table
 - fixed TifPath storing in .ini file
 - fixed bug in re-saving Terrain file
 - other minor fixes

V1.10  05.07.2004
 - Store altitude scaling data into TerraConv.dat, restore button added
 - Remember the folder (path) of Terrain and TIF files.

V1.01  17.06.2004
 - Fixed reading SIZE tag on terrain files that do not contain XPTS and
   YPTS tags (value = size-1).
 - Display version and copyright text on status line on program start.

V1.00  27.05.2004
 - First release


-----------------------------------------------------------------------------

TerraConv is copyright (c) 2004-2007 Pauli Lindgren.

Terraconv is "freeware": you may freely use TerraConv to produce images
for commercial or non-commercial purposes, and you can give TerraConv to
your friends (but you must include this document file unmodified).
However, you are not allowed to distribute TerraConv on your web page or as
part of any commercial software collection without prior written permission.

