NCSA Reformat
Peter Webb, National Center for Supercomputing Applications
pwebb@ncsa.uiuc.edu

This tool converts images from one file format to another.  Currently, it
can convert X window dumps, Sun Raster, raw raster, TIFF, FITS and GIF files 
to HDF.

I am soliciting comments on the layout of the user interface, and the basic
functionality.  If you have suggestions - how to make the tool eaiser to use
or features that you would like to see added, please contact me at the above
address.  This code has been tested on the a Sun 3, SGI Personal Iris and a
Cray running UNICOS.  It will most likely run on any Unix system.

For documentation, see the file help.txt, included in this distribution.
Also see the file users-guide for an brief introduction to Reformat.

To install this tool, first modify the Makefile.  You must indicate the type of
your operating system, and the locations of NCSA HDF and the X window system.
HDF is required, but X is not. 

The tool has two versions.  One uses a simple command line interface and the
other uses an X-based graphical user interface.  The X version of the tool
requires X version 11, release 4 (and the Athena Widget Set).  Be warned that
the executable for the X version is more than 700Kb in size.

After modifying the Makefile, type 'make withx' to build the version that
uses X, and 'make withoutx' to build the simpler version.  The first command
will produce an executable file called 'xreformat', the second, one called
'reformat'.

Adding a new file type to Reformat:

I tried to design the program so that this task could be done by any
reasonably competent programmer.  Please let me know if you do add any new
file types, and send me your code.  I'll include it in future distributions.

Step 1:	Write an appropriate conversion routine.  Look at any of the current
	conversion routines to see what sort of interface is required of the
	top-level conversion routine.  The routine must return a value of type
	ErrorCode.  You'll need to include "error.h", and take a look at 
	"error.c" for the strings that map to the codes.  If you want to issue
	any error messages, add a string for the name of your routine to the
	table 'names' in "error.c", and an entry (NOT the same as the function
	name - mine are all close, but not identical) in the 'FuncName'
	enumerated type in "error.h".  Make sure to add the string and the
	enumerated type value in the same position - the latter is used as an
	index to find the former.

Step 2: Decide on a short (3-8 letter) name for your new type.  Add this name
        to the enumerated type 'DataType' in "types.h".  Also, make a new
        #define statement for the new type.  Now, find the table 'FileTypeMap'
	in "cmdline.c".  Add a new entry to that table for the new type.

Step 3: Locate the table 'cvtFuncs' in "reformat.c".  This is a large matrix
	of function pointers.  Each entry (i, j) in the matrix is the actual
	name of the function used to convert from type i to type j.  A NULL
	entry means that no such routine exists.  Note that most of the
	entries are NULL, except those in the HDF column.  Add a new row to
	the table, making sure to place it such that its index cooresponds to
	the index of the new type (as defined in the enumerated type in 
	"types.h").  If your new type requires the PBM library, make an entry
	in the PBMTypeMap list.

Step 4: Now find the table 'writeFuncs' in "reformat.c".  Add an entry (the
	name of the routine) for the procedure that writes out data of your
	new format.  Even if you don't need to write out data in that format,
	you MUST have such a routine.  Look at some of the examples in the
	distribution for the interface.  This is a design drawback.  Make sure
	that the new entry is in the correct position - this table is also
	indexed by the enumerated type of file types.  Write a stub for the
	routine.  Add the name and a new entry in "error.h" and "error.c" (as
	explained above) for error reporting.

Step 5: Add the name of the file to the list of object files in the Makefile.
	Compile it and try it out.  The new type will be available as a
	command line option in reformat, and as a pickable type in xreformat.