============== pdfCropMargins

The pdfCropMargins program is a command-line application to automatically crop the margins of PDF files. Cropping the margins can make it easier to read the pages of a PDF document -- whether the document is printed or displayed on a screen -- because the display fonts are larger. This program is similar to the Perl script pdfcrop except with many more options.

Features

• Automatically detects the margins and can crop a given percentage of them.
• Can crop all the pages to the same size to give a uniform appearance (such as in two-up).
• Works on Linux, Windows, Cygwin, and OS X/Darwin.
• Has an optional graphical user interface (GUI) for interactive cropping.
• Renders and analyzes page images to find the bounding boxes, which allows it to deal with noisy scanned PDFs.
• A rudimentary 'undo' capability is implemented by default.
• Can crop pages uniformly based on the nth smallest crop values, which helps with noisy images or documents where a few pages have unwanted markings in their margins.
• Can automatically run a document previewer on the output file.
• The format of automatically-generated output-file names is easily modifiable.
• Preserves document catalog information such as outlines if possible.
• Crops rotated pages according to their appearance in the document viewer.
• Can deal with at least simple cases of password-encrypted files.
• Works with either MuPDF, the pdftoppm program, or the Ghostscript program to find the bounding boxes.
• Can automatically apply a Ghostscript repair operation to attempt to fix corrupt PDF files.

This GIF shows the optional GUI, before and after cropping a document:

.. image:: https://user-images.githubusercontent.com/1791335/63413846-9c9e3400-c3c8-11e9-90f5-6e429ae2d74b.gif :width: 450px :align: center :alt: [GIF of pdfCropMargins]

What's New

See the CHANGELOG <https://github.com/abarker/pdfCropMargins/blob/master/CHANGELOG.rst>_ for recent changes and new features.

• Version 2.1.4 extends the uniform and same page size options to allow selecting individual margins. The options are --uniform4 and --samePageSize4, which both take four characters of either 't' or 'f'. It also adds the --replaceOriginal option which is the same as --modifyOriginal but does not create a backup copy.

• Version 2.1.2 has new options to center text on the pages after cropping. They are --centerText, --centerTextHoriz, --centerTextVert, and --centeringStrict.

• New in version 2.0.1, the option --setSamePageSize (-ssp) allows a custom page box size to be passed in rather than having the program calculate the largest containing box size.

Installing

The easiest way to install the pdfCropMargins program is by using pip.

The basic features work out of the box, some of the options require either the external program pdftoppm or Ghostscript. For information on installing those programs on Linux and Windows, see: Installing pdftoppm and/or Ghostscript <https://github.com/abarker/pdfCropMargins/tree/master/doc/installing_pdftoppm_and_ghostscript.rst>_ .

Linux/Ubuntu

If you are installing via pip with the --user option be sure $HOME/.local/bin is in your system PATH. (To install system-wide without --user the pip3 command below would need to be run with sudo.)

.. code-block:: sh

sudo apt install python3-tk sudo apt install ghostscript poppler-utils # Optional, for ghostscript and pdftoppm. pip3 install pdfCropMargins --user --upgrade

Troubleshooting: If you have problems with the install of PyMuPDF, the first thing to try is to upgrade your version of the pip program and then retry:

.. code-block:: sh

pip3 install pip --upgrade --user

If you still get an error "Failed building wheel for pymupdf" with the GUI install you can try forcing a binary install of PyMuPDF:

.. code-block:: sh

pip3 install pdfCropMargins --user --upgrade --only-binary pymupdf

Windows

The install command is:

.. code-block:: sh

pip install pdfCropMargins --upgrade

The pip program should be automatically installed along with Python. If you cannot find the pip executable you can usually run it like this:

.. code-block:: sh

python -m pip <arguments-to-pip>

Note that on some Windows installs the executable for Python is py rather than python.

In order for the command pdfcropmargins to work from the command line the Python bin directory must be on the Windows Path. The system-wide Python bin directory should already be on the path if you checked the box to modify Path when you installed Python; otherwise it should be added. (Note that if you install with the --user option to pip then you need to be sure that the local Python bin directory is in the Windows Path.)

Running

The program can be run 1) from the command line, 2) from the command line with a GUI, 3) from a Python program, or 3) from the source repo.

Running from the command line

After installation via pip the program can be run with either the command pdfcropmargins or the command pdf-crop-margins. For example:

.. code-block:: sh

pdfcropmargins -v -s -u your-file.pdf

That command prints verbose output, forces all pages to be the same size (-s) and then crops each page by the same amount (-u) for a uniform appearance, retaining the default of 10% of the margins. To run the same command with the GUI for fine-tuning, use:

.. code-block:: sh

pdfcropmargins -v -s -u -gui your-file.pdf

For help and to see the many command-line options that are available, run:

.. code-block:: sh

pdfcropmargins -h | more

The full output of that command is also listed below, at the bottom of this page. On Windows you may need to explicitly put the Python distribution's Scripts directory into your environment PATH in order to avoid having to use the full pathname.

Running with the GUI

To run the GUI, assuming that version of pdfCropMargins has been installed, just pass the -gui flag in addition to any other flags. The program is still a command-line application, and still respects all the flags, but the GUI lets you fine-tune the values of some of the command-line arguments such as the percent to crop, etc. The output filenames, etc., are all the same as for the command-line version. Options modifiable from the GUI are initially set to any values passed in on the command line.

The graphical display shows the effect of each crop when you hit the 'Crop' button. Multiple cropping calls for the same document tend to be faster because the PDF pages usually only need to be rendered to images one time.

Python interface

The program can also be called from a user's Python program (when the pdfCropMargins package is discoverable in the Python path). Just import the crop function and then call it with a list containing the usual command-line arguments as separate items. For example:

.. code-block:: python

from pdfCropMargins import crop crop(["-p", "20", "-u", "-s", "paper1.pdf"]) crop(["-p", "0", "-gui", "paper2.pdf"])

Any necessary exception handling should be performed by the calling code. The code may call sys.exit, so checking for SystemExit or BaseException may be required.

The crop function always returns four values, some of which may be set to None:

• the output file path,

• the exit code,

• the text written to standard input,

• the text written to standard output.

If the keyword argument string_io is set true (the default is false) then standard output and standard error streams are temporarily redirected to capture any output text as strings, which are returned as the final two arguments. Otherwise those values are set to None. The keyword argument quiet implies the string_io argument, but does not echo anything to the terminal while the crop function runs.

An example usage:

.. code-block:: python

output_doc_pathname, exit_code, stdout_str, stderr_str = crop( ["-p4", "0", "10", "0", "10", "paper2.pdf"], string_io=True, quiet=False)

Running from the source distribution

The pdfCropMargins program can be run directly from the source code directory tree, provided the dependencies are installed. Just clone the repo and run the program pdfCropMargins.py located in the bin directory.

To pip install the program and its dependencies from the cloned repo rather than from PyPI just go to the root of the source directory and run pip install . (As usual, for code development use the -e option to make the code editable.)

Getting good crops

• To diagnose unexpected crops, look at the pages with the smallest delta values, as indicated in the verbose (-v) output or at the bottom of the GUI. This tells you the page with the smallest crop amount for a margin.

• Running without the -u or -s options will crop each page separately, so you can see which pages might be causing problems (such as pages with noise near the borders or margin text).

• To get cropped pages all the same size be sure to use both -s to first make pages the same size and -u to crop each page by the same amount.

• Sometimes a small pre-crop is needed (-ap or -ap4) to get past small, unwanted markings near the edges of pages.

Documentation

.. In vim use this to get output: :read !pdf-crop-margins -h

To see the documentation, run::

pdf-crop-margins -h | more

The output of that command follows::

Usage: pdfcropmargins [-h] [-o OUTFILE_PATH_OR_DIR] [-v] [-gui] [-p PCT] [-p4 PCT PCT PCT PCT] [-pt] [-