Subversion Repositories planix.SVN

.ds dQ /usr/lib/postscript

.TH POSTMD 1 "DWB 3.2"

.SH NAME

.B postmd

\- matrix display program for PostScript printers

.SH SYNOPSIS

\*(mBpostmd\f1

.OP "" options []

.OP "" files []

.SH DESCRIPTION

.B postmd

reads a series of floating point numbers from

.IR 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

.OP \-

is one of the input

.IR files ,

the standard input is read.

The following

.I options

are understood:

.TP 0.75i

.OP \-b num

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

.OP \-c num

Print

.I num

copies of each page.

By default only one copy is printed.

.TP

.OP \-d dimen

Sets the default matrix dimensions for all input

.I files

to

.IR dimen .

The

.I dimen

string can be given as rows or rows\^\(mu\^columns.

If columns is omitted it will be set to rows.

By default

.B 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.

.TP

.OP \-g list

.I list

is a comma- or space-separated string of integers, each lying between

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.

.B 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.

.TP

.OP \-i list

.I list

is a comma- or space-separated string of

.I N

floating point numbers that

partition the real line into

.RI 2 N +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 assigned automatically by

.B postmd

or arbitrarily selected using the

.OP \-g

option.

The default interval

.I list

is ``\*(mB\-1,0,1\fP'' which partions the real line into 7 regions.

.TP

.OP \-m num

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

.OP \-n num

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

.OP \-o list

Print pages whose numbers are given in the comma separated

.IR list .

The list contains single numbers

.I N

and ranges

.IR N1\-\|N2 .

A missing

.I N1

means the lowest numbered page, a missing

.I N2

means the highest.

.TP

.OP \-p mode

Print

.I files

in either \*(mBportrait\fP or \*(mBlandscape\fP

.IR mode .

Only the first character of

.I mode

is significant.

The default

.I mode

is \*(mBportrait\fP.

.TP

.OP \-w window

.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

.OP \-x num

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

.OP \-y num

Translate the origin

.I num

inches along the positive y axis.

Positive

.I num

moves everything up the page.

The default offset is 0.

.TP

.OP \-E name

Set the character encoding for text fonts to

.IR name .

Requesting

.I name

means include file

.MI \*(dQ/ name .enc \f1.

A nonexistent encoding file is silently ignored.

The default selects file

.MR \*(dQ/Default.enc .

.TP

.OP \-L file

Use

.I file

as the PostScript prologue.

.br

The default is

.MR \*(dQ/postmd.ps .

.PP

Three options allow insertion of arbitrary PostScript

at controlled points in the translation process:

.TP 0.75i

.OP \-C file

Copy

.I file

to the output file;

.I file

must contain legitimate PostScript.

.TP

.OP \-P string

Include

.I string

in the output file;

.I string

must be legitimate PostScript.

.TP

.OP \-R action

Requests special

.I action

(e.g.,

.MR manualfeed )

on a per page or global basis.

The

.I action

string can be given as

.IR request ,

.IM request : page\f1\|,

or

.IM request : page : file\f1\|.

If

.I page

is omitted or given as 0, the request

applies to all pages.

If

.I file

is omitted, the request

lookup is done in

.MR \*(dQ/ps.requests .

.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

.B 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

.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 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.

.SH EXAMPLES

For example, suppose

.I 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

.EE

and prepending the header,

.EX

dimension 20x50

interval -100.0 .100e+3

grayscale 0 128 254 128 0

.EE

to

.I file

and typing the command line:

.EX

postmd \f2file

.EE

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).

.SH DIAGNOSTICS

A 0 exit status is returned if

.I files

were successfully processed.

.SH 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.

.PP

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

.B postmd

displays below each image.

.SH FILES

.MW \*(dQ/postmd.ps

.br

.MW \*(dQ/forms.ps

.br

.MW \*(dQ/ps.requests

.SH SEE ALSO

.BR dpost (1),

.BR postdaisy (1),

.BR postdmd (1),

.BR postio (1),

.BR postprint (1),

.BR postreverse (1),

.BR posttek (1),

.BR psencoding (1)