deba-bocho 0.5.3

Installation

Requires ImageMagick so you might need to, e.g:

% sudo apt-get install imagemagick

If you want to use Wand instead of calling convert directly, you’ll also need to perform some some additional steps, e.g:

% sudo apt-get install libmagickwand-dev
% pip install wand

See their installation instructions for more details.

On OS X, you’ll want to use Homebrew to get the low-level dependencies in place:

% brew install ghostscript imagemagick

Once all that’s sorted, you just need to pip install deba-bocho.

PyPy: Oh My!

For simple operations, there’s not much difference in performance between CPython and PyPy. If you want to use the shadow effect, it’s a different matter. Cue unscientific benchmarking run on my laptop…

Python 2.7:

% time bocho /tmp/report.pdf --preset example --shadow
...
bocho /tmp/report.pdf --preset example --shadow  35.89s user 0.15s system 99% cpu 36.132 total

PyPy:

% time bocho /tmp/report.pdf --preset example --shadow
...
bocho /tmp/report.pdf --preset example --shadow  4.10s user 0.18s system 99% cpu 4.297 total

Making PyPy about 10x as fast as Python 2.7. The same process without --shadow takes around 2.5 seconds with both implementations.

Usage

For information on usage, run bocho --help. If you want to use it as a module:

>>> import bocho
>>> help(bocho.assemble)

Configuration

If you will be using the same options many times, it’s probably worth creating a preset in a config.ini file (see config.example.ini or the example below to get started).

By default, bocho will check for $HOME/.config/bocho/config.ini, so it’s probably best to keep your config there, but you can pass the --config option with the path to an alternative location.

[example]
pages = 1,3,5,7,9
width = 630
height = 290
border = 4
reuse = true
delete = true
verbose = true
use_convert = true
parallel = 5

You can tell bocho to use this preset by calling:

bocho /path/to/file.pdf --preset example [--config /path/to/config.ini]

TODO

• implement rotation properly ✓

• allow a “zoom” option ✓

• optional drop-shadows ✓

• make shadows smarter in their orientation (they’re currently uniform, not respecting the angle / transformations)

• make the basic edge separators optional ✓

• automatic spacing as an option as well as fixed pixel spacing

• horizontal and vertical spacing ✓

• horizontal and vertical offsets ✓

• optional right-to-left stacking ✓

• handle non-A4 aspect ratio input documents ✓

• optionally apply transforms:

  • affine ✗ (abandoned in favour of vertical / horizontal shear effects)

  • shear ✓ (applied by creating simplified affine transforms)

  • stretch (can be achieved in a similar fashion to shear)

  • perspective

• ensure sliced PNGs are large enough when custom width / height are specified

• fix x and y spacing calculation to account for any applied rotation & transformation

• allow transforms to be configurable (probably with presets defined in an .ini file)

• drop the PyPDF dependency ✓

• use an ImageMagick binding rather than using subprocess to call convert ✓ (Wand)

• optionally re-use pages between runs ✓

• allow user-specified resolution for the PDF to PNG conversion ✓

• docs ✓

• pretty pictures illustrating the effect of the various options

• use proper logging

License

See LICENSE.txt. Test images are from the USC-SIPI Image Database (http://sipi.usc.edu/database/). The test PDF is “Distributed Space-Time Interference Alignment” (arXiv:1405.0032).