\documentstyle[11pt,epsf]{report}
\addtolength{\oddsidemargin}{-.875in}
\addtolength{\evensidemargin}{-.875in}
\addtolength{\textwidth}{1.75in}
\setlength{\topmargin}{-.75in}
\setlength{\textheight}{8.75in}
\title{\begin{center}
\hspace*{1mm}%\special{psfile=funky-owl.PS hoffset=-100}\hspace*{1mm}
\vspace{2cm}
\epsfbox{/afs/sipb/project/doc/ibitmap/ibitart.ps}
\end{center}
\bf{Inessential Bitmaps (XBM format)}}

\author{The Student Information Processing Board\\\\Eri Izawa}
\date{March 7, 1994}

\def\thesection {\arabic{section}}
\def\thesubsection {\thesection.\arabic{subsection}}
\def\thesubsubsection {\thesubsection .\arabic{subsubsection}}

\begin{document}

\maketitle

\begin{center}
\hspace*{1mm}
\vspace{2cm}
\epsfbox{/afs/sipb/project/doc/ibitmap/drae.ps}

\end{center}

%setenv TEXINPUTS /afs/sipb.mit.edu/project/sipb/lib/tex/macros:

\section{Introduction: What are Bitmaps?}

Welcome to bitmapping!  If you have ever wanted to draw or design your
own screen backgrounds, draw up your own xscreensaver pattern, make
artwork for your World Wide Web homepage, or just plain try out your
artistic urges on Athena, bitmaps may well be just what you wanted.
This guide details how to create and display XBM format bitmaps, which
are black and white and easily displayable on your background screen
or on the WWW.

A bitmap is basically a map of bits (surprise, surprise) --- but when
taken altogether and viewed through bitmap programs, the patterns of
bits form a picture.  Sometimes the pictures can be pretty impressive.
If you have had any experience with painting programs (such as Mac
Paint, Super Paint, or such), then you will find the format
reassuringly similar.

One note about large bitmaps: they take up a lot of space in your
account.  It's a good idea to keep your large bitmaps compressed (type
\verb+compress <filename>+ to compress, \verb+uncompress <filename>+ 
to uncompress) to save space when you aren't working on them.
Luckily, there are many ways to view even compressed bitmap files.

\section{Making Bitmaps}

Making xbm-format bitmaps is just like making your common
paint-program generated picture.  If you've never used a paint program
before, don't worry; it only takes a minute to learn --- although, as
with any art, the more you practice, the more you can do with it.

\subsection{Where the Programs Live}

Many different bitmap programs exist here and there.  I suggest the
following:

\begin{verbatim}
% attach x11r5
% /mit/x11r5/$bindir/bitmap
\end{verbatim}

(The \verb+afs+ path is: \verb+/afs/athena/astaff/project/x11r5/$bindir/bitmap+.)

Note that this program for some reason is not capable of loading large
(about 300 by 300 and larger) bitmaps, though it is perfectly usable
for making them.  Hopefully this bug will be corrected soon.  Another
bug it seems to have is that enlarging the edit window {\it after} a
bitmap is loaded may cause the program to become unusable.  To avoid
this, start up the program, enlarge it, and then load your bitmap.
Aside from these bugs, however, it is a generally good program.

Another all around good program is xpaint.  First \verb+attach
graphics+, and then do:

\begin{verbatim}
% /mit/graphics/$bindir/xpaint
\end{verbatim}

(The \verb+afs+ path is: \verb+/afs/athena/contrib/graphics/bin/$bindir/xpaint+)

This is a color painting program; however, since bitmaps do not store
color information, the colors are meaningless and you should stick to
black and white.  The program is slightly flaky.  However, it has such
useful features as Zoom, although in a different format than standard
bitmap programs (you need to go to the Image menu and select the
Change Zoom feature, and from there type in something like `2' or `3'
instead of `1'; then use the scroll bars to move around).  Xpaint is
also useful for converting bitmaps to other formats --- but this will
be discussed later.

Do not confuse xpaint with dxpaint, a Decstation-only bitmap-making
program that seems to have at least one major bug.

%Another one, which unfortunately runs only on no-longer existent
%Vaxes, is:
%
%\begin{verbatim}
%% /mit/graphics/bitmap/bitmap
%\end{verbatim}
%
%The following may or may not exist in usable form (people are working
%on it).  It is a version of the above program, and will hopefully run
%on RS6000s:
%
%\begin{verbatim}
%% /mit/graphics/rsaixbin/bitmap
%\end{verbatim}
%
%Ignore the error messages it spews all over your screen (it spews a
%lot).  If, by some chance, after running this program you discover
%that any new emacs windows you start up come out looking very strange,
%you can fix this problem by doing \verb+xrdb -load .Xresources+.
%
%There may soon be another program available for Decstations as well.
%If it does exist, it will be:
%
%\begin{verbatim}
%% /mit/graphics/decmipsbin/bitmap
%\end{verbatim}
%

Another program that creates bitmap is in sipb.  \verb+add sipb+, and
then type \verb+xfig &+ to start the program.  It is {\it not} a
standard bitmap editor (it is a drawing program, not a paint program)
--- in fact, it can not edit bitmap files.  It can, however, save its
drawings in bitmap format (choose option
\verb+Export+, and from there choose, as your format, \verb+x11
bitmap+).

I do not recommend the default bitmap program in
\verb+/usr/athena/bin/bitmap+, though you may have to if none of the 
above work.  It lacks several important features, like Zoom and Undo,
but it tends to work on most machines, and should be fine for small
bitmaps.

\subsection{Using the program}

The basic idea with most paint and bitmap programs is pretty obvious
--- point at the square you want colored in and click there.  Most
programs are also self-obvious when it comes to their various
features.  Play around and experiment if you're not sure what
something does.  Don't forget to save your bitmap in your home
directory.  Some people end the bitmap names with \verb+.xbm+, but
this is not necessary.

Some techniques you might want to try:

\begin{description}

\item{FLOOD FILL:} This is wonderful for turning areas white or
black (usually the left mouse key for black, the right mouse key for
white).  Be very careful with FLOOD FILL, lest you wind up with a
completely black bitmap by accident; make sure areas you want to FLOOD
FILL are completely bounded by a solid line.  Always be ready to UNDO
after a FLOOD FILL.  Bitmap programs that lack UNDO should be avoided
for this reason.

\item{ZOOM:} If you're working on a large (bigger than 100x100) bitmap,
use the ZOOM feature to do detail work and touch-ups.  This is
probably the most important feature after FLOOD FILL.

\item{PATTERN FILL:} To create something that looks like medium grey on
a b/w monitor, fill in the grid in a checkerboard fashion, alternating
black with white (use the ZOOM if necessary).  Doing this with the
LINE feature is often easier than going dot-by-dot.  To make darker or
lighter greys, add more black or white squares in a consistent,
regular fashion.  You may also make any number of textures or patterns
like this.  To fill in large regions of a bitmap with the pattern, I
suggest selecting, copying, and pasting pieces of the pattern in
appropriate places (being careful so that the pattern meshes smoothly
with other sections that contain the same pattern).  If you ever find
a bitmap program that will FLOOD FILL an area with a specific pattern,
by all means use that instead.

\item{FILLED Shape:} With the \verb+x11r5+ bitmap program, using the 
FILLED RECTANGLE or CIRCLE feature while depressing the left mouse
button will create a black shape; depressing the right button will
create a white shape, and the middle will create a shape that contains
whatever color contrasts with the background.

\end{description}

\section{Showing Bitmaps --- Basic Stuff}

If you just want to put up one copy of the bitmap and be able to click
it away, use \verb+showbitmap+.  You can \verb+add consult+ and then
do \verb+showbitmap -rv <bitmap name>+.

(The path is \verb+/mit/consult/$bindir/showbitmap+.)

The -rv flag merely inverts the bitmap coloration; for some reason,
showbitmap puts up bitmaps inverted on some machines, and thus the -rv
is necessary to see the original form.

Another way to put up one copy of a bitmaps, even compressed ones, is
to use:

\begin{verbatim}
% /mit/graphics/$bindir/xloadimage <bitmap name>
\end{verbatim}

To put a bitmap up on your root screen (the background), use:

\begin{verbatim}
% xsetroot -bitmap <bitmap name>
\end{verbatim}

This will place a tile pattern of your bitmaps onto your root screen.
If you're using compressed bitmaps, you can use the following to do
the same thing:

\begin{verbatim}
% /mit/graphics/$bindir/xloadimage -onroot <bitmap name>
\end{verbatim}

\section{Showing Bitmaps --- Background Slideshow}

If you're like me and have a bunch of different bitmaps that you like,
but hate to manually change your background, here's a nifty little
program that will do it for you.  Just type it up into an emacs
buffer, save it (I call mine XSRB1 and XSRB.un), and then run it as a
background process (just type \verb+XSRB1 &+ at the prompt).  To stop
a backgrounded process, do \verb+ps -ux+ and then type \verb+kill -9
<PID number>+.

\subsection{``XSRB1''}

(Note: this works for compressed bitmaps, but you must have graphics
added or in your path.  To add graphics, merely type \verb+add
graphics+.  This will also work for non-compressed bitmaps.)

\begin{verbatim}
#!/bin/csh -f
set pictures = `ls /mit/rei/bitart/Backgrounds`
set num = 1
while ($num)
        foreach i ($pictures)
                xloadimage -onroot /mit/rei/bitart/Backgrounds/$i >& /dev/null
                sleep 60
        end
end
\end{verbatim}

\subsection{``XSRB.un''}

(Note: this works only on uncompressed bitmaps.)

\begin{verbatim}
#!/bin/csh -f
set pictures = `ls /mit/rei/bitart/IS`
set num = 1
while ($num)
        foreach i ($pictures)
                xsetroot -bitmap /mit/rei/bitart/IS/$i >& /dev/null       
        end
end
\end{verbatim}

Note: the above program does not have a sleep time because it was
designed to produce an ``animation'' by throwing up slightly different
bitmaps one after the other.

\section{Putting Bitmaps into your World Wide Web homepage}

If you use the World Wide Web, you know that it can put up some really
nice images, including bitmaps and compressed bitmaps.

In your homepage file (\verb+<filename>.html+), put in something like
the following:

% do ctrl-u and the double-quote for the below

\begin{verbatim}
<IMG SRC="http://www.mit.edu:8001/afs/athena.mit.edu/user/r/e/rei/bitart/drae">
\end{verbatim}

This will insert that bitmap.  If your file is compressed, add
\verb+.Z+ to the end of the name.  If the bitmap is especially large,
you might also want to move it out of your homepage.

\section{Putting Bitmaps in Startup Files}

To get a specific bitmap on your root screen whenever you login, put
something like this in your .startup.X file:

\begin{verbatim}
xloadimage -onroot ~/bitart/Backgrounds/Respite &
/mit/sipb/$bindir/xscreensaver -geometry -25-55
\end{verbatim}

If you want a screensaver to start up, you should also add:

\begin{verbatim}
/mit/sipb/$bindir/xscreensaver -geometry -25-55
\end{verbatim}

Of course, substitute your own bitmap and pathname in!  Then, to
customize your screensaver icon, put something like the below in your
.Xresources file:

\begin{verbatim}
xscreensaver*icon.bitmap:/mit/rei/bitart/drae
xscreensaver*float.bitmap:/mit/rei/bitart/dolphin
xscreensaver*useBackground:true
\end{verbatim}

The \verb+float.bitmap+ section tells xscreensaver to use a different
bitmap for when the icon floats around on the screen.

\section{Printing Bitmaps}

If you create a bitmap and want to take a hardcopy home to tape on
your door, you can print it like this:

\begin{verbatim}
% add consult
% showbitmap <bitmapname> &
% xdpr -P<printername>
\end{verbatim}

and click on the window with the bitmap once your pointer turns into a
crosshatch.  Xdpr tries to print bitmaps as large as possible.  If you
want your little bitmap to look like a little bitmap when printed, do:

\begin{verbatim}
% xdpr -scale <number> -P<printername>
\end{verbatim}

where \verb+<number>+ scales the image's size up by that factor.
\verb+1+ is absolutely tiny.  \verb+4+ is about right if you want the 
paper image to be about the same size as the screen image.

Another way of printing out bitmaps is listed below, and involves
converting the bitmap into PostScript.

\section{Advanced Stuff}

\subsection{Converting to PostScript and Inserting into Files}

The graphics locker contains several programs to convert bitmaps to
other formats such as PostScript (which can be inserted into \LaTeX{}
documents).

Both xpaint and xv have this capability.  Basically, load (or open)
your xbm format bitmap through either program, and then save it as a
PostScript file (add \verb+.ps+ to the end of its name).  Now, in
PostScript form, it can be printed out or added to your documents.
Both programs save files in Encapsulated PostScript form.

Then, in your \LaTeX{} document, you need to add \verb+epsf+ to the
\verb+\documentstyle[]+ command, and then put in something like the 
following:

\begin{verbatim}
\hspace*{1mm}
\vspace{2cm}
\epsfbox{filename.ps}
\end{verbatim}

where you want the bitmap.

One last thing: you will have to \verb+attach sipb+ and then do

\begin{verbatim}
% setenv TEXINPUTS .:/mit/sipb/lib/tex/macros:/usr/athena/lib/tex/macros+
\end{verbatim}

before trying to \verb+latex+ your document.

If you have problems, see the Inessential \LaTeX{} guide for more
details on this and other \LaTeX{} tricks.  In-depth information is
also available in the More \LaTeX{} on Athena: Reports and Advanced
Topics publication, available at Graphic Arts.  You may also access it
via online \verb+help+: in the main menu, go to the Archive of Online
Documentation, and from there go to the Archive of Athena Documents
Available at MIT Graphic Arts.

\subsection{Sending Bitmaps to Other Terminals}

If someone at another terminal wants to see your wonderful bitmaps,
you may send them directly to that person's screen.  First, the other
person must \verb=xhost +<your machine's name>=.  Then, you may do the
following:

\begin{verbatim}
% xsetroot -display <the other machine name>:0 -bitmap <bitmapname>
\end{verbatim}

\section{Where to Find Sample Bitmaps}

You may use any of the programs mentioned above to go around and view
other people's bitmaps; in addition, you may find some on the World
Wide Web, in various homepages and elsewhere.

Places to find neat bitmaps include:
% (Need to ask for permission for some of these)
%        /mit/abbe/graphics/bitmaps/ (3)
%        /mit/aragorn/visual/Bitart/
%        /mit/dagoura/BIT/
%        /mit/tlw/bits/
%        /mit/wchuang/bitmaps/

\begin{verbatim}
/mit/rei/bitart/ 	
/mit/rei/bitart/Backgrounds/ 
/afs/athena/user/r/j/rjbarbal/Bitmaps
/usr/lib/X11/bitmaps/
/mit/sipb/lib/bitmap/
/mit/dcctdw/Bitart/
/mit/dcctdw/Bitart.more/
/mit/yandros/stuff/graphics/
\end{verbatim}

Note: to access some of the above, you may need to type \verb+aklog
sipb+ first.  Also, some of the bitmaps are in \verb+.gz+ format, a
special compression format.  You may need to copy them and unzip them
(\verb+gzip+ and \verb+gunzip+ are both available in the sipb locker)
to view them yourself.  Anything ending in just \verb+.Z+ is probably
a bitmap that you should be able to view with \verb+xloadimage+, as
outlined above.  Also, remember that \verb+.xbm+ is sometimes used to
denote xbm format bitmaps.

You may also use WWW (type \verb+Mosaic &+ at your prompt) and find
rei's homepage from the SIPB homepage, where I have some of my bitmaps
available for viewing.

Hopefully some of the examples will give you a general idea of what is
possible with xbm-format bitmaps.  The rest is up to you.

If you have questions about anything in this document, or find new
bitmap programs, feel free to email me at \verb+rei@mit.edu+, or stop
by SIPB.

\begin{center}
\hspace*{1mm}
\vspace{2cm}
\epsfbox{/afs/sipb/project/doc/ibitmap/dolphin.ps}

\end{center}

\end{document}