GRIPS 2: Government Rast…rocessing Software & Data/GRIPS_2.cdr/dos/pcshow/doc/pcshow.doc

Text File | 1990-01-06 | 27KB | 1,107 lines

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:

[e-mail]    [e-mail]
[e-mail]    [e-mail]


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:

[e-mail]
[e-mail]

Send reports regarding software suggestions
or comments via electronic mail to:

[e-mail]


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: