.TH PSCHART 1 "6 August 2002" "WFDB 10.2.7" "WFDB Applications Guide"
.SH NAME
pschart \- produce annotated `chart recordings' on a PostScript device
.SH SYNOPSIS
\fBpschart\fR [ [ \fIoptions\fR ... ] \fIscript\fR ... ]
.SH DESCRIPTION
.PP
\fBpschart\fR produces high-quality annotated plots of WFDB records
on PostScript devices.  When rendered on a PostScript laser printer or
phototypesetter, the plots closely resemble those that appear on pages 99\-177
of the \fIMIT-BIH Arrhythmia Database Directory\fR.
.PP
\fBpschart\fR reads one or more \fIscript\fR files containing
newline-terminated commands.  Its standard output is a PostScript file suitable
for printing directly with no further processing.  By default, \fBpschart\fR
draws `zero-width' lines;  doing so typically reduces the printing time by a
factor of three for a first-generation (300 dpi) laser printer while producing
visually pleasing results.  If the output is destined for a high-resolution
(600 dpi or more) printer or phototypesetter, however, be sure to use the
\fB-d\fR option (see below), or the traces and grid will be invisible (or
nearly so).
.SS Options:
.TP
\fB-a\fR \fIann\fR
Print annotations from annotator \fIann\fR (default: `atr').  To suppress
annotation printing, use `\fB-a ""\fR'.
.TP
\fB-A\fR \fIann\fR
As for \fB-a\fR, but for a second annotator.  The second set of annotations
is shown below the first set.
.TP
\fB-b\fR \fIn\fR
Set the binding offset to \fIn\fR millimeters (default: 0).  The inside margin
is increased by \fIn\fR mm, and the outside margin is decreased by the same
amount.
.TP
\fB-c\fR \fIstring\fR
Print `Copyright \(co \fIstring\fR' in the left page footer;  \fIstring\fR may
include whitespace if it is quoted.  The characters `%d', if included in
\fIstring\fR, are replaced by the current year.  A default copyright notice is
printed if no \fB-c\fR option is specified.  To suppress printing the copyright
notice, use `\fB-c ""\fR'.
.TP
\fB-C\fR
Produce charts in color (default: black and white).
.TP
\fB-Ca\fR \fIr g b\fR
Draw annotations (if enabled) in the specified color. The color is
specified using three numerical arguments (with values between 0 and 1
inclusive) that indicate the amounts of red, green, and blue respectively.
Examples: \fB-Ca 0.5 0.5 1.0\fR produces light blue (the default obtained
using \fB-C\fR only); \fB-Ca 0 0.5 0\fR produces a deep green color.
.TP
\fB-Cg\fR \fIr g b\fR
Draw the grid (if enabled) in the specified color. Default: red (1 0 0).
.TP
\fB-Cl\fR \fIr g b\fR
Draw labels and other non-annotation text in the specified color.  Default:
black (0 0 0).
.TP
\fB-Cs\fR \fIr g b\fR
Draw signals in the specified color.  Default: deep blue (0 0 0.5).
.TP
\fB-d\fR \fIn\fR
Set up for using a printer with a resolution of \fIn\fR dots per inch (default:
\fIn\fR = 300, the typical resolution for laser printers).  For a
phototypesetter, \fIn\fR is typically 1200 or 2400.  Note that \fIn\fR
does not have to be correct in order to get properly scaled output;  the
value determines the granularity of the calculations made by \fBpschart\fR
and the line width used by the printer, but not the scales.
.TP
\fB-e\fR
Process even-numbered pages in a manner appropriate for two-sided printing.
Even-numbered pages are printed with reversed page headers, and with the
outside margin on the left (default: page headers are not reversed, and
the inside margin is always on the left).
.TP
\fB-E\fR
Generate EPSF format (encapsulated PostScript file format), suitable for
inclusion in another PostScript file.
.TP
\fB-g\fR
Print a 0.5 mV x 0.2 sec grid with 0.1 mV x 0.04 sec subticks under each strip
(default: no grid).  This grid is drawn using the \fBgrid\fR procedure in
the prolog file (see \fBENVIRONMENT\fR below).
.TP
\fB-G\fR
Print a 0.5 mV x 0.2 sec grid without subticks under each strip
(default: no grid).  This grid is drawn using the \fBGrid\fR procedure in
the prolog file (see \fBENVIRONMENT\fR below).
.TP
\fB-h\fR
Print a usage summary.
.TP
\fB-H\fR
Read the signal files in high-resolution mode (default: standard mode).
These modes are identical for ordinary records.  For multifrequency records,
the standard decimation of oversampled signals to the frame rate is suppressed
in high-resolution mode (rather, all other signals are resampled at the highest
sampling frequency).
.TP
\fB-i\fR \fIfile\fR
Print the (text) contents of \fIfile\fR instead of the title in the title area
of the first page of output.  The text is printed in a monospaced font;  use
spaces rather than tabs in the text to align columns.
.TP
\fB-l\fR
Label the signals in the margins next to each strip (default: no signal
labels).
.TP
\fB-L\fR
Print in landscape orientation (default: portrait orientation).
.TP
\fB-m\fR \fIinside outside top bottom\fR
Specify page margins in millimeters.  Defaults: \fItop\fR and \fIbottom\fR,
25 mm; \fIinside\fR and \fIoutside\fR, 25\-37.5 mm (half of the difference
between the page width and the default strip width).  The default strip width
is the largest multiple of 25 mm that is at least 50 mm less than the page
width.  Note that page headers and footers, time stamps, and signal labels are
printed in the margins.  Also note that hardware-enforced, printer-specific
margins are not included;  the margins specified using \fB-m\fR apply to the
imageable area, and not necessarily to the physical page.
.TP
\fB-M\fR
Print marker bars across the signals to show the locations of beat annotations
(equivalent to \fB-M1\fR).
.TP
\fB-M\fR\fIbarstyle\fR
Set marker bar and annotation format (note: no space between \fB-M\fR and
\fIbarstyle\fR).  Legal values for \fIbarstyle\fR: 0 (no bars); 1 (bars across
all signals); 2 (bars across attached signal, annotations at center);  3 (bars
across attached signal, annotations above bars).  Default: \fIbarstyle\fR = 0.
.TP
\fB-n\fR \fIn\fR
Use \fIn\fR as the number of the first page (default: 1).  Use `\fB-n 0\fR'
(or any negative value for \fIn\fR) to suppress page numbering.
.TP
\fB-p\fR
Pack sufficiently short strips side-by-side (default: print each strip centered
between the inside and outside margins in a row by itself).
.TP
\fB-P\fR \fIpagesize\fR
Specify the size of the output pages to be printed.  Legal values for
\fIpagesize\fR are: `letter' (8.5" x 11", 216 mm x 279 mm; imageable area
209 mm x 272 mm), `lwletter' (8.5" x 11", 216 mm x 279 mm; imageable area
203 mm x 277 mm), `legal' (8.5" x 14", 216 mm x 356 mm; imageable area
209 mm x 348 mm), `legal13' (8.5" x 13", 216 x 330 mm; imageable area 209 mm x
322 mm), `A4' (8.27" x 11.69", 210 mm x 297 mm; imageable area 202 mm x 289
mm), `A5' (5.84" x 8.27", 148 mm x 210 mm; imageable area 140 mm x 202 mm);
`B4' (9.84" x 13.9", 250 mm x 353 mm; imageable area 249 mm x 356 mm),
`B5' (6.93" x 9.84", 176 mm x 250 mm; imageable area 173 mm x 249 mm), or
`\fIwidth\fRx\fIheight\fR' (where \fIwidth\fR and \fIheight\fR are the width
and height of the imageable area in millimeters).  `lwletter' is the standard
letter size for the Apple LaserWriter;  all of the other predefined page sizes
are those used by the Sun SPARCprinter.  Note that some printers may require
non-standard PostScript code to select non-standard page sizes;  in such cases,
it may be necessary to customize the prolog file (see \fBFILES\fR).  Default:
letter size.
.TP
\fB-r\fR
Print ``Record \fIxxx\fR'' as the first part of the title of each strip, where
\fIxxx\fR is the record name.
.TP
\fB-R\fR
Print a record name as part of the header on each page.  If strips from two or
more records are printed on one page, the name of the last record is printed.
.TP
\fB-s\fR \fIsignal-list\fR
Print only the signals named in the \fIsignal-list\fR (one or more signal
numbers, separated by spaces;  default: print all signals).
.TP
\fB-S\fR \fIscale-mode timestamp-mode\fR
Print scales and timestamps in the specified modes.  Legal values for
\fIscale-mode\fR: 0 (no scales); 1 (mm/unit in footers); 2 (units/tick in
footers); 3 (mm/unit above strips); 4 (units/tick above strips); 5 (mm/unit
within strips); 6 (units/tick within strips).  Legal values for
\fItimestamp-mode\fR: 0 (no timestamps); 1 (elapsed times only); 2 (absolute
times if defined, elapsed times otherwise).  Defaults: \fIscale-mode\fR = 1,
\fItimestamp-mode\fR = 2.
.TP
\fB-t\fR \fIn\fR
Set the time scale to \fIn\fR millimeters per second (default: \fIn\fR = 12.5,
half of the standard scale for chart recorders).
.TP
\fB-T\fR \fItitle\fR
Set the page title to \fItitle\fR (which may include whitespace if quoted).
If no \fB-T\fR option is specified, the page title is constructed from the
date of the last recording on the page, if defined, or today's date otherwise.
To suppress printing the page title, use `\fB-T ""\fR'.
.TP
\fB-u\fR
Generate `unstructured' PostScript as a workaround for a bug in the Adobe
TranScript software (also see \fBENVIRONMENT\fR below).  Default: generate
structured PostScript, suitable for processing by page-selection or
page-reversal post-processors.
.TP
\fB-v\fR \fIn\fR
Set the voltage (ordinate) scale to \fIn\fR millimeters per millivolt.  Signals
that do not have units of millivolts (as specified in the record's header file)
are scaled proportionately, as specified by the calibration file (see
\fBwfdbcal\fR(5)).  The default scale is 5 mm/mV, half of the standard scale
for chart recorders.
.TP
\fB-V\fR
Verbose mode (echo each command as it is read from the script file).
.TP
\fB-w \fIn\fR
Set the line width for signals, grid lines, and marker bars to \fIn\fR mm.
Default: 0 (the narrowest possible width;  note that some devices may not
render zero-width lines correctly).
.TP
\fB-1\fR
Print only the first character of each comment annotation.
.SS Color output
If none of the \fB-C\fR options is used, output is in black and white.  If
any color option is used, output is in the default colors (light blue
annotations, red grid, black labels, deep blue signals) unless overridden
by one or more of the \fB-Ca\fR, \fB-Cg\fR, \fB-Cl\fR, or \fB-Cs\fR options.
Color output can be rendered in greyscale by monochrome PostScript printers,
although black-and-white output may look better in such cases.
.SS Scripts:
.PP
Any argument that is not an option or an option argument is taken as the
name of a script of newline-terminated commands to be executed by
\fBpschart\fR.  If the script name is `-', \fBpschart\fR reads commands from
the standard input.  Options that follow a script name are not applied to the
processing of that script, so it is possible to use two or more scripts with
different sets of options in a single run.  Standard commands are of the
following form:
.br
	\fIrecord\fR \fItime\fR \fItitle\fR
.br
in which \fIrecord\fR is the name of the record for which a strip is to be
printed, \fItime\fR indicates the time of the left edge of the strip to be
printed, and \fItitle\fR is a description to be printed above the strip.
Fields are separated by spaces or tabs.  If the \fItime\fR field contains a
hyphen (`-'), the portion that precedes the hyphen is taken as the time of the
left edge of the strip, and the portion that follows the hyphen indicates the
end of the desired segment;  additional strips continuous with the first are
printed if necessary.  Unless the \fB-p\fR option is specified, strips that
are less than the full width of the page are centered within the margins.  The
\fItitle\fR field may include embedded spaces or tabs, or it may be omitted.
A totally empty command line specifies a page break, i.e., it causes
\fBpschart\fR to put the next strip at the top of a new page, even if the
current page is not full.
.SH ENVIRONMENT
.PP
The environment variable \fBPSCHARTPRO\fR can be used to name an
alternate prolog file (see below) for custom formats.  The environment
variable \fBTRANSCRIPTBUG\fR may be set (to any value) to generate
`unstructured' PostScript by default (see the \fB-u\fR option above).
It may be necessary to set and export the shell variables \fBWFDB\fR
and \fBWFDBCAL\fR (see \fBsetwfdb\fR(1)).
.SH FILES
.TP
\fB/usr/local/lib/ps/pschart.pro\fR
default PostScript prolog file.
.TP
\fB/usr/local/lib/ps/12lead.pro\fR
alternative PostScript prolog file, suitable for printing standard 12-lead
diagnostic ECGs (10 seconds, 4 traces, with the top three traces divided into
2.5 second segments by marker bars).  This file redefines the grid drawn by
the \fB-G\fR option (see the \fBGrid\fR procedure for details).
.SH BUGS
.PP
On older PostScript printers, output may be quite slow.  A full page, with
grids and default scales, typically takes about 3 minutes to render on an Apple
LaserWriter, or about 6 minutes on a Linotronic 1200 dpi phototypesetter. Most
modern printers can render \fBpschart\fR output at nearly full speed.
.PP
If the record you wish to plot is sampled at a very high rate relative to the
printer resolution (i.e., if one sample interval would appear on the page as
much less than the distance between pixels), you may wish to use \fBxform\fR(1)
to decimate to a lower frequency for efficiency's sake.  In extreme cases, this
may be necessary to avoid running out of memory in your PostScript printer.
.PP
Specifying EPSF output using the \fB-E\fR option does not prevent \fBpschart\fR
from producing multi-page output, which is not permitted in EPSF.  You should
make sure that your output fits entirely onto one page (most easily verified
using the \fB-V\fR option) before including it in another document.  Note that
the bounding box calculated by \fBpschart\fR covers the entire width of the
page and most of its height (excluding only about half of the top and bottom
margins, so that the header and footer material is included), even if only a
small portion of the page contains plots.  If you wish to fit such a plot into
another document with a minimum of empty space around it, you may either edit
the bounding box comment in the \fBpschart\fR output, or specify a page size
that closely matches the size of your plot.  The document in which
\fBpschart\fR output is included can arbitrarily rescale the plot, so that
scales expressed in mm/unit cannot be relied upon.
.PP
Under MS-DOS, a bug in \fBcommand.com\fR makes it impossible to pass an empty
string in the argument list of a command, so that \fB-a ""\fR, \fB-c ""\fR, and
\fB-T ""\fR do not work as described above.  Type a space between the quotation
marks to avoid this bug, or use one of the UNIX shells that have been ported to
MS-DOS instead of \fBcommand.com\fR..
.PP
There are too many options.  Invoke \fBpschart\fR with no arguments for a
brief summary of options.
.SH SEE ALSO
\fBpsfd\fR(1), \fBsetwfdb\fR(1), \fBview\fR(1), \fBwave\fR(1), \fBwview\fR(1),
\fBxform\fR(1)
.SH AUTHOR
George B. Moody (george@mit.edu)
.SH SOURCES
http://www.physionet.org/physiotools/wfdb/app/pschart.c
.br
http://www.physionet.org/physiotools/wfdb/app/pschart.pro