% terminals.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: terminals.tex 1261 2012-07-11 21:38:05Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Producing image files}
\label{ch:image_formats}

Pyxplot is able to produce graphical output in a wide range of image formats,
including both vector graphic formats such as PostScript and scalable vector
graphics ({\tt svg}), and rasterised formats such as bitmap ({\tt bmp}) and
jpeg. Additionally, it can produce graphical output for immediate preview on
screen. In this chapter we describe how to select and control which image
format should be used.

\section{The {\tt set terminal} command}
\label{sec:set_terminal}

The \indcmdt{set terminal} is used to select the image format in which output
should be produced, and also to specify a range of fine controls such as
whether output should be in color or black-and-white. In its simplest usage,
the command is followed by the name of the output image format which is to be
used, which may be any of the options listed in Table~\ref{tab:output_terminals}.

\begin{table}
\centerline{\includegraphics[width=9cm]{examples/eps/ex_set_terminal}}
\caption{A list of the properties of the graphical output formats supported by Pyxplot.}
\label{tab:output_terminals}
\end{table}

\subsection{Previewing graphs on the screen}
\index{X11 terminal}

Three output terminal produce immediate previews to the screen: {\tt
X11\_\-single\-Window}, {\tt X11\_\-persist}, {\tt X11\_\-multi\-Window}.  The
default of these options -- i.e.\ the default terminal when Pyxplot is started
up in interactive mode -- is {\tt X11\_\-single\-Window}.  In this terminal,
each time a new plot is generated, if the previous plot is still open on the
display, the old plot is replaced with the new one. This way, only one plot
window is open at any one time. This behaviour is intended to prevent the
desktop from becoming flooded with plot windows.

The alternative {\tt X11\_\-multi\-Window} terminal is similar in all respects
except that each new plot is generated in a new window, regardless of whether
any previous plots are still open on the display. This is especially useful
when multiple plots are to be compared side-by-side:\index{multiple windows}

\begin{verbatim}
set terminal X11_singleWindow
plot 'data1.dat'
plot 'data2.dat'  <-- first plot window disappears
\end{verbatim}

\noindent c.f.:

\begin{verbatim}
set terminal X11_multiWindow
plot 'data1.dat'
plot 'data2.dat'  <-- first plot window remains
\end{verbatim}

The third of these terminals, {\tt X11\_\-persist}, is similar to {\tt
X11\_\-multi\-Window} but keeps plot windows open after Pyxplot terminates in
distinction from the above two terminals, which close all plot windows upon
exit.

\subsection{Producing images on disk}

The remaining terminals listed in Table~\ref{tab:output_terminals} direct
graphical output to disk in a selection of rasterised and vector graphics
formats. The filename of the resulting image file may be set using the
\indcmdt{set output}, as in the example:

\begin{verbatim}
set output 'my_plot.eps'
\end{verbatim}

Use of rasterised image formats inevitably results in some loss of image
quality since the plot has to be rasterised into a bitmapped graphic image. By
default, this rasterisation is performed at a resolution of
$300\,\mathrm{dpi}$, though this may be changed using the \indcmdt{set terminal
dpi}, which should be followed by a numerical value. Alternatively, the
resolution may be changed using the {\tt DPI} option in the {\tt settings}
section of a configuration file (see Chapter~\ref{ch:configuration}).\index{set
terminal command!dpi modifier@{\tt dpi} modifier}\index{bitmap
output!resolution}\index{image resolution}

\subsection{The complete syntax of the {\tt set terminal} command}

In addition to being used to select the graphical format in which output should
be produced, the \indcmdt{set terminal} takes many options for fine-tuning the
behaviours of particular terminals. Its complete syntax is:

\begin{verbatim}
set terminal ( X11_singleWindow | X11_multiWindow | X11_persist |
               bmp | eps | gif | jpeg | pdf | png | postscript |
               svg | tiff )
             ( color | colour | monochrome )
             ( dpi <value> )
             ( portrait | landscape )
             ( invert | noinvert )
             ( transparent | solid )
             ( antialias | noantialias )
             ( enlarge | noenlarge )
\end{verbatim}

The following table lists the effects which each of these settings has:

\begin{longtable}{p{3cm}p{9cm}}
{\tt X11\_singleWindow} & Displays plots on the screen (in X11 windows, using \ghostview or other viewing application selected using the \indcmdt{set viewer}). Each time a new plot is generated, it replaces the old one, to prevent the desktop from becoming flooded with old plots.\footnote{The authors are aware of a bug, that this terminal can occasionally go blank when a new plot is generated. This is a known bug in \ghostview, and can be worked around by selecting File $\to$ Reload within the \ghostview\ window.} {\bf [default when running interactively; see below]}\\
{\tt X11\_multiWindow} & As above, but each new plot appears in a new window, and the old plots remain visible. As many plots as may be desired can be left on the desktop simultaneously.\\
{\tt X11\_persist} & As above, but plot windows remain open after Pyxplot closes.\\
{\tt bmp} & Sends output to a Windows bitmap ({\tt .bmp}) file. The filename for this file should be set using {\tt set output}. This is a bitmap graphics terminal. \index{bmp output}\\
{\tt eps} & As above, but produces Encapsulated PostScript.\index{Encapsulated PostScript}\index{PostScript!Encapsulated}\\
{\tt gif} & As above, but produces a gif image. This is a bitmap graphics terminal.\index{gif output}\\
{\tt jpeg} & As above, but produces a jpeg image. This is a bitmap graphics terminal.\index{jpeg output}\\
{\tt pdf} & As above, but produces pdf output.\index{pdf output}\\
{\tt png} & As above, but produces a png image. This is a bitmap graphics terminal.\index{png output}\\
{\tt postscript} & As above, but sends output to a PostScript file. {\bf [default when running non-interactively; see below]}\index{PostScript output}\\
{\tt svg} & As above, but produces an svg image.\footnote{The {\tt svg} output terminal is experimental and may be unstable. It relies upon the use of the {\tt svg} output device in Ghostscript, which may not be present on all systems.}\index{svg output}\\
{\tt tiff} & As above, but produces a tiff image. This is a bitmap graphics terminal.\index{tiff output}\\
{\tt color} & Allows datasets to be plotted in color. Automatically they will be displayed in a series of different colors, or alternatively colors may be specified using the {\tt with color} plot modifier (see below). {\bf [default]}\index{color output}\\
{\tt color} & Equivalent US spelling of the above. \\
{\tt monochrome} & Opposite to the above; all datasets will be plotted in black by default.\index{monochrome output}\\
{\tt dpi} & Sets the number of dots per inch at which rasterised graphic output should be sampled (i.e.\ the output image resolution)\\
{\tt portrait} & Sets plots to be displayed in upright (normal) orientation. {\bf [default]}\index{portrait orientation}\\
{\tt landscape} & Opposite of the above; produces side-ways plots. Not very useful when displayed on the screen, but you fit more on a sheet of paper that way around.\index{landscape orientation}\\
{\tt invert} & Modifier for the bitmap output terminals identified above -- i.e.\ the {\tt bmp}, {\tt gif}, {\tt jpeg}, {\tt png} and {\tt tiff} terminals -- which produces output with inverted colors.\footnote{This terminal setting is useful for producing plots to embed in talk slideshows, which often contain bright text on a dark background. It only works when producing bitmapped output, though a similar effect can be achieved in PostScript using the {\tt set textcolor} and {\tt set axescolor} commands (see Section~\ref{sec:set_colors}).}\index{colors!inverting}\\
{\tt noinvert} & Modifier for the bitmap output terminals identified above; opposite to the above. {\bf [default]}\\
{\tt transparent} & Modifier for the {\tt gif} and {\tt png} terminals; produces output with a transparent background.\index{transparent terminal}\index{gif output!transparency}\index{png output!transparency}\\
{\tt solid} & Modifier for the {\tt gif} and {\tt png} terminals; opposite to the above. {\bf [default]}\\
{\tt antialias} & Modifier for the bitmap output terminals identified above; produces antialiased output, with color boundaries smoothed to disguise the effects of pixelisation {\bf [default]}\\
{\tt noantialias} & Modifier for the bitmap output terminals identified above; opposite to the above\\
{\tt enlarge} & Enlarge or shrink contents to fit the current paper size.\index{enlarging output}\\
{\tt noenlarge} & Do not enlarge output; opposite to the above. {\bf [default]}\\
\end{longtable}

\section{The default terminal}

The default terminal is normally {\tt X11\_singleWindow}. There are two
exceptions to this.  When Pyxplot is not called from within an X11
session\footnote{i.e.\ the environment variable {\tt DISPLAY} is not set.}, and
it therefore cannot open graphical display windows, the default terminal
changes to {\tt eps}.  When Pyxplot is used non-interactively -- i.e.\ one or
more command scripts are specified on the command line, and Pyxplot exits as
soon as it finishes executing them -- the {\tt X11\_persist} terminal becomes
default, since it does not close plot windows when Pyxplot exits.

\section{PostScript output}

If the {\tt enlarge} modifier is used with the \indcmdt{set terminal} then the
whole plot is enlarged, or, in the case of large plots, shrunk, to the current
paper size, minus a small margin. The aspect ratio of the plot is preserved.

\subsection{Paper sizes}
\label{sec:set_papersize}

By default, the {\tt postscript} terminal, and the {\tt enlarge} terminal
option, read the paper size for their output from the user's system locale
settings. It may be changed, however, with \indcmdt{set papersize}, which may
be followed either by the name of a recognised paper size, or by the dimensions
of a user-defined size, specified as a {\tt height}, {\tt width} pair, both
being measured in millimetres. For example:

\begin{verbatim}
set papersize a4
set papersize 100,100
\end{verbatim}

\noindent A complete list of recognised paper size names can be found in
Appendix~\ref{ch:paper_sizes}.\footnote{Marcus Kuhn has written a very complete
treatise on international paper sizes, which can be downloaded from:
\url{http://www.cl.cam.ac.uk/~mgk25/iso-paper.html}. Further details on the
Swedish extensions to this system, and the Japanese B-series, can be found on
Wikipedia: \url{http://en.wikipedia.org/wiki/Paper_size}.}\index{Kuhn,
Marcus}\index{paper sizes}

\section{Backing up over-written files}
\index{overwriting files}\index{backup files}\label{sec:file_backup}

By default, when graphical output is sent to a file -- i.e.\ a PostScript file
or a bitmap image -- any pre-existing file is overwritten if its filename
matches that of the file which Pyxplot generates. This behaviour may be changed
with the \indcmdt{set backup}, which has the syntax:

\begin{verbatim}
set backup
set nobackup
\end{verbatim}

When this switch is turned on, pre-existing files will be renamed with a tilde
($\sim$) appended to their filenames, rather than being overwritten.

\section{Changing font}
\index{font!changing}\index{sans-serif}

The font used by Pyxplot can be changed using the \indcmdt{set preamble}.  In
latex, fonts are changed by adding a header to a document, and the \indcmdt{set
preamble} specifies text that should be passed to latex before rendering any of
the text labels on the present canvas.  For example, the following command
changes the default font to sans-serif:

\begin{verbatim}
set preamble r"\renewcommand{\familydefault}{\sfdefault}"
\end{verbatim}