Inserting figures into TeX documents
Szab´oP´eter Budapest University of Technology and Ecomomics http://www.inf.bme.hu/\~pts/ (without the backslash)
Abstract
∗ My article deals with the practical considerations of inserting sampled figures into TeX documents. Sub-topics: Choosing the appropriate compression for sampled images. Software • patents. PostScript and PDF compatibility. Conversion of PNG, JPEG, TIFF and GIF files to PDF (for pdfTeX) and • EPS (for dvips). sam2p, a conversion utility I’ve developed recently. Creating pixel-based figures with transparent pixels. Transparency support • in sam2p.
The LATEX graphics package and epsf.tex for exist that give the user full control over the image plain TEX provide an easy and fairly standard way representation parameters. for including EPS figures into TEX documents with This article analyses the problem and possi- PostScript target, and pdfTeX together with the gra ble solutions in detail, and presents the new util- phics package supports PDF figures in LATEX docu- ity sam2p written by the author of the article, that ments with PDF targets. This works fine for vector implements these solutions. images, because serious editors have EPS export ca- Concepts Although PostScript and PDF are most pability, and one can convert an EPS file to PDF often used for faithfully representing two-dimension- with several utilities (such as epstopdf bundled with al vector graphics, they have sophisticated features teTEX, ps2pdf bundled with Ghostscript, PSTill and for displaying sampled image data as well. Unfortu- Acrobat Distiller). nately the PostScript and PDF output facilities of Inclusion of raster (bitmap) images seems to be existing image converters and editors don’t make use even simpler and less troublesome at the first glance. of these advanced features: they often produce large, Under UNIX, the convert utility of ImageMagick slow and incompatible PostScript or PDF code. sam can be used to create a PBM or PGM file, which 2p is a new sampled image conversion utility that can be converted to EPS by the pnmtops utility of gives the user full control to adjust compliance, com- NetPBM. Filters mentioned in the previous para- pression and encoding of the PostScript and PDF graph can be used to create a PDF file from the output files. EPS. There are several other approaches, which will The concept of sampled images is rather sim- be described later in this article. ple: the image is a rectangular array of pixels, in But high-quality raster image files tend to be which the color of each pixel is independent of the huge, and thus documents containing raster images others. A color consists of one or more components can be only trasferred on the network only slowly, (channels, planes): for example, the colors of the and printing is even more slower. It is common RGB color space are composed of a red, a green that a PostScript version of a small article with a and a blue component. The name sampled image few dozen raster illustrations becomes larger than comes from the fact that only a finite number of 100 MB, and printing each page on a personal prin- pixel samples of the continuous picture are stored. ter takes half an hour. Software techniques such (The sampled image is also quantized, e.g. the com- as compression and colorspace transformation can ponents are integers in the range 0 ... 255, where 0 be used to make these images much smaller, and means darkest, 255 means lightest.) Sampled im- PostScript and PDF support much of these tech- ages are also called raster images or bitmap images. niques, but unfortunately currently no free utilities Some images have an alpha channel, which describes the opacity of the pixels: a pixel having α = 0 is fully transparent, and a pixel with α = 1 is opaque. ∗ The author thanks GUST for funding his participation Non-rectangular shapes can be represented with a in EuroBachoTEX 2002, and Ferenc Wettl for testing sam2p.
TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting 1001 Szab´oP´eter rectangular image having transparent pixels outside sam2p) output sampled PostScript images as EPS. the shape, and opacity can be used this way to draw There is a thumbnail/preview feature in the EPS arbitrary shapes atop of each other. format, but sam2p doesn’t emit one, because most Recent versions of the PostScript and PDF for- utilities (including the utilities related to TEX) ig- mats fully support the notions defined above. Many nore it, and they would call Ghostscript to render an features are not available in older PostScript print- independent preview anyway. ers, and there are even some features (such as opac- ity) that are documented in the file format, but not Smaller output Sampled images, especially when rendered in high resolution ( 300 DPI), tend to be implemented in any common free renderers. Thus, ≥ compatibility must be always considered when cre- large and occupy much space on disk. A PDF file ating a PostScript or PDF file containing a sam- with many high resolution figures in it gets down- pled image. These two file formats are based on loaded slowly from the web, and a PDF file with low a common graphics model, and thus they are al- resolution images looks ugly when printed. A long most equivalent. The actual image data (being ei- PostScript file containing large images prints very ther compressed or not) is stored the same way in slowly, and might even fill up the disk space of the PostScript and PDF files, only the syntax of the computer running the printer spooler. (Just imagine surrounding meta-information (such as the image multiple PostScript files of 200 MB being printed on width, height and color space specification) is dif- an old, dedicated print server with small hard disks. ferent. This situation often happened to the author.) Large The most important difference between Post- PostScript files print especially slowly, because the Script and PDF formats is that PostScript is a full- parallel-port interface on which the printer is con- featured programming language, and it gives more nected to the computer is too slow, or the processor power to the programmer to represent the image. embedded to the printer running the PostScript in- For example, one can write a PostScript program terpreter is slow. It is really annoying to wait more that would compute and draw a Mandelbrot or Julia than a minute for a single A4 page, and even more set as a sampled image, but there is no similar capa- annying to wait for someone else’s job running at bility in PDF (i.e the pixels have to be pre-computed this “speed”. before the generation of the PDF file). The pro- When running TEX on an old machine, the user gramming constructs of PostScript can be used to must wait several minutes for TEX finishing skip- compensate the weaknesses of the interpreter: for ping long EPS files after finding geometry (bound- example, older interpreters don’t support the Flate ing box) information. The situation is even worse (ZIP) compression, but this can be overcome by today, when one expects WYSIWYG, or – at least including a pure PostScript implementation of the – instant preview. Several minutes is definitely not instant. /FlateDecode filter into the EPS file, just before the image data, and executing the supplied code Thus, the generated PostScript and PDF files when the filter is missing from the interpreter itself. should be as small as possible. This can be accom- sam2p does this and several other tricks to increase plished by: compatibility of PostScript files. Unfortunately this apply filtering to reduce noise, increase contrast • doesn’t work for PDF; there is no way to extend the etc.: This should be done manually in graph- list of available filters. ical image editors. Sometimes even a size re- Raster images are most commonly used as il- duction of a factor of 4 can be achieved by re- lustrations in more complex documents, thus the moving noise and unnecessary information. As holding PostScript and PDF files should be gen- part of the filtering, the user should adjust the erated embeddable. The design of the PDF file color palette: black should be exactly black (RGB format makes embedding any PDF file (including triplet #000000), and white should be completely the most complex ones) very easy, even without the white (RGB triplet #ffffff), because otherwise special attention of the generator. PostScript fig- Ghostscript would print glaring gray regions. ures, on the other hand, share a common names- using less bits for representing a single color com- pace (and very limited memory) with the document • ponent: A black-white image needs only 1 bit per they are embedded into, and extreme caution should pixel, and it would be big waste to include it as be taken to avoid conflicts with the document it- an 8-bit RGB image with 24 bits per pixel. Even self and with other figures. Encapsulated PostScript color images can be encoded with a few bits when (EPS) is the most common file format of embed- using only a palette of very few number of dif- dable PostScript code, and most utilities (including ferent colors. PostScript and PDF support may
1002 TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting Inserting figures into TeX documents
sample formats ranging between 1 ... 33 bits per PSL2. PostScript LanguageLevel 2 supports sev- pixel. • eral color spaces (e.g. “indexed”=paletted), and using compression adequate for the image types: all compression filters except ZIP. Ghostscript, PS • There is no universal method that finds the com- till, Acrobat Distiller, and most PostScript print- pression with best ratio, but in general, continu- ers today understand this LanguageLevel. ous-tone color or gray images (such as photos or PSL3. The most important feature added by scanned paintings) should be compressed with the • JPEG (DCT) compression filter, black-white im- Level3 is Flate compression. Ghostscript supports ages should be encoded with the the Group3 Fax this and many other features of this level. Unfor- (CCITTFax) filter, and ZIP compression (Flate) tunately Level3 is too new, it has not been imple- is quite good for other sample formats. When mented by major printer vendors yet. ZIP compression is not available on the printer, The history of PDF files is shorter: PDF1.0 LZW (patented till 19 June 2003) or RLE (poor roughly corresponds to PSL2, and PDF1.2 added ratio) can be used. ZIP compression. It is important to note that most image data should be preconditioned for compres- PostScript printers cannot print PDF files, because • sion: There are several predictors (such as hori- random access (i.e arbirary file seeking, positioning) zontal differencing) that convert similar patterns would be required, but printers are connected with found in the image to repeating data bytes, so the parellel, USB or TCP interface, which provides only compression ratio of some filters will be improved. serial data stream access. There are, however, ad- Sometimes the user has a priori knowledge about vanced printers that read the whole PDF file into the structure of the image, and knows the best com- their memory before processing it. As a conclu- bination of compression filters, parameters and pre- sion, neither PDF or PostScript can fully replace dictors. Although many converters support some the other one, so sam2p supports both. kind of Postscript or PDF compression, unfortu- In sam2p, the user can specify the exact ver- nately free utilities that would respect the exact wish sion of the PostScript or PDF format the output of the user haven’t existed before sam2p. should comply to, and the program gives an error A beginner who doesn’t want to know about all message on illegal combinations (such as ZIP com- the details, can use the output profile created by an pression in PSL2). In some cases, tricky PostScript expert. An output profile consists of several inde- code is used to emulate features of higher levels. For pendent rules. For example, if the profile contains a example, RLE and ZIP (de)compression is provided rule with DCT compression, and another rule with even in PSL1 (!), by inlining the pure PostScript Fax compression, sam2p will choose automatically implementation of the decompressor into the EPS the first rule for continuous-tone RGB images, and file. More examples: indexed images are emulated the second rule for black-white images. When two in PSLC, and a grayscale-mapped version of the rules are in conflict (i.e. they are both applicable), colorimage operator is provided for PSL1. The the one that has been declared first is applied. implementations of these PostScript tricks are cur- rently incompatible with each other, but the archi- More compatible output The PostScript format tecture of sam2p makes adding more combinations has evolved much over time. Newer versions provide possible. This way, compatibility is not an alterna- color images and more compression filters: tive of file size, but it is an alternative of decompres- PSL1. This is the very first PostScript specifica- sion and printing speed. • tion, called LanguageLevel1, as defined by Adobe in 1985. It doesn’t have any predefined filters, sam2p sam2p is a UNIX command line utility writ- and supports only grayscale images directly. Very ten in ANSI C++ that converts many raster im- limited support for RGB images with few dif- age formats into Adobe PostScript or PDF files. It ferent colors exists, using the setrgbcolor and gives full control to the user to specify standards- imagemask operators. compliance, compression, and bit depths. The im- PSLC. This is Level1 PostScript with the CMYK ages are not vectorized. It is common that sam2p • extension. The CMYK color space is not impor- can compress an image down to an 50kB Level1 tant for sam2p, but the extension also adds the PostScript file without quality loss, while other pop- colorimage operator with the ability of drawing ular converters produce multi-megabyte output. sa arbitrary RGB (and CMYK) images. This is the m2p is unique, because it provides some Level3 com- standard that ancient PostScript printers follow. pression filters even on Level1 devices.
TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting 1003 Szab´oP´eter
The program source code for UNIX systems is the CCITT Fax encoding filter. Additional keys and available from http://www.inf.bme.hu/~pts/sam values of the output rule dictionary will be described 2p-latest.tar.gz. The license is GNU GPL. Doc- later. umentation, compilation instructions and examples The Profile contains a single output rule most are included. The author can be reached via e- of the time, but it is possible to specify more than mail at
1004 TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting Inserting figures into TeX documents
processed by pdfTeX, because pdfTeX forces ZIP Implementation considerations sam2p manip- compression on non-BI images. ulates possibly huge raster images. Today desktop /SampleFormat: specifies the bit depth and color computers tend to have more and more system mem- • space in which the samples are stored. Possi- ory, into which the entire image can be read. But ble values are: /Opaque, /Transparent, /Gray1, free memory shouldn’t be wasted: the programmer /Indexed1, /Mask, /Transparent2, /Gray2, /In must have precise control over the memory allocated dexed2, /Transparent4, /Rgb1, /Gray4, /Index for image data. The program should be fast, even ed4, /Transparent8, /Rgb2, /Gray8, /Indexed8, when converting large images. Scripting languages /Rgb4, /Rgb8, /Asis. Use /Asis together with and Java provide memory management (i.e. auto- IJG compression. matic memory deallocation, and safety from illegal /WarningOK: true or false. With false (non- memory access), but are slow and they waste re- • default), this output rule is disabled for an image sources when dealing with image data. Among the if it would cause warnings to be printed. popular programming languages, only C and C++ /TransferEncoding: any of /Binary, /ASCII, fulfills the mentioned memory usage and speed re- • /Hex=/AHx, /A85. /ASCII is useful only when quirements. no image data will be stored, for example with The code would include stacked encoding fil- /Opaque and /Transparent. ters, for example the ASCII85Encode filter writes the actual data to the output file, reads the output /Compression: any of /None, /LZW, /ZIP=/Flat of the LZWEncode filter, which indeed reads the out- • e=/Fl, /RLE=/RunLength, /Fax=/CCITTFax, /D put of a predictor. The filters and predictors can CT=/JPEG, /IJG, /JAI. DCT is JPEG compression have multiple implementations (such as a truly in- with the PostScript /DCTEncode filter (creates ternal, one using a shared library such as zlib, or one large JPEG files), /IJG is JPEG compression us- that spawns an external process to do the job). This ing cjpeg by the Independent JPEG Group (rec- complexity can be easily handled within the object- ommended, produces small JPEG files), /JAI is oriented paradigm, but would be a mess in pure mostly verbatim inclusion of a JPEG file read C. Other reasons for C++ beyond supporting ob- from /InputFile. /ZIP generally doesn’t work jects are the powerful syntactic sugars and the stan- in PSL2 or PDF1.0, and other filters generally dardness and standards-compliance of compilers: no don’t work in PSLC. Because of the PostScript more confusion and partial implementations with trickery, there is a chance that /ZIP and /RLE traditional or ANSI C. So sam2p is implemented works even in PSL1. in Standard C++, but without using
TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting 1005 Szab´oP´eter
sam2p is modular in the source level, but mono- the convert utility (from ImageMagick, Debian lithic after it has been compiled. For example, it is • package graphics/imagemagick), with output for- quite easy to include a new type of input image for- mats EPS: EPS2: EPSI: EPSF: PS: PS2:. Most of mat by writing a file in XYZ.cpp, and registering the these formats are big and slow, and ImageMagick loader in sam2p main.cpp; after that, sam2p has to sometimes produces illegal ADSC comments, so be recompiled. The program doesn’t use any exter- dvips cannot embed the image. Apart from ADSC nal libraries, but it is able to call external programs, bug, ImageMagick seems to create the most com- for example, the cjpeg utility is invoked when the patible and best embeddable EPS files. The EPS: user requests IJG compression. In future versions format should be used for Level1 EPS, and EPS2: of sam2p, the user will have a choice between multi- for Level2 EPS. The others are obsolete. Partially ple implementations of the same compression filter. respects the -compress option. sam2p doesn’t require any C++-specific libraries, the convert utility with PDF: output format. not even STL or libstdc++. • Only partially respects the -compress option, Modularity is especially important in the foll- and produces illegal %PDF-1.1 header with the wing areas: Loaders (that load InputFiles), Appliers /FlateDecode filter. (that apply an output rule and create the Output- the Save as PostScript feature of xv (former De- Files) and compression filters. Currently it is very • bian package non-free/graphics/xv). Does RLE easy to add new Loaders and Appliers, because their compression with PSL1 (!), image can be adjusted interface to the main program is small, simple and to the paper size, but cannot generate EPS. well-defined. New compression filters will probaby the tiff2ps utility from libtiff (Debian package never be added, because PostScript and PDF sup- • graphics/libtiff-tools). Needs the -z and -e op- ports only the filters already implemented. How- tions; the -2 (Level2) option is recommended. ever, alternate implementations of existing filters The scaling (size) of the image is still somewhat would be important, but the code has to be reor- obscure, the scale operation should be removed ganized a little for that. from the EPS file by hand. When generating sam2p is being developed on a Linux system, Level2 EPS, tiff2ps fully respects the compres- and currently only flavors of UNIX are supported as sion of the TIFF file, and produces an equally run-time platforms. Porting to Win32 or Mac would small EPS. The tiffcp utility can be used to not be hard, because the user interface is minimal, adjust the TIFF compression. Unfortunately, old but the author isn’t experienced enough and doesn’t versions of tiff2ps don’t support Flate compres- have time to do it. sion, and new versions partially support LZW compression due to the Unisys patent. tiff2ps Legal issues The LZW compression is patented: seems to be the most advanced EPS-generator, software containing LZW (de)compression code can but it still cannot exploit all features of the PDF be distributed only with the prior written permis- and PostScript sampled image model. sion of Unisys. According to
1006 TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting Inserting figures into TeX documents
the jpg2pdf shareware utility, available from preamble can be found in the sam2p sources with • http://www.sanface.com/jpg2pdf.html. Only filename contrib/aprea.ps. the RGB color space, with JPEG compression. Ghostscript can read PDF files besides PS files. Simplistic software with stupid legal limitations. However, some PDFs tend to be too complicated The author has investigated several PHP mod- for Ghostscript, so they should be converted into a • ules that generate PDF, but they were not general simpler, temporary PostScript first. This can be enough to support all SampleFormats. accomplished by the File/Export. . . menu item of Adobe Acrobat, the File/Print menu item of Adobe the imagetops utility from CUPS (Debian pack- • Acrobat Reader, or the pdftops utility found in the age net/cupsys). This is a smart shell script that XPdf distribution. Unfortunately pdftops ignores invokes djpeg, pngtopnm, bmptopnm, giftopnm, the bitmap fonts embedded by pdfTeX. tifftopnm, ppmtogpm and pnmtops. No way to The psrender utility written by the author of specify compression. sam2p calls Ghostscript to convert a PostScript file Better transparency PSL3 and PDF1.3 provide to another PostScript containing all pages as big a better way to specify images with transparence raster graphics. This is useful when printing onto pixels. This way uses patterns and masked images. an old PostScript (Level 2) printer with small mem- However, most present printers and utilities don’t ory or buggy implementation. However, the output support these features yet, so these are not included of psrender tends to be big (multi-megabyte for into sam2p. For complete support, a new type of a single page), thus the document gets printed very color space (RGBA: RGB with transparecy) should slowly. But sometimes even an extremely long print- be implemented. ing time is better than having no printout at all. Currently sam2p produces the transparent im- psrender is available from the Search facility of ages by calling the PostScript imagemask operator http://www.freshmeat.net/, the other utilitites for all different colors. This can be slow and make mentioned are part of major Linux distributions. the output file large and less compressible. Conclusion sam2p makes the creation of small, Rendering: the reverse direction It is easy to compatible PostScript and PDF figures containing convert a PostScript or a PDF document into a se- sampled images possible. Documents with these fig- ries of bitmap files, using GNU Ghostscript: ures are small, and can be printed or transferred quite fast. There is work still to be done, but sam2p gs -g100x200 -sDEVICE=ppmraw -q -dNOPAUSE is already more general and more sophisticated than -dBATCH -q -dSAFER any other converter the author is aware of. -sOutputFile=out%d.ppm infile.ps During further development, the software has In the command above, -r specifies the DPI re- to be tested, and bugs have to be fixed. Planned fea- soulution, -g specifies the image size in pixels (thus tures (such as PDF output, and better transparency it should be doubled for double resolution), ppmraw handling) have to be implemented. is the output file format (should be pbmraw for black- white, pgmraw for 8-bit grayscale and ppmraw for 8- References bit RGB). The files out1.ppm, out2.ppm etc. will [1] Ed Taft, Steve Chernicoff and Carline Rose: be generated. These files can be loaded into The PostScript Language Reference. GIMP, or they can be converted to other sampled Addison–Wesley. 1999. image formats with ImageMagick’s convert utility [2] Jim Meeehan, Ed Taft, Steve Chernicoff and or the pnmto* utilities of NetPBM. Carline Rose: PDF Reference. Second edition. Sometimes it is more convenient to specify the Addison–Wesley. 2000. sampled image size in PostScript points (72 bp = 1 in): gs -dDEVICEWIDTHPOINTS=100 -dDEVICEHEIGHTP OINTS=200 -r144 -sDEVICE=ppmraw -q -dNOPAUSE -dBATCH -dSAFER -sOutputFile=out%d.ppm infile.ps Some malicious PostScript files override the res- olution or the page size specified on the command line. This can be avoided by prepending the follow- ing a special preamble to the PostScript file. This
TUGboat, Volume 0 (2001), No. 0 — Proceedings of the 2001 Annual Meeting 1007