Debian Codegraph @

texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex

raw
1 \documentclass[10pt,a4paper]{article}
2 \usepackage{hologo} % used for LuaTeX, PdfTeX and PdfLaTeX logos
3 \usepackage{graphicx}
4 \usepackage{textcomp}
5 \usepackage{url}
6 \title{pdflatexpicscale}
7 \author{Peter Willadt\footnote{willadt at t-online.de}}
8 \date{2024-10-18} %version #version
9 \begin{document}
10 \maketitle
11
12 \begin{abstract}
13 \noindent pdflatexpicscale is software that scales bitmap images to be
14 included into Pdf\LaTeX\ documents down to a size sufficient for printing.
15 This document describes installation and usage.
16 \end{abstract}
17
18 \tableofcontents
19
20 \section{Introduction}
21
22 Picture size matters. Digital cameras produce unnecessary large images, this
23 leads to excessive download times and wasted processing power in the print
24 driver, for example. Tuning images by hand is fine, but it costs lots of time
25 and there may be situations where you need e.g. low-res pictures for the web
26 and high-res pictures for print. When there are requirements that force the
27 size of images in our document to change, the fun will probably be gone.
28
29 There is a freely accessible article\label{tugboatart} in TUGboat (\url{%
30 https://www.tug.org/TUGboat/tb37-3/tb117willadt.pdf}) accompanying
31 this package.
32
33
34 \subsection{Similiar Work/Prior Art}
35
36 There have been prior attempts to do similiar things. I found
37 \texttt{degrade.sty}\footnote{see
38 \url{http://mirror.ctan.org/graphics/degrade}}
39 and an equivalent con\TeX t module, there are at least two threads on
40 stackexchange\footnote{see
41 \texttt{http://tex.stackexchange.com/questions/14429/\\
42 pdftex-reduce-pdf-size-reduce-image-quality}
43 and
44 \texttt{http://tex.stackexchange.com/\\questions/2198/how-to-create-small-pdf-files-for-the-internet}}
45 and there had been, as
46 I have learned, some work by Axel Berger and others, posted 2011-03-31 on
47 \texttt{de.comp.text.tex}.
48
49 But what motivated me most to find something better than scaling pictures
50 individually was seeing that Adobe InDesign\textregistered\ does
51 scale graphics according to the output intent.
52
53 \section{Installation}
54
55 \subsection{Prerequisites}
56
57
58 You \label{section:requisites} have to install Perl version~5, if it is not
59 installed already. If you are using Linux, I recommend to use the tools of
60 your distribution. As a windows user, you may probably use Strawberry Perl.
61 You also need the following Perl modules:
62 \begin{itemize}
63 \item \texttt{GD} (at least version 2.2),
64 \item \texttt{Image::ExifTool},
65 \item \texttt{File::Basename},
66 \item \texttt{File::Spec},
67 \texttt{File::Copy}, and
68 \item \texttt{Getopt::Long}.
69 \end{itemize}
70
71 There are no further requirements for the versions of the software to install,
72 but it may be wise to use recent releases.
73 There are several ways to get these modules, if you have not got them
74 already. The most popular are probably:
75
76 \begin{itemize}
77 \item use your Linux distribution's software manager
78 \item use the Perl CPAN module
79 \item use ActiveState's \texttt{ppm} software, if you happen to use
80 ActivePerl.
81 \end{itemize}
82
83 Detailed description of these procedures is beyond the scope of this
84 document.
85
86 As of 2024, no further external software is needed, in contrast to earlier
87 versions.
88
89 \subsection{Installation}
90
91 If pdflatexpicscale.pl is part of your \TeX\ distribution,
92 chances are good that you only have to install missing Perl modules, if
93 any. Otherwise the following should apply:
94
95 Having installed Perl and the required modules, it is sufficient to move
96 the file \texttt{pdflatexpicscale.pl} to a place that is included in your PATH
97 and to make it executable. Of course, there are alternatives. You may perhaps
98 prefer to type the following instead:
99
100 \texttt{perl /path/to/pdflatexpicscale.pl myarticle}\\
101
102 \section{Basic usage}
103
104 \subsection{Preparing your \LaTeX\ file, Part~1}
105
106 I will assume that you use the graphicx package to include images. The most
107 important point is \emph{not} to give path names when you use
108 \verb|\includegraphics|. You do not have to keep all graphics in the current
109 directory, as the graphicx package comes with the
110 \verb|\graphicspath| directive.
111
112 So, if you have all images in the directory where your \LaTeX\ file resides,
113 you are done with this. If not, you should undertake the following steps:
114
115 \begin{enumerate}
116 \item List every path to images within the \verb|\graphicspath| directive.
117 \item Remove the paths from the \verb|\includegraphics| commands.
118 \end{enumerate}
119
120 Here is an example: If your \LaTeX\ file looks like this:
121
122 \begin{verbatim}
123 Some text...
124 \includegraphics[size=2in]{/home/fred/photo1}
125 Some other text...
126 \includegraphics[size=1in]{/srv/www/htdocs/logo}
127 \end{verbatim}
128
129 then you should edit it to the following:
130
131 \begin{verbatim}
132 \graphicspath{{/home/fred/}{/srv/www/htdocs/}}
133 Some text...
134 \includegraphics[size=2in]{photo1}
135 Some other text...
136 \includegraphics[size=1in]{logo}
137 \end{verbatim}
138
139 You hopefully do not have distinct pictures with the same name in the listed
140 folders. With \verb|\graphicspath| you have to use double braces, even if you
141 use only one directory. The best place for the \verb|\graphicspath| statement
142 is probably near the beginning of your \LaTeX\ file.
143
144 \subsection{Preparing your \LaTeX\ file, Part~2}
145
146 As size and resolution of images will change, you should specify the display
147 size of your images by means that are independent of the image, e.g. by using
148 something like\\
149 \verb|\includegraphics[width=.3\textwidth]{...}|\\
150 or\\
151 \verb|\includegraphics[width=2cm]{...}|
152
153 \subsection{A complete example}
154
155 The workflow looks like this:
156
157 \begin{itemize}
158 \item Edit your file.
159 \item Run Pdf\LaTeX\ on your file.
160 \item Create a directory for your scaled pictures.
161 \item Run pdflatexpicscale on your file.
162 \item Change the \verb|\graphicspath| directive in your file to use the
163 downscaled images.
164 \item Run Pdf\LaTeX\ on your file.
165 \end{itemize}
166
167 Let us assume that your \LaTeX\ document is called \texttt{myarticle.tex},
168 that all images reside in the project directory and that you have done the
169 preparation steps described above. Let us further assume that you want to
170 produce a PDF file suitable for preview with 72~dpi image resolution.
171
172 So you create a subdirectory called \texttt{previewpix} and run Pdf\LaTeX\
173 like usual on \texttt{myarticle}. Then you issue\\
174 \texttt{pdflatexpicscale --printdpi=72 --destdir=previewpix myarticle}
175
176 If you are curious, you may insert \texttt{--verbose} anywhere before your
177 project name (and before running it). Then you fire up your editor and add the
178 following line near the beginning of your \LaTeX\ file:
179
180 \verb|\graphicspath{{previewpix/}}|
181
182 You may probably check the size of \texttt{myarticle.pdf}. Then run Pdf\LaTeX\
183 again on \texttt{myarticle}. I have told you to use double braces with
184 \verb|\graphicspath|, haven't I? If you still are curious, you can again
185 check the size of \texttt{myarticle.pdf}.
186
187 When it is time to prepare a print version, you create a directory for images
188 with more detail, say \texttt{printpix}. You reset the \verb|\graphicspath|,
189 run Pdf\LaTeX, issue\\
190 \texttt{pdflatexpicscale --printdpi=300 --destdir=printpix myarticle}\\
191 and set \verb|\graphicspath{{printpix/}}| before the next Pdf\LaTeX\ run.
192
193 \section{Advanced usage}
194
195 \subsection{Excluding files from scaling}
196
197 You will probably exclude files from scaling when you think that scaling will
198 harm. You may achieve this by several means. Before you ask: Enumerating
199 files to exclude is not really cool, so this is not supported.
200
201 \begin{enumerate}
202 \item Use \verb|\includegraphics| for this files with full path names. This is
203 uncool, but can be done.
204 \item Pack these files into a special source directory. Read the following
205 explanation.
206 \end{enumerate}
207
208 It works like this: you create three directories for pictures:
209
210 \begin{itemize}
211 \item One for images to stay unscaled. Let's call it \texttt{hires}
212 \item One for images to scale. Let's call it \texttt{images}
213 \item One for downscaled images. Let's call it \texttt{printimg}
214 \end{itemize}
215
216 Then you use the feature of \verb|\graphicspath| to include several
217 directories. Before the first \LaTeX\ run, you say\\
218 \verb|\graphicspath{{hires/}{images/}}|
219 and after pdflatexpicscale is through, you change it to\\
220 \verb|\graphicspath{{hires/}{printimg/}}|
221
222 \subsection{Monochrome Images}
223
224 While \label{section:monochrome}Pdf\TeX\ supports JBIG2 files,
225 pdflatexpicscale does not. Scaling JBIG2 files down looks like a bad idea,
226 anyway.
227
228 Scaling monochrome\footnote{\emph{Monochrome} in the technical sense of one
229 bit per pixel as opposed to grayscale or color images that use only one
230 color.} images may lead to bad results. I recommend converting them to
231 grayscale before scaling, as blurred details are perhaps better than missing
232 details. pdflatexpicsacle will scale B/W images only if their resolution is at
233 least two times higher as requested.
234
235 \subsection{Gory details}
236
237 pdflatexpicscale reads the log file, not the \LaTeX\ source. So you have to
238 run Pdf\LaTeX\ at least once before something can happen.
239
240 Pure black-and-white images will be treated different from other picture
241 files: They get four times the resolution, as probably every pixel counts.
242 Images that are only a little larger than ideal will not get scaled, but you
243 may change this from the command line.
244 If an image will not be scaled, it will be just copied to the destination
245 directory.
246
247 pdflatexpicscale looks only for the width of images, so if you intend do do
248 anisotropic scaling you will not get best results.
249
250 Clipping will not work with pdflatexpicscale. The \emph{graphicx} package
251 devises picture size from the picture file, then applies clipping to it and
252 afterwards does scaling, rotation and so on. As pdflatexpicscale changes
253 pictures (as well dimensions as nominal resolution), clipping results will
254 change too, you will end up with a mess. The same thing happens when you do
255 not give the figure dimensions in units relying only on document properties
256 (like page width).
257
258 \subsection{Command line options}
259
260 All command line options have to be prepended by two minus signs. If they take
261 arguments, you should add an equal sign and the argument to your option. All
262 command line options are optional, but you have to specify a project name.
263
264 \paragraph{destdir} followed by \emph{a directory name relative to the current
265 directory} specifies where the scaled pictures should go. The default is
266 \texttt{printimg}. The directory has to exist, pdflatexpicscale will not
267 create directories.
268
269 \paragraph{printdpi} followed by the resolution in dpi lets you change the
270 target resolution. Default is 300, for online use you may supply 96, e.g.
271
272 \paragraph{srcdir} followed by \emph{the directory where your unscaled
273 pictures are} is normally not required, as pdflatexpicscale gets the path
274 names from the log file it reads. You may set this option if you have already
275 changed the \verb|\graphicspath| and are too lazy to change it again. The
276 default is empty.
277
278 \paragraph{tolerance} followed by a number lets you change the range in which
279 pictures remain unscaled because they are near the target resolution. Default
280 is 20, that means 20~percent. If target resolution is 300~dpi, files up to
281 320~dpi get accepted too. Change to 0 if you want no tolerance.
282
283 \paragraph{draft/final} Setting one of these options will use reasonable
284 defaults, if you do not want to use any of the further options.
285 Please call \texttt{pdflatexpicscale.pl --help} to see concrete values.
286
287 \paragraph{verbose} entertains you by showing what the program is about to
288 do.
289
290 \paragraph{version} shows the software version.
291
292 Calling pdflatexpicscale.pl without any options and without a project name will
293 display a short usage text.
294
295 \subsection{Printer testing}
296
297 You can---and you should---actually print a file with images scaled to
298 distinct resolutions and compare the results. If paper quality matters for you
299 (inkjet user?), you should repeat this with different paper.
300
301 If you belong to the once-privileged class of people who own a PostScript
302 printer, you may copy the file testprinter.ps to your printer. For all other
303 folks, this file is useless. Software like Ghostscript will convert the
304 rasters to uniform colored areas. Anyway, here is what you should see:
305
306 \begin{itemize}
307 \item The uppermost part of the page will present squares filled with
308 lines. With my printer, 100~lpi is the best I can get.
309
310 \item The middle part of the page shows squares with five levels of gray with
311 dotted raster. The result should be similiar.
312
313 \item The bottom of the page is dedicated to the ends of the gray scale. Can
314 you distinguish 94\% gray from white? Or 6\% gray from black?
315
316 \end{itemize}
317
318 \section{License}
319
320 pdflatexpicscale.pl and the accompanying files are subject to the current
321 version of the \LaTeX\ project public license.
322
323 \section{Bugs, Improvements, and Changes}
324
325 Please submit bug reports to the package author (me). I will be glad to make
326 the package better.\label{bugs}
327
328 The file version dates of all the files in this package shall be kept
329 consistent, even if only one of the files changes. pdflatexpicscale.pl,
330 however, has also a version number. This number will only be changed when
331 there are functional changes to pdflatexpicscale.pl.
332
333 \subsection{Changelog}
334
335 \paragraph{2016-07-28} Upload of first public version to CTAN.
336
337 \paragraph{2016-07-31} Reformatted \emph{Gory details} section and added
338 information about anisotropic scaling and clipping
339
340 \paragraph{2016-08-02} Fixed some typos. Corrected handling of lines wrapped
341 in the log file.
342
343 \paragraph{2016-10-20} Removed a nagging error message when the program was
344 called without arguments. Added the argument \texttt{--help}, both due to
345 suggestions by Karl Berry (thanks a lot).
346
347 \paragraph{2016-12-12} Section on similiar work and prior art added (on request).
348
349 \paragraph{2017-01-22} Added url of TUGboat article.
350
351 \paragraph{2017-01-23} Fixed inconsistent version numbers and changed the url
352 of degrade.sty on recommendation of CTAN board. Added text on versioning at
353 the beginning of section~\ref{bugs}. Thanks a lot to the always quick action
354 and helpful and polite hints.
355
356 \paragraph{2017-02-01} With very long pathnames in the log file,
357 pdflatexpicscale did not find pictures. This is fixed, hopefully.
358
359 \paragraph{2018-02-12} Only changes to this document, not to the software: In
360 this document, the option \texttt{tolerance} had been listed as
361 \texttt{printdpi}. From now on, this is corrected.
362
363 As the TUGboat article corresponding to pdflatexpicscale is freely available
364 now, the link on page~\pageref{tugboatart} has been adjusted.
365
366 \paragraph{2024-10-18}
367
368 Added section~{section:monochrome} with hints for B/W images to
369 documentation. Also did some minor edits, especially to accompany the
370 following changes (see section~\ref{section:requisites}).
371
372 As there have been issues with ImagMagick, pdflatexpicscale no longer uses
373 external software; Perl's GD and Image::ExifTool modules are used instead.
374
375 Added new shortcut options \texttt{--draft} and \texttt{--final}.
376
377 Refactored pdflatexpicscale.pl, hopefully without bad side effects.
378
379 % for file version please see line 8
380 \end{document}
381
382 %%% Local Variables:
383 %%% mode: latex
384 %%% TeX-master: t
385 %%% End: