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