pdfminify 0.2.1

Description:

pdfminify 0.2.1

pdfminify

pdfminify is intended to re-compress PDF images while operating directly at PDF
level (i.e., no re-compression using PostScript). It parses the PDF file,
hashes all image references, re-links resources that are duplicate (i.e., have
the same MD5 hash value) and also is able to re-compress images which are
stored with lossless compression in order to use JPEG. It tries to calculate
the physical extent of the images (which, depending on the inclusion method,
can be a bit messy) and then is able to calculate the actual image resolution.
If it exceeds a given target resolution, it can also re-sample images (i.e.,
re-scaling them using ImageMagick) before re-integrating them into the target
PDF.
In particular, I wrote this software because PDFs generated by the libcairo PDF
export are huge. Images that are used are included a dozen times and only
lossless compression is used. Therefore I use pdfminify to decrease the
filesize later.
Another use for pdfminify is that it is able to convert PDFs into PDF/A-1b
compliant PDF files. Since this is something that's really difficult to do,
there are no guarantees regarding the resulting PDF -- please check for
yourself if the results still behave identical to your source version.
Finally, pdfminify is able to digitally sign your PDF files. For this you will
need an X.509 certificate and corresponding keypair. The signature will be
included in the PDF in the form a banner with metadata and sophisticated PDF
readers will be able to verify that the PDF has not been tampered with.
Requirements
pdfminify needs at least Python 3.5 and the llpdf Python
package at least v0.0.4. It furthermore
uses the "identify" and "convert" utilities of ImageMagick. It uses the former
to determine the width, height, colorspace and bits per component of image
files and the latter to convert images from PNM (the internal format that
pdfminify is capable of writing natively) to JPEG.
Acknowledgments
pdfminify uses the Toy Parser Generator (TPG) of Christophe Delord
(http://cdsoft.fr/tpg/). It is included (tpg.py file) and licensed under the
GNU LGPL v2.1 or any later version. Despite its name, it is far from a toy. In
fact, it is the most beautiful parser generator I have ever worked with and
makes grammars and parsing exceptionally easy, even for people without any
previous parsing experience. If you need parsing and use Python, TPG is the
go-to solution I would recommend. Seriously, it's amazing. Check it out.
Copyright and license details can be found in EXTERNAL_LICENSES.md.
Usage
$ pdfminify
usage: pdfminify [-h] [-d dpi] [-j] [--jpeg-quality percent]
[--no-downscaling] [--cropbox x,y,w,h]
[--unit {cm,inch,mm,native}] [--one-bit-alpha]
[--remove-alpha] [--background-color color]
[--strip-metadata] [--saveimgdir path] [--raw-output]
[--pretty-pdf] [--no-xref-stream] [--no-object-streams]
[--pdfa-1b] [--color-profile iccfile] [--sign-cert certfile]
[--sign-key keyfile] [--sign-chain pemfile] [--signer name]
[--sign-location hostname] [--sign-contact-info infotext]
[--sign-reason reason] [--sign-page pageno]
[--sign-font pfbfile] [--sign-pos x,y] [--embed-payload path]
[--no-pdf-tagging] [--decompress-data] [--analyze]
[--dump-xref-table] [--no-filters] [-v]
pdf_in pdf_out

Minifies PDF files, can crop them, convert them to PDF/A-1b and sign them
cryptographically.

positional arguments:
pdf_in Input PDF file.
pdf_out Output PDF file.

optional arguments:
-h, --help show this help message and exit
-d dpi, --target-dpi dpi
Default resoulution to which images will be resampled
at. Defaults to 150 dots per inch (dpi).
-j, --jpeg-images Convert images to JPEG format. This means that lossy
compression is used that however often yields a much
higher compression ratio.
--jpeg-quality percent
When converting images to JPEG format, the parameter
gives the compression quality. It is an integer from
0-100 (higher is better, but creates also larger
output files).
--no-downscaling Do not apply downscaling filter on the PDF, take all
images as they are.
--cropbox x,y,w,h Crop pages by additionally adding a /CropBox to all
pages of the PDF file. Pages will be cropped at offset
(x, y) to a width (w, h). The unit in which offset,
width and height are given can be specified using the
--unit parameter.
--unit {cm,inch,mm,native}
Specify the unit of measurement that is used for input
and output. Can be any of cm, inch, mm, native,
defaults to native. One native PDF unit equals 1/72th
of an inch.
--one-bit-alpha Force all alpha channels in images to use a color
depth of one bit. This will make transparent images
have rougher edges, but saves additional space.
--remove-alpha Entirely remove the alpha channel (i.e., transparency)
of all images. The color which with transparent areas
are replaced with can be specified using the
--background-color command line option.
--background-color color
When removing alpha channels, specifies the color that
should be used as background. Defaults to white.
Hexadecimal values can be specified as well in the
format '#rrggbb'.
--strip-metadata Strip metadata inside PDF objects that is not strictly
required, such as /PTEX.* entries inside object
content.
--saveimgdir path When specified, save all handled images as individual
files into the specified directory. Useful for image
extraction from a PDF as well as debugging.
--raw-output When saving images externally, save them in exactly
the format in which they're also present inside the
PDF. Note that this will produce raw image files in
some cases which won't have any header (but just
contain pixel data). Less useful for image extraction,
but can make sense for debugging.
--pretty-pdf Write pretty PDF files, i.e., format all dictionaries
so they're well-readable regarding indentation.
Increases required file size a tiny bit and increases
generation time of the PDF a little, but produces
easily debuggable PDFs.
--no-xref-stream Do not write the XRef table as a XRef stream, but
instead write a classical PDF XRef table and trailer.
This will increase the file size a bit, but might
improve compatibility with old PDF readers (XRef
streams are supported only starting with PDF 1.5).
XRef-streams are a prerequisite to object stream
compression, so if XRef-streams are disabled, so will
also be object streams (e.g, --no-object-streams is
implied).
--no-object-streams Do not compress objects into object-streams. Object
stream compression is introduced with PDF 1.5 and
means that multiple simple objects (without any stream
data) are concatenated together and compressed
together into one large stream object.
--pdfa-1b Try to create a PDF/A-1b compliant PDF document.
Implies --no-xref-stream, --no-object-streams,
--remove-alpha, removes transpacency groups and adds a
PDF/A entry into XMP metadata.
--color-profile iccfile
When creating a PDF/A-1b PDF, gives the Internal Color
Consortium (ICC) color profile that should be embedded
into the PDF as part of the output intent. When
omitted, it defaults to the sRGB IEC61966 v2 "black
scaled" profile which is included within pdfminify.
--sign-cert certfile pdfminify can additionally cryptographically sign your
result PDF file with an X.509 certificate and
corresponding key. This parameter specifies the
certificate filename.
--sign-key keyfile This parameter specifies the key filename, also in PEM
format.
--sign-chain pemfile When signing a PDF, this gives the PEM-formatted
certificate chain file. Can be omitted if this should
not be included in the PKCS#7 signature.
--signer name The name of the person responsible for signing the
document.
--sign-location hostname
The location of the signing; usually this is the
hostname of the computer that the signature is
generated on.
--sign-contact-info infotext
A contact information field under which the signer can
be reached. Usually a phone number of email address.
--sign-reason reason The reason why the document was signed.
--sign-page pageno Page number on which the signature should be
displayed. Defaults to 1.
--sign-font pfbfile To be able to include metadata text in the signature
form, a T1 font must be included into the PDF. This
gives the filename of the font that is to be used for
that purpose. Must be in PFB (PostScript Font Binary)
file format and will be included in the result PDF in
full (i.e., not reduced to the glyphs that are
actually needed). Defaults to the Bitstream Charter
Serif font that is included within pdfminify.
--sign-pos x,y Determines where the signature will be placed on the
page. Units are determined by the --unit variable and
the position is relative to lower left corner.
--embed-payload path Embed an opaque file as a payload into the PDF as a
valid PDF object. This is useful only if you want to
place an easter egg inside your PDF file.
--no-pdf-tagging Omit tagging the PDF file with a reference to
pdfminify and the used version.
--decompress-data Decompress all FlateDecode compressed data in the
file. Useful only for debugging.
--analyze Perform an analysis of the read PDF file and dump out
useful information about it.
--dump-xref-table Dump out the XRef table that was read from the input
PDF file. Mainly useful for debugging.
--no-filters Do not apply any filters on the source PDF whatsoever,
just read it in and write it back out. This is useful
to reformat a PDF and/or debug the PDF reader/writer
facilities without introducing other sources of
malformed PDF generation.
-v, --verbose Show verbose messages during conversation. Can be
specified multiple times to increase log level.

pdfminify version 0.2.1; llpdf version: 0.0.4

Bugs
PDF is an inherently messy format and parsing it really isn't pretty. I've
implemented only what I needed to implement in order to get my job done. I'm
sure there's dozens of examples in which pdfminify just plainly doesn't work or
creates broken output PDFs. Please feel free to fix these errors and send in a
pull request. I think it's a genuinely useful tool and therefore would be nice
to support a wider variety of PDFs than just those that I happen to generate.
If you encounter an issue but are unable to fix it because you don't know
enough about Python, PDF (or either), I will still look at your issue if you
report it on GitHub. However due to my lack of time, I cannot promise that I
can fix it -- to be honest, PDF is so complicated that I'm not even sure that I
can find what the issue is. In any case, be sure to include a minimal example
PDF that demonstrates the issue in the bug report.
License
pdfminify is licensed under the GNU GPL v3 (except for external components as
TPG, which has its own license). Later versions of the GPL are explicitly
excluded.
TPG (Toy Parser Generator) falls under its respective license (see
EXTERNAL_LICENSES.md).