NCSA PC Show for the IBM PC, XT, AT, and PS/2 Version 1.0 January 1989 University of Illinois at Urbana- Champaign NCSA PC Show Version 1.0 program and documentation are in the public domain. Specifically, we give to the public domain all rights for future licensing of the program, all resale rights, and all publishing rights. We ask, but do not require, that the following message be included in all derived works: Portions developed at the National Center for Supercomputing Applications at the University of Illinois at Urbana-Champaign. User Feedback READ ME NOW If you want to see more software like NCSA PC Show, send us a letter, email or US mail, telling us what you are doing with NCSA PC Show. We need to know: 1) What science you are working onPan abstract of your work would be fine; and 2) How NCSA PC Show has helped you, for example, by increasing your productivity or allowing you to do things you could not do before. We encourage you to cite the use of NCSA PC Show, and any other NCSA software you have used, 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 NCSA HDF with you. NCSA Contacts Mail all manual suggestions to: Mail user feedback, software suggestions and bugs to: NCSA Documentation NCSA Software Development 152 Computing Applications Bldg 152 Computing Applications Bldg. 605 E. Springfield Ave. 605 E. Springfield Ave. Champaign, IL 61820 Champaign, IL 61820 The email addresses are: The email addresses are: pubs@ncsa.uiuc.edu bugs@ncsa.uiuc.edu pubs@ncsavmsa.bitnet bugs@ncsavmsa.bitnet Disclaimer THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESS OR IMPLIED, FOR THE SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION, WARRANTY OF MERCHANTIBILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE. Trademark Acknowledgments Enhanced Graphics Adapter, Video Graphics Adapter, IBM PC, PC/AT, Personal System/2, and PC-DOS are registered trademarks of International Business Machines Corporation. Revolution 512 is a trademark of Number Nine Computer. i NCSA PC Show Table of Contents i National Center for Supercomputing Applications January 1989 Table of Contents Introduction Overview vi About PC Show vi Special Features vi System Requirements vi Use of This Manual vi Chapter 1 Entering and Exiting NCSA PC Show Chapter Overview 1.1 Starting PC Show 1.1 Exiting PC Show 1.2 Chapter 2 Viewing Images with NCSA PC Show Chapter Overview 2.1 Displaying Multiple Images 2.1 Animations in PC Show 2.2 Chapter 3 Palettes and Palette Manipulations Chapter Overview 3.1 What is a Palette? 3.1 Palette Manipulation Command Keys 3.2 Tables and Figures Table 1.1 Command Line Parameters 1.2 Table 2.1 General Image Command Keys 2.2 Table 3.1 Manipulation Command Keys 3.2 Figure 2.1 General Help Screen 2.3 Figure 2.2 Image Help Screen 2.4 Figure 3.1 Palette Help Screen 3.4 i NCSA PC Show Introduction i National Center for Supercomputing Applications January 1989 Introduction Overview This introduction provides an overview of NCSA PC Show. The organization and use of this manual are described and notational conventions are explained. About PC Show NCSA PC Show Version 1.0 displays images with the Enhanced Graphics Adapter (EGA), the Video Graphics Adapter (VGA), or the Revolution 512 graphics card from Number Nine Computer (NO9). PC Show can display either binary raster images or images contained in HDF files. Special Features Special Features of PC Show include % display of multiple images in sequence, % display of HDF formatted files or binary raster files, % display with EGA, VGA, or NO9 video controllers, % manipulations of palette while image is displayed, % simultaneous storage of multiple palettes, and % animation of multiple image sequences. System Requirements In order to run NCSA PC Show, you need the following hardware: % IBM PC, PC/AT, or IBM PS/2 with one of the following graphics controller boards: Enhanced Graphics Adapter, Video Graphics Adapter, or Revolution 512 % 320K memory for PC Show PC-DOS or MS-DOS Version 2.0 or later must also be installed on the machine before PC Show is run. Use of This Manual .c3.Organization of This Manual This manual is organized into three chapters. Each page of each chapter is given a unique number that consists of the chapter number, a period, and the number of that individual page (beginning with the first page of the chapter). For example, page 2.3 is the third page of the second chapter. Each chapter is divided into sections, and some sections are divided into subsections. .c3.Manual Contents This manual is organized into the following chapters and appendices: Chapter One, "Entering and Exiting NCSA PC Show," provides a brief discussion of the commands used to begin PC Show, command line parameters which enable special display options, and methods of exiting the program. Chapter Two, "Viewing Images In NCSA PC Show," delineates the various commands which concern the display of animations or multiple images. The chapter contains tables which depict two of the online help screens featured by PC Show. Chapter Three, "Palettes and Palette Manipulations," describes both the characteristics of various palettes and the commands which permit the manipulation of palettes. .c3.Typographic Conventions in This Manual Commands shown in courier boldface type represent a user entry. Program lists and screen displays are presented in courier type. Explanations of software display often include a printed representation of the screen display. These displays are shown in courier type. Keynames are shown in capital, boldface letters when it is intended that you press them; for example, "Press ENTER to advance to the Palette Help Screen." In descriptions of the various features and commands, a word or phrase that is used for the first time may be shown in italics. A definition or explanation of the term follows. 1.1 NCSA PC Show Entering and Exiting NCSA PC Show 1.1 National Center for Supercomputing Applications January 1989 1.1 NCSA PC Show Entering and Exiting NCSA PC Show 1.1 National Center for Supercomputing Applications January 1989 Chapter 1 Entering and Exiting NCSA PC Show Chapter Overview Starting PC Show Examples of Starting PC Show Exiting PC Show Chapter Overview This chapter provides a brief discussion of the commands used to begin NCSA PC Show, command line parameters which enable special display options, and methods of exiting the program. Starting PC Show To simply display an HDF file on an EGA monitor, enter a command of the form: C:\ > pcshow filename Then press ENTER and the image(s) in the HDF file will appear on the monitor. To display a binary raster image, you must specify additional command line parameters. Table 1.1 lists the additional parameters and their functions. The command to display a binary raster image on the EGA monitor takes the following form: C:\ > pcshow -b xdim ydim -m palettefile filename where xdim and ydim are the dimensions of the image in pixels, palettename is the name of the palette you wish to have the image shown with, and filename is the name of the file containing the list of image files to be displayed. It is important to include the parameters when using binary files; otherwise, the screen will remain black and no image may be viewed. These commands are sufficient to run PC Show using an EGA monitor. Special display options become available when additional command line parameters are specified. Chapters 2 and 3 discuss these options. Table 1.1 below lists the optional parameters. Table 1.1 Command Line Parameters Parameter Type Function -v Hardware Specifies VGA video controller card. -e Hardware Specifies EGA video controller card (Default Value). -9 Hardware Specifies NO9 video controller card. Table 1.1 Command Line Parameters (continued) Parameter Type Function -b xdim ydim File Format Specifies a list of binary file images contained in the parameter. (All the binary files must have x and y dimensions identical to those given in this command line.) -m palettefile File Format Specifies the name of the palette file to be used with binary files. -h File Format Indicates that the images are stored in HDF format files. -c Screen Location Centers the image on the screen. -p xloc yloc Screen Location Labels an x, y coordinate on the screen for the upper-left hand corner of the image. -a Miscellaneous Specifies that the HDF file of the images or the binary files in the list are to be shown as an animation, one image after another until all the images have been displayed. -s Miscellaneous Specifies that the filename parameter for binary files is actually the filename of the image, rather than the name for a file containing a list of the image filenames. Examples of Starting PC Show Suppose you have a list of binary images of the dimensions 256 by 320 in a file named image.lst. In order to display the images using the palette test.pal and centering them on a VGA monitor screen, you would enter the command: C:\ > pcshow -b 256 320 -v -c -m test.pal image.lst In order to display only a single binary file, you need to use the -s parameter. For example, if you wish to display on a NO9 monitor a single binary file named image.pic of the dimensions 320 by 512 with the palette test.pal, you would enter: C:\ > pcshow -s -9 -m test.pal -b 320 512 image.pic If an animation is to be depicted, then the filename parameter must be a file containing the image names or an HDF file. Also, all the images to be animated must be of the same dimensions; otherwise, they will be distorted upon display. To display an animation of a binary sequence of images contained in the file named image.lst, you would enter: C:\ > pcshow -a -v -m pic.pal -b 320 320 image.lst Exiting PC Show To exit the program, type q while the image is displayed on the screen. The program displays the next image in the HDF file or the next image on the list of binary images. If the current image is the last or only image, the program returns to DOS. If you type q after viewing the final image and are not returned to DOS, press CONTROL-C to exit the program. If CONTROL-C does not exit the program, re-boot the computer. Please use the Bugs and Suggestions report form at the back of this manual to report any problems to NCSA, in order that they may be remedied in future releases of NCSA PC Show. 2.1 NCSA PC Show Viewing Images with NCSA PC Show 2.1 National Center for Supercomputing Applications January 1989 2.1 NCSA PC Show Viewing Images with NCSA PC Show 2.1 National Center for Supercomputing Applications January 1989 Chapter 2 Viewing Images with NCSA PC Show Chapter Overview Displaying Multiple Images Animations in PC Show General Image Commands Online Help Screens Scrolling Through the Image Chapter Overview This chapter delineates the various commands which concern the display of animations or multiple images. The chapter contains tables which depict two of the online help screens featured by PC ShowPthe General Help Screen and the Image Help Screen. Displaying Mutiple Images The multiple image function of PC Show assumes that the images reside either as multiple images inside an HDF file or as members of a list in a file of image names of a binary file. For example, to display on a NO9 monitor the HDF file images.hdf, which contains multiple images, enter: C:\ > pcshow -9 images.hdf Notice that the command line to display multiple images from an HDF file does not differ from the command line to display a single image from an HDF file. This is one advantage of storing your images in HDF files. To display on an EGA monitor multiple images from a binary file named images.1st of the dimensions 256 by 320 with the palette test.pal, enter: C:\ > pcshow -b 256 320 -m test.pal images.1st when the file images.1st is a list of the binary images to be displayed, one image name per line. Such an image listing file should resemble the list below: myimage1.256 myimage2.256 testimage.256 lastimage.256 You may wish to make the extension of your image file the width of the image, as the example above demonstrates, to prompt your memory. The first image in the file is automatically displayed after entering the command to execute PC Show. After the first image is viewed, it is possible to modify the palette or the image using the commands listed on the help screens. To quit viewing the current image and view the next image in the file, type q. This will cause PC Show to advance automatically to the next image. In this manner, all the images in the file may be viewed once. To repeat viewing of any image re-execute PC Show. Animations in PC Show The following sections present the various animation and manipulation command keys in PC Show and describe their functions. General Image Commands Table 2.1 lists general commands that deal with the image itself. They do not concern the actual location of the image on the screen. Table 2.1 General Image Command Keys Command Key Function i Displays information concerning the current image or animation being displayed. The information shown includes: the current x and y coordinates of the upper-left corner of the image, the x and y dimensions of the image, and indicates that the image is part of an animation and the mouse is activated, if such is the case. a Runs the animation sequence again. If the current image is not part of an animation sequence, the command is invalid, and will have no effect. k Causes PC Show to treat the current image as merely a single image and to eliminate further animation. If the current image is not part of an animation sequence, the command is invalid. o Toggles the VGA screen off and on. Does not affect other types of monitors. NOTE: Turning the VGA screen on or off affects neither the actual operations of the software, nor the retention of information concerning the image or its display upon the screen. q Displays the next image in the HDF file, or the next image in the list of binary file names. In either case, if the current image is the last, the program returns to DOS. m Activates or deactivates the mouse if one is present. / Slows down animation. * Speeds up animation. Table 2.1 General Image Command Keys (Continued ) Command Key Function , Asks for the upper-left and right hand corner (comma) coordinates and magnifies the image to fill the screen. Online Help Screens Three online help screens are available during program executionPthe General Help Screen, the Palette Help Screen, and the Image Help Screen. To view the General Help Screen, press ? while the image is displayed on the monitor. When you press ?, PC Show enters the sequence of help screens. To advance through the help screens, press ENTER; pressing any other key returns to the image display. For easy reference, the General Help Screen is presented in Figure 2.1. Figure 2.1 General Help Screen i Shows Information About The Image a Shows Animation Again k Ends Animation Mode o Toggles VGA Screen Off Or On q Exits Viewing Image Or Animation ? Shows This Help Sequence m Activates/Deactivates Mouse / Slows Down Animation Speed * Speeds Up Animation Speed , Asks For Upper Left Hand Corner And Lower Right Hand Corner Coordinates Of An Area On The Screen To Magnify To Fill The Screen. PC Show does not accept commands that are entered while you are viewing the help screen. Help screen commands are valid only while you are viewing the image. To continue viewing the image, press any key but ENTER. If you press ENTER, PC Show advances to the Palette Help Screen. Scrolling Through the Image Due to the limited size of video monitors, often only portion of an image is displayed on the screen. To allow viewing of an entire image, scrolling functions are available. Figure 2.2 lists the scrolling functions as they are listed in the Image Help Screen. Figure 2.2 Image Help Screen left arrow Moves Image Left Ten Pixels up arrow Moves Image Up Ten Pixels down arrow Moves Image Down Ten Pixels right arrow Moves Image Right Ten Pixels page up Pages Up A Full Screen On The Image page down Pages Down A Full Screen On The Image home Moves To The Upper Left Hand Corner Of Image end Moves To The Lower Right Hand Corner Of Image x Inputs X And Y Coordinates For Upper Left Hand Corner This help screen is only accessible by entering the command ? and pressing ENTER twice to pass both the General Help Screen and the Palette Help Screen. 3.1 NCSA PC Show Palettes and Palette Manipulations 3.1 National Center for Supercomputing Applications January 1989 3.1 NCSA PC Show Palettes and Palette Manipulations 3.1 National Center for Supercomputing Applications January 1989 Chapter 3 Palettes and Palette Manipulations Chapter Overview What is a Palette? Palette Manipulation Command Keys Chapter Overview This chapter describes the characteristics of various palettes and the commands which permit manipulation of palettes. The online Palette Help Screen is also depicted for easy reference. What is a Palette? A palette is a group of data used by the computer to determine how the data in the image file is to be mapped to the set of available colors. The palette is arranged in memory as three separate arrays, each of 256 bytes of character data. Each of the arrays represents one of the color components of the palettePred, green, or blue. Entries in each component array range from 0 to 255. The smaller values correspond to lighter shades and larger values correspond to darker shades. The color displayed on the video screen is a combination of red, green, and blue shades from individual component arrays indexed by the value of the data from the image file. The Revolution 512 board by Number Nine Computers provides a full 256 shades of red, green, and blue for each of the 256 entries in the palette. The VGA board by IBM provides only 64 shades of red, green, and blue for each of the 256 entries in the palette. The EGA board provides the same 64 shades of red, green, and blue, but the palette is limited to only 16 entries. Because the EGA palette is limited to only 16 colors, and most image information has 256 colors, an algorithm is required to convert between the two. This method uses a frequency count to find the colors occurring most often in the image data, and assigns their values to the first 16 entries in the palette. In this fashion, the image is displayed in only the 16 most popular colors contained in the data. Many of the PC Show command keys intended to modify the palette will not work properly for an image which is displayed on an EGA monitor. If the command fails, pressing the command key will not affect the palette. The command keys that modify the palette are presented in the following section. The palette is arranged in memory as three separate arrays of 256 bytes of character data corresponding to each color component. These arrays are modified in various ways by the palette manipulation command keys. NOTE: Unless otherwise noted, it is assumed that succeeding command keys will modify all components of the palette in the same manner. Palette Manipulation Command Keys Table 3.1 lists the command keys that manipulate the palette. Table 3.1 Manipulation Command Key Function Command Keys f Rotates the palette. The second entry replaces the first, the first entry replaces the zeroth, the zeroth the 255th, and so forth, until all the entries are moved down one increment. This continues until the SPACE BAR is pressed. You may control the speed of the rotation using the + and - command keys. b Performs the same function as the f command key, except that it rotates the palette in the opposite direction. The speed of the rotation may be controlled using the + and - keys. + Increases the speed of the rotation of the palette when the continuous rotation commands are operating. - Decreases the speed of the rotation of the palette when the continuous rotation commands are operating. space bar Stops the rotation of the palette only when the continuous rotation commands are operating. Also stops animations in mid- sequence. e Rotates the palette forward one increment. v Rotates the palette backward one increment. r Resets the current palette to the default values defined when it was read in. This command will affect all palette manipulations which have been performed. You may make the current palette the default palette by pressing the command key d. Table 3.1 Manipulation Command Key Function Command Keys (Continued) c Toggles the color bar on or off. Displays the current palette in the lower-left hand corner of the screen. The palette is represented as a color bar of continuous values from 0 to 255 from left to ight.This is useful for observing the effects of various palette manipulations and does not change the image underneath the palette. l Reads a new palette from the disk. If an HDF file is in use, then another palette is read from that file. If binary files are being used, then a palette file name is requested. n Advances the current palette to the next palette stored in memory. If the current palette is the last one in memory, this command advances to the first palette in memory. s Stores the current palette in the HDF file if one is in use, or requests a file name for the current palette. The convention for assigning names to a palette is to append the palette name with .pal. u Exchanges the red, green, and blue components of the current palette in the following fashion: the red component is replaced by the green component, the green component is replaced by the blue component, and the blue component is replaced by the red component. t Exchanges the entries in the palette end for end.That is, the last entry is exchanged with the first, the next to last is exchanged with the second, and so on through the palette. g Takes the binary value for each of the components and inverts it bit by bit; thus, a dark red becomes a light red and black becomes white. Table 3.1 Manipulations Command Key Function Command Keys (Continued) h Invokes the fiddle mode. In this mode, you can use the arrow keys modify the palette in the following way: up or down movement compresses or expands the palette, and left or right movement shifts the palette left or right. To view the help screen that lists the fiddle command keys, press ?. The fiddle mode command is not available for EGA graphics mode. d Replaces the default palette in memory with the current palette. You should store the modified palette before loading or switching palettes in order to prevent loss of the modifications made. p Moves the color bar on the screen. Prompts you to enter the upper-left hand corner coordinates of the color bar. For easy reference, the Palette Help Screen which displays the commands associated with manipulating the palette is shown in Figure 3.1. You can only access this help screen by entering the command ? and pressing ENTER to pass by the General Help Screen. To return to the image, press any key but ENTER. Pressing ENTER advances to the Image Help Screen. Figure 3.1 Palette Help Screen f Rotates Palette Continuously Forward b Rotates Palette Continuously Backward + Speeds Up Palette Rotation - Slows Down Palette Rotation space bar Stops Palette Rotation e Rotates Palette Once Forward v Rotates Palette Backward r Resets Palette To Initial Settings c Toggles Color Bar On Or Off The Screen l Loads In A New Palette n Shows Next Palette In Memory s Stores Current Palette On Disk v Swaps Red, Green, And Blue Components Of Palette t Transposes Palette g Inverts Palette Bitwise h Enters Fiddle Mode d Makes Current Palette The Default Palette p Moves Position Of The Color Bar BUGS AND SUGGESTIONS Please notify us of any bugs you have found in our software and any suggestions you have for future releases or products. Using the report form below, mail user feedback, software suggestions, or bugs to: NCSA Software Development 152 Computing Applications Bldg. 605 E. Springfield Ave. Champaign, IL 61820 Send reports regarding bugs via electronic mail to: bugs@ncsa.uiuc.edu bugs@ncsavmsa.bitnet Send reports regarding software suggestions or comments via electronic mail to: softdev@ncsa.uiuc.edu REPORT FORM Name: Institution: Address (Electronic) Address (U.S. Mail) Telephone: ( ) P Version of NCSA PC Show: Type machine: Version of system software: Suggestion or description of problem: