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 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 or 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 causes that action to be taken. Dialog boxes with actions contain command buttons that activate the action just as pressing 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 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