RubyGems - pdfbeads - Versions diffs - 1.0.0 - Mend

pdfbeads 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

data/doc/pdfbeads.ru.html ADDED Viewed

@@ -0,0 +1,509 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<title>PDFBeads: сборка PDF из отсканированных страниц</title>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<meta name="Generator" content="Written directly in html">
+<meta name="Description" content="Руководство пользователя PDFBEADS версии 1.0">
+<style type="text/css">
+  body {
+    font-family: Times New Roman, Times, serif;
+    text-align: justify;
+  }
+  a:link {
+    color: blue; text-decoration: underline
+  }
+  a:hover {
+    color: fuchsia
+  }
+  a:active {
+    color: fuchsia
+  }
+  a:visited {
+    color: purple
+  }
+  h1 {
+    font-size: 36px;
+    font-family: Times New Roman, Times, serif;
+    text-align: center;
+    font-style: normal;
+    font-weight: bold
+  }
+  h2 {
+    font-size: 20px;
+    font-family: Arial, Helvetica, sans-serif;
+    text-align: center;
+    font-style: normal;
+    font-weight: bold;
+  }
+  h3 {
+    font-size: 16px;
+    font-family: Arial, Helvetica, sans-serif;
+    text-align: left;
+    font-style: italic;
+    font-weight: bold;
+  }
+  dt {
+    font-weight: bold;
+  }
+</style>
+</head>
+<body>
+<h1>Руководство пользователя PDFBEADS версии 1.0</h1>
+<p>(c) Алексей Крюков, 2010</p>
+<p>Утилита pdfbeads предназначена для создания электронных книг в формате
+PDF из предварительно обработанных отсканированных страниц. В отличие от
+других подобных программ, pdfbeads стремится строить PDF-файлы по модели,
+более привычной для формата DJVU, разделяя страницу на слои, различающиеся
+форматом сжатия данных и разрешением.</p>
+<p>Среди возможностей pdfbeads:</p>
+<ul>
+<li><p>сжатие графических данных с использованием форматов JBIG2 и
+JPEG2000;</p></li>
+<li><p>разделение «смешанных» файлов, созданных программой
+<a href="http://scantailor.sourceforge.net/">ScanTailor</a>, на текстовый
+и картиночный слои;</p></li>
+<li><p>подклейка фоновых изображений к предварительно бинаризованным
+текстовым страницам;</p></li>
+<li><p>обработка малоцветных индексированных изображений с сохранением
+цвета и выносом содержимого в передний план;</p></li>
+<li><p>разделение полноцветных изображений на фон и передний план по
+заданной маске;</p></li>
+<li><p>создание PDF-файлов с оглавлением и метаданными;</p></li>
+<li><p>добавление скрытого текстового слоя из документов в формате hOCR
+с корректной обработкой символов кириллицы.</p></li>
+</ul>
+<p>Название pdfbeads связано с тем, что сборка электронной книги из отдельных
+графических файлов может быть уподоблена нанизыванию бус. Кроме того, оно
+представляется вполне уместным для сценария, написанного на языке Ruby: ведь
+драгоценные камни, подобные рубину, как раз и служат для создания ювелирных
+украшений.</p>
+<h2>Требования</h2>
+<p>Для запуска программы требуется прежде всего интерпретатор языка Ruby
+версии 1.8 или 1.9, доступный в дистрибутивах большинства Unix-подобных
+систем. Версия для Windows может быть загружена с сайта <a
+href="http://www.rubyinstaller.org/">RubyInstaller</a>. Для корректной
+установки pdfbeads необходимо также загрузить пакетный менеджер RubyGems,
+представляющий собой стандартный интерфейс языка Ruby для работы с
+расширениями. Кроме того, в дополнение к основному дистрибутиву Ruby
+понадобятся расширения RMagick и hpricot (последнее&nbsp;&mdash; для
+обработки распознанного текста в формате hOCR).</p>
+<p>Если вы хотите создавать PDF-файлы с использованием формата сжатия
+данных JBIG2, то в системе также должна быть установлена утилита jbig2
+из пакета <a href="http://github.com/agl/jbig2enc">jbig2enc</a>. Внимание:
+по состоянию на октябрь 2010&nbsp;г., когда пишется этот файл,
+настоятельно рекомендуется использовать версию jbig2, самостоятельно
+собранную из исходников, доступных в репозитории git, поскольку более
+ранние версии не обеспечивают корректного сохранения информации о разрешении
+изображений.</p>
+<h2>Установка</h2>
+<p>Для того, чтобы скачать и установить наиболее свежую версию pdfbeads
+с помощью пакетного менеджера RubyGems, достаточно набрать в командной
+строке</p>
+<pre>
+gem install pdfbeads
+</pre>
+<p>Перед запуском программы необходимо удостовериться, что расширение
+RMagick установлено и доступно интерпретатору Ruby. К сожалению, эту
+зависимость нельзя отследить автоматически, поскольку в некоторых
+дистрибутивах Linux (в частности, Ubuntu) пакет RMagick устанавливается в
+обход механизма RubyGems, так что утилите gem о нем ничего не известно.</p>
+<p>Пользователям Ubuntu также следует иметь в виду, что в этом дистрибутиве
+исполняемые файлы из пакетов gem по умолчанию распаковываются в каталоги
+<tt>/var/lib/gems/1.8/bin</tt> и <tt>/var/lib/gems/1.9.1/bin</tt>
+(для Ruby 1.8 и 1.9 соответственно), изначально не включенные в переменную
+окружения PATH. Поэтому для того, чтобы утилиту pdfbeads можно было запускать
+без указания полного пути к ней, нужно либо соответствующим образом
+модифицировать переменную PATH, либо переместить файл <tt>pdfbeads</tt>
+в одну из директорий, традиционно используемых для размещения исполняемых
+файлов (например, <tt>/usr/local/bin</tt>).</p>
+<h2>Общие принципы</h2>
+<p>Методика работы pdfbeads основана на разграничении «основного»
+изображения, вокруг которого выстраивается страница PDF-документа, и различных
+вспомогательных файлов, связанных с текущей страницей.</p>
+<p>«Основными» считаются файлы, содержащие отсканированный
+текст, который может быть использован в качестве переднего плана (маски).
+Как правило, в этой роли должны выступать предварительно бинаризованные
+текстовые страницы. Кроме того, pdfbeads может обрабатывать малоцветные
+индексированные изображения с белым или прозрачным фоном, а также смешанные
+изображения, сочетающие бинаризованный текст с полутоновыми иллюстрациями.
+Последняя возможность наиболее полезна для работы с файлами, полученными при
+помощи программы <a href="http://scantailor.sourceforge.net/">ScanTailor</a>.</p>
+<p>Специальной обработке подвергаются файлы с двойным расширением,
+где расширению, указывающему на один из графических форматов (TIF(F),
+PNG, JP(E)G, JP2, JPX), предшествует один из следующих суффиксов:</p>
+<dl>
+<dt>bg или sep</dt>
+<dd><p>Фоновое изображение (полутоновое или индексированное);</p></dd>
+<dt>fg</dt>
+<dd><p>Изображение, предназначенное для раскраски текстового слоя (подобно
+блоку FG44 в DJVU);</p></dd>
+<dt>color</dt>
+<dd><p>Полноцветный скан, служащий источником для формирования файлов
+с суффиксами <tt>*.bg.*</tt> и <tt>*.fg.*</tt>;</p></dd>
+<dt>Спецификация цвета (напр. <tt>black</tt> или <tt>#ff00ff</tt>)</dt>
+<dd><p>Бинаризованное изображение, для отрисовки которого следует
+использовать указанный цвет.</p></dd>
+</dl>
+<p>Кроме того, при наличии в текущей директории HTML-файлов с расширением
+HTM(L) или HOCR, содержащих распознанный текст в формате hOCR, pdfbeads
+будет использовать их для формирования скрытого текстового слоя в PDF-файле.</p>
+<p>Некоторые из перечисленных выше видов вспомогательных файлов могут
+создаваться pdfbeads в качестве промежуточного этапа работы. Поскольку
+обработка изображений с помощью библиотеки ImageMagick, на которой основывается
+pdfbeads, иногда занимает довольно много времени, эти файлы в дальнейшем
+не удаляются с диска и могут быть повторно использованы при последующих
+прогонах в целях экономии времени. Для того, чтобы заставить pdfbeads
+заменить такие файлы заново созданными версиями, можно запустить его с опцией
+<tt>-f</tt> или <tt>--force-update</tt>.</p>
+<p>pdfbeads предназначен для сборки PDF из предварительно обработанных
+сканов, чем объясняются некоторые особенности работы программы:</p>
+<ul>
+<li><p>нет возможности как-то модифицировать сканы текстовых страниц,
+за исключением принудительного задания разрешения (предполагается,
+что они были созданы с желательными для пользователя настройками, так что
+дальнейшая обработка не требуется);</p></li>
+<li><p>не предусмотрена бинаризация и сегментация необработанных сканов,
+выполненных в цвете или в оттенках серого. Исключение представляют случаи
+полуавтоматической обработки (разделение «смешанных» страниц,
+где бинаризованный текст сочетается с полутоновыми картинками; сегментация
+полноцветных изображений по заданной маске), когда pdfbeads лишь завершает
+работу, начатую с помощью других программ;</p></li>
+<li><p>фоновые изображения, взятые непосредственно с жесткого диска
+пользователя, не подвергаются дополнительной обработке и кодируются
+«как есть».</p></li>
+</ul>
+<h2>Начало работы с программой</h2>
+<p>Программа использует следующий формат запуска из командной строки:</p>
+<pre>
+pdfbeads [options] [files to process] [&gt; output_file.pdf]
+</pre>
+<p>Список файлов для обработки может быть либо получен из листинга текущей
+директории, либо задан напрямую в командной строке. В обоих случаях pdfbeads
+проверяет имена файлов на соответствие определенному шаблону: к обработке
+принимаются только изображения TIF(F) или PNG (регистр букв не имеет значения),
+причем расширению файла не должно предшествовать никаких дополнительных
+суффиксов, отделенных точками. Это связано с тем, что двойные расширения
+используются программой для маркировки вспомогательных файлов, имеющих
+специальное назначение.</p>
+<p>Вместо записи PDF-файла на стандартное устройство вывода можно использовать
+опцию <tt>-o</tt> или <tt>--output</tt>, сопроводив ее указанием имени файла.</p>
+<h2>Обработка бинаризованных изображений</h2>
+<p>Для формирования переднего плана, или «маски», на странице
+PDF-документа, используются «основные» файлы отсканированных
+страниц, поданные на вход pdfbeads. При этом программа руководствуется
+следующими правилами:</p>
+<ul>
+<li><p>бинаризованные изображения в формате TIFF или PNG используются
+«как есть»;</p></li>
+<li><p>страницы со смешанным содержимым освобождаются от полутоновых
+изображений (об их обработке см. следующий раздел), а оставшийся
+черно-белый текст сохраняется в файле с расширением <tt>black.tiff</tt>,
+из которого затем и создается маска;</p></li>
+<li><p>индексированные изображения с белым или прозрачным фоном, содержащие
+небольшое количество цветов (по умолчанию&nbsp;&mdash; 4; это количество
+может быть изменено с помощью параметра <tt>-x</tt> (<tt>--max-colors</tt>)
+разбиваются на несколько бинаризованных файлов (по числу цветов), каждый
+из которых в дальнейшем кодируется отдельно. При этом pdfbeads использует
+предусмотренную форматом pdf возможность наложить на изображение две или
+более масок, указав для каждой из них свой цвет.</p></li>
+</ul>
+<p>Для черно-белых текстовых страниц рекомендуется использовать формат
+TIFF со сжатием данных CCITT Group 4 fax, поскольку pdfbeads в большинстве
+случаев в состоянии считывать данные из таких файлов без обращения к библиотеке
+ImageMagick, что существенно увеличивает скорость обработки.</p>
+<p>По умолчанию передний план страницы упаковывается с помощью технологии
+сжатия JBIG2, для чего pdfbeads использует утилиту <a
+href="http://github.com/agl/jbig2enc">jbig2enc</a> (автор&nbsp;&mdash; Адам
+Лэнгли). При этом можно задать опцию <tt>-p</tt> (<tt>--pages-per-dict</tt>),
+чтобы указать желательное количество страниц, использующих общий словарь
+разделенных символов (по умолчанию&nbsp;&mdash; 15).</p>
+<p>Если утилита jbig2enc недоступна, либо при запуске pdfbeads была указана
+опция <tt>-m</tt> (<tt>--mask-compression</tt>) с аргументом `G4' (синонимы&nbsp;&mdash;
+`Group4', `CCITTFax'), то вместо JBIG2-сжатия будет использоваться формат
+CCITT Group 4 fax.</p>
+<h2>Обработка полутоновых изображений</h2>
+<p>Полутоновые изображения используются в качестве фона PDF-страницы, который,
+как правило, должен иметь меньшее разрешение, чем маска. pdfbeads может
+взять фоновое изображение непосредственно с жесткого диска (из файла
+с дополнительным расширением <strong>bg</strong> или <strong>sep</strong>)
+либо сформировать его путем разделения смешанного файла.</p>
+<p>При обработке смешанных файлов картинки прежде всего отделяются от текста,
+для чего все черные пиксели окрашиваются белым цветом. Полученное изображение
+сохраняется на диск с учетом следующих параметров командной строки:</p>
+<dl>
+<dt>-b, --bg-compression</dt>
+<dd><p>Формат сжатия данных. Допускаются значения `JPEG2000' (с синонимами
+`JP2' или `JPX'), `JPEG' (с синонимом `JPG'), а также `LOSSLESS'
+(синонимы&nbsp;&mdash; `DEFLATE', `PNG'). Если используемая сборка библиотеки
+ImageMagick поддерживает формат JPEG2000, по умолчанию используется именно
+он; в противном случае&nbsp;&mdash; JPEG. Если выбрана опция LOSSLESS,
+то pdfbeads будет использовать для сжатия изображений технологию deflate.
+Следует иметь в виду, что это может привести к значительному возрастанию
+объема данных по сравнению с форматами JPEG2000 или JPEG.</p></dd>
+<dt>-B, --bg-resolution DPI</dt>
+<dd><p>Разрешение для фонового слоя. Разумные значения обычно лежат в пределах
+150–300 dpi (по умолчанию&nbsp;&mdash; 300).</p></dd>
+<dt>-g, --grayscale</dt>
+<dd><p>Заставляет pdfbeads принудительно конвертировать цветные картинки в
+оттенки серого. Данная опция может быть полезна в том случае, если исходные
+сканы были выполнены в цвете, но фактически содержали только черно-белые
+картинки, причем преобразование в оттенки серого не было выполнено на этапе
+первичной сканобработки. Такая ситуация часто возникает, в частности, при
+обработке цифровых фотографий с помощью программы ScanTailor.</p></dd>
+<p>Если pdfbeads загружает готовое фоновое изображение с диска, то какая-либо
+дополнительная обработка уже не производится. Картинки JPEG и JPEG2000
+вставляются в PDF-файл без изменений, а изображения, считанные из файлов
+TIFF и PNG, сжимаются по технологии deflate. Однако при наличии нескольких
+одноименных файлов, различающихся лишь расширением, предпочтение того или
+иного графического формата определяется значением параметра
+<tt>--bg-compression</tt>.</p>
+</dl>
+<h2>Сегментация полноцветных изображений по заданной маске</h2>
+<p>Разделение отсканированного изображения на слои связано с особыми
+сложностями в тех случаях, когда текст напечатан поверх рисунка или
+текстуры. Для того, чтобы упаковать такую страницу в pdf с помощью
+pdfbeads, необходимо подготовить два графических файла:</p>
+<ul>
+<li><p>бинаризованное или малоцветное индексированное изображение,
+содержащее только текст или другие элементы, которые должны быть вынесены
+на передний план;</p></li>
+<li><p>полноцветный скан той же страницы (pdfbeads распознаёт такие
+изображения по суффиксу <tt>*.color.*</tt> в их имени).</p></li>
+</ul>
+<p>Первый из двух файлов будет использован в качестве шаблона:
+руководствуясь его начертаниями, pdfbeads постарается сформировать из
+полноцветного скана два новых изображения, причем первое (с суффиксом
+<tt>*.bg.*</tt>) будет содержать фон, освобожденный от текстовых данных,
+а на втором (с суффиксом <tt>*.fg.*</tt>) останутся только элементы маски
+с присущей им текстурой. Данная процедура по смыслу напоминает операцию,
+осуществляемую утилитой <tt>djvumake</tt> при указании опции <tt>PPM</tt>,
+и имеет ту же самую цель: создание трехслойной страницы, где один из
+полноцветных слоев отвечает за отображение фона, а другой&nbsp;&mdash;
+за раскраску наложенной на этот фон маски.</p>
+<p>Для достижения желаемого результата необходимо, чтобы шаблон накладывался
+на полноцветное изображение без каких-либо сдвигов и искажений. В то же время
+разрешение этих двух изображений (и, соответственно, их пиксельные размеры)
+может быть различным: в этом случае на этапе сегментации будет использоваться
+копия шаблона, масштабированная до размеров цветной картинки. Если весь текст на
+странице набран черным цветом (или, по крайней мере, темнее фона), то для
+создания обоих файлов удобно использовать программу ScanTailor: для этого нужно
+вывести одну и ту же страницу сначала в режиме «черно-белый»,
+а затем&nbsp;&mdash; в режиме «цветной/серый».</p>
+<p>Следует иметь в виду, что в случае, если шаблон представлен малоцветным
+индексированным изображением, файл с суффиксом <tt>*.fg.*</tt> создан не
+будет: вместо этого на очищенный от текстовых данных фон будет наложена
+маска с изначально заданными цветами.</p>
+<p>В заключение этого раздела отметим, что используемый pdfbeads алгоритм
+сегментации по заданной маске появился под влиянием
+<a href="http://www.imagemagick.org/discourse-server/viewtopic.php?p=41498#p41498">дискуссии
+на форуме ImageMagick</a>, где обсуждались возможные способы удаления текста
+с картинки с последующим заполнением образовавшихся «дырок»
+исходя из значений соседних пикселей.
+</p><h2>Дополнительные возможности</h2>
+<h3>Добавление метаданных</h3>
+<p>Для того, чтобы созданный pdfbeads PDF-документ содержал данные об авторе,
+заглавии книги и т. д., необходимо предварительно занести эти данные
+в специальный текстовый файл в кодировке ASCII или UTF-8. Каждая строка
+такого файла должна иметь формат</p>
+<pre>&lt;KEYWORD&gt;: "Текст"
+</pre>
+<p>В настоящее время в качестве ключевых слов распознаются <tt>Title</tt>,
+<tt>Author</tt>, <tt>Subject</tt> и <tt>Keywords</tt>. Строки, начинающиеся
+с символа `#', считаются комментариями и игнорируются.</p>
+<p>Ссылку на созданный файл можно передать pdfbeads с помощью опции
+<tt>-M</tt> (или <tt>--meta</tt>).</p>
+<h3>Метки страниц</h3>
+<p>pdfbeads позволяет задать метки страниц, которые могут быть использованы
+просмотрщиком PDF вместо их порядковых номеров. Таким образом можно привести
+нумерацию страниц электронного документа в соответствие с нумерацией страниц
+бумажной книги. Для этой цели pdfbeads использует параметр <tt>-L</tt> (или
+<tt>--labels</tt>). Аргумент этого параметра обязательно заключается в
+кавычки и может состоять из одной или нескольких спецификаций диапазонов
+нумерации, отделенных друг от друга символом точки с запятой.</p>
+<p>Диапазон нумерации формируется из следующих компонентов (каждый из
+них может быть опущен):</p>
+<ul>
+<li><p>Порядковый номер первой страницы диапазона в PDF-файле, отделенный
+двоеточием от остальной части спецификации. Внимание: страницы PDF-документа
+нумеруются, начиная с нуля, так что для первого диапазона это значение
+всегда должно быть равным нулю.</p></li>
+<li><p>Произвольный префикс нумерации (допускаются любые символы, кроме
+двойной кавычки, двоеточия, точки с запятой и знака процента).</p></li>
+<li><p>Описание формата нумерации, начинающееся со знака процента,
+за которым следует латинская буква, указывающая на ее стиль:</p></li>
+<dl>
+<dt>D</dt>
+<dd><p>арабские цифры;</p></dd>
+<dt>R</dt>
+<dd><p>заглавные римские цифры;</p></dd>
+<dt>r</dt>
+<dd><p>строчные римские цифры;</p></dd>
+<dt>A</dt>
+<dd><p>заглавные латинские буквы;</p></dd>
+<dt>a</dt>
+<dd><p>строчные латинские буквы.</p></dd>
+</dl>
+<p>Между знаком процента и идентификатором формата нумерации может стоять
+произвольное число, обозначающее отображаемый номер начальной страницы
+(по умолчанию&nbsp;&mdash; 1).</p>
+</ul>
+<p>Предположим, например, что книга начинается с двух ненумерованных
+титульных страниц, после чего следуют 32 страницы, пронумерованных
+римскими цифрами, а далее идет арабская нумерация, которая, однако,
+начинается сразу с 33. В таком случае целесообразно задать следующий
+аргумент для параметра <tt>--labels</tt>:</p>
+<pre>
+"0:Титул %D;2:%R;34:%33D"
+</pre>
+<h3>Добавление оглавления</h3>
+<p>pdfbeads предусматривает возможность добавить оглавление к создаваемому
+PDF-файлу. Для этого используется параметр <tt>-C</tt> (или <tt>--toc</tt>),
+принимающий в качестве аргумента путь к текстовому файлу.</p>
+<p>Файл оглавления должен иметь кодировку UTF-8 и состоять из строк, оформленных
+по следующему образцу (строки, начинающиеся с символа `#', игнорируются):</p>
+<pre>
+&lt;отступ&gt;"Заголовок" "Номер страницы" [0|-|1|+]
+</pre>
+<p>Уровень вложенности заголовка определяется его отступом (последний может
+состоять из пробелов или табуляторов, но одновременное использование тех и
+других в пределах одного файла не допускается). После отступа идут поля
+заголовка и номера страницы, которые разделяются любым числом пробельных
+символов и при необходимости заключаются в кавычки. Последний, необязательный
+параметр указывает, должен ли данный пункт оглавления отображаться
+развернутым по умолчанию (символы `+' и `1' означают «да»).</p>
+<p>Опцию <tt>--toc</tt> целесообразно использовать в сочетании с опцией
+<tt>--labels</tt>. В этом случае в файле оглавления можно использовать
+те же номера страниц, что и в бумажной книге, не задумываясь о сдвигах
+нумерации.</p>
+<h2>Лицензия</h2>
+<p>Данная программа является свободным программным обеспечением. Вы
+вправе распространять ее и/или модифицировать в соответствии с
+условиями версии 2 либо по вашему выбору с условиями более поздней
+версии Стандартной Общественной Лицензии GNU, опубликованной Free
+Software Foundation.</p>
+<p>Мы распространяем данную программу в надежде на то, что она будет
+вам полезной, однако НЕ ПРЕДОСТАВЛЯЕМ НА НЕЕ НИКАКИХ ГАРАНТИЙ, в том
+числе ГАРАНТИИ ТОВАРНОГО СОСТОЯНИЯ ПРИ ПРОДАЖЕ и ПРИГОДНОСТИ ДЛЯ
+ИСПОЛЬЗОВАНИЯ В КОНКРЕТНЫХ ЦЕЛЯХ. Для получения более подробной
+информации ознакомьтесь со Стандартной Общественной Лицензией GNU.</p>
+<p>Вместе с данной программой вы должны были получить экземпляр
+Стандартной Общественной Лицензии GNU. Если вы его не получили,
+сообщите об этом в Free Software Foundation, Inc., 59 Temple Place -
+Suite 330, Boston, MA 02111-1307, USA.</p>
+</body>
+</html>