\begindata{text,538938492}
\textdsversion{12}
\template{help}
\define{global
}
\define{footnote

attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}
\define{helptopic
}
\chapter{Image: an continuous tone digital picture inset

}
\section{What Image is

}\leftindent{
An image inset is capable of displaying color images -- images with 
multiple bits per sample.  The dataobject contains the actual image data 
while the view displays and provides an interface into the image 
manipulation functions.  The image inset should be used for the display of 
sampled (digitized) images.  The image inset lets you import foreign image 
format files, save them to an ATK datastream, to view the image on screen, 
and someday to manipulate the image contents at both the global level and 
the individual pixel level.  By using EZ to visit certain foreign image 
files (such as GIF), the foreign format data is imported and converted to 
ATK image format automatically, then displayed in the EZ window.  Once in 
ATK format, the image can be exported to several popular formats, including 
JPEG and Postscript.

}
\section{Starting Image

}\leftindent{
To start image type:


% \bold{ez filename.img}  


... or visit a foreign image file with EZ:


% \bold{ez filename.gif}

}
\section{Pop-up menu meanings

}\leftindent{
The image inset posts three different menu cards: \italic{Image}, 
\italic{Import}, and \italic{Export}.  


The \italic{image} menu card contains items relating to the viewing and 
saving of images:


\indent{\typewriter{Read} - Read an existing ATK image file into the 
current image view.  If the currently displayed image has been modified, 
you will first be queried on whether to save the modified file before 
reading in the new image data.


\typewriter{Write} - Write out the currently displayed image to a file in 
ATK datastream format.


\typewriter{Zoom In} - Increase the screen representation of the image by a 
factor of 2.  This operation does not affect the actual image data, only 
its appearance on screen.  There is a limit of 3 to the number of times 
that you can zoom in on an image, meaning that an image can be increased up 
to a factor of 8x its original size.


\typewriter{Zoom Out }- Reduce the screen representation of the image by a 
factor of one half.  This operation does not affect the actual image data, 
only its appearance on screen.  There is a limit of 3 to the number of 
times that you can zoom out on an image, meaning that an image can be 
shrunk down to a factor of 8x its original size.


\typewriter{Normal Size }- Return the screen representation of an image to 
its original dimensions.\typewriter{


Pan To Origin - }There are various tools for panning around an image: 
scroll bars, right-mouse button, and the panner object.  This operation 
returns the upper-left coordinate of the image to the upper-left corner of 
its available screen space.

\typewriter{
}\typewriter{Show True} - Lets you view an image with a private colormap in 
as real a manner as is possible given the underlying display hardware. 
 This can be useful when the shared default colormap is in such a state 
that the image cannot be reasonably portrayed.  When viewing an image with 
a private colormap, all other windows on the screen will probably render in 
false 
color\footnote{\
\begindata{fnote,538692616}
\textdsversion{12}
this is true of most display hardware that supports only a single installed 
colormap at any one time.  Other, high preformance display may allow more 
than one concurrently installed map\
\enddata{fnote,538692616}
\view{fnotev,538692616,4,0,0}}.


\typewriter{Show Fixed} - De-installs a private colormap that was installed 
with the Show True option.  


\typewriter{Set Save Quality }- Image data can be stored in either GIF or 
JPEG JFIF format file, encoded for mail-safe transport and surrounded with 
the normal ATK datastream keywords.  One of the nice features of JPEG is 
that it provides parameterization to the compression-quality tradeoff.  You 
can set the Quality level in the range from 5 to 95.  The higher the 
Quality level, the larger the resulting file and higher the fidelity of the 
saved image.  With low Quality settings, the image can be significantly 
compressed, resulting in shorter file transfer and decompression times.


}
The \italic{Import} menu card contains a list of foreign image formats that 
can be imported into the ATK image format:


\leftindent{\typewriter{\typewriter{Sunraster}} - Load a Sun raster image 
file.


\typewriter{GIF} - Load a 
GIF\footnote{\
\begindata{fnote,538692360}
\textdsversion{12}
\define{underline
menu:[Font~1,Underline~41]
attr:[Flags Underline Int Set]}
 \underline{G}raphics \underline{I}nterchange \underline{F}ormat (tm) \
\enddata{fnote,538692360}
\view{fnotev,538692360,5,0,0}}  image file.


\typewriter{\typewriter{Xbitmap}} - Load an X bitmap image file.


\typewriter{TIFF} - Load a 
TIFF\footnote{\
\begindata{fnote,538692104}
\textdsversion{12}
\define{underline
menu:[Font~1,Underline~41]
attr:[Flags Underline Int Set]}
 \underline{T}agged \underline{I}mage \underline{F}ile \underline{F}ormat\
\enddata{fnote,538692104}
\view{fnotev,538692104,6,0,0}}  file.


\typewriter{\typewriter{Xpixmap}} - Load an X Pixmap image file.


JPEG - Load a 
JPEG\footnote{\
\begindata{fnote,538691848}
\textdsversion{12}
\define{underline
menu:[Font~1,Underline~41]
attr:[Flags Underline Int Set]}
 \underline{J}oint \underline{P}hotographic \underline{E}xperts 
\underline{G}roup\
\enddata{fnote,538691848}
\view{fnotev,538691848,7,0,0}} image file.


PBM - Load a Portable Bitmap image file.


XWD - Load an X Window Dump image file.

}

The \italic{Export} menu card contains foreign image formats to which we 
can export from the ATK image format:


}\leftindent{\leftindent{GIF - Write the image as a GIF image file.


Postscript - Write the image as an Encapsulated Postscript file.


JPEG - Write the image as a JPEG file.


}}
\section{Including Images in documents

}
\indent{There are two ways to embed an image inset in a text document: (1) 
import a foreign image file (such as GIF or TIFF), or (2) insert an 
existing file that is in ATK image format.


To import an ATK image file into a document, simply choose the 
\italic{Insert File} menu item located on the \italic{File} menu card. 
 When prompted, enter the name of an ATK image file.   By convention, ATK 
image files should end in the suffix "img."


To import a foreign image file into a text document, simply type Esc-TAB 
and enter the string "image" when prompted.  What appears to be a picture 
frame will be displayed in the portion of the text beginning at the 
location of the text cursor.  Left-click the mouse in the picture area and 
the shadow on the frame will change from being on the right/bottom to being 
on the left/top, indicating that the image has the input focus.  At this 
time the image menus described above will be posted.  Now use one of the 
\italic{Import} menu items to load in the new image data from a file.

}

\section{Panning an Image

}
\leftindent{To pan an image, depress the right-mouse button and, while 
keeping it depressed, drag the mouse cursor to the desired target location. 
 There are two different panning styles supported by the image inset.  The 
first is a \italic{discreet} pan wherein the image view is not actually 
updated until the right mouse button is actually released at the target 
location.  While dragging the mouse in discreet pan mode, a set of 
crosshairs are displayed in reverse video that intersect at the current 
mouse location.  When the right mouse button is finally released, the image 
in rendered in the new location.


The second pan style supported is a \italic{continuous} pan wherein the 
image is updated on screen at close intervals such that it appears that the 
image is being dragged to its final destination.  


Both pan styles require that the right mouse button be depressed and 
dragged to a new location.  When the mouse button is released, the image is 
updated at this new location.


The default pan style is \bold{discreet} but \bold{continuous} panning can 
be enabled by adding this line to your preferences file:


}\typewriter{\leftindent{*.imagepanstyle: continuous}

}
\section{Printing an Image}


\leftindent{An image can be printed as per the usual ATK printing 
mechanisms -- choose the \italic{Print} menu item of the \italic{File} menu 
card.  


You can selectively print an image that is embedded in a text document by 
first converting the image to Postscript using the \italic{Export, 
Postscript} menu item.  First select the image in the document to be 
printed by clicking in its screen area to give it the input focus.  Then 
select the \italic{Export, Postscript} menu item and, when queried, type in 
the name of the file to contain the Postscript data.  This file can be 
shipped off to your local Laserwriter or other Postscript printer.

}
\section{Image Concepts


}\indent{In ATK terms, an image is a sequence of color samples in a 
two-dimensional space.  An image has a width, height and a type.  The type 
of an image can be one of BITMAP, GREYSCALE, RGB, or TRUE where each of 
these relates to how the color information is stored in the image data.  A 
BITMAP image is similar to the ATK raster format -- bits are packed 8 per 
byte; the size of each sample is 1 bit.  Bits that are enabled (1) 
represent a black pixel while bits that are off (0) represent a white 
pixel.  BITMAP images have no colormap.  GREYSCALE samples are 8 bits in 
length and index into a colormap where all allocated entries have equal 
red, green, and blue intensities.  RGB samples are also 8 bit quantities 
that index into a colormap.  TRUE images samples are 24 bits wide, with the 
first byte representing the red intensity, the second green, and the third 
blue.  In a TRUE image there is no colormap since the color information is 
located in the individual sample data.  The size of the colormap for each 
of the 8 bit/sample image types is variable.

}\section{
}
\section{Preferences

}
\indent{\bold{ImagePanStyle}: (discreet)

\indent{This preferences can be used to specify the pan style to be used 
when panning images.  By default, the discreet pan style is employed 
meaning that the image won't be updated on screen until the right mouse 
button is released.  The alternate pan style, continuous, updates the on 
screen image many times in quick succession making the image appear to be 
dragged across the screen.

}\leftindent{\bold{
}}\bold{ImageScrollClass: }(none)\italic{

}\leftindent{This preference can be used to specify an alternate "Class" to 
provide scrolling support.  There are three alternatives currently 
available:

\leftindent{The scrolling package provided in previous releases of ATK.  To 
use this alternative see the help file on \helptopic{oscroll}.

The "panner", a small box with a rectangle inside it which represents the 
screen. By dragging the screen around in the box, you change what is 
visible.  To use this alternative see the help file on \helptopic{panner}.

The "scpanner" package. This gives you both a scroll bar and a panner. 
Again, see the help file on \helptopic{panner}.

}}
\bold{ImageBorderSize}: 5

\indent{This preference specifies the size, in pixels, of the border that 
frames the image.  The border appears as a picture frame and is used to 
indicate the input focus.

}}

\section{Program Author}

\leftindent{
}\indent{Gary W. Keim (gk5g+@andrew.cmu.edu)

}
\section{Related tools}  


Select (highlight) one of the italicized names and choose "Show Help on 
Selected Word" from the pop-up menu to see the help file for:

\leftindent{\helptopic{
}}\leftindent{\helptopic{raster}

\helptopic{ppm2atkimage}

\helptopic{xwd2atkimage}

}\enddata{text,538938492}
