xref: /plan9/sys/src/cmd/postscript/postmd/postmd.1 (revision 7dd7cddf99dd7472612f1413b4da293630e6b1bc)
POSTMD 1 "DWB 3.2"
NAME
postmd - matrix display program for PostScript printers
SYNOPSIS
\*(mBpostmd\f1 .OP "" options [] .OP "" files []
DESCRIPTION
postmd reads a series of floating point numbers from 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 files are specified, or if .OP - is one of the input files , the standard input is read. The following options are understood:

0.75i .OP -b num Pack the bitmap in the output file using num byte patterns. A value of 0 turns off all packing of the output file. By default num is 6.

.OP -c num Print num copies of each page. By default only one copy is printed.

.OP -d dimen Sets the default matrix dimensions for all input files to dimen . The dimen string can be given as rows or rows\^\(mu\^columns. If columns is omitted it will be set to rows. By default postmd 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.

.OP -g list 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 .OP -i option. 255 corresponds to white and 0 to black. postmd assigns a default gray scale that omits white (i.e., 255) and gets darker as the regions move from left to right along the real line.

.OP -i list list is a comma- or space-separated string of N floating point numbers that partition the real line into 2 N +1 regions. The list must be given in increasing numerical order. The partitions are used to map floating point numbers read from the input files into gray scale integers that are assigned automatically by postmd or arbitrarily selected using the .OP -g option. The default interval list is ``\*(mB-1,0,1'' which partions the real line into 7 regions.

.OP -m num Magnify each logical page by the factor 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.

.OP -n num Print num logical pages on each piece of paper, where num can be any positive integer. By default num is set to 1.

.OP -o list Print pages whose numbers are given in the comma separated list . The list contains single numbers N and ranges N1-\|N2 . A missing N1 means the lowest numbered page, a missing N2 means the highest.

.OP -p mode Print files in either \*(mBportrait or \*(mBlandscape mode . Only the first character of mode is significant. The default mode is \*(mBportrait.

.OP -w window 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 files . Row and column indices start at 1 in the upper left corner and the numbers in the input files are assumed to be written in row major order. By default the entire matrix is displayed.

.OP -x num Translate the origin 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 num moves everything right. The default offset is 0 inches.

.OP -y num Translate the origin num inches along the positive y axis. Positive num moves everything up the page. The default offset is 0.

.OP -E name Set the character encoding for text fonts to name . Requesting name means include file .MI \*(dQ/ name .enc \f1. A nonexistent encoding file is silently ignored. The default selects file .MR \*(dQ/Default.enc .

.OP -L file Use file as the PostScript prologue.

The default is .MR \*(dQ/postmd.ps .

Three options allow insertion of arbitrary PostScript at controlled points in the translation process:

0.75i .OP -C file Copy file to the output file; file must contain legitimate PostScript.

.OP -P string Include string in the output file; string must be legitimate PostScript.

.OP -R action Requests special action (e.g., .MR manualfeed ) on a per page or global basis. The action string can be given as request , M request : page\f1\|, or M request : page : file\f1\|. If page is omitted or given as 0, the request applies to all pages. If file is omitted, the request lookup is done in .MR \*(dQ/ps.requests .

Only one matrix is displayed on each logical page, and each of the input 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 postmd 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 using the .OP -d option overrides this default behavior, and in that case the dimensions apply to all input files .

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 only apply to the current input file. Recognized header keywords are .MR dimension , .MR interval , .MR grayscale , and .MR window . The syntax of the value string that follows each keyword parallels what is accepted by the .OP -d , .OP -i , .OP -g , and .OP -w options.

EXAMPLES
For example, suppose file initially contains the 1000 numbers in a 20\(mu50 matrix. Then the command line: .EX postmd -d20x50 -i"-100 100" -g0,128,254,128,0 \f2file and prepending the header, .EX dimension 20x50 interval -100.0 .100e+3 grayscale 0 128 254 128 0 to file and typing the command line: .EX postmd \f2file produce exactly the same output. 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 (i.e., black), numbers equal to -100 or 100 into 128 (i.e., 50 percent black), and numbers between -100 and 100 into 254 (i.e., almost white).
DIAGNOSTICS
A 0 exit status is returned if files were successfully processed.
WARNINGS
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 600\(mu600 matrix is an optimistic upper bound for a two element interval list (i.e. five regions) using 8.5\(mu11 inch paper on a 300 dpi printer.

Using white (i.e., 255) in a gray scale list is not recommended and will not show up in the legend and bar graph that postmd displays below each image.

FILES
.MW \*(dQ/postmd.ps

.MW \*(dQ/forms.ps

.MW \*(dQ/ps.requests

SEE ALSO
dpost (1), postdaisy (1), postdmd (1), postio (1), postprint (1), postreverse (1), posttek (1), psencoding (1)