diff --git a/docs/advanced.rst b/docs/advanced.rst index 789e77d5..713087d9 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -1,6 +1,30 @@ Advanced features ================= +Control of unpaper +------------------ + +OCRmyPDF uses ``unpaper`` to provide the implementation of the ``--clean`` and ``--clean-final`` arguments. `unpaper `_ provides a variety of image processing filters to improve images. + +By default, OCRmyPDF uses only ``unpaper`` arguments that were found to be safe to use "blindly" on almost all files, without visually checking if the option is sensible for a given file. + +At your option, you may use ``--unpaper-args '...'`` to override the default arguments and forward other arguments to unpaper. The arguments passed to ``unpaper`` **must** be quoted, or ocrmypdf's will read them instead. No filename arguments should be provided. OCRmyPDF will assume it can append the input and output filenames, and that both are single files. + +In this example, we tell ``unpaper`` to expect two pages of text on a sheet (image), such as occurs when two facing pages of a book are scanned. ``unpaper`` uses this information to deskew each independently and clean up the margins of both. + +.. code-block:: bash + + ocrmypdf --clean --clean-final --unpaper-args '--layout double' input.pdf output.pdf + +.. warning:: + + Some ``unpaper`` features will reposition text within the image, which will cause the OCR text layer to be mispositioned if only ``-- + +.. warning:: + + Some ``unpaper`` features cause multiple input or output files to be consumed or produced. OCRmyPDF requires ``unpaper`` to consume one file and produce one file. An deviation from that condition. + + Control of OCR options ---------------------- @@ -17,7 +41,6 @@ If ``--redo-ocr`` is issued, then a detailed text analysis is performed. Text is If ``--force-ocr`` is issued, then all pages will be rasterized to images, discarding any hidden OCR text, and rasterizing any printable text. This is useful for redoing OCR, for fixing OCR text with a damaged character map (text is selectable but not searchable), and destroying redacted information. Any forms and vector graphics will be rasterized as well. - Time and image size limits """""""""""""""""""""""""" diff --git a/docs/release_notes.rst b/docs/release_notes.rst index 3bbcddf8..63c00f37 100644 --- a/docs/release_notes.rst +++ b/docs/release_notes.rst @@ -14,6 +14,11 @@ Note that it is licensed under GPLv3, so scripts that ``import ocrmypdf`` and ar replace: `#$1 `_ +v8.1.0 +------ + +- Added a feature, ``--unpaper-args``, which allows passing arbitrary arguments to ``unpaper`` when using ``--clean`` or ``--clean-final``. The default, very conservative unpaper settings are suppressed. + v8.0.1 ------