v11.3.0 release notes

Commit 1327ab3 introduced a fix for a regression, which was reported
in #581, #634. It appears that the actual cause of this issue was
default parameters to rasterize_pdf_page in pluggy not working as
expected, causing a default rotation=0 even when a rotation was needed.
As such the OCR image was generated with the wrong orientation,
causing the initial regression and fix in commit 1327ab3.

Now that the real problem is identified, it's apparent that the logic
prior to 1327ab3 was found and we can revert to 1327ab3 since it fixes
all known cases including #658.

This reverts 1327ab3 except for retaining improves to rotation output.

.github/ISSUE_TEMPLATE/1-general-issues.md

@@ -0,0 +1,28 @@
+---
+name: General issues
+about: Installation, packages, dependencies, "nothing works", test suite failures...
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+What's the problem?
+
+**To Reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+What did you expected to happen?
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**System (please complete the following information):**
+ - OS:
+ - Python version: 
+ - OCRmyPDF version:
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/2-problem-with-a-specific-input-file.md

@@ -1,6 +1,6 @@
 ---
-name: Bug report
+name: Problem with a specific input file
-about: Create a report to help us improve
+about: Something went wrong while trying to OCR a specific file
 title: ''
 labels: ''
 assignees: ''
@@ -20,13 +20,13 @@ ocrmypdf  ...arguments... input.pdf output.pdf
 Run with verbosity or higher `-v1` to see more detailed logging. This information may be helpful.
 
 **Example file**
-Include an input PDF or image that demonstrates your issue.
+If your issue is a problem that affects only certain files, and we will require an input file (PDF or image) that demonstrates your issue.
 
-Please provide an input file with no personal or confidential information. At your option you may `GPG-encrypt the file <https://github.com/jbarlow83/OCRmyPDF/wiki>` for OCRmyPDF's author only.
+Please provide an input file with no personal or confidential information. At your option you may [GPG-encrypt the file](https://github.com/jbarlow83/OCRmyPDF/wiki) for OCRmyPDF's author only.
 
 Links to files hosted elsewhere are perfectly acceptable. You could also look in ``tests/resources`` and see if any of those files reproduce your issue.
 
-(Exceptions: Issues with installation, command line argument parsing, test suite failures.Issues without example files usually cannot be resolved.)
+*(Issues without example files usually cannot be resolved. It's like reporting an issue against a web browser without providing a URL.)*
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.

.github/ISSUE_TEMPLATE/3-feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ''
-labels: enhancement
+labels: ''
 assignees: ''
 
 ---
@@ -13,5 +13,8 @@ A clear and concise description of what the problem is. Ex. I'm always frustrate
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
 **Additional context**
 Add any other context or screenshots about the feature request here.

.github/issue_template.md

@@ -1,32 +0,0 @@
-**Describe the issue**
-A clear and concise description of what the issue is.
-
-**To Reproduce**
-What command line were you trying to run?
-
-```bash
-ocrmypdf  ...arguments... input.pdf output.pdf
-```
-
-**Example file**
-Please include an example *input* PDF (or image). You could also try to use of the files in ``tests/resources/`` to illustrate your issue.
-
-Please check any or all that apply about the example file:
-
-- [ ] This is the input file
-- [ ] The file contains no personal or confidential information
-
-Please do *not* submit files with confidential information. At your option you may encrypt files for OCRmyPDF's author only.
-
-Issues submitted without an example input file are less likely to be resolved. The output file is generally not helpful.
-
-**Expected behavior**
-A clear and concise description of what you expected to happen. Include screenshots if applicable.
-
-**System:**
-
-- OS: [e.g. Linux, macOS]
-- OCRmyPDF Version: [e.g. v10.3.0]
-
-**Additional context**
-Add any other context about the problem here.

.gitignore

@@ -7,6 +7,7 @@
 !.gitignore
 !.pre-commit-config.yaml
 !.readthedocs.yml
+!.github/
 
 # Dev scratch
 *.ipynb

azure-pipelines.yml

@@ -149,12 +149,6 @@ stages:
       - job: "macOS_Mojave"
         pool:
           vmImage: "macos-10.14"
-        strategy:
-          matrix:
-            Python37:
-              python.version: ""
-            Python38:
-              python.version: "python@3.8"
         steps:
           # https://github.com/actions/virtual-environments/issues/664
           # - task: UsePythonVersion@0
@@ -163,11 +157,8 @@ stages:
           - bash: |
               brew update
               brew unlink python@2
-              if [ "$(python.version)" != "" ]; then
+              brew upgrade python
-                brew upgrade $(python.version)
+              echo "Using Python `python3 --version`"
-              else
-                echo "Using Python `python3 --version`"
-              fi
             displayName: "Update brew and Python"
           - bash: |
               brew install \
@@ -177,8 +168,7 @@ stages:
                 leptonica \
                 openjpeg \
                 pngquant \
-                tesseract \
+                tesseract
-                unpaper
             displayName: "Install system packages"
           - bash: |
               pip3 install --upgrade pip

docs/installation.rst

@@ -190,7 +190,8 @@ of ocrmypdf, and install the following dependencies:
         python3-reportlab \
         qpdf \
         tesseract-ocr \
-        zlib1g
+        zlib1g \
+        unpaper
 
 We will need a newer version of ``pip`` then was available for Ubuntu 18.04:
 

docs/release_notes.rst

@@ -12,6 +12,76 @@ may be unreliable. Use the API to depend on precise behavior.
 The public API may be useful in scripts that launch OCRmyPDF processes or that
 wish to use some of its features for working with PDFs.
 
+v11.3.0
+=======
+
+-  The "OCR" step is describing as "Image processing" in the output messages when
+   OCR is disabled, to better explain the application's behavior.
+-  Debug logs are now only created when run as a command line, and not when OCR
+   is performed for an API call. It is the calling application's responsibility
+   to set up logging.
+-  For PDFs with a low number of pages, we gathered information about the input PDF
+   in a thread rather than process (when there are more pages). When run as a
+   thread, we did not close the file handle to the working PDF, leaking one file
+   handle per call of ``ocrmypdf.ocr``.
+-  Fixed an issue where debug messages send by child worker processes did not match
+   the log settings of parent process, causing messages to be dropped. This affected
+   macOS and Windows only where the parent process is not forked.
+-  Fixed the hookspec of rasterize_pdf_page to remove default parameters that
+   were not handled in an expected way by pluggy.
+-  Fixed another issue with automatic page rotation (#658) due to the issue above.
+
+v11.2.1
+=======
+
+-  Fixed an issue where optimization of a 1-bit image with a color palette or
+   associated ICC that was optimized to JBIG2 could have its colors inverted.
+
+v11.2.0
+=======
+
+-  Fixed an issue with optimizing PNG-type images that had soft masks or image masks.
+   This is a regression introduced in (or about) v11.1.0.
+-  Improved type checking of the ``plugins`` parameter for the ``ocrmypdf.ocr``
+   API call.
+
+v11.1.2
+=======
+
+-  Fixed hOCR renderer writing the text in roughly reverse order. This should not
+   affect reasonably smart PDF readers that properly locate the position of all
+   text, but may confuse those that rely on the order of objects in the content
+   stream. (#642)
+
+v11.1.1
+=======
+
+-  We now avoid using named temporary files when using pngquant allowing containerized
+   pngquant installs to be used.
+-  Clarified an error message.
+-  Highest number of 1's in a release ever!
+
+v11.1.0
+=======
+
+-  Fixed page rotation issues: #634, #589.
+-  Fixed some cases where optimization created an invalid image such as a
+   1-bit "RGB" image: #629, #620.
+-  Page numbers are now displayed in debug logs when pages are being grafted.
+-  ocrmypdf.optimize.rewrite_png and ocrmypdf.optimize.rewrite_png_as_g4 were
+   marked deprecated. Strictly speaking these should have been internal APIs,
+   but they were never hidden.
+-  As a precaution, pikepdf mmap-based file access has been disabled due to a
+   rare race condition that causes a crash when certain objects are deallocated.
+   The problem is likely in pikepdf's dependency pybind11.
+-  Extended the example plugin to demonstrate conversion to mono.
+
+v11.0.2
+=======
+
+-  Fixed issue #612, TypeError exception. Fixed by eliminating unnecessary repair of
+   input PDF metadata in memory.
+
 v11.0.1
 =======
 

misc/example_plugin.py

@@ -18,6 +18,25 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""
+An example of an OCRmyPDF plugin.
+
+This plugin adds two new command line arguments
+    --grayscale-ocr: converts the image to grayscale before performing OCR on it
+        (This is occasionally useful for images whose color confounds OCR. It only
+        affects the image shown to OCR. The image is not saved.)
+    --mono-page: converts pages all pages in the output file to black and white
+
+To use this from the command line:
+    ocrmypdf --plugin path/to/example_plugin.py --mono-page input.pdf output.pdf
+
+To use this as an API:
+    import ocrmypdf
+    ocrmypdf.ocr('input.pdf', 'output.pdf',
+        plugins=['path/to/example_plugin.py'], mono_page=True
+    )
+"""
+
 import logging
 
 from PIL import Image
@@ -30,6 +49,7 @@ log = logging.getLogger(__name__)
 @hookimpl
 def add_options(parser):
     parser.add_argument('--grayscale-ocr', action='store_true')
+    parser.add_argument('--mono-page', action='store_true')
 
 
 @hookimpl
@@ -52,7 +72,13 @@ def filter_ocr_image(page, image):
 
 @hookimpl
 def filter_page_image(page, image_filename):
-    output = image_filename.with_suffix('.jpg')
+    if page.options.mono_page:
-    with Image.open(image_filename) as im:
+        with Image.open(image_filename) as im:
-        im.save(output)
+            im = im.convert('1')
-    return output
+            im.save(image_filename)
+        return image_filename
+    else:
+        output = image_filename.with_suffix('.jpg')
+        with Image.open(image_filename) as im:
+            im.save(output)
+        return output

setup.py

@@ -76,7 +76,7 @@ setup(
         'pdfminer.six >= 20191110, != 20200720, <= 20200726',
         'pikepdf >= 1.14.0, < 2',
         'Pillow >= 7.0.0',
-        'pluggy >= 0.13.0',
+        'pluggy >= 0.13.0, < 1.0',
         'reportlab >= 3.3.0',  # oldest released version with sane image handling
         'tqdm >= 4',
     ],

src/ocrmypdf/_concurrent.py

@@ -49,7 +49,7 @@ def process_sigbus(*args):
     raise InputFileError("A worker process lost access to an input file")
 
 
-def process_init(queue, user_init):
+def process_init(queue, user_init, loglevel):
     """Initialize a process pool worker"""
 
     # Ignore SIGINT (our parent process will kill us gracefully)
@@ -62,6 +62,7 @@ def process_init(queue, user_init):
     # Reconfigure the root logger for this process to send all messages to a queue
     h = logging.handlers.QueueHandler(queue)
     root = logging.getLogger()
+    root.setLevel(loglevel)
     root.handlers = []
     root.addHandler(h)
 
@@ -69,7 +70,7 @@ def process_init(queue, user_init):
         user_init()
 
 
-def thread_init(_queue, user_init):
+def thread_init(_queue, user_init, _loglevel):
     # As a thread, block SIGBUS so the main thread deals with it...
     if hasattr(signal, 'SIGBUS'):
         signal.pthread_sigmask(signal.SIG_BLOCK, {signal.SIGBUS})
@@ -102,7 +103,7 @@ def exec_progress_pool(
         pool = pool_class(
             processes=max_workers,
             initializer=initializer,
-            initargs=(log_queue, task_initializer),
+            initargs=(log_queue, task_initializer, logging.getLogger("").level),
         )
         try:
             results = pool.imap_unordered(task, task_arguments)

src/ocrmypdf/_exec/ghostscript.py

@@ -81,8 +81,8 @@ def rasterize_pdf(
     raster_device: str,
     raster_dpi: Resolution,
     pageno: int = 1,
-    page_dpi: Resolution = None,
+    page_dpi: Optional[Resolution] = None,
-    rotation: int = None,
+    rotation: Optional[int] = None,
     filter_vector: bool = False,
 ):
     """Rasterize one page of a PDF at resolution raster_dpi in canvas units."""

src/ocrmypdf/_exec/pngquant.py

@@ -7,7 +7,11 @@
 
 """Interface to pngquant executable"""
 
+from contextlib import contextmanager
+from io import BytesIO
 from os import fspath
+from pathlib import Path
+from subprocess import PIPE
 from tempfile import NamedTemporaryFile
 
 from PIL import Image
@@ -28,34 +32,32 @@ def available():
     return True
 
 
-def quantize(input_file, output_file, quality_min, quality_max):
+@contextmanager
-    input_file = fspath(input_file)
+def input_as_png(input_file: Path):
-    output_file = fspath(output_file)
+    if not input_file.name.endswith('.png'):
-    if input_file.endswith('.jpg'):
+        with Image.open(input_file) as im:
-        with Image.open(input_file) as im, NamedTemporaryFile(suffix='.png') as tmp:
+            bio = BytesIO()
-            im.save(tmp)
+            im.save(bio, format='png')
-            args = [
+            bio.seek(0)
-                'pngquant',
+            yield bio
-                '--force',
-                '--skip-if-larger',
-                '--output',
-                output_file,
-                '--quality',
-                f'{quality_min}-{quality_max}',
-                '--',
-                tmp.name,
-            ]
-            run(args)
     else:
+        with open(input_file, 'rb') as f:
+            yield f
+
+
+def quantize(input_file: Path, output_file: Path, quality_min: int, quality_max: int):
+    with input_as_png(input_file) as input_stream:
         args = [
             'pngquant',
             '--force',
             '--skip-if-larger',
-            '--output',
-            output_file,
             '--quality',
             f'{quality_min}-{quality_max}',
-            '--',
+            '--',  # pngquant: stop processing arguments
-            input_file,
+            '-',  # pngquant: stream input and output
         ]
-        run(args)
+        result = run(args, stdin=input_stream, stdout=PIPE, stderr=PIPE, check=False)
+
+    if result.returncode == 0:
+        # input_file could be the same as output_file, so we defer the write
+        output_file.write_bytes(result.stdout)

src/ocrmypdf/_exec/unpaper.py

@@ -107,7 +107,7 @@ def run(input_file, output_file, dpi, mode_args):
 
 def validate_custom_args(args: str):
     unpaper_args = shlex.split(args)
-    if any('/' in arg for arg in unpaper_args):
+    if any(('/' in arg or arg == '.' or arg == '..') for arg in unpaper_args):
         raise ValueError('No filenames allowed in --unpaper-args')
     return unpaper_args
 

src/ocrmypdf/_graft.py

@@ -125,34 +125,38 @@ class OcrGrafter:
                 del self.pdf_base.pages[-1]
             emplaced_page = True
 
+        # Calculate if the text is misaligned compared to the content
         if emplaced_page:
             content_rotation = autorotate_correction
         text_rotation = autorotate_correction
         text_misaligned = (text_rotation - content_rotation) % 360
         log.debug(
-            f"Rotations for page {pageno}: [text, auto, misalign, content] = "
+            f"Text rotation: (text, autorotate, content) -> text misalignment = "
-            f"{text_rotation}, {autorotate_correction}, "
+            f"({text_rotation}, {autorotate_correction}, {content_rotation}) -> {text_misaligned}"
-            f"{text_misaligned}, {content_rotation}"
         )
 
         if textpdf and self.font:
-            # Graft the text layer onto this page, whether new or old
+            # Graft the text layer onto this page, whether new or old, possibly
+            # rotating the text layer by the amount is misaligned.
             strip_old = self.context.options.redo_ocr
             self._graft_text_layer(
                 page_num=pageno + 1,
                 textpdf=textpdf,
                 font=self.font,
                 font_key=self.font_key,
-                rotation=text_misaligned,
+                text_rotation=text_misaligned,
                 procset=self.procset,
                 strip_old_text=strip_old,
             )
 
-        # Correct the rotation if applicable
+        # Correct the overall page rotation if needed, now that the text and content
-        self.pdf_base.pages[pageno].Rotate = (
+        # are aligned
-            content_rotation - autorotate_correction
+        page_rotation = (content_rotation - autorotate_correction) % 360
-        ) % 360
+        self.pdf_base.pages[pageno].Rotate = page_rotation
-
+        log.debug(
+            f"Page rotation: (content, auto) -> page = "
+            f"({content_rotation}, {autorotate_correction}) -> {page_rotation}"
+        )
         if self.emplacements % MAX_REPLACE_PAGES == 0:
             self.save_and_reload()
 
@@ -226,7 +230,7 @@ class OcrGrafter:
         font: pikepdf.Object,
         font_key: pikepdf.Object,
         procset: pikepdf.Object,
-        rotation: int,
+        text_rotation: int,
         strip_old_text: bool,
     ):
         """Insert the text layer from text page 0 on to pdf_base at page_num"""
@@ -256,13 +260,13 @@ class OcrGrafter:
             corner = pikepdf.PdfMatrix().translated(mediabox[0], mediabox[1])
             # -rotation because the input is a clockwise angle and this formula
             # uses CCW
-            rotation = -rotation % 360
+            text_rotation = -text_rotation % 360
-            rotate = pikepdf.PdfMatrix().rotated(rotation)
+            rotate = pikepdf.PdfMatrix().rotated(text_rotation)
 
             # Because of rounding of DPI, we might get a text layer that is not
             # identically sized to the target page. Scale to adjust. Normally this
             # is within 0.998.
-            if rotation in (90, 270):
+            if text_rotation in (90, 270):
                 wt, ht = ht, wt
             scale_x = wp / wt
             scale_y = hp / ht

src/ocrmypdf/_pipeline.py

@@ -332,8 +332,10 @@ def rasterize_preview(input_file: Path, page_context: PageContext):
         output_file=output_file,
         raster_device='jpeggray',
         raster_dpi=canvas_dpi,
-        page_dpi=page_dpi,
         pageno=page_context.pageinfo.pageno + 1,
+        page_dpi=page_dpi,
+        rotation=0,
+        filter_vector=False,
     )
     return output_file
 
@@ -433,7 +435,7 @@ def rasterize(
 
     device = colorspaces[device_idx]
 
-    log.debug(f"Rasterize with {device}")
+    log.debug(f"Rasterize with {device}, rotation {correction}")
 
     # Produce the page image with square resolution or else deskew and OCR
     # will not work properly.
@@ -534,6 +536,9 @@ def create_ocr_image(image: Path, page_context: PageContext):
 
         # Pillow requires integer DPI
         dpi = tuple(round(coord) for coord in im.info['dpi'])
+        if page_context.pageinfo.rotation != 0:
+            log.info(f"Rotating {page_context.pageinfo.rotation}")
+            im = im.rotate(page_context.pageinfo.rotation)
         im.save(output_file, dpi=dpi)
     return output_file
 
@@ -753,7 +758,9 @@ def metadata_fixup(working_file: Path, context: PdfContext):
             # Reverse this, because PDF/A TechNote 0003:Metadata in PDF/A-1
             # and the XMP Spec do not make this recommendation.
             if meta.get('dc:title') == 'Untitled':
-                with original.open_metadata() as original_meta:
+                with original.open_metadata(
+                    set_pikepdf_as_editor=False, update_docinfo=False
+                ) as original_meta:
                     if 'dc:title' not in original_meta:
                         del meta['dc:title']
 

src/ocrmypdf/_sync.py

@@ -209,9 +209,10 @@ def exec_page_sync(page_context: PageContext):
     if options.pdf_renderer == 'hocr':
         (hocr_out, text_out) = ocr_engine_hocr(ocr_image_out, page_context)
         ocr_out = render_hocr_page(hocr_out, page_context)
-
+    elif options.pdf_renderer == 'sandwich':
-    if options.pdf_renderer == 'sandwich':
         (ocr_out, text_out) = ocr_engine_textonly_pdf(ocr_image_out, page_context)
+    else:
+        raise NotImplementedError(f"pdf_renderer {options.pdf_renderer}")
 
     return PageResult(
         pageno=page_context.pageno,
@@ -244,7 +245,8 @@ def exec_concurrent(context: PdfContext):
     """Execute the pipeline concurrently"""
 
     # Run exec_page_sync on every page context
-    max_workers = min(len(context.pdfinfo), context.options.jobs)
+    options = context.options
+    max_workers = min(len(context.pdfinfo), options.jobs)
     if max_workers > 1:
         log.info("Start processing %d pages concurrently", max_workers)
 
@@ -252,25 +254,29 @@ def exec_concurrent(context: PdfContext):
     ocrgraft = OcrGrafter(context)
 
     def update_page(result: PageResult, pbar):
-        sidecars[result.pageno] = result.text
+        try:
-        pbar.update()
+            tls.pageno = result.pageno + 1
-        ocrgraft.graft_page(
+            sidecars[result.pageno] = result.text
-            pageno=result.pageno,
+            pbar.update()
-            image=result.pdf_page_from_image,
+            ocrgraft.graft_page(
-            textpdf=result.ocr,
+                pageno=result.pageno,
-            autorotate_correction=result.orientation_correction,
+                image=result.pdf_page_from_image,
-        )
+                textpdf=result.ocr,
-        pbar.update()
+                autorotate_correction=result.orientation_correction,
+            )
+            pbar.update()
+        finally:
+            tls.pageno = None
 
     exec_progress_pool(
-        use_threads=context.options.use_threads,
+        use_threads=options.use_threads,
         max_workers=max_workers,
         tqdm_kwargs=dict(
             total=(2 * len(context.pdfinfo)),
-            desc='OCR',
+            desc='OCR' if options.tesseract_timeout > 0 else 'Image processing',
             unit='page',
             unit_scale=0.5,
-            disable=not context.options.progress_bar,
+            disable=not options.progress_bar,
         ),
         task_initializer=partial(worker_init, PIL.Image.MAX_IMAGE_PIXELS),
         task=exec_page_sync,
@@ -279,19 +285,20 @@ def exec_concurrent(context: PdfContext):
     )
 
     # Output sidecar text
-    if context.options.sidecar:
+    if options.sidecar:
         text = merge_sidecars(sidecars, context)
         # Copy text file to destination
-        copy_final(text, context.options.sidecar, context)
+        copy_final(text, options.sidecar, context)
 
     # Merge layers to one single pdf
     pdf = ocrgraft.finalize()
 
     # PDF/A and metadata
+    log.info("Postprocessing...")
     pdf = post_process(pdf, context)
 
     # Copy PDF file to destination
-    copy_final(pdf, context.options.output_file, context)
+    copy_final(pdf, options.output_file, context)
 
 
 class NeverRaise(Exception):
@@ -323,9 +330,12 @@ def run_pipeline(options, *, plugin_manager, api=False):
 
     work_folder = Path(mkdtemp(prefix="com.github.ocrmypdf."))
     debug_log_handler = None
-    if (options.keep_temporary_files or options.verbose >= 1) and not os.environ.get(
+    if (
-        'PYTEST_CURRENT_TEST', ''
+        (options.keep_temporary_files or options.verbose >= 1)
+        and not os.environ.get('PYTEST_CURRENT_TEST', '')
+        and not api
     ):
+        # Debug log for command line interface only with verbose output
         debug_log_handler = configure_debug_logging(Path(work_folder) / "debug.log")
 
     pikepdf_enable_mmap()

src/ocrmypdf/_validation.py

@@ -308,17 +308,6 @@ def check_closed_streams(options):  # pragma: no cover
     return True
 
 
-def log_page_orientations(pdfinfo):
-    direction = {0: 'n', 90: 'e', 180: 's', 270: 'w'}
-    orientations = []
-    for n, page in enumerate(pdfinfo):
-        angle = page.rotation or 0
-        if angle != 0:
-            orientations.append('{0}{1}'.format(n + 1, direction.get(angle, '')))
-    if orientations:
-        log.info('Page orientations detected: %s', ' '.join(orientations))
-
-
 def create_input_file(options, work_folder: Path) -> Tuple[Path, str]:
     if options.input_file == '-':
         # stdin

src/ocrmypdf/api.py

@@ -11,6 +11,7 @@ import sys
 from enum import IntEnum
 from pathlib import Path
 from typing import BinaryIO, Iterable, Union
+from warnings import warn
 
 from ocrmypdf._logging import PageNumberFilter, TqdmConsole
 from ocrmypdf._plugin_manager import get_plugin_manager
@@ -44,16 +45,28 @@ def configure_logging(
 ):
     """Set up logging.
 
-    Library users may wish to use this function if they want their log output to be
+    Before calling :func:`ocrmypdf.ocr()`, you can use this function to
-    similar to ocrmypdf command line interface. If not used, the external application
+    configure logging, if you want ocrmypdf's output to look like the ocrmypdf
-    should configure logging on its own.
+    command line interface. It will register log handlers, log filters, and
+    formatters, configure color logging to standard error, and adjust the log
+    levels of third party libraries. Details of this are fine-tuned and subject
+    to change. The ``verbosity`` argument is equivalent to the argument
+    ``--verbose`` and applies those settings.
 
-    ocrmypdf will perform all of its logging under the ``"ocrmypdf"`` logging namespace.
+    If this function is not called, ocrmypdf will not configure logging, and it
-    In addition, ocrmypdf imports pdfminer, which logs under ``"pdfminer"``. A library
+    is up to the caller of ``ocrmypdf.ocr()`` to set up logging as it wishes using
-    user may wish to configure both; note that pdfminer is extremely chatty at the log
+    the Python standard library's logging module. If this function is called,
-    level ``logging.INFO``.
+    the caller may of course make further adjustments to logging.
 
-    Library users may perform additional configuration afterwards.
+    Regardless of whether this function is called, ocrmypdf will perform all of
+    its logging under the ``"ocrmypdf"`` logging namespace. In addition,
+    ocrmypdf imports pdfminer, which logs under ``"pdfminer"``. A library user
+    may wish to configure both; note that pdfminer is extremely chatty at the
+    log level ``logging.INFO``.
+
+    This function does not set up the ``debug.log`` log file that the command
+    line interface does at certain verbosity levels. Applications should configure
+    their own debug logging.
 
     Args:
         verbosity (Verbosity): Verbosity level.
@@ -226,7 +239,7 @@ def ocr(  # pylint: disable=unused-argument
     user_words: os.PathLike = None,
     user_patterns: os.PathLike = None,
     fast_web_view: float = None,
-    plugins: Iterable[str] = None,
+    plugins: Iterable[Union[str, Path]] = None,
     keep_temporary_files: bool = None,
     progress_bar: bool = None,
     **kwargs,
@@ -280,6 +293,8 @@ def ocr(  # pylint: disable=unused-argument
     """
     if not plugins:
         plugins = []
+    elif isinstance(plugins, (str, Path)):
+        plugins = [plugins]
     else:
         plugins = list(plugins)
 
@@ -292,6 +307,9 @@ def ocr(  # pylint: disable=unused-argument
     }
     create_options_kwargs.update(kwargs)
 
+    if 'verbose' in kwargs:
+        warn("ocrmypdf.ocr(verbose=) is ignored. Use ocrmypdf.configure_logging().")
+
     options = create_options(**create_options_kwargs)
     check_options(options, _plugin_manager)
     return run_pipeline(options=options, plugin_manager=_plugin_manager, api=True)

src/ocrmypdf/builtin_plugins/ghostscript.py

@@ -39,13 +39,11 @@ def check_options(options):
     if gs_version < '9.20' and options.output_type != 'pdf' and not is_latin:
         # https://bugs.ghostscript.com/show_bug.cgi?id=696874
         # Ghostscript < 9.20 fails to encode multibyte characters properly
-        msg = (
+        log.warning(
-            "The installed version of Ghostscript does not work correctly "
+            f"The installed version of Ghostscript ({gs_version}) does not work "
-            "with the OCR languages you specified. Use --output-type pdf or "
+            "correctly with the OCR languages you specified. Use --output-type pdf or "
             "upgrade to Ghostscript 9.20 or later to avoid this issue."
         )
-        msg += f"Found Ghostscript {gs_version}"
-        log.warning(msg)
 
     if options.output_type == 'pdfa':
         options.output_type = 'pdfa-2'
@@ -63,9 +61,9 @@ def rasterize_pdf_page(
     raster_device,
     raster_dpi,
     pageno,
-    page_dpi=None,
+    page_dpi,
-    rotation=None,
+    rotation,
-    filter_vector=False,
+    filter_vector,
 ):
     ghostscript.rasterize_pdf(
         input_file,

src/ocrmypdf/builtin_plugins/tesseract_ocr.py

@@ -121,9 +121,7 @@ def validate(pdfinfo, options):
         os.environ['OMP_THREAD_LIMIT'] = str(tess_threads)
     else:
         tess_threads = int(os.environ['OMP_THREAD_LIMIT'])
-
+    log.debug("Using Tesseract OpenMP thread limit %d", tess_threads)
-    if tess_threads > 1:
-        log.info("Using Tesseract OpenMP thread limit %d", tess_threads)
 
 
 class TesseractOcrEngine(OcrEngine):

src/ocrmypdf/helpers.py

@@ -213,11 +213,15 @@ def clamp(n: T, smallest: T, largest: T) -> T:
 
 
 def pikepdf_enable_mmap():
-    try:
+    # try:
-        if pikepdf._qpdf.set_access_default_mmap(True):
+    #     if pikepdf._qpdf.set_access_default_mmap(True):
-            log.debug("pikepdf mmap enabled")
+    #         log.debug("pikepdf mmap enabled")
-    except AttributeError:
+    # except AttributeError:
-        log.debug("pikepdf mmap not available")
+    #     log.debug("pikepdf mmap not available")
+    # We found a race condition probably related to pybind issue #2252 that can
+    # cause a crash. For now, disable pikepdf mmap to be on the safe side.
+    log.debug("pikepdf mmap disabled")
+    return
 
 
 def deprecated(func):

src/ocrmypdf/hocrtransform.py

@@ -167,7 +167,10 @@ class HocrTransform:
     def topdown_position(self, element):
         pxl_line_coords = self.element_coordinates(element)
         line_box = self.pt_from_pixel(pxl_line_coords)
-        return -line_box.y2
+        # Coordinates here are still in the hocr coordinate system, so 0 on the y axis
+        # is the top of the page and increasing values of y will move towards the
+        # bottom of the page.
+        return line_box.y2
 
     def to_pdf(
         self,

src/ocrmypdf/leptonica.py

@@ -58,6 +58,24 @@ if not _libpath:
         ---------------------------------------------------------------------
         """
     )
+if os.name == 'nt':  
+    # On Windows, recent versions of libpng require zlib. We have to make sure 
+    # the zlib version being loaded is the same one that libpng was built with. 
+    # This tries to import zlib from Tesseract's installation folder, falling back
+    # to find_library() if liblept is being loaded from somewhere else.
+    # Loading zlib from other places could cause a version mismatch
+    _zlib_path = os.path.join(os.path.dirname(_libpath), 'zlib1.dll')
+    if not os.path.exists(_zlib_path):
+        _zlib_path = find_library('zlib')
+    try:
+        zlib = ffi.dlopen(_zlib_path)
+    except ffi.error as e:
+        raise MissingDependencyError(
+            """
+            Could not load the zlib library. It could be that Tesseract is not installed properly,
+            we can't find the installation on your system PATH environment variable.
+            """
+        ) from e
 try:
     lept = ffi.dlopen(_libpath)
     lept.setMsgSeverity(lept.L_SEVERITY_WARNING)

src/ocrmypdf/optimize.py

@@ -10,6 +10,7 @@ import sys
 import tempfile
 from collections import defaultdict
 from functools import partial
+from io import BytesIO
 from os import fspath
 from pathlib import Path
 from typing import (
@@ -27,6 +28,7 @@ from typing import (
     Union,
 )
 
+import img2pdf
 import pikepdf
 from pikepdf import Dictionary, Name, Object, Pdf, PdfImage
 from PIL import Image
@@ -37,7 +39,7 @@ from ocrmypdf._concurrent import exec_progress_pool
 from ocrmypdf._exec import jbig2enc, pngquant
 from ocrmypdf._jobcontext import PdfContext
 from ocrmypdf.exceptions import OutputFileAccessError
-from ocrmypdf.helpers import safe_symlink
+from ocrmypdf.helpers import deprecated, safe_symlink
 
 log = logging.getLogger(__name__)
 
@@ -75,23 +77,26 @@ def extract_image_filter(
     if image.Subtype != Name.Image:
         return None
     if image.Length < 100:
-        log.debug("Skipping small image, xref %s", xref)
+        log.debug(f"Skipping small image, xref {xref}")
         return None
 
     pim = PdfImage(image)
 
     if len(pim.filter_decodeparms) > 1:
-        log.debug("Skipping multiply filtered, xref %s", xref)
+        log.debug(f"Skipping multiply filtered image, xref {xref}")
         return None
     filtdp = pim.filter_decodeparms[0]
 
     if pim.bits_per_component > 8:
+        log.debug(f"Skipping wide gamut image, xref {xref}")
         return None  # Don't mess with wide gamut images
 
     if filtdp[0] == Name.JPXDecode:
+        log.debug(f"Skipping JPEG2000 iamge, xref {xref}")
         return None  # Don't do JPEG2000
 
     if Name.Decode in image:
+        log.debug(f"Skipping image with Decode table, xref {xref}")
         return None  # Don't mess with custom Decode tables
 
     return pim, filtdp
@@ -111,12 +116,23 @@ def extract_image_jbig2(
         and jbig2enc.available()
     ):
         try:
+            # Save any colorspace associated with the image, so that we
+            # will export a pure 1-bit PNG with no palette or ICC profile.
+            # Showing the palette or ICC to jbig2enc will cause it to perform
+            # colorspace transform to 1bpp, which will conflict the palette or
+            # ICC if it exists.
+            colorspace = pim.obj.ColorSpace
+            # Set to DeviceGray temporarily; we already in 1 bpc.
+            pim.obj.ColorSpace = pikepdf.Name.DeviceGray
             imgname = root / f'{xref:08d}'
             with imgname.open('wb') as f:
                 ext = pim.extract_to(stream=f)
             imgname.rename(imgname.with_suffix(ext))
         except pikepdf.UnsupportedImageTypeError:
             return None
+        finally:
+            # Restore image colorspace after temporarily setting it to DeviceGray
+            pim.obj.ColorSpace = colorspace
         return XrefExt(xref, ext)
     return None
 
@@ -227,7 +243,9 @@ def extract_images(
                 # Ignore soft masks
                 smask_xref = Xref(image.SMask.objgen[0])
                 exclude_xrefs.add(smask_xref)
+                log.debug(f"Skipping image {smask_xref} because it is an SMask")
             include_xrefs.add(xref)
+            log.debug(f"Treating {xref} as an optimization candidate")
             if xref not in pageno_for_xref:
                 pageno_for_xref[xref] = pageno
 
@@ -393,6 +411,47 @@ def transcode_jpegs(pike: Pdf, jpegs: Sequence[Xref], root: Path, options) -> No
         im_obj.write(compdata.read(), filter=Name.DCTDecode)
 
 
+def _transcode_png(pike: Pdf, filename: Path, xref: Xref) -> bool:
+    output = filename.with_suffix('.png.pdf')
+    with output.open('wb') as f:
+        img2pdf.convert(fspath(filename), outputstream=f)
+
+    with pikepdf.open(output) as pdf_image:
+        foreign_image = next(pdf_image.pages[0].images.values())
+        local_image = pike.copy_foreign(foreign_image)
+
+        im_obj = pike.get_object(xref, 0)
+        im_obj.write(
+            local_image.read_raw_bytes(),
+            filter=local_image.Filter,
+            decode_parms=local_image.DecodeParms,
+        )
+
+        # Don't copy keys from the new image...
+        del_keys = set(im_obj.keys()) - set(local_image.keys())
+        # ...except for the keep_fields, which are essential to displaying
+        # the image correctly and preserving its metadata. (/Decode arrays
+        # and /SMaskInData are implicitly discarded prior to this point.)
+        keep_fields = {
+            '/ID',
+            '/Intent',
+            '/Interpolate',
+            '/Mask',
+            '/Metadata',
+            '/OC',
+            '/OPI',
+            '/SMask',
+            '/StructParent',
+        }
+        del_keys -= keep_fields
+        for key in local_image.keys():
+            if key != Name.Length and str(key) not in keep_fields:
+                im_obj[key] = local_image[key]
+        for key in del_keys:
+            del im_obj[key]
+    return True
+
+
 def transcode_pngs(
     pike: Pdf,
     images: Sequence[Xref],
@@ -435,34 +494,11 @@ def transcode_pngs(
         )
 
     for xref in modified:
-        im_obj = pike.get_object(xref, 0)
+        filename = png_name(root, xref)
-        try:
+        _transcode_png(pike, filename, xref)
-            pix = leptonica.Pix.open(png_name(root, xref))
-            if pix.mode == '1':
-                compdata = pix.generate_pdf_ci_data(leptonica.lept.L_G4_ENCODE, 0)
-            else:
-                compdata = leptonica.CompressedData.open(png_name(root, xref))
-        except leptonica.LeptonicaError as e:
-            # Most likely this means file not found, i.e. quantize did not
-            # produce an improved version
-            log.error(e)
-            continue
-
-        # If re-coded image is larger don't use it - we test here because
-        # pngquant knows the size of the temporary output file but not the actual
-        # object in the PDF
-        if len(compdata) > int(im_obj.stream_dict.Length):
-            log.debug(
-                f"pngquant: pngquant did not improve over original image "
-                f"{len(compdata)} > {int(im_obj.stream_dict.Length)}"
-            )
-            continue
-        if compdata.type == leptonica.lept.L_FLATE_ENCODE:
-            rewrite_png(pike, im_obj, compdata)
-        elif compdata.type == leptonica.lept.L_G4_ENCODE:
-            rewrite_png_as_g4(pike, im_obj, compdata)
 
 
+@deprecated
 def rewrite_png_as_g4(pike: Pdf, im_obj: Object, compdata) -> None:
     im_obj.BitsPerComponent = 1
     im_obj.Width = compdata.w
@@ -483,6 +519,7 @@ def rewrite_png_as_g4(pike: Pdf, im_obj: Object, compdata) -> None:
     return
 
 
+@deprecated
 def rewrite_png(pike: Pdf, im_obj: Object, compdata) -> None:
     # When a PNG is inserted into a PDF, we more or less copy the IDAT section from
     # the PDF and transfer the rest of the PNG headers to PDF image metadata.

src/ocrmypdf/pdfinfo/info.py

@@ -630,6 +630,9 @@ worker_pdf = None
 def _pdf_pageinfo_sync_init(infile):
     global worker_pdf  # pylint: disable=global-statement
     pikepdf_enable_mmap()
+    # If this function is called as a thread initializer, we need a messy hack
+    # to close worker_pdf. If called as a process, it will be released when the
+    # process is terminated.
     worker_pdf = pikepdf.open(infile)
 
 
@@ -643,6 +646,7 @@ def _pdf_pageinfo_sync(args):
 def _pdf_pageinfo_concurrent(
     pdf, infile, progbar, max_workers, check_pages, detailed_analysis=False
 ):
+    global worker_pdf  # pylint: disable=global-statement
     pages = [None] * len(pdf.pages)
 
     def update_pageinfo(result, pbar):
@@ -663,17 +667,23 @@ def _pdf_pageinfo_concurrent(
         # a separate process.
         use_threads = True
 
-    exec_progress_pool(
+    try:
-        use_threads=use_threads,
+        exec_progress_pool(
-        max_workers=n_workers,
+            use_threads=use_threads,
-        tqdm_kwargs=dict(
+            max_workers=n_workers,
-            total=total, desc="Scanning contents", unit='page', disable=not progbar
+            tqdm_kwargs=dict(
-        ),
+                total=total, desc="Scanning contents", unit='page', disable=not progbar
-        task_initializer=partial(_pdf_pageinfo_sync_init, infile),
+            ),
-        task=_pdf_pageinfo_sync,
+            task_initializer=partial(_pdf_pageinfo_sync_init, infile),
-        task_arguments=contexts,
+            task=_pdf_pageinfo_sync,
-        task_finished=update_pageinfo,
+            task_arguments=contexts,
-    )
+            task_finished=update_pageinfo,
+        )
+    finally:
+        if worker_pdf and use_threads:
+            assert n_workers == 1, "Should have only one worker when threaded"
+            # This is messy, but if we ran in thread, close worker_pdf
+            worker_pdf.close()
     return pages
 
 

src/ocrmypdf/pluginspec.py

@@ -89,9 +89,9 @@ def rasterize_pdf_page(
     raster_device: str,
     raster_dpi: Resolution,
     pageno: int,
-    page_dpi: Optional[Resolution] = None,
+    page_dpi: Optional[Resolution],
-    rotation: Optional[int] = None,
+    rotation: Optional[int],
-    filter_vector: bool = False,
+    filter_vector: bool,
 ) -> Path:
     """Rasterize one page of a PDF at resolution raster_dpi in canvas units.
 
@@ -154,11 +154,29 @@ def filter_page_image(page: 'PageContext', image_filename: Path) -> Path:
     produced for a given page, this function will not be called. This is not
     the image that will be shown to OCR.
 
-    ocrmypdf will create the PDF page based on the image format used. If you
+    If the function does not want to modify the image, it should return
+    ``image_filename``. The hook may overwrite ``image_filename`` with a new file.
+
+    The output image should preserve the same physical unit dimensions, that is
+    (width * dpi_x, height * dpi_y). That is, if the image is resized, the DPI
+    must be adjusted by the reciprocal. If this is not preserved, the PDF page
+    will be resized and the OCR layer misaligned. OCRmyPDF does not nothing
+    to enforce these constraints; it is up to the plugin to do sensible things.
+
+    OCRmyPDF will create the PDF page based on the image format used. If you
     convert the image to a JPEG, the output page will be created as a JPEG, etc.
-    Note that the ocrmypdf image optimization stage may ultimately chose a
+    If you change the colorspace, that change will be kept. Note that the
+    OCRmyPDF image optimization stage, if enabled, may ultimately chose a
     different format.
 
+    If the return value is a file that does not exist, ``FileNotFoundError``
+    will occur. The return value should be a path to a file in the same folder
+    as ``image_filename``.
+
+    Implementation detail: If the value returned is falsy, OCRmyPDF will ignore
+    the return value and assume the input file was unmodified. This is deprecated.
+    To leave the image unmodified, ``image_filename`` should be returned.
+
     Note:
         This hook will be called from child processes. Modifying global state
         will not affect the main process or other child processes.

tests/test_rotation.py

@@ -15,6 +15,7 @@ from PIL import Image
 
 from ocrmypdf import leptonica
 from ocrmypdf._exec import ghostscript, tesseract
+from ocrmypdf._plugin_manager import get_plugin_manager
 from ocrmypdf.helpers import Resolution
 from ocrmypdf.pdfinfo import PdfInfo
 
@@ -256,3 +257,33 @@ def test_tesseract_orientation(resources, tmp_path):
     tesseract.get_orientation(  # Test results of this are unreliable
         tmp_path / '000001.png', engine_mode='3', timeout=10
     )
+
+
+def test_rasterize_rotates(resources, tmp_path):
+    pm = get_plugin_manager([])
+
+    img = tmp_path / 'img90.png'
+    pm.hook.rasterize_pdf_page(
+        input_file=resources / 'graph.pdf',
+        output_file=img,
+        raster_device='pngmono',
+        raster_dpi=Resolution(20, 20),
+        page_dpi=Resolution(20, 20),
+        pageno=1,
+        rotation=90,
+        filter_vector=False,
+    )
+    assert Image.open(img).size == (123, 151), "Image not rotated"
+
+    img = tmp_path / 'img180.png'
+    pm.hook.rasterize_pdf_page(
+        input_file=resources / 'graph.pdf',
+        output_file=img,
+        raster_device='pngmono',
+        raster_dpi=Resolution(20, 20),
+        page_dpi=Resolution(20, 20),
+        pageno=1,
+        rotation=180,
+        filter_vector=False,
+    )
+    assert Image.open(img).size == (151, 123), "Image not rotated"

tests/test_validation.py

@@ -55,7 +55,7 @@ def test_old_ghostscript(caplog):
         vd._check_options(
             *make_opts_pm(language='chi_sim', output_type='pdfa'), {'chi_sim'}
         )
-        assert 'Ghostscript does not work correctly' in caplog.text
+        assert 'does not work correctly' in caplog.text
 
     with patch('ocrmypdf._exec.ghostscript.version', return_value='9.18'), patch(
         'ocrmypdf._exec.tesseract.has_textonly_pdf', return_value=True