[misc] / bookmaker.py

#!/usr/bin/env python3
"""
bookmaker.py is a helper for optimizing PDFs of books for the production of small self-printed, self-bound physical books.  Towards this goal it offers various PDF manipulation options that may also be used indepéndently and for other purposes.
"""
help_epilogue = """
EXAMPLES:

Concatenate two PDFs A.pdf and B.pdf to COMBINED.pdf:
    bookmaker.py --input_file A.pdf --input_file B.pdf --output_file COMBINED.pdf

Produce OUTPUT.pdf containing all pages of (inclusive) page number range 3-7 from INPUT.pdf:
    bookmaker.py -i INPUT.pdf --page_range 3-7 -o OUTPUT.pdf

Produce COMBINED.pdf from A.pdf's first 7 pages, B.pdf's pages except its first two, and all pages of C.pdf:
    bookmaker.py -i A.pdf -p start-7 -i B.pdf -p 3-end -i C.pdf -o COMBINED.pdf

Crop each page 5cm from the left, 10cm from the bottom, 2cm from the right, and 0cm from the top:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf --crops "5,10,2,0"

Include all pages from INPUT.pdf, but crop pages 10-20 by 5cm each from bottom and top:
    bookmaker.py -i INPUT.pdf -c "10-20:0,5,0,5" -o OUTPUT.pdf

Same crops for pages 10-20, but also crop all pages 30 and later by 3cm each from left and right:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -c "10-20:0,5,0,5" -c "30-end:3,0,3,0"

Rotate by 90° pages 3, 5, 7; rotate page 7 once more by 90% (i.e. 180° in total):
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf --rotate 3 -r 5 -r 7 -r 7

Initially declare 5cm crop from the left and 1cm crop from right, but alternate direction between even and odd pages:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -c "5,0,1,0" -s

Quarter each OUTPUT.pdf page to carry 4 pages from INPUT.pdf, draw stencils into inner margins for cuts to carry binding strings:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf --nup4

Same --nup4, but define a printable-region margin of 1.3cm to limit the space for the INPUT.pdf pages in OUTPUT.pdf page quarters:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -n --print_margin 1.3

Same --nup4, but draw lines marking printable-region margins, page quarts, spine margins:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -n --analyze

NOTES:

For arguments like -p, page numbers are assumed to start with 1 (not 0, which is treated as an invalid page number value).

The target page shape so far is assumed to be A4 in portrait orientation; bookmaker.py normalizes all pages to this format before applying crops, and removes any source PDF /Rotate commands (for their production of landscape orientations).

For --nup4, the -c cropping instructions do not so much erase content outside the cropped area, but rather zoom into the page in a way that maximes the cropped area as much as possible into the available per-page area between printable-area margins and the borders to the other quartered pages.  If the zoomed cropped area does not fit in neatly into its per-page area, this will preserve additional page content.

The --nup4 quartering puts pages into a specific order optimized for no-tumble duplex print-outs that can easily be folded and cut into pages of a small A6 book.  Each unit of 8 pages from the source PDF is mapped thus onto two subsequent pages (i.e. front and back of a printed A4 paper):

 (front)      (back)
+-------+   +-------+
| 4 | 1 |   | 2 | 3 |
|-------|   |-------|
| 8 | 5 |   | 6 | 7 |
+-------+   +-------+

To facilitate this layout, --nup4 also pads the input PDF pages to a total number that is a multiple of 8, by adding empty pages if necessary.

(To turn above double-sided example page into a tiny 8-page book:  Cut the paper in two on its horizontal middle line.  Fold the two halves by their vertical middle lines, with pages 3-2 and 7-6 on the folds' insides.  This creates two 4-page books of pages 1-4 and pages 5-8.  Fold them both closed and (counter-intuitively) put the book of pages 5-8 on top of the other one (creating a temporary page order of 5,6,7,8,1,2,3,4).  A binding cut stencil should be visible on the top left of this stack – cut it out (with all pages folded together) to add the same inner-margin upper cut to each page.  Turn around your 8-pages stack to find the mirror image of aforementioned stencil on the stack's back's bottom, and cut that out too.  Each page now has binding cuts on top and bottom of its inner margins.  Swap the order of both books (back to the final page order of 1,2,3,4,5,6,7,8), and you now have an 8-pages book that can be "bound" in its binding cuts through a rubber band or the like.  Repeat with the next 8-pages double-page, et cetera.  (Actually, with just 8 pages, the paper may curl under the pressure of a rubber band – but go up to 32 pages or so, and the result will become quite stable.)
"""
import argparse
import io
import os
import sys

def handled_error_exit(msg):
    print(f"ERROR: {msg}")
    sys.exit(1)

try:
    import pypdf
except ImportError:
    handled_error_exit("Can't run at all without pypdf installed.")

# some general paper geometry constants
POINTS_PER_CM = 10 * 72 / 25.4
A4_WIDTH = 21 * POINTS_PER_CM
A4_HEIGHT = 29.7 * POINTS_PER_CM
A4 = (A4_WIDTH, A4_HEIGHT)

# constants specifically for --nup4
A4_HALF_WIDTH = A4_WIDTH / 2
A4_HALF_HEIGHT = A4_HEIGHT / 2
CUT_DEPTH = 1.95 * POINTS_PER_CM
CUT_WIDTH = 1.05 * POINTS_PER_CM
MIDDLE_POINT_DEPTH = 0.4 * POINTS_PER_CM
SPINE_LIMIT = 1 * POINTS_PER_CM
QUARTER_SCALE_FACTOR = 0.5

# some helpers
class HandledException(Exception):
    pass

def validate_page_range(p_string, err_msg_prefix):
    prefix = f"{err_msg_prefix}: page range string"
    if '-' not in p_string:
        raise HandledException(f"{prefix} lacks '-': {p_string}")
    tokens = p_string.split("-")
    if len(tokens) > 2:
        raise HandledException(f"{prefix} has too many '-': {p_string}")
    for i, token in enumerate(tokens):
        if token == "":
            continue
        if i == 0 and token == "start":
            continue
        if i == 1 and token == "end":
            continue
        try:
            int(token)
        except ValueError:
            raise HandledException(f"{prefix} carries value neither integer, nor 'start', nor 'end': {p_string}")
        if int(token) < 1:
            raise HandledException(f"{prefix} carries page number <1: {p_string}")
    start = -1
    end = -1
    try:
        start = int(tokens[0])
        end = int(tokens[1])
    except ValueError:
        pass
    if start > 0 and end > 0 and start > end:
        raise HandledException(f"{prefix} has higher start than end value: {p_string}")

def split_crops_string(c_string):
    initial_split = c_string.split(':')
    if len(initial_split) > 1:
        page_range = initial_split[0]
        crops = initial_split[1]
    else:
        page_range = None
        crops = initial_split[0]
    return page_range, crops

def parse_page_range(range_string, pages):
    start_page = 0
    end_page = len(pages)
    if range_string:
        start, end = range_string.split('-')
        if not (len(start) == 0 or start == "start"):
            start_page = int(start) - 1
        if not (len(end) == 0 or end == "end"):
            end_page = int(end)
    return start_page, end_page

def draw_cut(canvas, x_spine_limit, direction):
    outer_start_x = x_spine_limit - 0.5 * CUT_WIDTH * direction
    inner_start_x = x_spine_limit + 0.5 * CUT_WIDTH * direction
    middle_point_y =  A4_HALF_HEIGHT + MIDDLE_POINT_DEPTH * direction
    end_point_y =  A4_HALF_HEIGHT + CUT_DEPTH * direction
    canvas.line(inner_start_x, A4_HALF_HEIGHT, x_spine_limit, end_point_y)
    canvas.line(x_spine_limit, end_point_y, x_spine_limit, middle_point_y)
    canvas.line(x_spine_limit, middle_point_y, outer_start_x, A4_HALF_HEIGHT)

def parse_args():
    parser = argparse.ArgumentParser(description=__doc__, epilog=help_epilogue, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("-i", "--input_file", action="append", required=True, help="input PDF file")
    parser.add_argument("-o", "--output_file", required=True, help="output PDF file")
    parser.add_argument("-p", "--page_range", action="append", help="page range, e.g., '2-9' or '3-end' or 'start-14'")
    parser.add_argument("-c", "--crops", action="append", help="cm crops left, bottom, right, top – e.g., '10,10,10,10'; prefix with ':'-delimited page range to limit effect")
    parser.add_argument("-r", "--rotate_page", type=int, action="append", help="rotate page of number by 90° (usable multiple times on same page!)")
    parser.add_argument("-s", "--symmetry", action="store_true", help="alternate horizontal crops between odd and even pages")
    parser.add_argument("-n", "--nup4", action='store_true', help="puts 4 input pages onto 1 output page, adds binding cut stencil")
    parser.add_argument("-a", "--analyze", action="store_true", help="in --nup4, print lines identifying spine, page borders")
    parser.add_argument("-m", "--print_margin", type=float, default=0.43, help="print margin for --nup4 in cm (default 0.43)")
    args = parser.parse_args()

    # some basic input validation
    for filename in args.input_file:
        if not os.path.isfile(filename):
            raise HandledException(f"-i: {filename} is not a file")
        try:
            with open(filename, 'rb') as file:
                pypdf.PdfReader(file)
        except pypdf.errors.PdfStreamError:
            raise HandledException(f"-i: cannot interpret {filename} as PDF file")
    if args.page_range:
        for p_string in args.page_range:
            validate_page_range(p_string, "-p")
        if len(args.page_range) > len(args.input_file):
            raise HandledException("-p: more --page_range arguments than --input_file arguments")
    if args.crops:
        for c_string in args.crops:
            initial_split = c_string.split(':')
            if len(initial_split) > 2:
                raise HandledException(f"-c: cropping string has multiple ':': {c_string}")
            page_range, crops = split_crops_string(c_string)
            crops = crops.split(",")
            if page_range:
                validate_page_range(page_range, "-c")
            if len(crops) != 4:
                raise HandledException(f"-c: cropping does not contain exactly three ',': {c_string}")
            for crop in crops:
                try:
                    float(crop)
                except ValueError:
                    raise HandledException(f"-c: non-number crop in: {c_string}")
    if args.rotate_page:
        for r in args.rotate_page:
            try:
                int(r)
            except ValueError:
                raise HandledException(f"-r: non-integer value: {r}")
            if r < 1:
                raise HandledException(f"-r: value must not be <1: {r}")
    try:
        float(args.print_margin)
    except ValueError:
        raise HandledException(f"-m: non-float value: {arg.print_margin}")

    return args

def main():
    args = parse_args()
    if args.nup4:
        try:
            import reportlab.pdfgen.canvas
        except ImportError:
            raise HandledException("-n: need reportlab library installed for --nup4")

    # select pages from input files
    pages_to_add = []
    opened_files = []
    new_page_num = 0
    for i, input_file in enumerate(args.input_file):
        file = open(input_file, 'rb')
        opened_files += [file]
        reader = pypdf.PdfReader(file)
        range_string = None
        if args.page_range and len(args.page_range) > i:
            range_string = args.page_range[i]
        start_page, end_page = parse_page_range(range_string, reader.pages)
        if end_page > len(reader.pages):  # no need to test start_page cause start_page > end_page is checked above
            raise HandledException(f"-p: page range goes beyond pages of input file: {range_string}")
        for old_page_num in range(start_page, end_page):
            new_page_num += 1
            page = reader.pages[old_page_num]
            pages_to_add += [page]
            print(f"-i, -p: read in {input_file} page number {old_page_num+1} as new page {new_page_num}")

    # we can do some more input validations now that we know how many pages output should have
    if args.crops:
        for c_string in args.crops:
            page_range, _= split_crops_string(c_string)
            if page_range:
                start, end = parse_page_range(page_range, pages_to_add)
                if end > len(pages_to_add):
                     raise HandledException(f"-c: page range goes beyond number of pages we're building: {page_range}")
    if args.rotate_page:
        for r in args.rotate_page:
            if r > len(pages_to_add):
                 raise HandledException(f"-r: page number beyond number of pages we're building: {r}")

    # rotate page canvas (as opposed to using PDF's /Rotate command)
    if args.rotate_page:
        for rotate_page in args.rotate_page:
            page = pages_to_add[rotate_page - 1]
            page.add_transformation(pypdf.Transformation().translate(tx=-A4_WIDTH/2, ty=-A4_HEIGHT/2))
            page.add_transformation(pypdf.Transformation().rotate(-90))
            page.add_transformation(pypdf.Transformation().translate(tx=A4_WIDTH/2, ty=A4_HEIGHT/2))
            print(f"-r: rotating (by 90°) page {rotate_page}")

    # if necessary, pad pages to multiple of 8
    if args.nup4:
        mod_to_8 = len(pages_to_add) % 8
        if mod_to_8 > 0:
            print(f"-n: number of input pages {len(pages_to_add)} not multiple of 8, padding to that")
            for _ in range(8 - mod_to_8):
                new_page = pypdf.PageObject.create_blank_page(width=A4_WIDTH, height=A4_HEIGHT)
                pages_to_add += [new_page]

    # normalize all pages to portrait A4
    for page in pages_to_add:
        if "/Rotate" in page:
            page.rotate(360 - page["/Rotate"])
        page.mediabox.left = 0
        page.mediabox.bottom = 0
        page.mediabox.top = A4_HEIGHT
        page.mediabox.right = A4_WIDTH
        page.cropbox = page.mediabox

    # determine page crops, zooms, crop symmetry
    crops_at_page = [(0,0,0,0)]*len(pages_to_add)
    zoom_at_page = [1]*len(pages_to_add)
    if args.crops:
        for c_string in args.crops:
            page_range, crops = split_crops_string(c_string)
            start_page, end_page = parse_page_range(page_range, pages_to_add)
            crop_left_cm, crop_bottom_cm, crop_right_cm, crop_top_cm = [float(x) for x in  crops.split(',')]
            crop_left = crop_left_cm * POINTS_PER_CM
            crop_bottom = crop_bottom_cm * POINTS_PER_CM
            crop_right = crop_right_cm * POINTS_PER_CM
            crop_top = crop_top_cm * POINTS_PER_CM
            prefix = "-c, -t" if args.symmetry else "-c"
            suffix = " (but alternating left and right crop between even and odd pages)" if args.symmetry else ""
            print(f"{prefix}: to pages {start_page + 1} to {end_page} applying crops: left {crop_left_cm}cm, bottom {crop_bottom_cm}cm, right {crop_right_cm}cm, top {crop_top_cm}cm{suffix}")
            cropped_width  = A4_WIDTH - crop_left - crop_right
            cropped_height = A4_HEIGHT - crop_bottom - crop_top
            zoom = 1
            zoom_horizontal = A4_WIDTH / (A4_WIDTH - crop_left - crop_right)
            zoom_vertical = A4_HEIGHT / (A4_HEIGHT - crop_bottom - crop_top)
            if (zoom_horizontal > 1 and zoom_vertical < 1) or (zoom_horizontal < 1 and zoom_vertical > 1):
                raise HandledException("-c: crops would create opposing zoom directions")
            elif zoom_horizontal + zoom_vertical > 2:
                zoom = min(zoom_horizontal, zoom_vertical)
            else:
                zoom = max(zoom_horizontal, zoom_vertical)
            for page_num in range(start_page, end_page):
                if args.symmetry and page_num % 2:
                    crops_at_page[page_num] = (crop_right, crop_bottom, crop_left, crop_top)
                else:
                    crops_at_page[page_num] = (crop_left, crop_bottom, crop_right, crop_top)
                zoom_at_page[page_num] = zoom

    writer = pypdf.PdfWriter()
    if not args.nup4:
        # single-page output
        print("building 1-input-page-per-output-page book")
        odd_page = True
        for i, page in enumerate(pages_to_add):
            crop_left, crop_bottom, crop_right, crop_top = crops_at_page[i]
            zoom = zoom_at_page[i]
            page.add_transformation(pypdf.Transformation().translate(tx=-crop_left, ty=-crop_bottom))
            page.add_transformation(pypdf.Transformation().scale(zoom, zoom))
            cropped_width  = A4_WIDTH - crop_left - crop_right
            cropped_height = A4_HEIGHT - crop_bottom - crop_top
            page.mediabox.right = cropped_width * zoom
            page.mediabox.top = cropped_height * zoom
            writer.add_page(page)
            odd_page = not odd_page
            print(f"built page number {i+1} (of {len(pages_to_add)})")

    else:
        print("-n: building 4-input-pages-per-output-page book")
        print(f"-m: applying printable-area margin of {args.print_margin}cm")
        if args.analyze:
            print("-a: drawing page borders, spine limits")
        printable_margin = args.print_margin * POINTS_PER_CM
        printable_scale = (A4_WIDTH - 2 * printable_margin)/A4_WIDTH
        spine_part_of_page = (SPINE_LIMIT / A4_HALF_WIDTH) / printable_scale
        bonus_shrink_factor = 1 - spine_part_of_page
        new_page_order = []
        new_i_order = []
        eight_pack = []
        i = 0
        n_eights = 0
        for page in pages_to_add:
            if i == 0:
                eight_pack = []
            eight_pack += [page]
            i += 1
            if i == 8:
                i = 0
                new_i_order += [8 * n_eights + 3,
                                8 * n_eights + 0,
                                8 * n_eights + 7,
                                8 * n_eights + 4,
                                8 * n_eights + 1,
                                8 * n_eights + 2,
                                8 * n_eights + 5,
                                8 * n_eights + 6]
                n_eights += 1
                new_page_order += [eight_pack[3]]  # page front, upper left
                new_page_order += [eight_pack[0]]  # page front, upper right
                new_page_order += [eight_pack[7]]  # page front, lower left
                new_page_order += [eight_pack[4]]  # page front, lower right
                new_page_order += [eight_pack[1]]  # page back, upper left
                new_page_order += [eight_pack[2]]  # page back, upper right
                new_page_order += [eight_pack[5]]  # page back, lower left
                new_page_order += [eight_pack[6]]  # page back, lower right
        i = 0
        page_count = 0
        front_page = True
        for j, page in enumerate(new_page_order):
            if i == 0:
                new_page = pypdf.PageObject.create_blank_page(width=A4_WIDTH, height=A4_HEIGHT)

            # in-section transformations: align pages on top, left-hand pages to left, right-hand to right
            new_i = new_i_order[j]
            crop_left, crop_bottom, crop_right, crop_top = crops_at_page[new_i]
            zoom = zoom_at_page[new_i]
            page.add_transformation(pypdf.Transformation().translate(ty=(A4_HEIGHT / zoom - (A4_HEIGHT - crop_top))))
            if i == 0 or i == 2:
                page.add_transformation(pypdf.Transformation().translate(tx=-crop_left))
            elif i == 1 or i == 3:
                page.add_transformation(pypdf.Transformation().translate(tx=(A4_WIDTH / zoom - (A4_WIDTH - crop_right))))
            page.add_transformation(pypdf.Transformation().scale(zoom * bonus_shrink_factor, zoom * bonus_shrink_factor))
            if i == 2 or i == 3:
                page.add_transformation(pypdf.Transformation().translate(ty=-2*printable_margin/printable_scale))

            # outer section transformations
            page.add_transformation(pypdf.Transformation().translate(ty=(1-bonus_shrink_factor)*A4_HEIGHT))
            if i == 0 or i == 1:
                y_section = A4_HEIGHT
                page.mediabox.bottom = A4_HALF_HEIGHT
                page.mediabox.top    = A4_HEIGHT
            if i == 2 or i == 3:
                y_section = 0
                page.mediabox.bottom = 0
                page.mediabox.top  =  A4_HALF_HEIGHT
            if i == 0 or i == 2:
                x_section = 0
                page.mediabox.left   = 0
                page.mediabox.right  = A4_HALF_WIDTH
            if i == 1 or i == 3:
                page.add_transformation(pypdf.Transformation().translate(tx=(1-bonus_shrink_factor)*A4_WIDTH))
                x_section = A4_WIDTH
                page.mediabox.left   = A4_HALF_WIDTH
                page.mediabox.right  = A4_WIDTH
            page.add_transformation(pypdf.Transformation().translate(tx=x_section, ty=y_section))
            page.add_transformation(pypdf.Transformation().scale(QUARTER_SCALE_FACTOR, QUARTER_SCALE_FACTOR))
            new_page.merge_page(page)
            page_count += 1
            print(f"merged page number {page_count} (of {len(pages_to_add)})")
            i += 1
            if i > 3:
                if args.analyze:
                    # borders
                    packet = io.BytesIO()
                    c = reportlab.pdfgen.canvas.Canvas(packet, pagesize=A4)
                    c.setLineWidth(0.1)
                    c.line(0, A4_HEIGHT, A4_WIDTH, A4_HEIGHT)
                    c.line(0, A4_HALF_HEIGHT, A4_WIDTH, A4_HALF_HEIGHT)
                    c.line(0, 0, A4_WIDTH, 0)
                    c.line(0, A4_HEIGHT, 0, 0)
                    c.line(A4_HALF_WIDTH, A4_HEIGHT, A4_HALF_WIDTH, 0)
                    c.line(A4_WIDTH, A4_HEIGHT, A4_WIDTH, 0)
                    c.save()
                    new_pdf = pypdf.PdfReader(packet)
                    new_page.merge_page(new_pdf.pages[0])
                printable_offset_x = printable_margin
                printable_offset_y = printable_margin * A4_HEIGHT / A4_WIDTH
                new_page.add_transformation(pypdf.Transformation().scale(printable_scale, printable_scale))
                new_page.add_transformation(pypdf.Transformation().translate(tx=printable_offset_x, ty=printable_offset_y))
                x_left_spine_limit = A4_HALF_WIDTH * bonus_shrink_factor
                x_right_spine_limit = A4_WIDTH - x_left_spine_limit
                if args.analyze or front_page:
                    packet = io.BytesIO()
                    c = reportlab.pdfgen.canvas.Canvas(packet, pagesize=A4)
                if args.analyze:
                    # spine lines
                    c.setLineWidth(0.1)
                    c.line(x_left_spine_limit, A4_HEIGHT, x_left_spine_limit, 0)
                    c.line(x_right_spine_limit, A4_HEIGHT, x_right_spine_limit, 0)
                if front_page:
                    c.setLineWidth(0.2)
                    draw_cut(c, x_left_spine_limit, (1))
                    draw_cut(c, x_right_spine_limit, (-1))
                if args.analyze or front_page:
                    c.save()
                    new_pdf = pypdf.PdfReader(packet)
                    new_page.merge_page(new_pdf.pages[0])
                writer.add_page(new_page)
                i = 0
                front_page = not front_page

    # write and close
    for file in opened_files:
        file.close()
    with open(args.output_file, 'wb') as output_file:
        writer.write(output_file)


if __name__ == "__main__":
    try:
        main()
    except HandledException as e:
        handled_error_exit(e)