This is the help file for NCSA Reformat. Please send questions or bug reports
to:
Peter Webb
National Center for Supercomputing Applications
pwebb@ncsa.uiuc.edu
About this Help Document:
This is the online help for NCSA Reformat. The text may be scrolled by
positioning the mouse within the shaded scrollbar to the left and clicking the
left (go forward) and right (go backward) mouse buttons.
To search for a particular word or phrase, type the text into the dialog
box labeled "Search For:". The direction in which to search is indicated
by the highlighted box in the center of this help screen. Pressing <Enter>
while the mouse pointer is within the dialog box starts the search.
Alternatively, press the "Search" button. Text may be entered into the the
search box by selecting it with the mouse (two or more fast clicks of the
left button while the mouse is on the word or phrase), moving the pointer into
the dialog box and clicking the middle button. The selected text will be
inserted into the text field.
Table of Contents:
About NCSA Reformat
Using NCSA Reformat
The User Interface
The Athena Widget Set
Pointer
Mouse Click
Selecting Text
Command Buttons
Scrollbars
Dialog Boxes
The NCSA Reformat X Interface
The Message Window
The Dialog Boxes
The List of Files
The List of Types
The Command Buttons
Configuring Reformat
Converting Files
Error Messages
Warnings
Errors
About NCSA
About NCSA Reformat:
This utility provides a mechanism by which images can be transformed from
one storage format to another. It was initially developed to facilitate the
conversion of TIFF, FITS and GIF files to HDF files, so the conversion
routines are much the same as those used in the NCSA MacIntosh tool,
Import2HDF.
The graphical user interface requires X version 11, release 4 and the
Athena Widget set. It has been tested with release 2 and higher servers.
There is also a command line interface that does not require X.
Using NCSA Reformat:
This section of the document first describes the user interface conventions
of the Athena Widget Set, then continues with a discussion of the specifics of
actual interface itself, and an example of a complete file conversion. The
section concludes with a list of error messages and an explaination of what
each error means.
The User Interface:
The user interface is self-evident. OK, that's a joke. However, every
effort has been made to design an interface that is consistient and
straight-forward. Please send any comments you might have on this subject to
the author.
The Athena Widget Set:
The Athena Widget Set provides support for several common interface
paradigms. For those unfamiliar with the widget set, a description of those
employed in this program follows.
Pointer:
The mouse cursor.
Mouse Click:
Press and release the mouse button.
Selecting Text:
In a text field, two fast clicks selects (highlights) the word beneath the
pointer and three selects the entire line. Press and hold the left mouse
button while moving the mouse to select parts of words or lines.
Command buttons:
Rectangular or oval areas containing text, these buttons highlight their
borders when the pointer moves onto the button. Pressing the left mouse
button while the pointer is in the command button causes the entire button
to highlight and the action associated with the button to be performed.
Scrollbars:
Two thin parallel lines enclosing a shaded rectangle, a scroll bar may appear
in a vertical or horizontal orientation. The shaded rectangle is called a
"thumb" and reflects the percentage of the entire text currently displayed in
the visible part of the window. When the pointer moves into the scrollbar, the
cursor changes to a double-headed arrow with an orientation cooresponding to
that of the scrollbar. A single click of the left button scrolls the window
left or up, depending on the orientation. Likewise, a single click of the
right button scrolls the window right or down. The amount by which the text
scrolls is determined by the distance between the pointer and the left or top
edge of the scrollbar - the further away, the larger the amount of text
scrolled. The middle button may be used to "grab" the thumb. While the middle
button is held down, the thumb can be dragged by moving the mouse, and the
window will scroll correspondingly. Clicking the middle button "jumps" the
thumb to the postion of the cursor.
Dialog boxes:
A dialog box typically consists of a label and a value field. Some dialog
boxes may also contain command buttons. The value field of a dialog box
accepts text input from the user. Position the pointer within the dialog box
and type - the text will appear in the value field. Aside from the <Delete> or
<BackSpace> keyes, which work normally, there are several additional editing
features available to make text entry easier. The text entry cursor is a
small black triangle - text always appears to its left.
Ctrl-K: Kill all of the text between the cursor and the end of the line.
Ctrl-D: Delete the current character (to the right of the cursor).
Right-Arrow: Move the text input cursor to the right.
Left-Arrow: Move the text input cursor to the left.
The mouse cursor can also be used to position the text input cursor. Place
the pointer at the desired location and click the left mouse button. The
text input cursor will move to the position indicated by the pointer. If the
text grows too large for the value field, the text will scroll. The right and
left arrow buttons scroll the text when they are pressed at either end of the
value field.
When a dialog box has an associated action (for example, the search dialog box
on the help screen), pressing <Enter> causes that action to be taken. Dialog
boxes with actions contain command buttons that activate the action just as
pressing <Enter> does.
The NCSA Reformat X Interface:
The default layout of Reformat consists of a message window, dialog boxes
indicating the input and output file and directory name, a scrollable list of
the files in the current input directory, a scrollable list of input file types
and three command buttons. Occassionally, when an operation might have
unexpected side-effects, a confirmation dialog box appears.
The Message Window:
Located at the top of the application layout is the message window. Error,
warning and informational messages appear in this window as appropriate. See
the end of this docuemnt for a description of the error messages. Typing into
the message window has no effect. Often, the messages are too wide to fit into
the window. When this occurs, a horizontal scrollbar appears along the bottom
of the window - this may be used to view the rest of the text.
The Dialog boxes:
There are five dialog boxes in this version of Reformat. The entries in
each may be modified as described in "Dialog Boxes," above. Three of them,
however, deserve special mention. The Input Directory dialog box controls
which files are displayed in the list of of input files (located just below
the input directory box). Typing a new directory name (or adding or subtracting
from the current one) in the box and then pressing <Enter> causes the list of
files to be updated to reflect the new directory. Furthermore, the input file
dialog box is cleared, as a visual warning that the directory has been changed.
The output file remains unchanged, even when the output directory is modified.
Note that the output file dialog box is larger than the others, and contains
an extra entry, 'Compress?'. The Yes/No toggle to the right of this entry
indicates whether or not the HDF file will be compressed (using run-length
encoding) when it is written.
There is another dialog box which should be explained. It is not always
present on the screen, but rather comes and goes as necessary.
By definition, raw files are just raster data. The dimensions of the image
are not stored in the file. However, the dimensions are required in order that
the conversion process proceed without error. Therefore, whenever the raw
data type is selected as the input file type, a dialog box containing fields
for the image height and width will appear. It disappears as soon as another
input type is selected.
The List of Files:
This is a list of all of the visible files in the current directory. By
default, the list does not contain any files which begin with a period.
To help distinguish between directories, symbolic links, executable files and
plain files, a single character is appended to each file name. Directories are
indicated by a '/', symbolic links by a '@', executable files by a '*' and
plain files by a ' '. This will be familiar to those accustomed to the output
from the Unix 'ls -F' command. Some data files will seem to be executables, if
their access permissions indicate they are executable. (If that didn't make
sense, don't worry - just because you see a '*' on the end of a data file name
doesn't mean that the data file is actually executable, or that the data is
somehow corrupt.)
The list may be scrolled both vertically and horizontally. To select an
input file from this list, position the pointer over the file in question and
press and release the left mouse button. The filename will highlight briefly,
and the text field of the input file dialog box will be changed to reflect the
new choice. Choosing a directory instead of a file causes the input directory
to change to that directory.
Though it was stated above that files begining with a '.' do not appear in
this list of files, one special file, "../" always appears at the head of
the list. Note that the '/' at the end of the name indicates that this file
is a directory. In fact, it is the accepted Unix notation for the "parent"
directory, that directory directly above the current one. This file is
included to facilitate navigation of the filesystem tree. Selecting it causes
the input directory to change to the parent of the current directory.
Currently, when the input directory changes, the position of the scrollbars
does not reset. This means that no files may be visible initially. Scroll
to the top of the list to see the current files.
The List of Types:
Directly below the list of the files in the current directory is a list of
input file types. Select the correct type by positioning the pointer over the
type name and clicking the left mouse button. The text will remain highlighted
until a new type is selected. The list is currently fairly small, but may
increase in the future.
The Command Buttons:
The three command buttons are located to in the right column of the layout,
underneath the dialog box labeled "Output File:." They operate as described
in "Command Buttons" above. The "Convert" button performs the actual file
conversion, the "Help" button brings up this help screen and the "Quit"
button terminates the application.
Configuring NCSA Reformat:
Reformat understands all of the standard X command line switches. There
are too many of these to reproduce them here, and they are well-documented
in the X distribution. However, there are several command line (or
Xdefaults database) options that are unique to Reformat.
Switch: Description:
-inputdir Sets the input directory. (Default: current directory)
-outputdir Sets the output directory. (Default: current directory)
-noGUI Don't bring up the X graphical user interface. Allows use
of the command line interface.
Converting Files:
Before any actual conversion can take place, 5 pieces of information must
be specified: the input directory, the input file name, the input file type,
the output directory and the output file name. The input and output
directories default to the current directory and the output file name defaults
to 'file.hdf'. There is no default for the input file or type.
Select an input file and type as described above, and click on the button
labelled "Convert." The button will highlight, and remain highlighted until
the conversion routine finishes. Any appropriate warnings or informational
messages will appear in the message window. If the input file is large,
conversion can take quite some time, so please be patient.
Error Messages:
In general, messages are divided into three classes: informational, warnings
and errors. Those in the first class appear to confirm that an operation has
completed as requested. Warnings indicate that the operation may have failed
partially because of a condition beyond the application's control (file
permissions set incorrectly, bad data in input file, etc.). Errors usually
indicate that there is a bug in the program, and the application should be
terminated. Please report these to NCSA.
These listings are in alphabetical order.
Warnings:
Text: Description/Meaning/Remedy:
Bad color specified in data The data file contains a color specification
file. that the program cannot interpret. Try another
data file.
Background color equal to The foreground and the background were set to
foreground color (using black the same color. The background will be set to
and white). white, the foreground to black.
Can't allocate requested There is no more space in the color table. Try
color. quitting from another application.
Can't find application The file /usr/lib/X/app-defaults/Reformat
resource database file. does not exist. Try re-installing it. See
the README and the Makefile for more
information on this.
Can't open input file. Check The input file could not be read. It does not
name and protection. exist or is does not grant read permission.
Can't open output file. Check The output file could not be written. Perhaps
name and protection. the current directory is unwriteable, or the
file system is full.
Conversion operation failed. For some reason (about which the program cannot
be more specific) the conversion operation
has failed. Make sure the file actually
contains an image.
Couldn't find default font in The user did not specify a font, and there is
merged resource database. no specification in the .Xdefaults file.
Specify one on the command line or add one to
the .Xdefaults file.
Couldn't find default geometry A geometry string was not specified on the
in merged resource database. command line or in the .Xdefaults file.
Specify one.
Couldn't open specified file. A file could not be opened. Perhaps the
permissions are wrong or the filesystem is
full.
Data in the file does not match The conversion routines can sometimes tell when
the specified file type. a data file is not of the correct type.
Specify one that is, or change the type.
File already exists. Overwrite A file with the same name as the output file
permission denied. No action already exists. The user refused to allow
taken. the program to overwrite the file. As a
result, no conversion took place.
File does not contain a A conversion routine was expecting to find a
palette. palette in the input file, but didn't. Check
the input file.
File system error. Check file There was a problem with a file. Check to be
name and protections. sure that the input file is readable, and that
the output directory can be written to.
Image is too complex. Too HDF supports a palette of 256 colors for 8-bit
many color planes. images. This image contains more than 256
colors.
Input file correct type, but There may exist multiple, non-compatible
wrong version. versions of a given file format. In that case
the conversion routines can recognize the file,
but cannot interpret the data.
Input file name doesn't make The input file name is nonsensical. Check for
sense. (Possibly NULL?) extra spaces or special characters.
Input file type not specified. The user did not indicate what type of data is
stored in the input file. Click on one of the
types in the input file type list.
Invalid background color. The color specified for the background does not
exist on this X server.
Invalid foreground color. The color specified for the foreground does not
exist on this X server.
Invalid background color. The color specified for the background does not
exist on this X server.
Output file is corrupted! Somehow, bad data was written to the output
Please report this to NCSA. file. Please send email about this.
Output file name doesn't make The output file name is nonsensical. Check for
sense. (Possibly NULL?) extra spaces or special characters.
Output file type not specified. The user did not indicate what type of data is
to be stored in the output file. Click on one
of the types in the output file type list.
That action/use is not yet a Some actions that the user interface might
supported feature. imply are possible have not yet been
implemented. For example, all file types can
not be converted to all other types.
The dimensions of the image One or both of the dimensions of the image
specify an area of zero size. is zero. The data file is likely corrupted.
Try it with other utilities that understand
that file type.
There is no colormap in the The input file does not contain any information
input file. relating the pixel data to actual colors. In
this case, Reformat generates a default
gray-scale palette.
The input file appears to be The file is the correct type and version (as
corrupted. far as can be determined) but the data does not
make sense. Check the file with other
utilities or applications that understand that
file type.
Too many colors. The image requires more colors than can fit
into an HDF palette.
Unable to determine file type. The conversion routines have a limited set of
rules which are used to "guess" the type of the
input files. This message appears when that
type cannot be determined, and the user has not
specified a type.
Unrecognized command line One or more of the options specified on the
option. command line is ill-formed. Check the command
line again, and examine the documentation.
Errors:
Internal error. This never This is an indication of a bug in the program.
happens. (Please report this Please let us know about this.
error to NCSA).
Input in incorrect format The parameters passed to a routine were not
what the routine was expecting. Again, an
indication of a bug.
No more dynamic memory. NCSA Reformat has consumed all of the memory
available, yet wants more. Could be a bug,
but maybe the swap space on the machine should
be increased.
Null pointer unexpected. A null pointer was encountered where none was
expected. If there are no memory problems,
this definitely indicates a bug.
This machine is not powerful There is not enough memory or support hardware
enough to run this program. for Reformat to function properly. Try running
it on a more powerful machine.
About NCSA:
The National Center for Supercomputing Applications (NCSA) is a publicly
funded research facility on the Urbana/Champaign campus of the University of
Illinois. Our mission (and we do choose to accept it) is to increase the
productivity of scientists and others using supercomputers.
If you want to see more software like this, you need to send us a letter,
email or US mail, telling us how you are using our software. We need to know:
(1) What science you are working on - an abstract of your work would be fine;
and (2) How NCSA software has helped you, for example by increasing your
productivity or allowing you to do things that you could not do before.
We encourage you to cite NCSA software in your publications. A bibliography of
your work would be extremely helpful.
NOTE: This is a new kind of shareware. You share your science and successes
with us, and we can get more resources to share more software like this with
you.
Contacts:
Feedback, bugs, and software or documentation suggestions (US Mail):
NCSA Software Tools Group
152 Computing Applications Bldg.
605 E. Springfield Ave.
Champaign, IL 61820
Bugs/Suggestions:
bugs@nsca.uiuc.edu
bugs@ncsavma.bitnet
All other Communications:
softdev@ncsa.uiuc.edu
softdev@ncsavma.bitnet