summaryrefslogtreecommitdiff
path: root/graphics/pbmtopk/doc/pbmtopk.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pbmtopk/doc/pbmtopk.tex')
-rw-r--r--graphics/pbmtopk/doc/pbmtopk.tex179
1 files changed, 179 insertions, 0 deletions
diff --git a/graphics/pbmtopk/doc/pbmtopk.tex b/graphics/pbmtopk/doc/pbmtopk.tex
new file mode 100644
index 0000000000..b963197716
--- /dev/null
+++ b/graphics/pbmtopk/doc/pbmtopk.tex
@@ -0,0 +1,179 @@
+%%% pbmtopk.tex
+%%% AJCD 21/9/90
+%%% Short article for UK TeX User's Group newsletter about the PBMtoPK and
+%%% PKtoPBM programs.
+
+\documentstyle[a4,verbatim]{article}
+
+\title{PBMtoPK --- Converting bitmaps to fonts}
+\author{Angus Duggan ({\tt ajcd@uk.ac.ed.lfcs})}
+\date{21 September 1990}
+
+%%% Please alter this directory
+\def\inaston{[tex-archive.fonts.duggan]}
+
+%%% Dates of Usenet posting
+\def\postingdates{at the beginning of August, with three patches on 10th
+August, 12th August, and 21st September}
+
+%%% Example font for this document
+\font\examplf=examplf
+
+%%% new environment for examples; small, indented, verbatim
+\newenvironment{example}%
+ {\quote\small\verbatim}%
+ {\endverbatim\endquote\smallskip}
+
+\begin{document}
+
+\maketitle
+
+\section*{PBMtoPK.}
+PBMtoPK is a program for converting and collecting bitmaps into a PK format
+font, for use with \TeX. PKtoPBM performs the inverse operation, extracting
+bitmaps from a PK format font.
+
+\section*{PBMPLUS.}
+The PBM (Portable BitMap) format was created by Jef Poskanzer as a ``lowest
+common denominator'' format, which images could be translated to and from with
+ease. The bitmap representation is given in plain ASCII text, so that images
+can be mailed between different machines and networks without the usual
+problems of encoding and decoding. (The ASCII representation of the bitmap
+also allows you to create or alter images with a text editor, if no better
+tools are available.)
+
+The PBM format is very simple:
+\begin{example}
+P1
+16 16
+0000011111100000
+0001100000011000
+0010000000000100
+0100000000000010
+0100000000000010
+1000110000110001
+1000110000110001
+1000000000000001
+1000000000000001
+1000000000000001
+1000100000010001
+0100010000100010
+0100001111000010
+0010000000000100
+0001100000011000
+0000011111100000
+\end{example}
+The image above is a smiley face ({\examplf S}).
+The first two characters of the file contain the ``magic number'' of the
+file --- in the case of a PBM file, this is ``{\tt P1}''. The width and height
+of the image follow, seperated by whitespace (spaces, tabs or newlines), and
+then the image data, encoded as ones and zeros. The PBM format specification
+allows white space to appear almost anywhere in the file --- the image need
+not have newlines between image rows, and the bits can be seperated by
+whitespace if desired. Comments can be included in PBM files, but most of the
+PBM filters will delete them from their output.
+
+The PBMPLUS toolkit contains programs to perform many common image
+manipulation operations on PBM format images, such as cropping, cutting,
+pasting, rotating, shearing, converting between image formats, etc..
+These programs are usually arranged as {\em filters\/}; they take the input
+image on the default input stream, and write their output to the default
+output stream. This organisation allows multiple image manipulations to be
+strung together in a pipeline, creating no unnecessary temporary files.
+
+There are two other image formats which are supported by the PBMPLUS toolkit.
+These
+are the PGM (Portable GrayMap) format, and the PPM (Portable PixMap) format,
+which are lowest common denominator formats for grayscale and colour images
+respectively. These formats have the magic numbers P2 and P3, and a similar
+organisation of the image data. In addition, there are binary variants
+on the PBM, PGM and PPM formats, which are unsuitable for mailing. These
+variants have the magic numbers P4, P5, and P6.
+
+Writing programs which use the PBMPLUS formats is made a lot easier by the
+PBMPLUS libraries, which provide functions for reading and writing PBMPLUS
+images in
+their entirety, or row by row.
+
+The PBMPLUS toolkit has been ported to VMS and other systems.
+
+\section*{Using PBMtoPK.}
+PBMtoPK and PKtoPBM are based on Tom Rokicki's PXtoPK and PKtoPX programs.
+They are written in C, and are linked with the PBM library. PBMtoPK can be
+used to incorporate bi-level images into \TeX\ documents, by creating a font
+which contains the images used in the document as characters.
+Figure~\ref{fig:beast} shows an example graphic which was created in this way.
+
+\begin{figure}[hbt]\centering
+\mbox{\examplf B}
+\caption{A scanned line-drawing converted by PBMtoPK}\label{fig:beast}
+\end{figure}
+
+Some DVI drivers may have problems handling the large characters which are
+typically created by this process. This should not be a problem if the driver
+adheres to the recently-published draft Level~0 DVI driver specifications.
+
+To create a simple font containing only one image (in the character position
+of ``A''), a command similar to
+\begin{example}
+pbmtopk example.300pk example.tfm 300 -s10 -c65 image.pbm
+\end{example}
+\noindent
+would be used. This command will create the PK font file {\tt example.300pk}
+and the TFM file {\tt example.tfm}, setting the resolution of the font to 300
+dots per inch, and the design size of the font to 10 points. To include this
+image in the document, a font declaration should be put in the document
+prologue:
+\begin{example}
+\font\imagefont=example
+\end{example}
+The font may then be selected, and the image can be typeset by placing the
+character ``A'' on the page. For example:
+\begin{example}
+\begin{figure}[hbt]\centering
+\mbox{\imagefont A}
+\caption{A scanned image converted by PBMtoPK}
+\end{figure}
+\end{example}
+The TFM and PK files will probably have to be moved to
+an appropriate directory (the exact directory names are site and DVI driver
+specific); DVI drivers and previewers may also require that the location of the
+PK and TFM files are included in option files or environment variables.
+
+The major disadvantage of this method of including raster graphics in \TeX\
+output is that the user must know many details about the output device.
+
+PBMtoPK provides a large number of options which can be used to alter
+information in the PK and TFM font files --- the designsize, resolution,
+font parameters, and the coding scheme and font family name comments can all
+be reset. Options are provided to set the character's width, height, depth,
+and italic correction in the TFM file for each character (these need not be
+the same as the
+character's actual width or height in pixels), and the character origin and
+horizontal and vertical escapements in the PK file. Sensible guesses are made
+for any piece of information not supplied, based on the information
+which was supplied and the image size.
+
+If multiple images are being included in one font file, or a font is being
+converted from another format into a PK font, the command-line options
+rapidly become unwieldy and may overflow the maximum command line size.
+A facility is therefore provided to read the character-specific options from a
+file, which can be prepared with a text editor, or automatically generated.
+
+Ligature and kerning tables are not catered for at all by PBMtoPK --- if these
+features are required in the font, the TFM file should be converted to a PL
+(Property List) file, edited by hand, and converted back into a TFM file.
+
+The interface to PKtoPBM is much simpler; the name of the PK file from which
+glyphs are to be extracted is given on the command line, with a list of names
+for the PBM files mixed with switches which set the number of the next
+character to be extracted.
+
+\section*{Getting PBMtoPK.}
+PBMtoPK and PKtoPBM are on the Aston archive, in the directory {\tt\inaston}.
+PBMtoPK was posted to Usenet group {\tt alt.sources} \postingdates, and
+so should be available from any archive storing {\tt alt.sources}.
+
+\noindent\hfill{\examplf A}.
+
+\end{document}