gandalf@csli.STANFORD.EDU (Juergen Wagner) (09/06/88)
Many people have picked up the `bmx' package from csli.stanford.edu. For
some very strange reasons, the man page for `bmx' never appeared in the
shell archives... I have mailed it to a couple of people but since the
number of requests is too large, I decided to post it.
Apologies,
Juergen "Gandalf" Wagner, gandalf@csli.stanford.edu
Center for the Study of Language and Information (CSLI), Stanford CA
---------------------------------------------------------------------------
#! /bin/sh
#
# Archive 'bmxman.1of1' created by Juergen Wagner at csli
# Date is Thu Sep 1 18:32:13 1988
#
# This is a shell archive. Remove anything before this line
# then unpack it by saving it in a file and feeding it into sh.
# (Files unpacked will be owned by you and have default permissions).
#
# This archive contains the following files: (use them wisely)
# ./bmx.man (14230 bytes)
#
if `test ! -s ./bmx.man`
then
echo "Extracting ./bmx.man"
sed 's/^X//' > ./bmx.man << 'foo_bar_and_baz'
X.TH BMX L "August 17th, 1988"
X.SH NAME
Xbmx \- convert bitmaps between formats
X
X.SH SYNOPSIS
X.I bmx
X[operators]
X
X.SH DESCRIPTION
X.PP
X.I Bmx
Xprovides a flexible tool to convert bitmaps between
Xdifferent formats. A few bitmap operations are also available.
X
X.I Bmx
Xsupports a variety of bitmap formats both, for input and output; a few
X(printer languages) are only available as output formats. The program
Xserves as an interface to a library of C function which provides I/O and
Xother operations for bitmaps in the formats listed below.
X
X.I Bmx
Xinvokes without arguments prints a somewhat lengthy help text.
XOtherwise, it takes a list of operator calls which describe a sequence
Xof operations to be performed. The general syntax for operators is
Xa option-style operator name (i.e. starting with a dash) followed by
Xits arguments. Arguments may be bitmap names, file names, or parameters
Xspecifying the operators behavior.
X
XAll transactions performed are logged to a log file. Any errors abort
Xthe program.
X
X.SH BITMAPS
XBitmaps are read into the system using the \fB-in\fP operator, and written
Xto files using the \fI-out\fP operator. Other operators allow to perform
Xbitmap manipulations. Please, note that all bitmaps are assumed to have
Xwidths/heights which are multiples of 16 pixels. This restriction may be
Xdropped in a future release.
X
XBitmaps are addressable by their names. Names are assigned during bitmap
Xcreation. Names may be strings of arbitrary length - all characters are
Xsignificant.
X
X.SH OPERATORS
XThe following operators are available:
X.IP "-in name format file options.."
XA bitmap is read into memory. The bitmap is read from file \fBfile\fP ("-"
Xdenotes standard input), receives the specified name, and is assumed to be
Xin the specified format. Additional options may help \fBbmx\fP to classify
Xor decode the image. See the section FORMATS for descriptions of the format
Xoptions.
X
X.IP "-out name format file options.."
XA bitmap is written to a file. The arguments to the \fB-out\fP operator are
Xanalogous to the \fB-in\fP arguments. Standard output is denoted by "-".
X
X.IP "-info bitmap_name"
XPrint information about the respective bitmap (size, depth, ...).
X
X.IP "-list"
XList all bitmaps currently in memory. Basically, this is a \fB-info\fP
Xapplied to all bitmaps loaded.
X
X.IP "-log [logfile]"
XSpecify the logfile. Without an argument, this disables the log file. If the
Xlog file is given, all further logging is printed to that file ("-" denotes
Xstandard error output).
X
X.IP "-fiddleop bitmapnames.."
XPerforms \fIfiddleop\fP on the bitmaps listed. The operator has to be one of
X\fBinv\fP (invert bits), \fBrev\fP (reverse bits word-wise), \fBrev2\fP
X(reverse bits byte-wise), \fBswap\fP (swap bytes word-wise).
X
X.IP "-frame bitmap [frame_width]"
XPut a black frame of with \fIframe_width\fP (default: 1) around the bitmap.
X
X.IP "-concat bitmap1 bitmap2 newbitmap [location] [options]"
XThe two bitmaps, \fIbitmap1\fP and \fIbitmap2\fP, are concatenated to give
Xa new bitmap \fInewbitmap\fP. "Concatenation" means that a new bitmap is
Xcreated, just large enough to hold the original two bitmaps arranged as
Xspecified by \fBlocation\fP (by default: left). Location is a meaningful
Xcombination of "left", "right", "above", "below". Other options are "black"
Xand "white", specifying the background color of the new bitmap.
XNote that bitmap dimensions are multiples of 16 pixels.
X
X.IP "-help"
XPrint a help text. (You get the same thing by invoking \fBbmx\fP without
Xany arguments.)
X
X.SH FORMATS
X
XThe keywords in the following table are the keywords you can use to
Xselect a bitmap format with the \fB-in\fP and \fB-out\fP operators.
XWith those operators, any words following the bitmap name, the format
Xname, and the file name, are taken to be options to this format. Options
Xtake the syntactic form of a single word, or a word followed by a value.
XIn the latter case, the option name and the value are separated by an
Xequal sign (e.g. \fIresize=40\fP).
X
XIt is an error to give options not recognized by the format converter.
X
XThere may be different options for reading and writing bitmaps in a
Xcertain format.
X
X.IP "gandalf, g"
X(Gandalf's favourite format)
XBasically, this is a format I use to store
Ximages in a more or less compact way. It will change as soon as I implement
Xcolor maps. There is an option \fBdense\fP for output, forcing run-length
Xencoding.
X
X.IP "ascii, asc, a"
X(ASCII representation)
XOptions are \fB0\fP (zero) and \fB1\fP (one). By default, the characters to
Xrepresent bits are zeroes and ones. This can be changed by specifying the
Xabove options with a value describing the respective characters. All characters
Xdifferent from the two characters denoting bits are ignored.
X
XExample:
X.br
X -in bits ascii image.pbm
X.br
X -in bits ascii image.asc 0=\\ 1=*
X
X.IP "raster, ras, r"
X(Sun Rasterfile)
XStandard Sun rasterfiles in 68000 byte order can be read with this format
Xconverter module. The image has to be a monochrome image in RT_STANDARD
Xformat. There are no options.
X
XExample:
X.br
X -in background ras screendump.ras
X
X.IP "iconedit, icon, i"
X(Sun Iconedit file)
XThe bitmap is supposed to be in format version 1 with 16 valid bits per item,
Xthe depth has to be one. On output, all data items are written as hexidecimal
Xnumbers with four digits. However, on input, the items may be octal, binary,
Xhexidecimal, or decimal. There are no options.
X
XExample:
X.br
X -in icon iconedit /usr/include/images/letter.image
X
X.IP "impress, imp, l"
X(imPRESS format)
XThis format is output-only. It is intended to produce a file suitable for
Xan Imagen printer. The paper size is assumed to be 8.5x11.0 inch (US letter
Xsize). The module can be changed to use A4 paper format.
XThere are no options.
X
XExample:
X.br
X -out dump imp dump.imp
X.br
X -out dump imp -
X
X.IP "dlionbm, dlion, d"
X(Xerox-1108 InterLisp bitmap)
XThis bitmap format is what you get when saving a bitmap under InterLISP.
XA bitmap is recognized if somewhere in the input file occurs
X.br
X (RPAQ \fIname\fP (READBITMAP))
X.br
Xwhere name is some symbol. The next line is then supposed to be the first
Xline of the bitmap data (width and height), followed by the image.
XWhen writing the bitmap, the module uses UNIX-style line feeds, so there might
Xbe a problem when you actually try to read the file into an InterLISP system.
XThis format doesn't take any options.
X
XExample:
X.br
X -in screen dlion xerox.dump
X
X.IP "laserjet, lj, h"
X(HP LaserJet format)
XThe HP LaserJet format is output-only. I encountered some problems with bitmaps
Xlarger than 128x128, probably due to a malfunctioning spooler which mistreated
Xsome control characters. According to the user manual, however, everything
Xshould be ok the way the module produces the image. There is an option to
Xspecify the resolution (be default, the image is made as large as possible).
XSince I had these weird problems with the spooler, I didn't landscape mode.
XThe resolution is specified using \fBres=\fP\fIres\fP, where \fIres\fP is one
Xof 75, 150, 300. If the value given doesn't fit the image on the page, it is
Xincreased.
X
X.IP "macpaint, macp, m"
X(MacPaint document)
XMacPaint documents are confined to 576x720 images. Documents written by this
Xpackage have a zeroed header, i.e. do not carry pattern information.
X
XThe input side doesn't take any options. Since there is no magic number, there
Xis also no way of detecting whether a given image is a valid MacPaint image,
Xor not.
X
XOn output, the bitmap is adjusted to size 576x720, all extra bits are zero.
XTwo options, \fBx=\fP\fIxoffset\fP and \fBy=\fP\fIyoffset\fP allow to give
Xan offset.
X
XExample:
X.br
X -in slide2 macpaint screen.0
X.br
X -out slide2 macpaint slide2.macpaint x=100 y=100
X
X.IP "postscript, ps, p"
X(Simple PostScript images)
XSince I did not intend to write a full PostScript interpreter, this module
Xunderstands nothing else but what is in the format it is writing its bitmaps
Xin. There are two ways to encode a PostScript image: one as a plain string, and
Xone using run-length encoding.
X
XWhen reading an image, it is automatically
Xdetected which encoding is used, so there are no options.
X
XWhen writing an image, there are a few options. By default, a plain string
Xis produced. This may, however, not work with some printers when the string
Xgets too long, and may also lead to significant image transmission times.
XThe option \fBdense\fP forces run-length encoding.
X
XUsually, the image is made as large as possible. With \fBresize=\fP\fIfactor\fP
Xyou can specify a factor in percent the image should be shrunk or blown up.
XFor normal images, only shrinking is available, since 100% fill the page.
XIn combination with the \fBtex\fP option which produces a file suitable for
Xinclusion in TeX files (using the \\special command), the default size might be
Xtoo small. Files using the \fBtex\fP option can be included in TeX documents:
X.nf
X
X This is how one can include an image:
X \\special{psfile=picture.ps}
X \\vskip 0in
X That's it. Be sure to use the new DVI2PS. Resize factors
X of 50, 100, and 200 look pretty nice.
X \\bye
X
X.fi
XThere are some versions of dvi2ps which screw up the printer, so be sure to
Xget the right dvi2ps.
X
XExamples:
X.br
X -in pic ps eagle.ps
X.br
X -out pic ps eagle.ps resize=75
X.br
X -out pic ps eagle.ps resize=250 tex dense
X
X.IP "printronix, ptx, t"
X(Printronix printer format)
XThis just dumps a bitmap in Printronix format. There are no options.
X(Be careful with certain spoolers. Some spoolers eat the control characters.)
X
XExample:
X.br
X -out picture ptx pic.ptx
X
X.IP "sixel, six, s"
X(Sixel format - LN03 Printer)
XSupposed to convert to (not from) images suitable for LN03 printers. I have
Xnever tried the conversion myself but somebody told me it works. There might
Xbe some resizing problems with bitmaps of size different from 1152x900.
XThere are no options.
X
XExample:
X.br
X -out weird sixel -
X
X.IP "ucbvax, ucb, u"
X(Weird format of ucbvax:pub/xbackgrounds/*)
XYeah! Finally, the format of the weird bitmaps in the \fIxbackgrounds\fP
Xdirectory of ucbvax is readable. There are no options, and I do not
Xrecommend to use this weird format for anything other than reading a bitmap.
X
XExample:
X.br
X -in nice ucbvax yosemite
X
X.IP "xbitmap, xicon, x"
X(X Bitmap as C header file)
XThe reader automatically determines whether the given input file contains
Xa X10 or a X11 bitmap. It understands the #define lines specifying width,
Xheight, and hot spot. On output, the option \fBversion=\fP\fIvers\fP allows
Xto write X10/X11 bitmaps (vers 10 or vers 11), the default is X11.
XThe option \fBname\fP takes
Xan argument which is used as the bitmap name. The hot spot can be specified
Xwith \fBhot_x=\fP\fIhotx\fP and \fBhot_y=\fP\fIhoty\fP.
X
XExample:
X.br
X -in icon x icon.x11
X.br
X -in icon x icon.x10
X.br
X -out icon x icon.x10 version=10
X.br
X -out icon x icon.x name=tty version=11 hot_x=8 hot_y=8
X
X.IP "xwindow, xwd, w"
X(X Window Dump Format)
XOn input, there are no options. The module automatically recognizes versions
Xand display types (hopefully). It understands XYFormat with a single plane,
Xand ZFormat of up to 8 planes. Currently supported display types include SUN,
XuVAX, and HP Bobcat (which uses a slightly :-) different header).
X
XOn output, things become more sophisticated. Since some machines do wierd
Xbyte swapping, or use different headers, one has to specify what the target
Xmachine is supposed to be.
X
XOptions are \fBversion=\fP\fIversion\fP (10 or 11), \fBformat=\fP\fIdisp\fP
X(display type: SUN, UVAX, BOBCAT, ...), \fBx=\fP\fIxoff\fP and
X\fBy=\fP\fIyoff\fP (specifying offsets for the xwud window), and
X\fBborder=\fP\fIwidth\fP (border width).
X
XExample:
X.br
X -in window xwd term.xwd
X.br
X -out window xwd fullmoon.xwd format=BOBCAT x=-100 y=-60
X
X.IP "ccittfax, fax, f"
X(G3/G4 FAX Format, CCITT Rec. T.4/T.6, VII.3)
Xnot implemented yet.
X
X.IP "cvl, c"
X(CVL Format)
XThe CVL images understood by this package have to obey the following
Xrestrictions: 1 band/pixel, 1 bit/pixel, 1 bit/band, two-dimensional,
Xsingle plane, single hyperplane. By default, the header fields are not
Xbyte swapped when a bitmap is written. The option \fBswap\fP causes swapping.
XWhen a bitmap is read, header fields are swapped automatically if necessary.
X
XExample:
X.br
X -out bits cvl pic.cvl swap
X
X.IP "pppf, ppp, pp"
X(Program Products Picture File Format)
XThis doesn't take any options.
X
XExample:
X.br
X -in image pppf image.pppf
X
X.SH AVAILABILITY
XThe package is *NOT* in the public domain. The copyright remains with
Xthe author.
X
XThe entire package may be copied and redistributed in any form provided that
Xthe copyright notices are not changed or removed. It must, however, not
Xbe used in any licensed software without the author's consent.
X
XAny software containing this package as a whole, or parts of it, has to be
Xdistributed free of charge (possibly with a reasonable fee for copying and
Xshipping), and machine-readable sources of this file have to be made
Xaccessible.
X
X.I Bmx
Xhas been posted to comp.sources.unix, and should be available from there as
Xsoon as Rich Salz has approved the package. Until then, \fIbmx\fP can be
Xobtained from csli.stanford.edu (Internet#36.9.0.46) via anonymous ftp from
X\fBpub/Gandalf/bmx.*\fP (program, library, man pages, sample bitmaps).
X
XPlease, send bug reports, comments, etc. to gandalf@csli.stanford.edu.
X
X.SH "THE FUTURE"
XI am planning to implement more formats (GIF, TIFF, IFF, ...). This program
Xis not intended to be something completely new, independent of all other
Xbitmap conversion and manipulation programs. It should be more of an interface
Xbetween different bitmap worlds, to allow the exchange of images between
Xsystems.
X
XTherefore, bitmap editors, CAD programs, printer spoolers, etc. could use
X\fBbmx\fP to extend the range of images available and usable. If
Xyou feel the need for additional formats, send me a specification of the
Xrespective formats, together with at least one typical image per format,
Xso I can try my module. If you have a converter of some kind, I'd be happy
Xto try to integrate it into \fIbmx\fP (should not be too difficult).
X
X.SH AUTHOR
XJuergen Wagner (gandalf@csli.stanford.edu), Center for the Study of
XLanguage and Information (CSLI), Stanford University (formerly at
XFraunhofer-Institut fuer Arbeitswirtschaft und Organisation, Stuttgart).
foo_bar_and_baz
else
echo "will not overwrite ./bmx.man"
fi
echo "Finished archive 1 of 1"
# if you want to concatenate archives, remove anything after this line
exit 0
--
Juergen "Gandalf" Wagner, gandalf@csli.stanford.edu
Center for the Study of Language and Information (CSLI), Stanford CA