path: root/usr/src/man/man1/postmd.1

'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH postmd 1 "9 Sep 1996" "SunOS 5.11" "User Commands"
.SH NAME
postmd \- matrix display program for PostScript printers
.SH SYNOPSIS
.LP
.nf
\fBpostmd\fR [\fB-b\fR \fInum\fR] [\fB-c\fR \fInum\fR] [\fB-d\fR \fIdimen\fR] [\fB-g\fR \fIlist\fR] [\fB-i\fR \fIlist\fR] 
     [\fB-m\fR \fInum\fR] [\fB-n\fR \fInum\fR] [\fB-o\fR \fIlist\fR] [\fB-p\fR \fImode\fR] [\fB-w\fR \fI window\fR] 
     [\fB-x\fR \fInum\fR] [\fB-y\fR \fInum\fR] [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/lib/lp/postscript/postmd\fR 
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpostmd\fR filter reads a series of floating point numbers from
\fIfile\fRs, 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 \fIfile\fRs are
specified, or if \fB-\fR is one of the input \fIfile\fRs, the standard input is
read.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-b\fR \fInum\fR\fR
.ad
.RS 13n
.rt  
Packs the bitmap in the output file using \fInum\fR byte patterns. A value of
\fB0\fR turns off all packing of the output file. By default, \fInum\fR is
\fB6\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-c\fR \fInum\fR\fR
.ad
.RS 13n
.rt  
Prints \fInum\fR copies of each page. By default, only one copy is printed.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-d\fR \fIdimen\fR\fR
.ad
.RS 13n
.rt  
Sets the default matrix dimensions for all input \fIfile\fRs to \fIdimen\fR.
The \fIdimen\fR string can be given as \fIrows\fR or \fIrows\fR\fBx\fR
\fIcolumns\fR. If \fIcolumns\fR is omitted it will be set to rows. By default,
\fBpostmd\fR 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.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-g\fR \fIlist\fR\fR
.ad
.RS 13n
.rt  
\fIlist\fR 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 \fB-i\fR option. 255 corresponds to white, and
0, to black. The \fBpostmd\fR 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.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-i\fR \fIlist\fR\fR
.ad
.RS 13n
.rt  
\fIlist\fR is a comma-, space-, or slash(\fB/\fR)-separated string of  \fIN\fR
floating point numbers that partition the real line into 2\fIN\fR+1 regions.
The \fIlist\fR must be given in increasing numerical order. The partitions are
used  to map floating point numbers read from the input \fIfile\fRs into gray
scale integers that are either assigned automatically by \fBpostmd\fR or
arbitrarily selected using the \fB-g\fR option. The default interval \fIlist\fR
is \fB-1,0,1\fR, which partions the real line into seven regions.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-m\fR \fInum\fR\fR
.ad
.RS 13n
.rt  
Magnifies each logical page by the factor \fInum\fR. Pages are scaled uniformly
about the origin which, by default, is located at the center of each page. The
default magnification is \fB1.0\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-n\fR \fInum\fR\fR
.ad
.RS 13n
.rt  
Prints \fInum\fR logical pages on each piece of paper, where \fInum\fR can be
any positive integer. By default, \fInum\fR is set to  \fB1\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-o\fR \fIlist\fR\fR
.ad
.RS 13n
.rt  
Prints pages whose numbers are given in the comma separated \fIlist\fR. The
list contains single numbers \fIN\fR and ranges \fIN1 \fR- \fIN2\fR. A missing
\fIN1\fR means the lowest numbered page, a missing \fIN2\fR means the highest.
The page range is an expression of logical pages rather than physical sheets of
paper. For example, if you are printing two logical pages to a sheet, and you
specified a range of \fB4\fR, then two sheets of paper would print, containing
four page layouts. If you specified a page range of \fB3-4\fR, when requesting
two logical pages to a sheet; then \fIonly\fR page 3 and page 4 layouts would
print, and they would appear on one physical sheet of paper.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR \fImode\fR\fR
.ad
.RS 13n
.rt  
Prints \fIfile\fRs in either portrait or landscape \fImode\fR. Only the first
character of \fImode\fR is significant. The default \fImode\fR is portrait.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-w\fR \fIwindow\fR\fR
.ad
.RS 13n
.rt  
\fIwindow\fR 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 \fIfiles\fR. Row and column indices start at \fB1\fR in the upper left
corner and the numbers in the input \fIfile\fRs are assumed to be written in
row major order. By default, the entire matrix is displayed.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-x\fR \fInum\fR\fR
.ad
.RS 13n
.rt  
Translates the origin \fInum\fR 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 \fInum\fR moves everything
right. The default offset is  \fB0\fR inches.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-y\fR \fI num\fR\fR
.ad
.RS 13n
.rt  
Translates the origin \fInum\fR inches along the positive y axis. Positive
\fInum\fR moves everything up the page. The default offset is  \fB0\fR.
.RE

.sp
.LP
Only one matrix is displayed on each logical page, and each of the input
\fIfile\fRs 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, \fBpostmd\fR 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 \fB-d\fR
option overrides this default behavior, and in that case the dimensions apply
to all input \fIfile\fRs.
.sp
.LP
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 \fBdimension\fR, \fBinterval\fR,
\fBgrayscale\fR, and \fBwindow\fR. The syntax of the value string that follows
each keyword  parallels what is accepted by the \fB-d\fR, \fB-i\fR, \fB-g\fR,
and \fB-w\fR options.
.SH EXAMPLES
.LP
\fBExample 1 \fRGenerating an interval list
.sp
.LP
For example, suppose \fIfile\fR initially contains the 1000 numbers in a 20x50
matrix. Then you can produce exactly the same output by completing three steps.

.RS +4
.TP
1.
First, issue the following command line:
.sp
.in +2
.nf
example% \fBpostmd -d20x50 -i"-100 100" -g0,128,254,128,0 file\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
2.
Second, prepend the following header to \fBfile\fR:
.sp
.in +2
.nf
example% \fBpostmd -d20x50 -i"\(mi100 100" -g0,128,254,128,0 file\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
3.
Third, issue the following command line:
.sp
.in +2
.nf
example% \fBpostmd file\fR
.fi
.in -2
.sp

.RE
.sp
.LP
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 FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/lib/lp/postscript/forms.ps\fR\fR
.ad
.sp .6
.RS 4n

.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/lib/lp/postscript/ps.requests\fR\fR
.ad
.sp .6
.RS 4n

.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 12n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fBnon-zero\fR
.ad
.RS 12n
.rt  
An error occurred.
.RE

.SH SEE ALSO
.sp
.LP
\fBdpost\fR(1), \fBpostdaisy\fR(1), \fBpostdmd\fR(1), \fBpostio\fR(1),
\fBpostprint\fR(1), \fBpostreverse\fR(1), \fBposttek\fR(1), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
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 by 600 matrix is an optimistic upper bound for a two element interval list
(that is, five regions) using 8.5 by 11 inch paper on a 300 dpi printer.
.sp
.LP
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 \fBpostmd\fR displays below each
image.