
% This file must be processed by pdfLaTeX three times.
% In the next step run
%    ppower4 png2pdf.pdf docu.pdf
% and view docu.pdf

\documentclass[12pt,a4paper,titlepage]{article}
\usepackage{lscape}
\usepackage{ifpdf}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{mathptmx}
\usepackage[scaled=.92]{helvet}
\usepackage{courier}
\usepackage{array}
\usepackage{enumerate}
\usepackage{longtable}
\usepackage{latexsym}
\usepackage{varioref}
\usepackage{color}
\ifpdf
\usepackage[activate=normal]{pdfcprot}
\usepackage[pdftex]{graphicx}
\usepackage{epstopdf}
\usepackage{background}
\usepackage{pause}
\pdfcompresslevel=9
\usepackage[
  pdftex,
  a4paper=true,
  pdftitle={png2pdf},
  pdfsubject={Using the png2pdf program},
  pdfauthor={Dipl.-Ing. D. Krause},
  colorlinks=true,
  linkcolor=black,
  pdfpagemode=None,
  pdfstartview=FitH
]{hyperref}
\definecolor{bgred}{rgb}{1.0,0.501961,0.501961}
\definecolor{bgblue}{rgb}{0.8,0.8,1}
\else
\usepackage[dvips]{graphicx}
\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
\usepackage[
  dvips,
  colorlinks=true,
  linkcolor=black
]{hyperref}
\definecolor{bgred}{rgb}{1.0,0.501961,0.501961}
\definecolor{bgblue}{rgb}{0.8,0.8,1}
\fi
\usepackage{listings}
\lstset{numbers=left, numberstyle=\tiny, numbersep=5pt, basicstyle=\small}
\lstset{showstringspaces=true}
% \setlength{\parindent}{0cm}
\author{Dipl.-Ing.~D.~Krause}
\title{The png2pdf program}

\begin{document}
\begin{sloppy}
\maketitle
\cleardoublepage
\ifpdf\pdfbookmark[1]{\contentsname}{tocanc}\fi
\tableofcontents
\cleardoublepage
\section{Overview}
The png2pdf program can be used to convert \textsc{png} image files to
\textsc{pdf} files.
If the \textsc{png} file contains an alpha channel one can mix the image
against a background color and/or create a \textsc{pdf} image mask or
\textsc{pdf} transparency data.

The program is mainly intended for pdfLaTeX users who want to
create flyers or posters having colored background.
\clearpage
\section{Installation}
\subsection{Installation from source on \textsc{unix} systems}
\subsubsection{Prerequisitions}
The following software packages should be installed before
you start to install png2pdf:
\begin{itemize}
\item	\textbf{zlib} (required)\\*
A general purpose compression library\footnote{\url{http://www.gzip.org/zlib}}.
\item	\textbf{libpng} (required)\\*
A library for dealing with \textsc{png}
images\footnote{\url{http://www.libpng.org/pub/png/libpng.html}}.
\item	\textbf{libbz2} (recommended)\\*
Another compression library\footnote{\url{http://sources.redhat.com/bzip2}}.
\item	\textbf{dklibs} (required)\\*
Dirk Krause's libraries\footnote{\url{http://sourceforge.net/projects/dklibs}}.
\end{itemize}
The png2pdf software can be retrieved on the SourceForge project
website\footnote{\url{http://sourceforge.net/projects/png2pdf}}.
Documentation is available via the project homepage also hosted at
SourceForge\footnote{\url{http://png2pdf.sourceforge.net}}.
\subsubsection{Installation procedure}
\paragraph{zlib, libpng, libbz2 and dklibs}~\\
These libraries are installed as usual by running
\begin{lstlisting}
  ./configure
  make
  make install
\end{lstlisting}
\clearpage
\paragraph{png2pdf}~\\
Make sure the environment variables \textsc{cflags} and \textsc{ldflags}
are set properly to point into the ``include'' and ``lib'' subdirectories
of the installation directories for the libraries listed above. The
\textsc{cflags} variable should contain something like ``-I/usr/local/include'',
the \textsc{ldflags} variable ``-L/usr/local/lib''.

Both variables must not point to the directory created while unpacking
the dklibs source archive and used to build dklibs! Reason: There are
two different versions of the ``dkconfig.h'' file. An initial version is
shipped with the dklibs distribution, it includes the ``config.h'' file
created by the configure script. During installation a final version
is written to ``/usr/local/include/dkconfig.h'', this file must be used
by applications linked against the dklibs libraries. If the initial version
is used instead, it loads the ``config.h'' file but finds the application's
file instead of the file created for the dklibs project. Many
\#define instructions will be missing in this case!

After making sure to have the correct values for \textsc{cflags}
and \textsc{ldflags} run
\begin{lstlisting}
  ./configure
  make
  make install
\end{lstlisting}
to install the software.

\subsection{Executable setup for Windows}
For Windows users there is a setup.exe available via the
dklibs project website
\footnote{\url{http://sourceforge.net/projects/dklibs}}.
In the file releases section you find dklibs-win32-*.*.* containing
two files dklibs-win32-*.*.*-*-setup.exe. Choose the highest version
number for the recent version. The ``user'' file installs the dklibs-based
software and documentation, the ``dev'' file also installs all used sources.
\emph{Note:} The ``dev'' file is significantly larger.
\clearpage
\section{Usage}
\subsection{Common dkapp options}
The program uses the dklibs library set for preferences handling,
localization, logging etc.
At program startup the permanent options are read first before
processing command line options. The options used are the result
of combining the permanent options and the command line options.
\subsubsection{Help and version information}
\begin{itemize}
\item	-h\\*
-\/-help\\*
shows a help text.
\item	-v\\*
-\/-version\\*
shows version information.
\end{itemize}
\subsubsection{Permanent options handling}
\begin{itemize}
\item	-c \textit{options}\\*
-\/-configure \textit{options}\\*
configures permanent options (preferences).
\item	-u\\*
-\/-unconfigure\\*
removes all permanent options.
\item	-C\\*
-\/-show-configuration\\*
shows the permanent options.
\item	-r \textit{options}\\*
-\/-reset \textit{options}\\*
overrides the permanent options for this program invokation and
uses the command line options only.
\end{itemize}
\subsection{Png2pdf options}
\begin{itemize}
\item	-p 1.2\\*
-p 1.3\\*
-p 1.4\\*
-\/-pdf-level=1.2\\*
-\/-pdf-level=1.3\\*
-\/-pdf-level=1.4\\*
chooses the \textsc{pdf} format version.
\item	-m \textit{r,g,b}\\*
--mix-background=\textit{r,g,b}\\*
sets a default background color for color mixing. This background
color is used if the \textsc{png} file does not contain a background chunk
or if the -s option is used (see below).\\*
-m-\\*
--mix-background=-\\*
turns explicit mixing off and leaves this up to the libpng library.
\item	-s\\*
-\/-mix-specified\\*
ignores the background chunk contained in the \textsc{png} file. The program
uses the background specified in the -m option (see above) regardless
whether or not the \textsc{png} file contains a background chunk.\\*
-s-\\*
-\/-mix-specified=off\\*
disables this behaviour.
\item	-a\\*
-\/-transparency\\*
passes alpha channel data from the \textsc{png} file to the \textsc{pdf} file. This
feature is available for \textsc{pdf} format 1.4 only.\\*
-a-\\*
-\/-transparency=off\\*
denies writing of alpha channel information to the \textsc{pdf} file.
\item	-i\\*
-\/-image-mask\\*
converts the alpha channel from the \textsc{png} file into a \textsc{pdf} image mask.
This requires \textsc{pdf} format 1.3 or above. By default all pixels having
opacity 0 are masked out. The -l option (see below) inverts the
level so only pixels with full opacity are drawn, all others are masked
out.\\*
-i-\\*
-\/-image-mask=off\\*
disables image mask generation.
\item	-l\\*
-\/-invert-levels\\*
can be used in conjunction with -i to invert the image mask level.\\*
-l-\\*
-\/-invert-levels=off\\*
switches back to normal imake mask level.
\item	-t\\*
-\/-alpha-transparency\\*
indicates that the alpha channel contains transparency data.\\*
By default alpha channel data is interpreted as opacity.\\*
\item	-t-\\*
-\/-alpha-transparency=off\\*
switches back to default behaviour (alpha channel is opacity).
\item	-b\\*
-\/-fill-background\\*
can be used in conjunction with -a or -i to fill the image are with
the default background color before applying the image.\\*
-b-\\*
-\/-fill-background=off\\*
turns background filling off.
\item	-n\\*
-\/-interpolation\\*
adds an entry to the image dictionary indicating that viewers should
attempt an image interpolation to obtain smoother transitions.\\*
Use with care. Image interpolation is not supported for all output
devices. Different viewers may use different algorithms. So the
representation of the image may vary depending on the viewer software
and output device.
\item	-f\\*
-\/-file-time-check\\*
inspects the modification time of source \textsc{png} and destination \textsc{pdf} file
when png2pdf is run on a directory.\\*
-f-\\*
-\/-file-time-check=off\\*
turns modification time inspection off (and forces a conversion for
all files).
\end{itemize}
\clearpage
\section{Examples}
\subsection{Overview}
\begin{figure}[ht]
{\centering
\includegraphics[width=5cm]{fbt.png}
\caption{The original image, \textsc{png} file directly included by pdf\LaTeX{}}
\label{img:fbt}
}
\end{figure}
In the examples section we use the image fbt.png. This image contains
a clock showing 5 before 12. The hour dots and the center of the clock
are fully opaque, the white center becomes more and more transparent when
moving from the image center to the image borders.
See figure~\vref{img:fbt}.
The image was included using
\lstset{language={TeX}}
\begin{lstlisting}
  \begin{figure}[ht]
  {\centering
  \includegraphics[width=5cm]{fbt.png}
  \caption{The original image}
  \label{img:fbt}
  }
  \end{figure}
\end{lstlisting}
\lstset{language={}}
The LaTeX source must be processed using pdfLaTeX three times
to make sure to have all labels and bookmarks recognized.
The next step in processing is to run ppower4 to have the background
effects.
Among others the packages color, ifthen, ifpdf, background and pause are needed
for the examples.
\clearpage
\subsection{Explicit background color}
\begin{figure}[ht]
{\centering
\ifpdf
\includegraphics[width=5cm]{x1.pdf}
\else
\includegraphics[width=5cm]{x1.eps}
\fi
\caption{Now mixed against white background}
\label{img:b2}
}
\end{figure}
Using the commands
\begin{lstlisting}
  bmeps -p2 -c -er8 fbt.png x1.eps
  png2pdf -m 255,255,255 -s fbt.png x1.pdf
\end{lstlisting}
we create an EPS and a \textsc{pdf} version of the image.
The image is included using
\lstset{language={TeX}}
\begin{lstlisting}
  \begin{figure}[ht]
  {\centering
  \ifpdf
  \includegraphics[width=5cm]{x1.pdf}
  \else
  \includegraphics[width=5cm]{x1.eps}
  \fi
  \caption{Now mixed against a white background}
  \label{img:b2}
  }
  \end{figure}
\end{lstlisting}
\lstset{language={}}
\clearpage
\pagecolor{bgred}
\subsection{Colored background}
\label{sec:unique-colored-background}
\begin{figure}[ht]
{\centering
\ifpdf
\includegraphics[width=5cm]{x2.pdf}
\else
\includegraphics[width=5cm]{x2.eps}
\fi
\caption{Now mixed against light red background}
\label{img:b3}
}
\end{figure}
Now we create a light red background using
\begin{lstlisting}
  \pagecolor{bgred}
\end{lstlisting}
The images files are created by running
\begin{lstlisting}
  bmeps -p3 -c -e8f -am255,128,128s fbt.png x2.eps
  png2pdf -m 255,128,128 -s fbt.png x2.pdf
\end{lstlisting}
This image was included using
\lstset{language={TeX}}
\begin{lstlisting}
  \begin{figure}[ht]
  {\centering
  \ifpdf
  \includegraphics[width=5cm]{x2.pdf}
  \else
  \includegraphics[width=5cm]{x2.eps}
  \fi
  \caption{Now mixed against light red background}
  \label{img:b3}
  }
  \end{figure}
\end{lstlisting}
\lstset{language={}}
\clearpage
\ifpdf\vpagecolor{bgred}\fi
\subsection{Background effects}
\subsubsection{Mixing against background color}
\begin{figure}[ht]
{\centering
\ifpdf
\includegraphics[width=5cm]{x2.pdf}
\else
\includegraphics[width=5cm]{x2.eps}
\fi
\caption{Still the same image mixed against light red background}
\label{img:b4}
}
\end{figure}
On this page we have a color effect, the top of the page is light
red as on the previous page, the bottom is lighter.
Including the images from section~\vref{sec:unique-colored-background}
results in a visible rectangle background, see figure~\vref{img:b4}.
Depending on the \textsc{pdf} level we can use we have two choices:
\begin{itemize}
\item	Mixing against a constant background and adding an image
	mask (\textsc{pdf} level 1.3 and above) or
\item	Passing the alpha channel to the \textsc{pdf} file (\textsc{pdf} level 1.4).
\end{itemize}
\clearpage
\subsubsection{Adding an image mask}
\begin{figure}[ht]
{\centering
\ifpdf
\includegraphics[width=5cm]{x3.pdf}
\else
\includegraphics[width=5cm]{x3.eps}
\fi
\caption{Image containing image mask}
\label{img:b5}
}
\end{figure}
We create a \textsc{pdf} file containing an image mask by
\begin{lstlisting}
  png2pdf -i -m 255,128,128 -s fbt.png x3.pdf
  cp x2.eps e3.eps
\end{lstlisting}
The result can be seen in figure~\vref{img:b5}.
\subsubsection{Using alpha channel}
\begin{figure}[ht]
{\centering
\ifpdf
\includegraphics[width=5cm]{x4.pdf}
\else
\includegraphics[width=5cm]{x3.eps}
\fi
\caption{Image containing alpha channel}
\label{img:b6}
}
\end{figure}
Best quality is achieved when passing the \textsc{png} file's alpha channel to the
\textsc{pdf} file by running
\begin{lstlisting}
  png2pdf -a -m 255,128,128 -s fbt.png x4.pdf
\end{lstlisting}
The result can be seen in figure~\vref{img:b6}.
\clearpage
\pagecolor{white}
\subsection{Image interpolation}
This section shows the impact of the ``-n'' option used to
add an ``interpolate~image'' entry to the image directory.
The logo was converted to \textsc{pdf} twice, the
first example
(figure~\vref{fig:non-interpolated-image})
comes without image interpolation, the second
examples
(figure~\vref{fig:interpolated-image})
uses interpolation.

To view the difference zoom into the page to have the images
filling the screen width.

\begin{figure}[bh]
{\centering
\includegraphics[width=\linewidth]{png2pdf-logo1.pdf}
\caption{Image without interpolation}
\label{fig:non-interpolated-image}
}
\end{figure}
\begin{figure}[bh]
{\centering
\includegraphics[width=\linewidth]{png2pdf-logo2.pdf}
\caption{Interpolated image}
\label{fig:interpolated-image}
}
\end{figure}
\clearpage
\subsection{Beamer presentation example}
To embed partial transparent \textsc{pdf} graphics into beamer
presentations, use ``\textbackslash{}usepackage\{graphicx\}'' and
``\textbackslash{}includegraphics\{\ldots{}\}''.\\
The example uses an image png2pdf-logo.pdf produced by
\begin{lstlisting}
  png2pdf -a -n png2pdf-logo.png png2pdf-logo.pdf
\end{lstlisting}
which is placed over a color gradient background.
\lstinputlisting{beamtest.tex}
The result can be seen in \href{http://png2pdf.sourceforge.net/beamtest.pdf}{beamtest.pdf}.
\clearpage
\end{sloppy}
\end{document}

% use ppower4

