
                             - XIM -

    "Xim" is an X program that displays 8-bit and 24-bit images
on 8-bit color and monochrome monitors.  It makes viewing images of
various depths and sizes on a variety of displays fast and easy.
Additionally, various processing options are available for displaying
images as bitmaps.  This bitmap conversion is useful for making images
suitable for printing on conventional printers via "xdpr".  Color
dithering is used to bring 24-bit images down to 8.

The image files are in my particular (yet another) format.  Images are
straight forward pixmaps or color separations, which may either be
compressed (for those Unix systems with the the "compress" and "zcat"
commands) or runlength encoded.  The header on each file is 1024 bytes
in size and contains necessary information about formats, sizes,
authors, encoding flags, and the colormap pixmap(s).  Many pixmaps may
follow the header.  Images are in characters (no ints or shorts) so as
to be easily portable accross machines.

The program's interaction is loosely based on "xwud".  A right button
press exits the program.  The middle button displays the coordinates of
the mouse.  The left button advances to the next pixmap, if any.
A new colormap is created and installed only if there isn't enough room
in the default map.  Leave and Enter events seem to be sufficient to
process, although in some cases button presses events will trick the
program.  "Uwm" seems pretty good about not doing this.  The command
line options available are:

    -in <file>      The input file to display, otherwise stdin is used.
    -display <host> Display on alternate host.
    -cmap           Force the creation of a new colormap. (Color only)
                      This is faster and images with ncolors > 250 use
                      this anyway.
    -mono           Force monochrome bitmap translation. (Color only)
    -inverse        Display in reverse video. (Monochrome only)
    -mfs            Use modified floyd steinberg for half-toning. 
                      Default is -fs (regular floyd steinberg).
    -dither[=4]     Halftone using dithering and 8x8 matrix.
                      4x4 matrix is an extra option.
                    Note: -dither, -mfs and -fs are mutually exclusive
                      and work in monochrome Only.
    -enhance[=1-9]  Edge enhance images. Degrees 1 to 9 are available.
                    9 is the default, the maximum, and the fastest
                    enhancement value. (Monochrome only)
                    Note: This may have adverse effects on some non-
                        continuous (ie. dithered) color images. 
    -debug          Print debugging information.
    -runlen         Now almost obsolete, this flag is now in the header.

    Note: All the options can be abbreviated to their unique spelling.
     ex: % xim -in map200.Z -dit=4 -en -dis unix:0


This program works well on ibm rt, vaxstation and vax/gpx
machines and their various compilers.  If you are using release 2 or
greater, compile with "cc -O xim.c -lX11 -o xim".

This ImageHeader format can handle 8 or 24-bit images.  In the 24-bit
format, a number of channels (3 or 4) are specified. The rgb (& alpha)
buffers follow the header, respectively.  The colormap in the header is
not used.  The channels are kept seperate to make color separations
easier and compression more effective.
If the number of channels is 0 or 1, an image use only 8-bits
and the colormap is used for all of the following pixmaps.

Other images and code are available from m9-520-1.mit.edu (18.80.0.45).
They should all test some aspect of this program:
 traced -- a color and runlength encoded file.
 traced2.grey.Z -- a large image, enhances well but slowly.
 map200.Z -- doesn't use too many colors, enhances well.
 mandrill.Z -- a familiar image, uses few colors, doesn't enhance well
   	since color tones are dithered continuous (check it out with "xmag").
 sound_pics.Z -- has many pixmaps strung together in one file. (Sound
    propagation in a lecture hall, boring to most.)
 lenna8.Z -- Nicer than a mandrill to look at.
 lenna24.Z -- The same in 24-bit format, a big file.

Bugs and known short comings are:
- XPutImage still has bugs.  Expose events in color want to have 
    modulo 4 dimensions, which I seemed to have patched up here. Expose
    events of monochrome images displayed on color monitors may shift
    horizontally.
- Leaving and iconifing the window installs the default colormap, but
    not necessarily the map that was in use when the program was called.
- The cursor's colors are changed when it is necessary to display >254
    colors accurately. On the vax/gpx, only 254 colors are available in
    the colormap since the cursor keeps the last two.
- There aren't any 24-bit displays here and aren't supported yet.
- Mapped and UnMapped events should be looked for to make colormap
    switching more robust when iconifying.
- An entire image must be read in before being displayed. Not useful
    when an image is pipped in from another slow proccess program.
- Doesn't do any gamma or color display corrections.

Finally, images and tar files should certainly be ftp'd in binary mode.

I am open to and encourage any suggestions or improvements.  Please send
them to me so that I may incorporate them.  Please note what version you
are referring to. 

Enjoy!

Philip R. Thompson  (phils@athena.mit.edu)
Computer Resource Lab. (CRL) of the Department of
Architecture and Urban Planning at M.I.T..

