sheet2pdf.py

#!/usr/bin/env python3
"""Put finished sound sheets on A4 pages as one print-ready PDF.

    python sheet2pdf.py -i "sheets/*.png" [-o track.pdf] [--paper a4] [--dpi 600]
                        [--align left] [--bilevel]

Every sheet becomes one page, in the order given.  The raster is placed at
exactly its physical size and never scaled: the signal lives in the length of
each ink bar, so any resampling smears the bar ends.  Print with "Actual size"
/ 100%, never "Fit to page".

Physical size comes from each image's own dpi metadata, or from --dpi.  Pages
are --paper, portrait or landscape -- whichever that sheet fits; a sheet larger
than the paper is refused rather than quietly shrunk.

A last sheet holding fewer strips is narrower than the rest, and --align says
where that one goes: left (default) and right put it flush with the left or the
right edge of the full sheets, center centres it on its own page.  Left is what
a batch scanner wants -- every page then has its strips at the same place, so
one crop fits all of them.  The reference is the widest sheet in the batch,
centred on its page, so a batch of equal sheets sits exactly where it always
did whichever setting is used.

Nothing checks the print scale on the page itself, and nothing needs to: one
strip is one second, so a page the printer scaled comes back with proportionally
more or fewer rows per strip and cut_strips derives the matching sample rate.
Pass its --pitch the width this side printed and it reports the scale as a
number anyway.

Images are embedded losslessly (Flate).  Pillow's own Image.save(".pdf")
re-encodes greyscale as JPEG and sizes the page to the image; this avoids both.
"""
import argparse
import glob
import os
import sys
import zlib

from PIL import Image

import page

MM = 72 / 25.4                 # PDF points per millimetre


def image_object(im, bilevel):
    """Image -> (XObject body, mode). Lossless in every mode."""
    if bilevel:
        # threshold, never dither: error diffusion would smear each bar end
        # across neighbouring rows, and every row is one audio sample
        im = im.convert("1", dither=Image.Dither.NONE)
    elif im.mode not in ("1", "L", "RGB"):
        im = im.convert("L")
    space, bits = ("/DeviceRGB", 8) if im.mode == "RGB" else \
                  ("/DeviceGray", 1 if im.mode == "1" else 8)
    data = zlib.compress(im.tobytes(), 9)
    body = (b"<< /Type /XObject /Subtype /Image /Width %d /Height %d "
            b"/ColorSpace %s /BitsPerComponent %d /Filter /FlateDecode "
            b"/Length %d >>\nstream\n" % (im.width, im.height,
                                          space.encode(), bits, len(data)))
    return body + data + b"\nendstream", im.mode


def sheet_mm(path, dpi):
    """Sheet size in mm, from its own dpi tag unless --dpi overrides it."""
    with Image.open(path) as im:
        dpi = dpi or (im.info.get("dpi") or (None,))[0]
        if not dpi:
            raise SystemExit("%s: no dpi metadata, pass --dpi (the print "
                             "resolution the sheets were generated for)" % path)
        return im.width / dpi * 25.4, im.height / dpi * 25.4, dpi


def sheet_page(path, dpi, bilevel, ids, paper="a4", align="left", widest=None):
    """One sheet -> (page body, content body, image body, one-line report)."""
    page_id, content_id, image_id = ids
    w_mm, h_mm, dpi = sheet_mm(path, dpi)
    widest = widest or w_mm
    # the box follows the widest sheet, so a narrow last page does not land on a
    # differently turned one and lose the alignment it was placed for
    page_w, page_h = page.box(widest, h_mm, paper, path)
    free = (page_w - widest) / 2                  # what the widest sheet leaves
    ox = {"left": free, "center": (page_w - w_mm) / 2,
          "right": free + widest - w_mm}[align]
    oy = (page_h - h_mm) / 2
    im = Image.open(path)

    img, mode = image_object(im, bilevel)
    ops = ["q", "%.3f 0 0 %.3f %.3f %.3f cm" % (w_mm * MM, h_mm * MM, ox * MM, oy * MM),
           "/Im0 Do", "Q"]
    content = "\n".join(ops).encode("ascii")

    body = (b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 %.2f %.2f] /Resources "
            b"<< /XObject << /Im0 %d 0 R >> >> /Contents %d 0 R >>"
            % (page_w * MM, page_h * MM, image_id, content_id))
    stream = b"<< /Length %d >>\nstream\n%s\nendstream" % (len(content), content)
    report = ("%s: %d x %d px @ %g dpi = %.1f x %.1f mm, %s -> %s %s, "
              "margins %.1f x %.1f mm"
              % (path, im.width, im.height, dpi, w_mm, h_mm, mode, paper,
                 "portrait" if page_w < page_h else "landscape", ox, oy))
    return body, stream, img, report


def build(objs):
    """Object bodies (1-based) -> PDF bytes."""
    out = bytearray(b"%PDF-1.4\n%\xe2\xe3\xcf\xd3\n")
    offsets = []
    for i, body in enumerate(objs, 1):
        offsets.append(len(out))
        out += b"%d 0 obj\n" % i + body + b"\nendobj\n"
    xref = len(out)
    out += b"xref\n0 %d\n0000000000 65535 f \n" % (len(objs) + 1)
    for off in offsets:
        out += b"%010d 00000 n \n" % off
    out += (b"trailer\n<< /Size %d /Root 1 0 R >>\nstartxref\n%d\n%%%%EOF\n"
            % (len(objs) + 1, xref))
    return bytes(out)


def convert(paths, out, dpi=None, bilevel=False, paper="a4", align="left"):
    first = 3                   # 1 catalog, 2 page tree, then three per sheet
    widest = max(sheet_mm(p, dpi)[0] for p in paths)
    pages, streams, images, reports = [], [], [], []
    for i, path in enumerate(paths):
        ids = (first + 3 * i, first + 3 * i + 1, first + 3 * i + 2)
        body, stream, img, report = sheet_page(path, dpi, bilevel, ids, paper,
                                               align, widest)
        pages.append(body)
        streams.append(stream)
        images.append(img)
        reports.append(report)

    kids = b" ".join(b"%d 0 R" % (first + 3 * i) for i in range(len(paths)))
    objs = [b"<< /Type /Catalog /Pages 2 0 R >>",
            b"<< /Type /Pages /Kids [%s] /Count %d >>" % (kids, len(paths))]
    for triple in zip(pages, streams, images):
        objs += list(triple)
    with open(out, "wb") as f:
        f.write(build(objs))

    for r in reports:
        print(r)
    print("%s: %d page%s, %.2f MB"
          % (out, len(paths), "" if len(paths) == 1 else "s", os.path.getsize(out) / 1e6))
    print('print at 100% / "Actual size", never "Fit to page"')
    print("cut_strips --pitch reports the scale on the way back, so nothing "
          "needs measuring on paper")


def demo():
    """Synthetic sheets through the writer, cross-checked with pypdf if present."""
    import re
    import tempfile
    with tempfile.TemporaryDirectory() as d:
        pdf = os.path.join(d, "out.pdf")
        srcs = []
        for k in range(3):
            p = os.path.join(d, "sheet_%d.png" % k)
            Image.new("L", (4724, 6590), 255).save(p, dpi=(600, 600))
            srcs.append(p)

        convert(srcs, pdf)
        a4_w, a4_h = (v * MM for v in page.paper("a4"))
        raw = open(pdf, "rb").read()
        assert b"/DCTDecode" not in raw, "greyscale must not be re-encoded as JPEG"
        assert b"/FlateDecode" in raw
        assert b"/Count 3" in raw and raw.count(b"/Type /Page ") == 3
        assert b"/Font" not in raw, "no page needs a font"
        boxes = re.findall(rb"/MediaBox \[0 0 ([\d.]+) ([\d.]+)\]", raw)
        assert len(boxes) == 3 and all(abs(float(w) - a4_w) < 0.1 and
                                       abs(float(h) - a4_h) < 0.1 for w, h in boxes), boxes
        cm = re.findall(rb"([\d.]+) 0 0 ([\d.]+) ([\d.]+) ([\d.]+) cm", raw)
        assert len(cm) == 3
        w_pt, h_pt = float(cm[0][0]), float(cm[0][1])
        # placed at exactly px/dpi, not at some tidy rounded size, and centred
        assert abs(w_pt / MM - 4724 / 600 * 25.4) < 0.01, cm[0]
        assert abs(h_pt / MM - 6590 / 600 * 25.4) < 0.01, cm[0]
        assert abs(float(cm[0][2]) * 2 + w_pt - a4_w) < 0.1
        assert abs(float(cm[0][3]) * 2 + h_pt - a4_h) < 0.1

        # a short last sheet: --align decides where it sits under the full ones
        narrow = os.path.join(d, "narrow.png")
        Image.new("L", (4724 // 2, 6590), 255).save(narrow, dpi=(600, 600))
        origins = {}
        for how in ("left", "center", "right"):
            convert(srcs[:1] + [narrow], pdf, align=how)
            cm = re.findall(rb"([\d.]+) 0 0 ([\d.]+) ([\d.]+) ([\d.]+) cm",
                            open(pdf, "rb").read())
            origins[how] = [(float(c[2]), float(c[0])) for c in cm]   # (x, width)
        (fx, fw), (nx, nw) = origins["left"]
        assert abs(fx - nx) < 0.01, "left should share the left edge"
        (fx, fw), (nx, nw) = origins["right"]
        assert abs((fx + fw) - (nx + nw)) < 0.01, "right should share the right edge"
        (fx, fw), (nx, nw) = origins["center"]
        assert abs((a4_w - nw) / 2 - nx) < 0.01, "center should centre the narrow one"
        assert nx > fx, "and that is not where left put it"

        # bilevel stays 1 bit per pixel and gets smaller
        convert(srcs[:1], pdf + "1", bilevel=True)
        assert b"/BitsPerComponent 1" in open(pdf + "1", "rb").read()
        assert os.path.getsize(pdf + "1") < os.path.getsize(pdf)

        # a sheet that only fits sideways lands on a landscape page
        land = os.path.join(d, "land.png")
        Image.new("L", (6590, 4400), 255).save(land, dpi=(600, 600))
        convert([land], pdf)
        box = re.search(rb"/MediaBox \[0 0 ([\d.]+) ([\d.]+)\]",
                        open(pdf, "rb").read()).groups()
        assert abs(float(box[0]) - a4_h) < 0.1, box

        # bigger than A4 is refused, not shrunk
        big = os.path.join(d, "big.png")
        Image.new("L", (8000, 6590), 255).save(big, dpi=(600, 600))
        try:
            convert([big], pdf)
            assert False, "oversized sheet accepted"
        except SystemExit:
            pass

        # no dpi anywhere is an error, not a guess
        nodpi = os.path.join(d, "nodpi.png")
        Image.new("L", (100, 100), 255).save(nodpi)
        try:
            convert([nodpi], pdf)
            assert False, "missing dpi silently guessed"
        except SystemExit:
            pass

        try:
            from pypdf import PdfReader
        except ImportError:
            print("demo ok (pypdf absent, structure checked by hand)")
            return
        convert(srcs, pdf)              # the landscape test above left one page
        r = PdfReader(pdf)
        assert len(r.pages) == 3
        for pg in r.pages:
            assert abs(float(pg.mediabox.width) - a4_w) < 0.1
            assert pg.images[0].image.size == (4724, 6590)
    print("demo ok")


if __name__ == "__main__":
    if "--demo" in sys.argv:
        demo()
        raise SystemExit
    p = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("-i", "--input", required=True, nargs="+",
                   help="sheet images or glob patterns, one page each, in order")
    p.add_argument("-o", "--output", help="PDF path (default: next to the sheets)")
    p.add_argument("--dpi", type=float, help="print resolution the sheets were "
                                             "generated for; overrides the image metadata")
    page.add_align_arg(p)
    p.add_argument("--bilevel", action="store_true",
                   help="threshold to 1 bit per pixel, so the printer's halftone "
                        "screen never gets to reinterpret the bar ends")
    page.add_paper_arg(p)
    a = p.parse_args()
    # expand globs here: cmd.exe and PowerShell pass them through as-is
    files = [f for x in a.input for f in (sorted(glob.glob(x)) or [x])]
    if a.output:
        out = a.output
    elif len(files) == 1:
        out = os.path.splitext(files[0])[0] + ".pdf"
    else:
        # name the PDF after the folder holding the sheets, not after sheet 1
        out = (os.path.dirname(files[0]) or os.path.abspath(".")) + ".pdf"
    convert(files, out, a.dpi, a.bilevel, a.paper, a.align)