1DVIPNG(1) User commands DVIPNG(1)
2
6 dvipng - A DVI-to-PNG translator
7
9 dvipng [options] filename
10 dvipng [options] [filename] -
12
14 This program makes PNG and/or GIF graphics from DVI files as obtained
15 from TeX and its relatives.
16 If GIF support is enabled, GIF output is chosen by using the dvigif
18 binary or with the --gif option.
19 The benefits of dvipng/dvigif include
21 · Speed. It is a very fast bitmap-rendering code for DVI files. On a
23 fairly low-end laptop, it takes less than a second to generate 150
24 one-formula images. This makes dvipng suitable for generating large
25 amounts of images on-the-fly, as needed in preview-latex, WeBWorK
26 and others.
27 · It does not read the postamble, so it can be started before TeX
29 finishes. There is a --follow switch that makes dvipng wait at EOF
30 for further output, unless it finds the POST marker that indicates
31 the end of the DVI.
32 · Interactive query of options. dvipng can read options interactively
34 through stdin, and all options are usable. It is even possible to
35 change the input file through this interface.
36 · Supports PK, VF, PostScript Type1, and TrueType fonts, color spe‐
38 cials and simple PostScript inclusion specials.
39 · and more...
41
43 Many of the parameterless options listed here can be turned off by suf‐
44 fixing the option with a zero (0); for instance, to turn off page
45 reversal, use -r0. Such options are marked with a trailing *.
46 - Read additional options from standard input after processing the
48 command line.
49 --help
51 Print a usage message and exit.
52 --version
54 Print the version number and exit.
55 -bd num
57 -bd color_spec
58 -bd 'num color_spec'
59 Set the pixel width of the transparent border (default 0). Using
60 this option will make the image edges transparent, but it only
61 affects pixels with the background color. Giving a color_spec will
62 set the fallback color, to be used in viewers that cannot handle
63 transparency (the default is the background color). The color spec
64 should be in TeX color \special syntax, e.g., 'rgb 1.0 0.0 0.0'.
65 Setting the fallback color makes the default border width 1 px.
66 --bdpi num
68 Set the base (Metafont) resolution, both horizontal and vertical,
69 to num dpi (dots per inch). This option is necessary when manually
70 selecting Metafont mode with the --mode option (see below).
71 -bg color_spec
73 Choose background color for the images. This option will be ignored
74 if there is a background color \special in the DVI. The color spec
75 should be in TeX color \special syntax, e.g., 'rgb 1.0 0.0 0.0'.
76 You can also specify 'Transparent' which will give you a transpar‐
77 ent background with the normal background as a fallback color.
78 -d num
80 Set the debug flags, showing what dvipng (thinks it) is doing. This
81 will work unless dvipng has been compiled without the DEBUG option
82 (not recommended). Set the flags as you need them, use -d -1 as the
83 first option for maximum output.
84 -D num
86 Set the output resolution, both horizontal and vertical, to num dpi
87 (dots per inch).
88 One may want to adjust this to fit a certain text font size (e.g.,
90 on a web page), and for a text font height of font_px pixels (in
91 Mozilla) the correct formula is
92 <dpi> = <font_px> * 72.27 / 10 [px * TeXpt/in / TeXpt]
94 The last division by ten is due to the standard font height 10pt in
96 your document, if you use 12pt, divide by 12. Unfortunately, some
97 proprietary browsers have font height in pt (points), not pixels.
98 You have to rescale that to pixels, using the screen resolution
99 (default is usually 96 dpi) which means the formula is
100 <font_px> = <font_pt> * 96 / 72 [pt * px/in / (pt/in)]
102 On some high-res screens, the value is instead 120 dpi. Good luck!
104 --depth*
106 Report the depth of the image. This only works reliably when the
107 LaTeX style preview.sty from preview-latex is used. It reports the
108 number of pixels from the bottom of the image to the baseline of
109 the image. This can be used for vertical positioning of the image
110 in, e.g., web documents, where one would use (Cascading StyleSheets
111 1)
112 <IMG SRC="<filename.png>" STYLE="vertical-align: -<depth>px">
114 The depth is a negative offset in this case, so the minus sign is
116 necessary, and the unit is pixels (px).
117 --dvinum*
119 Set this option to make the output page number be the TeX page num‐
120 bers rather than the physical page number. See the -o switch.
121 -fg color_spec
123 Choose foreground color for the images. This option will be ignored
124 if there is a foreground color \special in the DVI. The color spec
125 should be in TeX color \special syntax, e.g., 'rgb 1.0 0.0 0.0'.
126 --follow*
128 Enable follow mode. One of the benefits of dvipng is that it does
129 not read the postamble, so it can be started before TeX finishes.
130 This switch makes dvipng wait at EOF for further output, unless it
131 finds the POST marker that indicates the end of the DVI. This is
132 similar to tail -f but for DVI-to-PNG conversion.
133 --freetype*
135 Enable/disable FreeType font rendering (default on). This option is
136 available if the FreeType2 font library was present at compilation
137 time. If this is the case, dvipng will have direct support for
138 PostScript Type1 and TrueType fonts internally, rather than using
139 gsftopk for rendering the fonts. If you have PostScript versions of
140 Computer Modern installed, there will be no need to generate
141 bitmapped variants on disk of these. Then, you can render images at
142 different (and unusual) resolutions without cluttering the disk
143 with lots of bitmapped fonts. Note that if you have both FreeType
144 and T1lib on your system, FreeType will be preferred by dvipng. If
145 you for some reason would want to use T1lib rendering, use this
146 option.
147 --gamma num
149 Control the interpolation of colors in the greyscale anti-aliasing
150 color palette. Default value is 1.0. For 0 < num < 1, the fonts
151 will be lighter (more like the background), and for num > 1, the
152 fonts will be darker (more like the foreground).
153 --gif*
155 The images are output in the GIF format, if GIF support is enabled.
156 This is the default for the dvigif binary, which only will be
157 available when GIF support is enabled. See also the --png option.
158 --height*
160 Report the height of the image. This only works reliably when the
161 LaTeX style preview.sty from preview-latex is used. It reports the
162 number of pixels from the top of the image to the baseline of the
163 image. The total height of the image is obtained as the sum of the
164 values reported from --height and the --depth.
165 -l [=]num
167 The last page printed will be the first one numbered num. Default
168 is the last page in the document. If num is prefixed by an equals
169 sign, then it (and the argument to the -p option, if specified) is
170 treated as a physical (absolute) page number, rather than a value
171 to compare with the TeX \count0 values stored in the DVI file.
172 Thus, using -l =9 will end with the ninth page of the document, no
173 matter what the pages are actually numbered.
174 --mode mode
176 Use mode as the Metafont device name for the PK fonts (both for
177 path searching and font generation). This needs to be augmented
178 with the base device resolution, given with the --bdpi option. See
179 the file <ftp://ftp.tug.org/tex/modes.mf> for a list of resolutions
180 and mode names for most devices.
181 -M* Turns off automatic PK font generation (mktexpk). This will have no
183 effect when using PostScript fonts, since no PK font generation
184 will be done anyway.
185 --noghostscript*
187 This switch prohibits the internal call to GhostScript for display‐
188 ing PostScript specials. --noghostscript0 turns the call back on.
189 --nogssafer*
191 Normally, if GhostScript is used to render PostScript specials, the
192 GhostScript interpreter is run with the option -dSAFER. The
193 -nogssafer option runs GhostScript without -dSAFER. The -dSAFER
194 option in Ghostscript disables PostScript operators such as delete‐
195 file, to prevent possibly malicious PostScript programs from having
196 any effect.
197 -o name
199 Send output to the file name. A single occurrence of %d or %01d,
200 ..., %09d will be exchanged for the physical page number (this can
201 be changed, see the --dvinum switch). The default output filename
202 is file%d.png where the input DVI file was file.dvi.
203 -O x-offset,y-offset
205 Move the origin by x-offset,y-offset, a comma-separated pair of
206 dimensions such as .1in,-.3cm. The origin of the page is shifted
207 from the default position (of one inch down, one inch to the right
208 from the upper left corner of the paper) by this amount.
209 -p [=]num
211 The first page printed will be the first one numbered num. Default
212 is the first page in the document. If num is prefixed by an equals
213 sign, then it (and the argument to the -l option, if specified) is
214 treated as a physical (absolute) page number, rather than a value
215 to compare with the TeX \count0 values stored in the DVI file.
216 Thus, using -p =3 will start with the third page of the document,
217 no matter what the pages are actually numbered.
218 --picky*
220 No images are output when a warning occurs. Normally, dvipng will
221 output an image in spite of a warning, but there may be something
222 missing in this image. One reason to use this option would be if
223 you have a more complete but slower fallback converter. Mainly,
224 this is useful for failed figure inclusion and unknown \special
225 occurrences, but warnings will also occur for missing or unknown
226 color specs and missing PK fonts.
227 --png*
229 The images are output in the PNG format. This is the default for
230 the dvipng binary. See also the --gif option.
231 -pp firstpage-lastpage
233 Print pages firstpage through lastpage; but not quite equivalent to
234 -p firstpage -l lastpage. For example, when rendering a book, there
235 may be several instances of a page in the DVI file (one in "\front‐
236 matter", one in "\mainmatter", and one in "\backmatter"). In case
237 of several pages matching, -pp firstpage-lastpage will render all
238 pages that matches the specified range, while -p firstpage -l last‐
239 page will render the pages from the first occurrence of firstpage
240 to the first occurrence of lastpage. This is the (undocumented)
241 behaviour of dvips. In dvipng you can give both kinds of options,
242 in which case you get all pages that matches the range in -pp
243 between the pages from -p to -l. Also multiple -pp options accumu‐
244 late, unlike -p and -l. The - separator can also be :. Note that
245 -pp -1 will be interpreted as "all pages up to and including 1", if
246 you want a page numbered -1 (only the table of contents, say) put
247 -pp -1--1, or more readable, -pp -1:-1.
248 -q* Run quietly. Don't chatter about pages converted, etc. to standard
250 output; report no warnings (only errors) to standard error.
251 -Q num
253 Set the quality to num. That is, choose the number of antialiasing
254 levels for PK and T1lib rendering to be num*num. The default value
255 is 4 which gives 16 levels of antialiasing for antialiased fonts
256 from these two. If FreeType is available, its rendering is unaf‐
257 fected by this option.
258 -r* Toggle output of pages in reverse/forward order. By default, the
260 first page in the DVI is output first.
261 -T image_size
263 Set the image size to image_size which can be either of bbox,
264 tight, or a comma-separated pair of dimensions hsize,vsize such as
265 .1in,.3cm. The default is bbox which produces a PNG that includes
266 all ink put on the page and in addition the DVI origin, located 1in
267 from the top and 1in from the left edge of the paper. This usually
268 gives whitespace above and to the left in the produced image. The
269 value tight will make dvipng only include all ink put on the page,
270 producing neat images. This option overrides any papersize special
271 in the DVI file.
272 --t1lib*
274 Enable/disable T1lib font rendering (default on). This option is
275 available if the T1lib font library was present at compilation
276 time. If this is the case, dvipng will have direct support for
277 PostScript Type1 fonts internally, rather than using gsftopk for
278 rendering the fonts. If you have PostScript versions of Computer
279 Modern installed, there will be no need to generate bitmapped vari‐
280 ants on disk of these. Then, you can render images at different
281 (and unusual) resolutions without cluttering the disk with lots of
282 bitmapped fonts. Note that if you have both FreeType and T1lib on
283 your system FreeType will be preferred by dvipng, and if you for
284 some reason rather want to use T1lib, give the option --freetype0
285 (see above).
286 --truecolor*
288 On systems with a fairly new libgd, one can choose to generate
289 truecolor output. This will not be necessary in general unless you
290 include truecolor images via a PostScript special (i.e., the graph‐
291 ics or graphicx package). It will lead to longer execution time,
292 mostly because more data is written to disk.
293 -v* Enable verbose operation. This will currently indicate what fonts
295 is used, in addition to the usual output.
296 -x num
298 Set the x magnification ratio to num/1000. Overrides the magnifica‐
299 tion specified in the DVI file. Must be between 10 and 100000. It
300 is recommended that you use standard magstep values (1095, 1200,
301 1440, 1728, 2074, 2488, 2986, and so on) to help reduce the total
302 number of PK files generated. num may be a real number, not an
303 integer, for increased precision.
304 -z num
306 Set the PNG compression level to num. This option is enabled if
307 your libgd is new enough. The default compression level is 1, which
308 selects maximum speed at the price of slightly larger PNGs. For an
309 older libgd, the hard-soldered value 5 is used. The include file
310 png.h says ``Currently, valid values range from 0 - 9, correspond‐
311 ing directly to the zlib compression levels 0 - 9 (0 - no compres‐
312 sion, 9 - "maximal" compression). Note that tests have shown that
313 zlib compression levels 3-6 usually perform as well as level 9 for
314 PNG images, and do considerably fewer calculations. In the future,
315 these values may not correspond directly to the zlib compression
316 levels.''
317
319 The full manual is accessible in the info format, on most systems by
320 typing
321 info dvipng
323
325 This program is released under the GNU General Public License, see the
326 COPYING file in the dvipng distribution or
327 <http://www.gnu.org/licenses/gpl.html>.
328 Copyright (c) 2002-2005 Jan-Ake Larsson
330dvipng 1.5 2005-02-04 DVIPNG(1)