5. Graphics

‘dvipng’ attempts to handle graphics as included by the ‘graphicx’ and ‘graphics’ packages, without the need of specifying a driver to these packages. This means that it recognizes the encapsulated postscript inclusion meant for ‘dvips’, but is also able (from version 1.8) to include bitmapped graphics. It also tries to handle some of the raw PostScript that is output from various packages. Some of the possibilities and problems are mentioned below.

5.1 Encapsulated PostScript

When an EPS file is included, a call to GhostScript is performed to produce a bitmapped image that can be included. The default is to produce an image with transparent background, at the same size as the DVI page currently being converted to PNG, and include that as foreground on the PNG. Of course, if the image is to be cropped, that is done. The included image will be a truecolor image, so for maximum performance the output PNG will be in truecolor mode as well.

This conversion needs the ‘pngalpha’ output device to be present in your copy of GhostScript. If that device is not present, or you use the ‘--palette’ switch or request GIF output, the fallback is to use the ‘png16m’ device to produce a cropped opaque image for inclusion. Other relevant switches are ‘--noghostscript’ and ‘--nogssafer’. See section Option details.

The most common problem with including graphics is an incorrect bounding box. Complain to whoever wrote the software that generated the file if the bounding box is indeed incorrect. An adjusted boundingbox can be specified in the ‘\includegraphics’ call, as in this example (using ‘graphicx’):

\includegraphics[bb=10 20 100 200]{imagename.eps}

5.2 Bitmapped graphics

dvipng can include PNG, JPEG and GIF graphics. When including such images via ‘\includegraphics’ you need to specify the bounding box since TeX itself cannot read them from the files in question. The bounding box size should be given as ‘0 0 w h’ in pixels, e.g., if the file ‘imagename.png’ is 300x400 pixels, the inclusion would read

\includegraphics[bb=0 0 300 400]{imagename.png}

The default size is the image size in bp (“big points” in TeX nomenclature or PostScript points as other people have it, 72 per inch). That is, default resolution will be 72 dpi for included bitmaps, which is the default size in the few other bitmap-capable drivers that are known to me (dvipdfm and PDFLaTeX).

If you want 100 dpi you need to specify the width accordingly. You just divide your image width by 100: a 135 pixel wide image at 100 dpi will take up 1.35 inches. If you want 200 dpi you divide by 200, and so on. Simple, eh? The example above at 200 dpi would be 1.5 inches wide:

\includegraphics[bb=0 0 300 400,witdh=1.5in]{imagename.png}

5.3 Raw PostScript

dvipng attempts to handle raw PostScript. Rendering raw PostScript specials is done on top of the page by including a transparent image generated by the ‘pngalpha’ device in GhostScript (automatically selecting ‘truecolor’ mode in dvipng).

Included PostScript headers are respected, and if the header ‘tex.pro’ is included, dvipng also throws in ‘color.pro’ and ‘special.pro’. The package ‘xcolor’ includes its own headers with color names, and this is not only kept as a PostScript header, but is also read and interpreted by dvipng itself. An attempt is also made to respect the PGF header. The non-rendering specials from ‘hyperref’ are handled via some heuristics and do not give an error.

Really rendering and moving things with raw PostScript specials is more troublesome. The \rotatebox macro serves as a good example. The dvips driver of the graphicx package surrounds DVI glyphs with PostScript code so that after conversion by dvips, the glyphs (now themselves in PostScript) will be rotated in the desired way. dvipng does not handle this, at present. An attempt has been made to handle the rendering specials output by PGF (tikz), and also PSTricks. Some things work, but others do not. This is especially clear when mixing PostScript and DVI rendering commands such as glyphs. dvipng cannot at present detect if PostScript code moves ‘currentpoint’ or rotates the frame since GhostScript does not return such information. A recommendation would be to produce images from these packages as EPS files and include them into your document in the standard manner.

Another way to handle this would be to use a slower fallback (with dvips and gs, for example). If you want to disable raw PostScript handling in dvipng, use the switch ‘--norawps’. This switch turns off the internal call to GhostScript intended to display these raw PostScript specials. Further, when dvipng encounters raw PostScript and the gs call is turned off, it gives a warning. It is now possible to use the switch ‘--picky’ to disable page rendering of pages with warnings, and use the slower fallback for these pages.

This document was generated by Jan-Åke on December 14, 2010 using texi2html 1.82.