Debian Codegraph @

PKG-INFO

raw
1 Metadata-Version: 2.4
2 Name: img2pdf
3 Version: 0.6.2
4 Summary: Convert images to PDF via direct JPEG inclusion.
5 Home-page: https://gitlab.mister-muffin.de/josch/img2pdf
6 Download-URL: https://gitlab.mister-muffin.de/josch/img2pdf/repository/archive.tar.gz?ref=0.6.2
7 Author: Johannes Schauer Marin Rodrigues
8 Author-email: Johannes Schauer Marin Rodrigues <[email protected]>
9 License: GNU LESSER GENERAL PUBLIC LICENSE
10 Version 3, 29 June 2007
11
12 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
13 Everyone is permitted to copy and distribute verbatim copies
14 of this license document, but changing it is not allowed.
15
16
17 This version of the GNU Lesser General Public License incorporates
18 the terms and conditions of version 3 of the GNU General Public
19 License, supplemented by the additional permissions listed below.
20
21 0. Additional Definitions.
22
23 As used herein, "this License" refers to version 3 of the GNU Lesser
24 General Public License, and the "GNU GPL" refers to version 3 of the GNU
25 General Public License.
26
27 "The Library" refers to a covered work governed by this License,
28 other than an Application or a Combined Work as defined below.
29
30 An "Application" is any work that makes use of an interface provided
31 by the Library, but which is not otherwise based on the Library.
32 Defining a subclass of a class defined by the Library is deemed a mode
33 of using an interface provided by the Library.
34
35 A "Combined Work" is a work produced by combining or linking an
36 Application with the Library. The particular version of the Library
37 with which the Combined Work was made is also called the "Linked
38 Version".
39
40 The "Minimal Corresponding Source" for a Combined Work means the
41 Corresponding Source for the Combined Work, excluding any source code
42 for portions of the Combined Work that, considered in isolation, are
43 based on the Application, and not on the Linked Version.
44
45 The "Corresponding Application Code" for a Combined Work means the
46 object code and/or source code for the Application, including any data
47 and utility programs needed for reproducing the Combined Work from the
48 Application, but excluding the System Libraries of the Combined Work.
49
50 1. Exception to Section 3 of the GNU GPL.
51
52 You may convey a covered work under sections 3 and 4 of this License
53 without being bound by section 3 of the GNU GPL.
54
55 2. Conveying Modified Versions.
56
57 If you modify a copy of the Library, and, in your modifications, a
58 facility refers to a function or data to be supplied by an Application
59 that uses the facility (other than as an argument passed when the
60 facility is invoked), then you may convey a copy of the modified
61 version:
62
63 a) under this License, provided that you make a good faith effort to
64 ensure that, in the event an Application does not supply the
65 function or data, the facility still operates, and performs
66 whatever part of its purpose remains meaningful, or
67
68 b) under the GNU GPL, with none of the additional permissions of
69 this License applicable to that copy.
70
71 3. Object Code Incorporating Material from Library Header Files.
72
73 The object code form of an Application may incorporate material from
74 a header file that is part of the Library. You may convey such object
75 code under terms of your choice, provided that, if the incorporated
76 material is not limited to numerical parameters, data structure
77 layouts and accessors, or small macros, inline functions and templates
78 (ten or fewer lines in length), you do both of the following:
79
80 a) Give prominent notice with each copy of the object code that the
81 Library is used in it and that the Library and its use are
82 covered by this License.
83
84 b) Accompany the object code with a copy of the GNU GPL and this license
85 document.
86
87 4. Combined Works.
88
89 You may convey a Combined Work under terms of your choice that,
90 taken together, effectively do not restrict modification of the
91 portions of the Library contained in the Combined Work and reverse
92 engineering for debugging such modifications, if you also do each of
93 the following:
94
95 a) Give prominent notice with each copy of the Combined Work that
96 the Library is used in it and that the Library and its use are
97 covered by this License.
98
99 b) Accompany the Combined Work with a copy of the GNU GPL and this license
100 document.
101
102 c) For a Combined Work that displays copyright notices during
103 execution, include the copyright notice for the Library among
104 these notices, as well as a reference directing the user to the
105 copies of the GNU GPL and this license document.
106
107 d) Do one of the following:
108
109 0) Convey the Minimal Corresponding Source under the terms of this
110 License, and the Corresponding Application Code in a form
111 suitable for, and under terms that permit, the user to
112 recombine or relink the Application with a modified version of
113 the Linked Version to produce a modified Combined Work, in the
114 manner specified by section 6 of the GNU GPL for conveying
115 Corresponding Source.
116
117 1) Use a suitable shared library mechanism for linking with the
118 Library. A suitable mechanism is one that (a) uses at run time
119 a copy of the Library already present on the user's computer
120 system, and (b) will operate properly with a modified version
121 of the Library that is interface-compatible with the Linked
122 Version.
123
124 e) Provide Installation Information, but only if you would otherwise
125 be required to provide such information under section 6 of the
126 GNU GPL, and only to the extent that such information is
127 necessary to install and execute a modified version of the
128 Combined Work produced by recombining or relinking the
129 Application with a modified version of the Linked Version. (If
130 you use option 4d0, the Installation Information must accompany
131 the Minimal Corresponding Source and Corresponding Application
132 Code. If you use option 4d1, you must provide the Installation
133 Information in the manner specified by section 6 of the GNU GPL
134 for conveying Corresponding Source.)
135
136 5. Combined Libraries.
137
138 You may place library facilities that are a work based on the
139 Library side by side in a single library together with other library
140 facilities that are not Applications and are not covered by this
141 License, and convey such a combined library under terms of your
142 choice, if you do both of the following:
143
144 a) Accompany the combined library with a copy of the same work based
145 on the Library, uncombined with any other library facilities,
146 conveyed under the terms of this License.
147
148 b) Give prominent notice with the combined library that part of it
149 is a work based on the Library, and explaining where to find the
150 accompanying uncombined form of the same work.
151
152 6. Revised Versions of the GNU Lesser General Public License.
153
154 The Free Software Foundation may publish revised and/or new versions
155 of the GNU Lesser General Public License from time to time. Such new
156 versions will be similar in spirit to the present version, but may
157 differ in detail to address new problems or concerns.
158
159 Each version is given a distinguishing version number. If the
160 Library as you received it specifies that a certain numbered version
161 of the GNU Lesser General Public License "or any later version"
162 applies to it, you have the option of following the terms and
163 conditions either of that published version or of any later version
164 published by the Free Software Foundation. If the Library as you
165 received it does not specify a version number of the GNU Lesser
166 General Public License, you may choose any version of the GNU Lesser
167 General Public License ever published by the Free Software Foundation.
168
169 If the Library as you received it specifies that a proxy can decide
170 whether future versions of the GNU Lesser General Public License shall
171 apply, that proxy's public statement of acceptance of any version is
172 permanent authorization for you to choose that version for the
173 Library.
174
175 Project-URL: Home, https://gitlab.mister-muffin.de/josch/img2pdf
176 Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
177 Requires-Python: >=3.5
178 Description-Content-Type: text/markdown
179 License-File: LICENSE
180 Requires-Dist: Pillow
181 Requires-Dist: pikepdf
182 Dynamic: author
183 Dynamic: download-url
184 Dynamic: home-page
185 Dynamic: license-file
186 Dynamic: summary
187
188 [![Travis Status](https://travis-ci.com/josch/img2pdf.svg?branch=main)](https://app.travis-ci.com/josch/img2pdf)
189 [![Appveyor Status](https://ci.appveyor.com/api/projects/status/2kws3wkqvi526llj/branch/main?svg=true)](https://ci.appveyor.com/project/josch/img2pdf/branch/main)
190
191 img2pdf
192 =======
193
194 Lossless conversion of raster images to PDF. You should use img2pdf if your
195 priorities are (in this order):
196
197 1. **always lossless**: the image embedded in the PDF will always have the
198 exact same color information for every pixel as the input
199 2. **small**: if possible, the difference in filesize between the input image
200 and the output PDF will only be the overhead of the PDF container itself
201 3. **fast**: if possible, the input image is just pasted into the PDF document
202 as-is without any CPU hungry re-encoding of the pixel data
203
204 Conventional conversion software (like ImageMagick) would either:
205
206 1. not be lossless because lossy re-encoding to JPEG
207 2. not be small because using wasteful flate encoding of raw pixel data
208 3. not be fast because input data gets re-encoded
209
210 Another advantage of not having to re-encode the input (in most common
211 situations) is, that img2pdf is able to handle much larger input than other
212 software, because the raw pixel data never has to be loaded into memory.
213
214 The following table shows how img2pdf handles different input depending on the
215 input file format and image color space.
216
217 | Format | Colorspace | Result |
218 | ------------------------------------- | ------------------------------------ | ------------- |
219 | JPEG | any | direct |
220 | JPEG2000 | any | direct |
221 | PNG (non-interlaced, no transparency) | any | direct |
222 | TIFF (CCITT Group 4) | 1-bit monochrome | direct |
223 | JBIG2 (single-page generic coding) | 1-bit monochrome | direct |
224 | any | any except CMYK and 1-bit monochrome | PNG Paeth |
225 | any | 1-bit monochrome | CCITT Group 4 |
226 | any | CMYK | flate |
227
228 For JPEG, JPEG2000, non-interlaced PNG, TIFF images with CCITT Group 4
229 encoded data, and JBIG2 with single-page generic coding (e.g. using `jbig2enc`),
230 img2pdf directly embeds the image data into the PDF without
231 re-encoding it. It thus treats the PDF format merely as a container format for
232 the image data. In these cases, img2pdf only increases the filesize by the size
233 of the PDF container (typically around 500 to 700 bytes). Since data is only
234 copied and not re-encoded, img2pdf is also typically faster than other
235 solutions for these input formats.
236
237 For all other input types, img2pdf first has to transform the pixel data to
238 make it compatible with PDF. In most cases, the PNG Paeth filter is applied to
239 the pixel data. For 1-bit monochrome input, CCITT Group 4 is used instead. Only for
240 CMYK input no filter is applied before finally applying flate compression.
241
242 Usage
243 -----
244
245 The images must be provided as files because img2pdf needs to seek in the file
246 descriptor.
247
248 If no output file is specified with the `-o`/`--output` option, output will be
249 done to stdout. A typical invocation is:
250
251 $ img2pdf img1.png img2.jpg -o out.pdf
252
253 The detailed documentation can be accessed by running:
254
255 $ img2pdf --help
256
257 With no command line arguments supplied, img2pdf will read a single image from
258 standard input and write the resulting PDF to standard output. Here is an
259 example for how to scan directly to PDF using scanimage(1) from SANE:
260
261 $ scanimage --mode=Color --resolution=300 | pnmtojpeg -quality 90 | img2pdf > scan.pdf
262
263 Bugs
264 ----
265
266 - If you find a JPEG, JPEG2000, PNG or CCITT Group 4 encoded TIFF file that,
267 when embedded into the PDF cannot be read by the Adobe Acrobat Reader,
268 please contact me.
269
270 - An error is produced if the input image is broken. This commonly happens if
271 the input image has an invalid EXIF Orientation value of zero. Even though
272 only nine different values from 1 to 9 are permitted, Anroid phones and
273 Canon DSLR cameras produce JPEG images with the invalid value of zero.
274 Either fix your input images with `exiftool` or similar software before
275 passing the JPEG to `img2pdf` or run `img2pdf` with `--rotation=ifvalid`
276 (if you run img2pdf from the commandline) or by passing
277 `rotation=img2pdf.Rotation.ifvalid` as an argument to `convert()` when using
278 img2pdf as a library.
279
280 - img2pdf uses PIL (or Pillow) to obtain image meta data and to convert the
281 input if necessary. To prevent decompression bomb denial of service attacks,
282 Pillow limits the maximum number of pixels an input image is allowed to
283 have. If you are sure that you know what you are doing, then you can disable
284 this safeguard by passing the `--pillow-limit-break` option to img2pdf. This
285 allows one to process even very large input images.
286
287 Installation
288 ------------
289
290 On a Debian- and Ubuntu-based systems, img2pdf can be installed from the
291 official repositories:
292
293 $ apt install img2pdf
294
295 If you want to install it using pip, you can run:
296
297 $ pip3 install img2pdf
298
299 If you prefer to install from source code use:
300
301 $ cd img2pdf/
302 $ pip3 install .
303
304 To test the console script without installing the package on your system,
305 use virtualenv:
306
307 $ cd img2pdf/
308 $ virtualenv ve
309 $ ve/bin/pip3 install .
310
311 You can then test the converter using:
312
313 $ ve/bin/img2pdf -o test.pdf src/tests/test.jpg
314
315 If you don't want to setup Python on Windows, then head to the
316 [releases](https://gitlab.mister-muffin.de/josch/img2pdf/releases) section and download the latest
317 `img2pdf.exe`.
318
319 GUI
320 ---
321
322 There exists an experimental GUI with all settings currently disabled. You can
323 directly convert images to PDF but you cannot set any options via the GUI yet.
324 If you are interested in adding more features to the PDF, please submit a merge
325 request. The GUI is based on tkinter and works on Linux, Windows and MacOS.
326
327 ![](screenshot.png)
328
329 Library
330 -------
331
332 The package can also be used as a library:
333
334 import img2pdf
335
336 # opening from filename
337 with open("name.pdf","wb") as f:
338 f.write(img2pdf.convert('test.jpg'))
339
340 # opening from file handle
341 with open("name.pdf","wb") as f1, open("test.jpg") as f2:
342 f1.write(img2pdf.convert(f2))
343
344 # opening using pathlib
345 with open("name.pdf","wb") as f:
346 f.write(img2pdf.convert(pathlib.Path('test.jpg')))
347
348 # using in-memory image data
349 with open("name.pdf","wb") as f:
350 f.write(img2pdf.convert("\x89PNG...")
351
352 # multiple inputs (variant 1)
353 with open("name.pdf","wb") as f:
354 f.write(img2pdf.convert("test1.jpg", "test2.png"))
355
356 # multiple inputs (variant 2)
357 with open("name.pdf","wb") as f:
358 f.write(img2pdf.convert(["test1.jpg", "test2.png"]))
359
360 # convert all files ending in .jpg inside a directory
361 dirname = "/path/to/images"
362 imgs = []
363 for fname in os.listdir(dirname):
364 if not fname.endswith(".jpg"):
365 continue
366 path = os.path.join(dirname, fname)
367 if os.path.isdir(path):
368 continue
369 imgs.append(path)
370 with open("name.pdf","wb") as f:
371 f.write(img2pdf.convert(imgs))
372
373 # convert all files ending in .jpg in a directory and its subdirectories
374 dirname = "/path/to/images"
375 imgs = []
376 for r, _, f in os.walk(dirname):
377 for fname in f:
378 if not fname.endswith(".jpg"):
379 continue
380 imgs.append(os.path.join(r, fname))
381 with open("name.pdf","wb") as f:
382 f.write(img2pdf.convert(imgs))
383
384
385 # convert all files matching a glob
386 import glob
387 with open("name.pdf","wb") as f:
388 f.write(img2pdf.convert(glob.glob("/path/to/*.jpg")))
389
390 # convert all files matching a glob using pathlib.Path
391 from pathlib import Path
392 with open("name.pdf","wb") as f:
393 f.write(img2pdf.convert(*Path("/path").glob("**/*.jpg")))
394
395 # ignore invalid rotation values in the input images
396 with open("name.pdf","wb") as f:
397 f.write(img2pdf.convert('test.jpg'), rotation=img2pdf.Rotation.ifvalid)
398
399 # writing to file descriptor
400 with open("name.pdf","wb") as f1, open("test.jpg") as f2:
401 img2pdf.convert(f2, outputstream=f1)
402
403 # specify paper size (A4)
404 a4inpt = (img2pdf.mm_to_pt(210),img2pdf.mm_to_pt(297))
405 layout_fun = img2pdf.get_layout_fun(a4inpt)
406 with open("name.pdf","wb") as f:
407 f.write(img2pdf.convert('test.jpg', layout_fun=layout_fun))
408
409 # use a fixed dpi of 300 instead of reading it from the image
410 dpix = dpiy = 300
411 layout_fun = img2pdf.get_fixed_dpi_layout_fun((dpix, dpiy))
412 with open("name.pdf","wb") as f:
413 f.write(img2pdf.convert('test.jpg', layout_fun=layout_fun))
414
415 # create a PDF/A-1b compliant document by passing an ICC profile
416 with open("name.pdf","wb") as f:
417 f.write(img2pdf.convert('test.jpg', pdfa="/usr/share/color/icc/sRGB.icc"))
418
419 Comparison to ImageMagick
420 -------------------------
421
422 Create a large test image:
423
424 $ convert logo: -resize 8000x original.jpg
425
426 Convert it into PDF using ImageMagick and img2pdf:
427
428 $ time img2pdf original.jpg -o img2pdf.pdf
429 $ time convert original.jpg imagemagick.pdf
430
431 Notice how ImageMagick took an order of magnitude longer to do the conversion
432 than img2pdf. It also used twice the memory.
433
434 Now extract the image data from both PDF documents and compare it to the
435 original:
436
437 $ pdfimages -all img2pdf.pdf tmp
438 $ compare -metric AE original.jpg tmp-000.jpg null:
439 0
440 $ pdfimages -all imagemagick.pdf tmp
441 $ compare -metric AE original.jpg tmp-000.jpg null:
442 118716
443
444 To get lossless output with ImageMagick we can use Zip compression but that
445 unnecessarily increases the size of the output:
446
447 $ convert original.jpg -compress Zip imagemagick.pdf
448 $ pdfimages -all imagemagick.pdf tmp
449 $ compare -metric AE original.jpg tmp-000.png null:
450 0
451 $ stat --format="%s %n" original.jpg img2pdf.pdf imagemagick.pdf
452 1535837 original.jpg
453 1536683 img2pdf.pdf
454 9397809 imagemagick.pdf
455
456 Comparison to pdfLaTeX
457 ----------------------
458
459 pdfLaTeX performs a lossless conversion from included images to PDF by default.
460 If the input is a JPEG, then it simply embeds the JPEG into the PDF in the same
461 way as img2pdf does it. But for other image formats it uses flate compression
462 of the plain pixel data and thus needlessly increases the output file size:
463
464 $ convert logo: -resize 8000x original.png
465 $ cat << END > pdflatex.tex
466 \documentclass{article}
467 \usepackage{graphicx}
468 \begin{document}
469 \includegraphics{original.png}
470 \end{document}
471 END
472 $ pdflatex pdflatex.tex
473 $ stat --format="%s %n" original.png pdflatex.pdf
474 4500182 original.png
475 9318120 pdflatex.pdf
476
477 Comparison to podofoimg2pdf
478 ---------------------------
479
480 Like pdfLaTeX, podofoimg2pdf is able to perform a lossless conversion from JPEG
481 to PDF by plainly embedding the JPEG data into the pdf container. But just like
482 pdfLaTeX it uses flate compression for all other file formats, thus sometimes
483 resulting in larger files than necessary.
484
485 $ convert logo: -resize 8000x original.png
486 $ podofoimg2pdf out.pdf original.png
487 stat --format="%s %n" original.png out.pdf
488 4500181 original.png
489 9335629 out.pdf
490
491 It also only supports JPEG, PNG and TIF as input and lacks many of the
492 convenience features of img2pdf like page sizes, borders, rotation and
493 metadata.
494
495 Comparison to Tesseract OCR
496 ---------------------------
497
498 Tesseract OCR comes closest to the functionality img2pdf provides. It is able
499 to convert JPEG and PNG input to PDF without needlessly increasing the filesize
500 and is at the same time lossless. So if your input is JPEG and PNG images, then
501 you should safely be able to use Tesseract instead of img2pdf. For other input,
502 Tesseract might not do a lossless conversion. For example it converts CMYK
503 input to RGB and removes the alpha channel from images with transparency. For
504 multipage TIFF or animated GIF, it will only convert the first frame.
505
506 Comparison to econvert from ExactImage
507 --------------------------------------
508
509 Like pdflatex and podofoimg2pf, econvert is able to embed JPEG images into PDF
510 directly without re-encoding but when given other file formats, it stores them
511 just using flate compressen, which unnecessarily increases the filesize.
512 Furthermore, it throws an error with CMYK TIF input. It also doesn't store CMYK
513 jpeg files as CMYK but converts them to RGB, so it's not lossless. When trying
514 to feed it 16bit files, it errors out with Unhandled bps/spp combination. It
515 also seems to choose JPEG encoding when using it on some file types (like
516 palette images) making it again not lossless for that input as well.