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. |