# png2pdf - PNG to PDF converter

Help, version info and preferences / Conversion options / Examples

## Usage

### General usage

      png2pdf [<options>] [ <inputfile> [ <outputfile> ] ]
      png2pdf <directory>

One can either specify input and output file name (stdin and stdout if there are no names) or a directory name.
When running on a directory, the directory is searched for PNG files, all PNG files (or all newer PNG files when using option -f) are converted into PDF files.

### Help, version information and permanent option handling

#### Overview

As other dkapp-based applications too, png2pdf can save permanent options (preferences).
When the program is run permanent options are processed first, command line options specify changes relative to the permanent options.

#### Getting help

      png2pdf -h
      png2pdf --help

shows a help text.

#### Getting version information

      png2pdf -v
      png2pdf --version

shows version information.

#### Setting permanent options

Use

      png2pdf -c

to set permanent options.
I.e.

      png2pdf -c -p 1.4 -f
      png2pdf --configure -p 1.4 -f

tells the program you want to write PDF format 1.4 files. When running on a directory the program compares the modification times of PNG and PDF files, a conversion is only run if necessary.

#### Showing permanent options

Use

      png2pdf -C
      png2pdf --show-configuration

to list the values of all permanent options.

#### Temporarily overriding permanent options

Use

      png2pdf -r <options> ...
      png2pdf --reset <option>

to skip preferences processing for one program invokation.
The -r options must be the first command line argument. This option is recommended when using the programs in scripts.

#### Removing all permanent options

Use

      png2pdf -u
      png2pdf --unconfigure

to remove all permanent options.

### Conversion options

#### PDF format level

      -p <level>
      --pdf=<level>

sets the PDF format level to "1.2", "1.3" or "1.4" (without quotes of course).
Different PDF format levels enable different features: 1.3 and above allow to create image masks, 1.4 allows alpha channel data.

#### Mixing against a background color

      -m <r,g,b>
      --mix-background=<r,g,b>

i.e.

      -m 255,128,128

defines to mix against a light red background. The background specified here is only used if the file does not contain a background chunk unless the -s option is used.
If mixing against a specified background was saved as permanent option

      -m-

turns this off.

#### Overriding the background chunk

      -s
      --mix-specified

can be used in conjunction with the -m option to override the background chunk.
If overriding the background chunk was saved as permanent option

      -s-
      --mix-specified=no

turns this off

#### Writing an image mask

      -i
      --image-mask

converts the PNG alpha channel into a PDF image mask (if there is a PNG alpha channel).
If this option was saved as permanent option

      -i-
      --image-mask=no

turns this off.

#### Writing a PDF alpha channel

      -a
      --transparency

converts the PNG alpha channel (if there is one) into a PDF alpha channel.
If this option was saved as permanent option

      -a-
      --transparency=no

turns this off.

#### Invert image mask levels

When creating a PDF image mask only pixels having opacity 0 are masked out by default.
Using

      -l
      --invert-levels

one can invert this behaviour, only pixels having full opacity are drawn, all others are masked out. If this option was saved as permanent option

      -l-
      --invert-levels=no

turns this off.

#### Alpha channel is transparency

By default the alpha channel is assumed to contain opacity data. Using

      -t
      --alpha-transparency

this is switched to transparency data.
If this option was saved as permanent option

      -t-
      --alpha-transparency=no

turns this off.

#### Modification time check when running on a directory

When running on a directory the program converts every PNG file into a PDF file of same name, suffix .PDF.
Using

      -f
      --file-time-check

one can prevent unnecessary conversions by comparing modification time stamps.
If this option was saved as permanent option

      -f-
      --file-time-check=no

turns this off.

### Examples

#### Original image

In these examples we use the image stefan_255_rgba.png from the PNG web site.
This image contains a colored bird before a white background, a shadow of the bird is constructed using a black foreground and different alpha (opacity).

#### Image processing

The image is converted into a PDF file, i.e. by running

      png2pdf -m 255,128,128 -s stefan_255_rgba.png x1.pdf

The inclusion into the pdfLaTeX source looks like this:

      \documentclass[12pt,a4paper,titlepage]{article}
      \usepackage{ifpdf}        % LaTeX or pdfLaTeX
      \usepackage{color}        % we want to use background color
      \ifpdf
      \usepackage{background}   % for the background effects, PPower4 necessary
      \fi
      \definecolor{bgred}{rgb}{1.0,0.501961,0.501961}
      ...
      \begin{document}
      ...
      \begin{figure}
      {\centering
      \ifpdf
      \includegraphics[width=5cm]{x1.pdf}
      \else
      \includegraphics[width=4cm]{x1.eps}
      \fi
      \caption{Some caption}
      \label{fig:some-label}
      }
      \end{figure}
      ...
      \end{document}

#### Simple inclusion of the original PNG file

If we simply include the PNG file using

      \begin{figure}
      {\centering
      \includegraphics[width=5cm]{stefan_255_rgba.png}
      \caption{Some caption}
      \label{fig:some-label}
      }
      \end{figure}

pdfLaTeX seems to ignore the alpha channel in the PNG file, it shows the black foreground without mixing.

#### Mixing against white background

      png2pdf -m 255,255,255 -s stefan_255_rgba.png x1.pdf

produces a picture as expected.

#### Colored background

Now imagine we want to create a poster or flyer, we want to have a colored background.
Before the page containing the image starts we use

      \pagecolor{bgred}

in the LaTeX source1 to create a light red background.
For the image conversion

      png2pdf -m 255,128,128 -s stefan_255_rgba.png x1.pdf

we specify the same background.

#### Background effects

If we use this image on a page containing a background effect instead of a simple background color we have a visible background rectange.
We must create either an image mask or PDF alpha channel data to avoid this.

#### PDF image mask

      png2pdf -m 255,128,128 -s -i stefan_255_rgba.png x1.pdf

For this image this is closer to the result we want but it's not yet the best we can get.

#### PDF alpha channel data

      png2pdf -m 255,128,128 -s -a stefan_255_rgba.png x1.pdf

looks best.

1 | If you use pagecolor in the document or vpagecolor in pdfLaTeX you need to post-process the PDF file using PPower4.