Add new --pages feature to limit OCR to only specific pages

src/ocrmypdf/_pipeline.py

@@ -251,12 +251,14 @@ def is_ocr_required(page_context):
 
     ocr_required = True
 
-    if pageinfo.has_text:
+    if options.pages and pageinfo.pageno not in options.pages:
+        log.debug(f"skipped {pageinfo.pageno} as requested by --pages {options.pages}")
+        ocr_required = False
+    elif pageinfo.has_text:
         if not options.force_ocr and not (options.skip_text or options.redo_ocr):
-            log.error(
+            raise PriorOcrFoundError(
                 "page already has text! - aborting (use --force-ocr to force OCR)"
             )
-            raise PriorOcrFoundError()
         elif options.force_ocr:
             log.info("page already has text! - rasterizing text and running OCR anyway")
             ocr_required = True

src/ocrmypdf/_validation.py

@@ -41,7 +41,7 @@ from .exec import (
     tesseract,
     unpaper,
 )
-from .helpers import is_file_writable, re_symlink
+from .helpers import is_file_writable, re_symlink, is_iterable_notstr, monotonic
 
 # -------------
 # External dependencies
@@ -172,6 +172,33 @@ def check_options_preprocessing(options):
             raise BadArgsError(str(e))
 
 
+def _pages_from_ranges(ranges):
+    if is_iterable_notstr(ranges):
+        return set(ranges)
+    pages = []
+    page_groups = ranges.replace(' ', '').split(',')
+    for g in page_groups:
+        if not g:
+            continue
+        try:
+            start, end = g.split('-')
+        except ValueError:
+            pages.append(int(g) - 1)
+        else:
+            pages.extend(range(int(start) - 1, int(end)))
+
+    if not monotonic(pages):
+        log.warning(
+            "List of pages to process contains duplicate pages, or pages that are "
+            "out of order"
+        )
+    if any(page < 0 for page in pages):
+        raise BadArgsError("pages refers to a page number less than 1")
+
+    log.debug("OCRing only these pages: %s", pages)
+    return set(pages)
+
+
 def check_options_ocr_behavior(options):
     exclusive_options = sum(
         [
@@ -180,9 +207,11 @@ def check_options_ocr_behavior(options):
         ]
     )
     if exclusive_options >= 2:
-        raise BadArgsError(
-            "Error: choose only one of --force-ocr, --skip-text, --redo-ocr."
-        )
+        raise BadArgsError("Choose only one of --force-ocr, --skip-text, --redo-ocr.")
+    if options.pages and options.sidecar:
+        raise BadArgsError("--pages and --sidecar are mutually exclusive")
+    if options.pages:
+        options.pages = _pages_from_ranges(options.pages)
 
 
 def check_options_optimizing(options):

src/ocrmypdf/api.py

@@ -188,6 +188,7 @@ def ocrmypdf(  # pylint: disable=unused-argument
     png_quality=None,
     jbig2_lossy=None,
     jbig2_page_group_size=None,
+    pages=None,
     max_image_mpixels=None,
     tesseract_config=None,
     tesseract_pagesegmode=None,

src/ocrmypdf/cli.py

@@ -380,6 +380,11 @@ optimizing.add_argument(
 advanced = parser.add_argument_group(
     "Advanced", "Advanced options to control Tesseract's OCR behavior"
 )
+advanced.add_argument(
+    '--pages',
+    type=str,
+    help="Limit OCR to the specified pages (ranges or comma separated), skipping others",
+)
 advanced.add_argument(
     '--max-image-mpixels',
     action='store',

src/ocrmypdf/helpers.py

@@ -66,6 +66,15 @@ def re_symlink(input_file, soft_link_name, *args, **kwargs):
     os.symlink(os.path.abspath(input_file), soft_link_name)
 
 
+def is_iterable_notstr(thing):
+    return isinstance(thing, Iterable) and not isinstance(thing, str)
+
+
+def monotonic(L):
+    """Does list increase monotonically?"""
+    return all(b > a for a, b in zip(L, L[1:]))
+
+
 def page_number(input_file):
     """Get one-based page number implied by filename (000002.pdf -> 2)"""
     return int(os.path.basename(os.fspath(input_file))[0:6])