'\"macro stdmacro
.if n .pH g1.postmd @(#)postmd	40.3 of 1/8/90
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} postmd 1 "Line Printer Spooling Utilities" "\&"
.if \nX=1 .ds x} postmd 1 "Line Printer Spooling Utilities"
.if \nX=2 .ds x} postmd 1 "" "\&"
.if \nX=3 .ds x} postmd "" "" "\&"
.TH \*(x}
.SH NAME
\f4postmd\fP \- matrix display program for PostScript printers
.SH SYNOPSIS
\f4postmd\fP
[\f2options\fP] [\f2files\fP]
.SH DESCRIPTION
The \f4postmd\fP filter
reads a series of floating point numbers from
.I files,
translates them into a PostScript gray scale image,
and writes the results on the standard output.
In a typical application the numbers might be 
the elements of a large matrix,
written in row major order, 
while the printed image could help locate
patterns in the matrix.
If no
.I files
are specified, or if \f4\-\fP is one of the input
.I files,
the standard input is read.
The following
.I options
are understood:
.TP 1.0i
\f4\-b \f2num\f1
Pack the bitmap in the output file using
.I num
byte patterns.
A value of 0 turns off all packing of the output file.
By default,
.I num
is 6.
.TP 1.0i
\f4\-c \f2num\f1
Print
.I num
copies of each page.
By default, only one copy is printed.
.TP 1.0i
\f4\-d \f2dimen\fP
Sets the default matrix dimensions for all input
.I files
to
.IR dimen .
The
.I dimen
string can be given as rows or rows\^\f4x\fP\^columns.
If \f2columns\fP is omitted it will be set to rows.
By default, \f4postmd\fP
assumes each matrix is square and sets the number of rows
and columns to the square root of the number of elements in
each input file.
.TP 1.0i
\f4-g \f2list\f1
.I List
is a comma or space separated string of integers, each lying between
0 and 255 inclusive,
that assigns PostScript gray scales to the regions of the real line
selected by the \f4\-i\fP option.
255 corresponds to white, and 0, to black.
The \f4postmd\fP filter
assigns a default gray scale that omits white (that is, 255) 
and gets darker as the regions move 
from left to right along the real line.
.TP 1.0i
\f4\-i \f2list\f1
.I List
is a comma, space or slash(/) separated string of 
\f2N\fP floating point numbers that
partition the real line into 2\f2N\f1+1 regions.
The
.I list
must be given in increasing numerical order.
The partitions are used 
to map floating point numbers read from the input
.I files
into gray scale integers that are either assigned automatically by
\f4postmd\fP
or arbitrarily selected using the
\f4-g\fP option.
The default interval
.I list
is \f4-1,0,1\fP, which partions the real line into seven regions.
.TP 1.0i
\f4-m \f2num\f1
Magnify each logical page by the factor
.IR num .
Pages are scaled uniformly about the origin
which, by default, is located at the center of
each page.
The default magnification is 1.0.
.TP 1.0i
\f4-n \f2num\f1
Print
.I num
logical pages on each piece of paper,
where
.I num
can be any positive integer.
By default,
.I num
is set to 1.
.TP 1.0i
\f4\-o \f2list\f1
Print pages whose numbers are given in the comma separated
.IR list .
The list contains single numbers
.I N
and ranges
\f2N1 \f1\- \f2N2\f1.
A missing
.I N1
means the lowest numbered page, a missing
.I N2
means the highest.
.TP 1.0i
\f4\-p \f2mode\f1
Print
.I files
in either portrait or landscape
.I mode.
Only the first character of
.I mode
is significant.
The default
.I mode
is portrait.
.TP 1.0i
\f4-w \f2window\f1
.I Window
is a comma or space separated list of four positive integers that
select the upper left and lower right corners of a submatrix from
each of the input
.IR files .
Row and column indices start at 1 in the upper left corner and the
numbers in the input
.I files
are assumed to be written in row major order.
By default, the entire matrix is displayed.
.TP 1.0i
\f4-x \f2num\f1
Translate the origin
.I num
inches along the positive x axis.
The default
coordinate system has the origin fixed at the
center of the page, with positive
x to the right and positive y up the page.
Positive
.I num
moves everything right.
The default offset is 0 inches.
.TP 1.0i
\f4-y \f2num\f1
Translate the origin
.I num
inches along the positive y axis.
Positive
.I num
moves everything up the page.
The default offset is 0.
.PP
Only one matrix is displayed on each logical page,
and each of the input
.I files
must contain complete descriptions of exactly one matrix.
Matrix elements are floating point numbers 
arranged in row major order in each input file.
White space, including newlines, 
is not used to determine matrix dimensions.
By default, \f4postmd\fP
assumes each matrix is square and sets the number of rows and columns
to the square root of the number of elements in the input file.
Supplying default dimensions on the command line
with the \f4-d\fP option
overrides this default behavior,
and in that case the dimensions apply to all input
.IR files .
.PP
An optional header can be supplied with each input file and is used
to set the matrix dimensions, 
the partition of the real line, 
the gray scale map, and a window into the matrix.
The header consists of keyword/value pairs, each on a separate line.
It begins on the first line of each input file and ends with the
first unrecognized string, which should be the first matrix element.
Values set in the header take precedence, 
but apply only to the current input file.
Recognized header keywords are \&\f4dimension\fP, \&\f4interval\fP,
\&\f4grayscale\fP, and \&\f4window\fP.
The syntax of the value string that follows each keyword 
parallels what's accepted by 
the \&\f4-d\fP, \&\f4-i\fP, \&\f4-g\fP, and \&\f4-w\fP options.
.SH EXAMPLES
For example, suppose file initially contains the 1000 numbers
in a 20x50 matrix.
Then you can produce exactly the same output
by completing three steps.
First, issue the following command line:
.nf

          \f4postmd -d20x50 -i"-100 100" -g0,128,254,128,0 \f2file\f1

.fi
Second, prepend the following header to \f2file\fP:
.nf

          \f4dimension 20x50
          interval  -100.0 .100e+3
          grayscale 0 128 254 128 0\f1

.fi
Third, issue the following command line:
.nf

          \f4postmd \f2file\f1

.fi
The interval list partitions the real line into five regions and
the gray scale list maps numbers less than \-100 or greater than 100
into 0 (that is, black), 
numbers equal to \-100 or 100 into 128 (that is, 50 percent black),
and numbers between \-100 and 100 into 254 (that is, almost white).
.SH NOTES
The largest matrix that can be adequately displayed is a function
of the interval and gray scale lists, the printer resolution,
and the paper size.
A 600x600 matrix is an optimistic upper bound for a two element interval
list
(that is, five regions) using 8.5x11 inch paper on a 300 dpi printer.
.PP
Using white (that is, 255) in a gray scale list 
is not recommended and won't show up in 
the legend and bar graph that \f4postmd\fP displays below each image.
.SH DIAGNOSTICS
An exit status of 0 is returned if
.I files
were successfully processed.
.SH FILES
\f4/usr/lib/postscript/postmd.ps
.br
/usr/lib/postscript/forms.ps
.br
/usr/lib/postscript/ps.requests\fP
.SH SEE ALSO
\f4dpost\fP(1),
\f4postdaisy\fP(1),
\f4postdmd\fP(1),
\f4postio\fP(1),
\f4postprint\fP(1),
\f4postreverse\fP(1),
\f4posttek\fP(1).
