Tabula Java извлекает таблицы из текстовых PDF в CSV, TSV и JSON: можно обработать весь документ, указанные страницы или точные области, выбрать алгоритм по пробелам либо линиям, задать границы столбцов и автоматизировать серию однотипных файлов из командной строки или Java-кода.

Рабочий процесс строится вокруг воспроизводимой команды: сначала проверяют, что в PDF действительно есть текстовый слой, затем выбирают страницы, ограничивают прямоугольную область таблицы и запускают один из двух способов разбора. Stream восстанавливает колонки по расположению слов и промежуткам между ними, а Lattice использует нарисованные границы ячеек. Результат можно направить в файл или стандартный вывод, поэтому извлечение удобно включать в сценарии подготовки данных, серверные задания и конвейеры проверки документов.

Качество определяется не количеством найденных символов, а правильной геометрией строк и столбцов. После первого запуска следует открыть CSV или TSV, проверить заголовки, число полей, переносы внутри ячеек и повторяющиеся строки, а затем закрепить удачные параметры области, страниц и алгоритма. Такой цикл особенно полезен для отчётов, выписок, расписаний и форм одинакового макета: одна проверенная команда заменяет повторное выделение таблицы вручную.

Какие PDF подходят для извлечения таблиц

Tabula Java читает символы и графические объекты, записанные внутри PDF. Самая быстрая проверка выполняется в обычном просмотрщике: попробуйте выделить мышью отдельное слово в таблице и скопировать его в текстовый редактор. Если вставляется осмысленный текст, движок обычно получает координаты букв и может собрать их в строки. Если выделяется только прямоугольная картинка либо копирование ничего не даёт, перед извлечением нужен OCR, создающий распознаваемый текстовый слой. Само наличие чётких букв на экране не доказывает, что они представлены символами, а не пикселями.

Машинно сформированные отчёты, экспорт из бухгалтерской системы и PDF, созданные из электронных таблиц, дают наиболее предсказуемый результат. В них каждая строка текста имеет устойчивые координаты, а линии сетки обычно являются векторными отрезками. Сложнее обрабатываются документы после печати и повторного сканирования, страницы с наклоном, декоративными рамками, водяными знаками, вертикальными заголовками и текстом, выходящим за границы ячейки. Такие особенности не всегда делают извлечение невозможным, но требуют более узкой области и проверки каждого столбца.

Не следует судить о таблице только по её внешнему виду. Две страницы могут выглядеть одинаково, но в одной вертикальные и горизонтальные границы нарисованы линиями, а в другой представляют собой фон изображения. В первом случае Lattice видит пересечения и строит сетку, во втором линии для него отсутствуют, и лучше пробовать Stream. Обратная ситуация встречается в документах без видимых границ: ровные промежутки между словами дают Stream достаточно информации, хотя визуально таблица выглядит как обычный выровненный текст.

Проверка текстового слоя до запуска

Для выборочной диагностики найдите в PDF редкое число или фамилию через поиск просмотрщика. Поиск должен перейти к нужной ячейке, а скопированная строка — сохранять буквы и цифры без подмены на квадраты. Затем проверьте порядок копирования: в некоторых документах символы визуально стоят правильно, но внутренний порядок чтения перемешан. Tabula Java опирается на координаты и часто восстанавливает колонки лучше простого копирования, однако полностью испорченная карта символов проявится в выходных данных теми же неверными знаками.

Если OCR уже выполнялся, оцените не только точность слов, но и положение невидимого текстового слоя. Сдвинутые рамки символов приводят к тому, что слово попадает в соседнюю колонку, несмотря на корректное отображение страницы. Полезно открыть PDF в просмотрщике с подсветкой выделения: синяя полоса должна совпадать с печатной строкой. При заметном смещении лучше повторить распознавание с выравниванием страницы и сохранением исходного изображения, а уже затем передавать документ движку таблиц.

Подготовка Java и рабочей папки

Для запуска нужен исполняемый файл Java и JAR с зависимостями. Проверку среды выполняют командой java -version: она должна вывести сведения о виртуальной машине, а не сообщение о неизвестной команде. Если Java установлена, но оболочка её не находит, укажите полный путь к исполняемому файлу либо добавьте каталог Java в переменную PATH. Разрядность виртуальной машины важна главным образом для доступной памяти: при обработке больших документов удобнее среда, способная использовать увеличенный heap.

Практично создать отдельную папку проекта и переименовать загруженный JAR в короткое имя tabula.jar. Рядом размещают исходные PDF, каталог результатов и текстовый файл с проверенными командами. Короткие пути уменьшают число ошибок с пробелами и национальными символами. Исходные документы лучше оставить неизменными, а результаты направлять в отдельный каталог: так повторный запуск не перезапишет входные файлы и не смешает таблицы из разных наборов.

java -version
java -jar tabula.jar --help

Вторая команда должна вывести справку с параметрами --area, --batch, --columns, --format, --pages, --lattice и --stream. Если вместо справки появляется сообщение о повреждённом JAR, проверьте размер загрузки и повторно получите файл с официального релиза. HTML-страница, сохранённая под расширением JAR, также вызывает ошибку формата: первые байты настоящего JAR соответствуют ZIP-контейнеру, а внутри находятся каталог META-INF и Java-классы.

Пути, кавычки и кодировка оболочки

Путь с пробелами заключают в кавычки целиком: "C:\PDF Tables\report.pdf". На Windows одинарные кавычки в классической командной строке не выполняют ту же роль, что в Unix-оболочке, поэтому безопаснее использовать двойные. В PowerShell следует отдельно учитывать перенаправление и специальные символы. На macOS и Linux имена файлов чувствительны к регистру, поэтому Report.pdf и report.pdf могут обозначать разные документы.

Для русского текста полезно явно согласовать кодировку процесса и выходного файла. Параметр виртуальной машины -Dfile.encoding=UTF8 ставят перед -jar, а результат сохраняют в приложение, которое умеет открывать UTF-8. Если электронная таблица показывает кракозябры, сначала импортируйте CSV через мастер данных и выберите UTF-8, а не открывайте двойным щелчком с системной кодировкой. Когда конечная система требует другую кодировку, корректнее преобразовать готовый UTF-8-файл отдельным инструментом, не меняя этап извлечения.

java -Dfile.encoding=UTF8 -jar tabula.jar report.pdf -f CSV -o result.csv

Первое извлечение и чтение результата

Минимальный запуск без дополнительных ключей обрабатывает первую страницу и печатает CSV в стандартный вывод. Для практической работы лучше сразу задавать файл через -o, иначе длинная таблица смешивается с содержимым терминала. Название входного PDF указывают последним аргументом. Если документ содержит несколько таблиц, запуск по всей странице может объединить подписи, колонтитулы и соседние блоки; этот первый результат нужен как диагностика, а не как окончательный экспорт.

java -jar tabula.jar report.pdf -p 1 -f CSV -o page-1.csv

Откройте результат как текст и посмотрите на число разделителей в нескольких строках. Одинаковое число запятых или табуляций ещё не гарантирует правильность, но быстро показывает, образовалась ли стабильная структура. Если весь текст оказался в одном поле, движок не увидел устойчивых границ колонок. Если одна визуальная строка распалась на несколько записей, причиной могут быть переносы, разная высота шрифта или несколько текстовых блоков в ячейке. Если в CSV попали заголовок страницы и номер листа, ограничьте область параметром -a.

CSV удобен для большинства табличных редакторов, но запятые внутри значений требуют кавычек и иногда затрудняют визуальную проверку. TSV разделяет поля табуляцией и часто легче читается в текстовом редакторе. JSON полезен, когда результат передаётся программе: он сохраняет структуру таблиц и ячеек без зависимости от выбранного символа-разделителя. Формат выбирают параметром -f CSV, -f TSV или -f JSON; регистр лучше писать так, как показано в справке.

Выбор страниц параметром --pages

По умолчанию обрабатывается только первая страница, поэтому отсутствие данных с дальнейших листов не является ошибкой. Параметр -p принимает отдельный номер, диапазон, комбинацию диапазонов и значение all. Нумерация начинается с единицы, как в просмотрщике PDF. Строка 1-3,5-7 выбирает страницы 1, 2, 3, 5, 6 и 7, пропуская четвёртую. Пробелы внутри списка лучше не использовать, чтобы оболочка не разделила значение на несколько аргументов.

java -jar tabula.jar report.pdf -p 1-3,5-7 -f TSV -o selected-pages.tsv
java -jar tabula.jar report.pdf -p all -f JSON -o all-pages.json

Обработка всех страниц уместна только после проверки макета. Если на титульном листе нет таблицы, а приложения имеют другую ориентацию, единая команда создаст лишние или неоднородные строки. Надёжнее разделить документ на группы страниц с одинаковой структурой и запускать для каждой группы собственную область. Это особенно важно, когда таблица на первой странице начинается ниже из-за заголовка, а на последующих продолжается сразу под колонтитулом.

Перед массовым запуском выберите одну типичную страницу из середины диапазона и одну пограничную страницу. Сравните число колонок, расположение заголовка и наличие продолжения строки. Если таблица переносится между страницами, решите, нужно ли удалять повторяющуюся строку заголовков при последующей обработке. Tabula Java извлекает видимую структуру каждой страницы и не знает, что одинаковые заголовки должны быть объединены или отброшены.

Точная область таблицы: --area

Параметр -a ограничивает анализ прямоугольником и является главным средством отделить таблицу от остального текста. Координаты задаются в порядке верх, левый край, низ, правый край, то есть y1,x1,y2,x2. Единица измерения — пункт PDF относительно верхнего левого угла страницы. Это отличается от многих графических систем, где начало координат находится внизу слева, поэтому механическое копирование чисел из другого инструмента часто даёт зеркально смещённую область.

java -jar tabula.jar report.pdf -p 2 -a 92,38,714,558 -f CSV -o table.csv

Верхняя граница должна проходить немного выше первой нужной строки, нижняя — немного ниже последней. Слишком тесная рамка обрезает верхние элементы букв или последние цифры и может изменить объединение текста. Слишком широкая захватывает подпись, номер страницы и соседние примечания. Начните с запаса в несколько пунктов, затем сужайте область по стороне, откуда поступает мусор. Изменяйте одну координату за раз и фиксируйте результат, иначе будет трудно понять, какое изменение улучшило структуру.

Если макет масштабируется между страницами или документы имеют разные размеры, абсолютные пункты заменяют процентами. Все четыре значения должны быть помечены процентным режимом; пример %10,5,90,95 означает прямоугольник от 10% высоты и 5% ширины до 90% высоты и 95% ширины. Проценты удобны для серий, где таблица занимает одинаковую долю страницы, но не сохраняет точность при плавающем заголовке или добавленных примечаниях.

java -jar tabula.jar report.pdf -p all -a %12,6,92,94 -f TSV -o proportional.tsv

Несколько областей на одной странице

Ключ -a можно повторить, если на странице расположены независимые таблицы. Каждая область обрабатывается отдельно, что снижает риск объединения соседних колонок. Порядок результатов соответствует порядку переданных областей и страниц, поэтому заранее решите, как потребитель будет различать таблицы. Для JSON границы области могут быть полезны как часть структуры, а для CSV удобнее направлять логические блоки в разные запуски и давать файлам понятные имена.

java -jar tabula.jar sheet.pdf -p 1 -a 80,30,360,560 -a 410,30,720,560 -f JSON -o two-tables.json

Повторяемые области подходят для страницы с двумя ведомостями, но не заменяют контроль пересечений. Если прямоугольники накладываются, одинаковый текст может попасть в результат дважды. Если между ними остаётся зазор, строка на границе будет потеряна. Для длинных документов сначала проверьте области на странице с максимальным количеством строк, затем на странице с короткой таблицей: нижняя рамка, рассчитанная по полному листу, может захватить примечание на коротком.

Как получить координаты без угадывания

У самого JAR нет встроенного визуального редактора рамки, поэтому координаты обычно подбирают через просмотрщик PDF, вспомогательный инструмент геометрии либо интерфейс Tabula, использующий тот же механизм извлечения. В визуальном интерфейсе рамку рисуют вокруг таблицы, проверяют предпросмотр и сохраняют шаблон. Для командной строки важны числовые границы и выбранный способ разбора; их переносят в параметры -a, -c, -l или -t. Такой подход разделяет удобную разметку и воспроизводимый запуск.

При переносе координат обязательно проверьте систему отсчёта. Значения должны описывать расстояния от верхнего и левого краёв, а не координаты нижнего левого угла. Для повёрнутых страниц полезно сначала посмотреть, как PDFBox интерпретирует ориентацию: визуальный поворот в просмотрщике и внутренний поворот страницы могут отличаться. Контрольный запуск с узкой областью в верхнем левом углу быстро показывает, в какой системе применяются числа.

Границы столбцов: --columns

Параметр -c задаёт X-координаты вертикальных разделителей. Он особенно полезен для таблиц без линий, где пробел между двумя колонками слишком мал или неодинаков. Передаются только внутренние границы, а не левый и правый края всей области. Например, три координаты создают четыре диапазона столбцов. Значения должны возрастать слева направо и попадать внутрь анализируемой области.

java -jar tabula.jar report.pdf -p 3 -a 100,40,700,560 -c 155,330,438 -t -f CSV -o fixed-columns.csv

Сначала определите границы по нескольким строкам, а не по одному заголовку. Заголовок может быть центрирован, объединён или переноситься, тогда его пробелы не отражают структуру данных. Надёжнее выбрать строки с заполненными значениями во всех колонках и провести разделитель по устойчивому пустому коридору. Если число в правом столбце иногда длиннее, оставьте запас, чтобы его знак не пересёк границу и не перешёл в соседнее поле.

Процентные координаты столбцов задают так же, как процентную область, например --columns %25,50,80.6. Они подходят для документов одинаковой композиции, сформированных на страницах разного формата. Если ширина самой таблицы меняется, проценты от страницы не помогут: координаты будут стабильны относительно листа, а не относительно прямоугольника данных. В таком наборе лучше предварительно нормализовать страницы или вычислять параметры отдельно по каждому шаблону.

Явные столбцы не исправляют неверную группировку строк. Если значения из двух визуальных строк соединены в одну, сначала настройте область и режим извлечения, затем уже уточняйте X-разделители. Наоборот, если строки распознаны правильно, но длинное описание разрывает соседний код, -c часто даёт более предсказуемый результат, чем автоматическое определение границ по пробелам.

Stream: таблицы, разделённые пробелами

Режим Stream выбирают ключом -t. Он предназначен для таблиц без полного набора линий между ячейками и анализирует расположение текстовых элементов. Слова объединяются в строки по вертикальному перекрытию, затем промежутки и повторяющиеся позиции помогают определить колонки. Поэтому результат зависит от реальных координат текста, а не от числа пробелов, которое видно после копирования. Ровно выровненные суммы, даты и коды обычно извлекаются хорошо даже при полностью белом фоне.

java -jar tabula.jar statement.pdf -p 2-8 -a 110,36,730,560 -t -f TSV -o statement.tsv

Stream чувствителен к свободному тексту. Длинное описание может занимать две строки, а соседние числовые поля — только первую; движок должен решить, относится ли вторая строка к той же записи. Перед экспортом проверьте строки с максимальной длиной текста, пустыми ячейками и отрицательными числами. Если переносы создают дополнительные записи, ограничьте область, задайте столбцы и предусмотрите последующее объединение строк по признаку пустого ключевого поля.

Автоматический выбор колонок может ошибаться, когда заголовок содержит больше слов, чем данные, либо когда в таблице много пропусков. Явные X-границы уменьшают неоднозначность. Ещё один полезный приём — исключить многострочный заголовок из области и добавить его в итоговую таблицу отдельно. Это не меняет данные, зато алгоритм оценивает структуру по регулярным строкам, а не по декоративной шапке.

Если таблица содержит точки-лидеры, длинные подчёркивания или разделители из символов, они становятся текстовыми элементами и могут образовать ложные колонки. Сузьте область до значимых данных или удалите такие элементы на подготовительном этапе. Переход на Lattice оправдан только тогда, когда PDF действительно содержит векторные границы ячеек; нарисованные текстовыми символами линии не образуют геометрическую сетку.

Lattice: таблицы с нарисованной сеткой

Режим Lattice включают ключом -l. Он ищет вертикальные и горизонтальные линии, их пересечения и прямоугольники ячеек, после чего распределяет текст по найденной сетке. Это лучший первый выбор для форм, экспортированных из электронных таблиц, где каждая ячейка отделена сплошной линией. В отличие от Stream, ширина пробелов между словами здесь менее важна: основную структуру задаёт геометрия границ.

java -jar tabula.jar grid.pdf -p all -a 75,28,744,568 -l -f CSV -o grid.csv

Визуально заметная сетка может оказаться растровой частью скана и тогда не даст Lattice ни одного пересечения. Проверить природу линии можно сильным увеличением: векторная линия остаётся резкой и часто выделяется как объект, а растровая распадается на пиксели. Другой тест — сравнить Lattice и Stream на одной узкой области. Если Lattice возвращает пусто или одну ячейку, а Stream находит текстовые строки, причина обычно в отсутствии пригодных векторных линий.

Разрывы в границах, цветной фон, двойные линии и ячейки без замкнутого контура могут дробить сетку. Tabula Java не предоставляет длинного набора морфологических настроек, поэтому основными рычагами остаются область, качество исходного PDF и выбор другого режима. Иногда узкая рамка, исключающая внешнюю декоративную границу, позволяет движку сосредоточиться на внутренней сетке. Если несколько столбцов объединены намеренно, итоговые ячейки тоже будут объединены и потребуют нормализации после экспорта.

Ключ -u сохраняет встроенные переводы строк внутри ячеек в табличном режиме. Он нужен, когда многострочный адрес или описание должны остаться одним полем. Без него текст может быть склеен иначе, что облегчает машинную обработку, но теряет внутреннее форматирование. Выбор зависит от следующего этапа: для долговременного хранения данных переносы полезны, для загрузки в систему с построчной логикой их часто заменяют пробелами после извлечения.

Как выбрать режим без долгого перебора

Сначала определите, существуют ли линии как геометрические объекты. Полная векторная сетка — аргумент в пользу Lattice; отсутствие линий — в пользу Stream. Затем сделайте два коротких запуска на одной странице и сравните не внешний вид, а три метрики: число извлечённых строк, стабильность числа столбцов и целостность ключевых значений. Режим, который дал красивую шапку, но потерял строки с пустыми ячейками, хуже режима с менее аккуратным заголовком и полным набором данных.

Ключ -g просит движок угадать область анализа на каждой странице. Он удобен для первичной разведки, когда таблица хорошо отделена от текста, но не заменяет фиксированную геометрию в повторяемом процессе. Автоопределение может выбрать разные рамки на соседних страницах из-за подписи, примечания или изменившегося числа строк. Для разовой задачи это экономит время; для регулярной загрузки лучше измерить и закрепить область.

Не включайте одновременно противоречивые принудительные режимы. Устаревшие параметры spreadsheet и no-spreadsheet сохранены для совместимости, но в новых командах понятнее использовать --lattice и --stream. Так журнал запуска однозначно показывает выбранный алгоритм, а сценарий легче проверять другим специалистам.

Форматы вывода: CSV, TSV и JSON

CSV создаёт строки с разделёнными полями и экранирует значения, содержащие запятые, кавычки или переводы строк. Проверяющая программа должна использовать полноценный CSV-парсер, а не делить строку простой операцией по запятой: иначе адрес Москва, ул. Лесная превратится в два столбца. При импорте в электронную таблицу задайте кодировку, разделитель и интерпретацию чисел вручную, чтобы ведущие нули в кодах и длинные идентификаторы не были преобразованы.

TSV использует табуляцию, поэтому удобен для данных с большим количеством запятых и десятичных дробей. Но табуляция внутри исходного текста также требует корректного экранирования, а программы могут по-разному трактовать переводы строк в кавычках. Для быстрой проверки TSV полезно открыть в редакторе, который показывает невидимые символы: сразу видно, где строка содержит лишнюю табуляцию или неожиданный перенос.

JSON выбирают для программной интеграции и диагностики нескольких таблиц. Структура позволяет сохранить группы строк и ячеек без неоднозначного разделителя. При этом JSON не превращает текст в числа автоматически: значение 00123 остаётся строкой и не теряет ведущие нули. Типизацию, очистку пробелов, преобразование дат и проверку обязательных полей выполняют на следующем этапе, где правила предметной области известны явно.

Параметр -o записывает вывод в указанный файл. Без него данные идут в STDOUT, что полезно для конвейера оболочки, но требует осторожности: диагностические сообщения должны оставаться в STDERR. Ключ -i подавляет сообщения STDERR и подходит для автоматизированной среды, где любой служебный текст считается ошибкой. Во время настройки тихий режим лучше не включать, иначе пропадут подсказки о проблемном документе.

java -jar tabula.jar input.pdf -p 4 -a 120,40,700,560 -t -f JSON -o output.json
java -jar tabula.jar input.pdf -p 4 -a 120,40,700,560 -t -f TSV > output.tsv

Предварительный просмотр и контроль структуры

Предпросмотр нужен не для оценки оформления, а для обнаружения систематической ошибки до массового запуска. Просмотрите первую, среднюю и последнюю строки таблицы, затем найдите строку с пустой ячейкой, длинным текстом и отрицательным числом. Убедитесь, что заголовок не стал частью данных, единицы измерения не отделились в новую строку, а примечание под таблицей не попало в последний столбец. Один удачный фрагмент в верхней части ещё не подтверждает корректность всей страницы.

Для широких таблиц сравнивайте правую часть отдельно. Ошибка часто возникает после десятого столбца, где значения становятся короче, сетка прерывается или страница обрезана. Посчитайте ожидаемое число колонок и проверьте его на каждой строке программно. В CSV это делает парсер, в JSON — проверка длины массива ячеек. Строки с другим числом полей складывают в отдельный отчёт, а не исправляют молча, потому что отклонение может означать как ошибку, так и законную объединённую ячейку.

Сравнение с исходником выполняют по контрольным суммам предметных данных. Для финансовой ведомости можно сопоставить итоговую сумму, для статистической таблицы — количество регионов, для расписания — число рейсов. Такие проверки выявляют потерянные строки, даже если визуально CSV выглядит аккуратно. Дополнительно полезно случайно выбрать несколько записей и сверить все поля с PDF, включая знаки минус, десятичные разделители и ведущие нули.

Пакетная обработка каталога

Ключ -b обрабатывает все PDF в указанном каталоге и уменьшает накладные расходы по сравнению с отдельным запуском виртуальной машины для каждого файла. В каталог следует помещать только документы одного ожидаемого типа. Смешивание счетов, отчётов и приложений с разной геометрией приводит к разнородным результатам, которые трудно отличить автоматически. Перед запуском создайте список входных имён и ожидаемых выходов, чтобы заметить пропущенный или дублированный файл.

java -jar tabula.jar -b incoming -p all -a %12,6,92,94 -t -f CSV

Пакетный режим особенно эффективен, когда все документы созданы одной системой и таблица занимает одинаковую область. Сначала проверьте параметры на небольшом наборе: типичный файл, самый длинный, самый короткий и документ с необычным значением. После запуска посчитайте выходные файлы, строки и ошибки. Файл с нулём строк не должен просто считаться пустым: возможно, у него другая ориентация, пароль, повреждённый текстовый слой или изменившийся шаблон.

Для нескольких шаблонов разбейте входной поток на каталоги по признаку макета. Признаком может быть размер страницы, текст заголовка, число страниц или версия формы, но решение должно приниматься до извлечения таблицы. Каждый каталог получает собственную команду и собственные проверки. Это надёжнее универсального набора координат, который вроде бы работает для всех документов, но незаметно сдвигает одну колонку в меньшей группе.

Если требуется обработать тысячи файлов, полезнее встроить библиотеку в долгоживущий JVM-процесс, чем многократно запускать java -jar. Значительная доля времени короткой команды уходит на старт виртуальной машины и загрузку классов. В серверном процессе JAR загружается один раз, документы обрабатываются последовательно или контролируемыми задачами, а результаты и ошибки получают единый журнал. Параллелизм следует ограничивать памятью и числом одновременно открытых PDF.

Шаблоны для повторяющихся документов

Шаблон — это зафиксированная геометрия области, страницы и выбранный способ извлечения. В визуальном интерфейсе Tabula рамку можно сохранить и повторно применить к документам похожего макета; для JAR тот же принцип реализуют как командный файл, конфигурацию или запись в базе. Важно хранить не только четыре координаты, но и формат страницы, список страниц, режим Stream или Lattice, границы столбцов, использование переносов и правила последующей проверки.

Название шаблона должно описывать поставщика и форму, а не конкретный файл: например, ежемесячная ведомость, страницы 2–5, альбомная. К шаблону полезно приложить эталонный PDF и ожидаемый результат. Когда поставщик изменит шрифт, поля или структуру шапки, автоматическая проверка покажет расхождение, а специалист сможет сравнить новый документ с эталоном и обновить координаты осознанно.

Не применяйте шаблон только потому, что совпало имя файла. Надёжнее проверить размер страницы и наличие нескольких якорных фраз в ожидаемых областях. Если якорь отсутствует, документ отправляют на ручную проверку. Такая защита предотвращает ситуацию, когда новый тип отчёта случайно обрабатывается старой командой и создаёт правдоподобный, но неверный CSV.

Документы с паролем

Для PDF, защищённого паролем открытия, используется параметр -s. Пароль передаётся процессу как аргумент командной строки, поэтому он может быть виден в истории оболочки и списке процессов. Для одноразовой ручной работы это допустимо только на доверенном компьютере; в автоматизации пароль лучше получать из защищённого хранилища и минимизировать его появление в журналах. Не записывайте команду с реальным секретом в общий сценарий или README.

java -jar tabula.jar protected.pdf -s "пароль" -p 1 -f CSV -o protected.csv

Пароль владельца и пароль открытия выполняют разные функции. Если просмотрщик открывает документ без запроса, но запрещает копирование, библиотека PDF может по-разному учитывать ограничения в зависимости от шифрования и разрешений. Ошибка дешифрования означает, что пароль неверен либо схема защиты не поддержана используемой PDF-библиотекой. Сначала убедитесь, что тот же пароль открывает файл в независимом просмотрщике, затем повторите запуск на копии с простым путём и без остальных параметров.

После успешной обработки защищённого документа выходной CSV уже не наследует шифрование PDF. Его нужно хранить по правилам исходных данных: права каталога, журнал доступа, срок хранения и безопасное удаление. Извлечение таблицы часто делает конфиденциальную информацию легче для поиска и массовой обработки, поэтому защита результата не менее важна, чем защита входного файла.

Интеграция через Java API

При встраивании в Java-код документ загружают через PDFBox, создают ObjectExtractor и получают страницы через PageIterator. На каждой странице выбирают алгоритм: SpreadsheetExtractionAlgorithm для сетки или BasicExtractionAlgorithm для текста и пробелов. Результатом является список объектов Table, содержащих строки и ячейки. Потоки и PDDocument обязательно закрывают, лучше конструкцией try-with-resources, иначе длительный процесс будет удерживать файлы и память.

try (PDDocument document = PDDocument.load(inputFile)) {
    ObjectExtractor extractor = new ObjectExtractor(document);
    PageIterator pages = extractor.extract();
    ExtractionAlgorithm algorithm = new BasicExtractionAlgorithm();
    while (pages.hasNext()) {
        Page page = pages.next();
        List<Table> tables = algorithm.extract(page);
        // проверить и записать tables
    }
}

Перед вызовом алгоритма страницу можно ограничить прямоугольной областью. В коде это позволяет хранить шаблоны как объекты конфигурации и выбирать их по типу документа. Не смешивайте единицы измерения: координаты PDF задаются в пунктах, порядок границ должен соответствовать API, а поворот страницы учитывается отдельно. Простой модульный тест с одной известной ячейкой помогает обнаружить ошибку системы координат до обработки всего набора.

Для записи данных можно использовать предоставленные писатели CSV или JSON либо преобразовать таблицу в собственную модель. Собственная модель оправдана, когда нужно сохранить номер страницы, индекс области, координаты ячейки и предупреждения качества. Не преобразуйте всё в строки без контекста слишком рано: геометрия помогает объяснить, почему значение попало в соседний столбец, и полезна при разборе спорных случаев.

Обработчик должен различать три исхода: таблица успешно извлечена и прошла проверки; таблица извлечена, но нарушены правила структуры; документ не удалось прочитать. Второй исход нельзя записывать как обычный успех. Например, список из одной таблицы с одной гигантской ячейкой технически не пуст, но явно не соответствует ожидаемым двадцати столбцам. Явные статусы и метрики делают конвейер контролируемым.

Stream и Lattice в коде

В API алгоритм выбирают явно. BasicExtractionAlgorithm группирует текстовые элементы, а SpreadsheetExtractionAlgorithm опирается на линии. Для автоматического решения можно сначала исследовать линии страницы и применить правило, но это правило нужно тестировать на конкретном корпусе. Наличие нескольких декоративных линий ещё не означает табличную сетку; наоборот, сетка с разрывами может быть обнаружена не полностью. Практичнее хранить выбор в шаблоне документа, а автоматическое решение использовать только для неизвестных файлов.

Если одна страница содержит таблицы разных типов, её разбивают на области и применяют алгоритм к каждой области отдельно. Верхняя ведомость с сеткой может извлекаться Lattice, а нижняя расшифровка без линий — Stream. Единый режим для всей страницы либо потеряет текст, либо создаст ложную сетку. В выходной модели каждой области назначают идентификатор, чтобы строки двух таблиц не смешались.

Отладочный инструмент и геометрия страницы

В составе JAR предусмотрен отдельный отладочный класс technology.tabula.debug.Debug. Его справку вызывают через classpath, а не через основной режим -jar. Инструмент полезен разработчикам, когда нужно исследовать внутренние объекты страницы и понять, какие линии или текстовые элементы видит движок. Вывод отладки не является итоговой таблицей; его используют для диагностики координат и подготовки воспроизводимого отчёта об ошибке.

java -cp tabula.jar technology.tabula.debug.Debug -h

При отладке сохраните проблемный PDF, точную команду, версию Java, ожидаемую область и небольшой пример неверного результата. Словесное описание колонки съехали недостаточно: нужно указать страницу, строку и значение, которое оказалось не там. Если документ конфиденциален, создайте минимальный обезличенный PDF с тем же расположением объектов. Ошибка, воспроизводимая на маленьком примере, значительно легче отделяется от особенностей исходных данных.

Отдельно проверяйте CropBox и MediaBox. Видимая область страницы может начинаться не в координате ноль, а просмотрщик скрывает эту деталь. Современная обработка учитывает смещённые рамки, но PDF, созданные необычным генератором, всё равно заслуживают проверки. Если область систематически сдвинута на одинаковое расстояние, сравните границы страницы через PDF-инспектор и попробуйте предварительно нормализовать документ печатью в новый PDF только на копии.

Производительность и память

Время обработки зависит от числа страниц, количества графических объектов, сложности шрифтов и выбранного алгоритма. Lattice тратит ресурсы на анализ линий и пересечений, Stream — на группировку текста. Измеряйте время на представительном наборе, а не на одной простой странице. Для пакетной задачи полезно отдельно записывать длительность открытия PDF, извлечения каждой страницы и сериализации результата: так видно, где находится узкое место.

Большой многостраничный PDF может потребовать заметный heap. Если процесс завершается с OutOfMemoryError, сначала сократите диапазон страниц и убедитесь, что проблема связана с объёмом, а не с повреждённым объектом на конкретной странице. Затем увеличьте лимит памяти виртуальной машины параметром -Xmx в разумных пределах и не запускайте слишком много процессов одновременно. Увеличение heap не исправит бесконечный или патологически сложный объект, поэтому проблемную страницу всё равно нужно изолировать.

java -Xmx2g -jar tabula.jar large.pdf -p 1-100 -a %10,5,95,95 -t -f JSON -o part-001.json

Деление документа на диапазоны снижает пиковую память и упрощает повторный запуск после ошибки. Имена результатов должны содержать диапазон страниц, а объединение выполняется после проверки каждого фрагмента. При этом нельзя просто склеивать CSV-тексты, если каждый фрагмент содержит заголовок или разные правила кавычек. Используйте CSV-парсер, удаляйте только подтверждённые повторные заголовки и сохраняйте исходный номер страницы.

Для многочисленных коротких документов главный расход — запуск JVM. Пакетный ключ или встроенный долгоживущий сервис устраняет повторную инициализацию. Но один процесс не должен бесконтрольно копить документы в памяти: открывайте, извлекайте, записывайте и закрывайте каждый PDF. Метрики памяти после каждого файла помогают заметить утечку или документ, резко увеличивающий потребление.

Проверка качества в автоматическом конвейере

Надёжный конвейер задаёт формальные ожидания. Минимальный набор: допустимое число таблиц на странице, диапазон количества строк, точное или допустимое число столбцов, обязательные заголовки, формат ключевого поля и контрольная сумма числового столбца. Каждая проверка должна выдавать понятное сообщение с именем файла и страницей. Проверка результат не пуст слишком слабая: ложная таблица из колонтитула тоже не пуста.

• Сравнивайте число полей в каждой строке с ожидаемой схемой и отдельно учитывайте законные объединённые ячейки.
• Проверяйте уникальность ключа, если каждая строка должна описывать отдельный объект или операцию.
• Ищите повторяющиеся заголовки внутри данных после объединения нескольких страниц.
• Контролируйте долю пустых значений по столбцам: резкий рост часто указывает на сдвиг границы.
• Сверяйте суммы, количества и диапазоны дат с итогами, напечатанными в PDF.
• Сохраняйте команду и шаблон вместе с результатом, чтобы извлечение можно было повторить.

При обнаружении отклонения не исправляйте файл на глаз без следа. Сохраните исходный результат, создайте исправленную версию и запишите правило преобразования. Если строка переносится из-за длинного описания, правило может объединять её с предыдущей только при пустом идентификаторе и непустом текстовом поле. Такие условия предотвращают случайное склеивание законной новой записи.

Для новых шаблонов полезна двойная проверка человеком. Один специалист настраивает область и режим, второй сверяет случайные строки и итоговые показатели. После утверждения эталонный набор становится регрессионным тестом: любое изменение Java, JAR, OCR или входного генератора прогоняется на тех же PDF и сравнивается со структурой эталона.

Типовые рабочие сценарии

Банковские и платёжные выписки

В выписке обычно есть дата, описание, дебет, кредит и остаток. Начните с области без реквизитов счёта и итогов страницы, выберите Stream, затем задайте границы числовых колонок. Проверьте операции с длинным описанием, пустым дебетом или кредитом и отрицательным остатком. Повторяющийся заголовок на каждой странице удаляют после извлечения только при полном совпадении ожидаемых названий полей. Итоговый остаток сверяют с напечатанным значением, а число операций — с диапазоном дат.

Статистические отчёты

Статистические таблицы часто имеют многоуровневую шапку и объединённые ячейки. Lattice может точно восстановить сетку, но логическая структура заголовка всё равно потребует преобразования: название группы распространяют на дочерние столбцы, единицы измерения сохраняют отдельно, сноски исключают из данных. Область лучше начинать со строки, где видны реальные разделители, а сложную шапку разобрать один раз по шаблону. Проверка включает число территорий и итоговые суммы.

Расписания и перечни

В расписаниях границы часто отсутствуют, зато позиции колонок стабильны. Stream с явными X-разделителями позволяет отделить время, маршрут и примечание. Особое внимание уделяют строкам с несколькими днями недели, диапазоном времени и переносом названия остановки. Если одна запись занимает две визуальные строки, правило объединения опирается на пустое поле времени во второй строке, а не только на отступ.

Счета и однотипные формы

В счёте таблица позиций обычно отделена от реквизитов, налогов и итогов. Ограничьте область строками товаров, чтобы адреса и банковские данные не образовали ложные колонки. Lattice подходит для сплошной сетки, Stream — для минималистичного макета без линий. Последнюю строку позиции отличают от блока итогов по структуре: у позиции есть код или количество, у итога — подпись и сумма. Сумму строк проверяют против напечатанного итога с учётом округления и налогов.

Научные и технические публикации

В статьях таблица окружена подписью, номером, ссылками и сносками. Область должна исключать подпись сверху и примечания снизу, если они не являются частью данных. Многострочные значения и математические символы требуют проверки кодировки и шрифтов. Если PDF содержит две колонки основного текста рядом с таблицей, анализ всей страницы почти неизбежно захватит посторонние абзацы, поэтому точная рамка обязательна.

Ошибки запуска и способы устранения

Команда java не найдена

Сообщение о неизвестной команде означает, что оболочка не видит исполняемый файл. Найдите каталог установленной Java, запустите его полным путём и затем настройте PATH. После изменения переменных закройте старое окно терминала и откройте новое: уже запущенная оболочка может не получить обновлённое окружение. Если на компьютере несколько Java, команда where java или which java показывает, какой файл используется первым.

Unable to access jarfile

Ошибка доступа к JAR обычно связана с неверной текущей папкой, опечаткой или кавычками. Выполните список файлов в текущем каталоге и убедитесь, что имя совпадает полностью. При абсолютном пути заключите его в двойные кавычки. Не путайте JAR с пакетом исходного кода: для команды нужен файл с зависимостями и исполняемым манифестом.

Invalid or corrupt jarfile

Проверьте, не была ли вместо бинарного файла сохранена страница ошибки или перенаправления. Размер в несколько килобайт подозрителен для сборки с зависимостями. Откройте копию программой для ZIP: настоящий JAR является ZIP-контейнером. Затем повторно скачайте файл и сравните хэш, если он опубликован или был зафиксирован при первом получении. Не пытайтесь исправлять JAR переименованием HTML или обычного ZIP.

PDF читается, но таблиц нет

Сначала проверьте текстовый слой и номер страницы. Затем запустите без области на одной странице, чтобы исключить ошибку координат. Попробуйте оба режима. Если текст появляется только как одна длинная строка, задайте столбцы для Stream. Если Lattice пуст, убедитесь, что линии векторные. Если весь PDF является сканом, выполните OCR и повторите тест на распознанной копии.

В результат попал весь текст страницы

Это ожидаемо при слишком широкой области или запуске по всей странице. Определите прямоугольник таблицы, исключив заголовки, подписи и колонтитулы. Для страниц одинакового макета используйте одну область; для первой страницы с иной шапкой создайте отдельный запуск. Автоматическое угадывание области можно использовать для разведки, но окончательную геометрию лучше закрепить.

Столбцы слились

В Stream задайте X-границы через -c по устойчивым пустым промежуткам. Проверьте строки с самыми длинными значениями и не проводите разделитель через символ. В Lattice слияние означает, что разделяющая линия отсутствует, разорвана или не распознана; тогда попробуйте Stream либо предварительно исправьте PDF. После экспорта нельзя безопасно делить поле по одному пробелу, если текстовые значения тоже содержат пробелы.

Одна строка распалась на несколько

Причина обычно в многострочной ячейке, различной базовой линии текста или переносе описания. Для Lattice проверьте -u, чтобы сохранить внутренние переводы строк в одной ячейке. Для Stream задайте колонки и разработайте правило объединения по ключевым полям. Не объединяйте любые строки с пустой первой ячейкой: в некоторых таблицах пустой ключ допустим как отдельная запись.

Лишние строки из колонтитулов

Сузьте вертикальные границы области. Если число строк таблицы меняется и нижний колонтитул иногда входит в рамку, удаляйте его по точному шаблону только после извлечения или используйте разные области для коротких и длинных страниц. Проверка по одному слову опасна: то же слово может встретиться в данных. Лучше сочетать позицию строки, число полей и полный текст колонтитула.

Неверный порядок текста

Некоторые PDF хранят символы не в визуальном порядке. Tabula Java использует координаты, но сложные направления письма, вертикальный текст и нестандартные шрифты могут дать перестановки. Проверьте копирование из независимого просмотрщика и попробуйте другой способ извлечения. Если проблема присутствует в самом текстовом слое, помогает пересоздание PDF или OCR с правильным языком и направлением текста.

Процесс завершился по памяти

Изолируйте диапазон страниц, увеличьте heap в пределах ресурсов и уменьшите параллелизм. Если сбой всегда происходит на одной странице, исследуйте её отдельно: большое встроенное изображение, сложный путь или повреждённый объект может потреблять непропорционально много памяти. Разбиение документа позволяет обработать остальные страницы и сохранить точный проблемный фрагмент для диагностики.

Работа с переносами, пустыми ячейками и объединениями

Пустая ячейка — часть структуры, а не ошибка. При очистке нельзя удалять все пустые поля, иначе значения сдвинутся влево. CSV-парсер должен сохранять последовательные разделители и пустое последнее поле. В JSON длина массива помогает заметить, что пустая ячейка исчезла. Схема данных должна различать пустую строку, отсутствие поля и значение, которое не удалось распознать.

Объединённая ячейка не имеет универсального представления в плоском CSV. Движок может поместить текст в первую ячейку диапазона, оставить соседние пустыми или объединить геометрическую область. На этапе нормализации решают, нужно ли распространить значение вниз или вправо. Такое заполнение допустимо только при знании смысла таблицы: название раздела можно распространить на строки группы, а итоговую сумму — нельзя.

Внутренние переводы строк следует сохранять до проверки. Замена всех переносов пробелом упрощает экспорт, но может склеить абзацы, адресные строки или перечисления. Сначала определите, является ли перенос частью одной ячейки или признаком новой записи. Для Lattice помогает геометрия ячейки, для Stream — наличие значений в ключевых колонках и вертикальное расстояние между текстовыми блоками.

Пробелы тоже несут смысл. Неразрывный пробел, узкий пробел и обычный пробел могут выглядеть одинаково, но по-разному участвовать в очистке и числовом преобразовании. Перед разбором суммы нормализуйте пробелы-разделители тысяч, сохраните знак и определите десятичный символ. Исходную строку стоит хранить рядом с преобразованным числом, чтобы спорное значение можно было проверить.

Особенности повёрнутых и разнородных страниц

Альбомная страница может иметь физически широкие размеры либо обычный размер с флагом поворота. Просмотрщик показывает оба варианта одинаково, но координаты и область могут отличаться. Настройте команду на одной странице и проверьте контрольную ячейку у каждого края. Если в одном PDF смешаны книжные и альбомные листы, разделите диапазоны и используйте отдельные области.

Автоматический поворот после OCR иногда меняет только отображение, не нормализуя внутреннюю геометрию. В результате рамка, рассчитанная на визуальный верх, попадает сбоку. Надёжное решение — создать нормализованную копию с применённым поворотом или вычислять область с учётом метаданных страницы. Любое преобразование выполняют на копии и проверяют, что текстовый слой не потерян.

Страницы разного размера требуют либо процентных координат, либо классификации по размеру. Проценты работают, если таблица масштабируется вместе со страницей. Если таблица сохраняет абсолютную ширину, а меняются только поля, процентные границы сместятся. Сравните реальные размеры и положение нескольких якорных ячеек, прежде чем выбирать систему координат для всего набора.

Безопасность и конфиденциальность данных

Обработка JAR не требует отправки PDF внешнему сервису, поэтому маршрут данных контролируется владельцем среды. Это не отменяет риски рабочего каталога, временных файлов, резервных копий и журналов. Ограничьте права на входные и выходные каталоги, не сохраняйте конфиденциальные примеры в общедоступном репозитории и удаляйте временные копии по установленной политике. При работе на сервере запускайте процесс от отдельной учётной записи без лишних привилегий.

JAR следует получать по проверяемому каналу и фиксировать SHA-256 после загрузки. Хэш не доказывает добросовестность программы, но позволяет убедиться, что один и тот же бинарный файл используется на тестовом и рабочем контуре. Перед обновлением зависимостей прогоните регрессионный набор PDF. Для организаций с требованиями к цепочке поставки полезно собирать из исходного кода в контролируемой среде и сохранять перечень зависимостей.

PDF может содержать сложные объекты, поэтому документы от недоверенного отправителя обрабатывают в изолированной среде с ограничением памяти, времени и доступа к сети. Тайм-аут предотвращает бесконечную обработку патологической страницы, а лимит размера входа — случайную загрузку гигантского файла. Ошибки парсера записывают без полного содержимого конфиденциальных ячеек: достаточно имени, страницы, типа ошибки и технического идентификатора.

Сравнение Tabula Java с аналогами

Программа	Лучше подходит для	Главное ограничение
Tabula Java	Повторяемого извлечения таблиц из текстовых PDF через CLI и JVM-код	Нет OCR и встроенной визуальной разметки
PDF Commander	Ручного редактирования, сборки и преобразования PDF в понятном интерфейсе	Не предназначен для программного разбора геометрии таблиц
Camelot	Python-конвейеров с несколькими способами разбора и экспортом в DataFrame	Работает с текстовыми PDF и требует Python-настройки
pdfplumber	Низкоуровневого анализа символов, линий и тонкой отладки таблиц в Python	Требует программирования и ручного подбора параметров
Excalibur	Визуального выделения областей и настройки извлечения на базе Camelot	Нужна отдельная среда и локальный веб-интерфейс

Tabula Java стоит выбирать, когда параметры уже известны и требуется стабильная команда или интеграция в JVM. Camelot удобнее в Python-аналитике, особенно когда нужен DataFrame и дополнительные способы разбора. pdfplumber полезен для нестандартной геометрии и визуальной отладки на уровне объектов. Excalibur подходит специалисту, которому проще рисовать области и сохранять правила в интерфейсе. PDF Commander разумнее для правки, объединения и обычного преобразования документов, но не заменяет специализированный движок массового извлечения таблиц.

Практическая последовательность настройки

1. Проверьте, что слова в таблице выделяются и копируются как текст; для скана сначала выполните OCR.
2. Запустите справку JAR и сохраните сведения о Java вместе с журналом проекта.
3. Выберите одну типичную страницу и экспортируйте её без области для первичной диагностики.
4. Ограничьте таблицу параметром -a, исключив заголовки, подписи и колонтитулы.
5. Сравните Stream и Lattice на одной области и выберите режим по полноте строк и стабильности колонок.
6. При необходимости задайте X-границы через -c по нескольким заполненным строкам.
7. Выберите CSV, TSV или JSON с учётом следующего этапа и явно задайте выходной файл.
8. Проверьте шапку, последнюю строку, пустые ячейки, длинный текст и контрольные суммы.
9. Закрепите параметры как шаблон и прогоните несколько документов разной длины.
10. Добавьте автоматические проверки и только после этого переходите к пакету или API.

Эта последовательность сокращает перебор, потому что каждый шаг отвечает на отдельный вопрос. Проверка текстового слоя отделяет задачу OCR от задачи таблиц; область отделяет нужный блок от страницы; режим определяет способ реконструкции; колонки уточняют геометрию; формат решает передачу данных; проверки подтверждают смысл. Если менять все параметры одновременно, красивый результат трудно воспроизвести и невозможно объяснить при следующем документе.

Как поддерживать шаблон после изменения формы

Изменение входного отчёта обычно проявляется не полной ошибкой, а небольшим сдвигом: новая строка в заголовке опускает таблицу, добавленный столбец меняет пробелы, другой шрифт расширяет значения. Поэтому шаблон должен иметь контрольные признаки. Проверяйте координату первой строки, ожидаемые заголовки, число колонок и долю пустых значений. Если два или более признака изменились, остановите автоматический импорт и отправьте файл на перенастройку.

При обновлении шаблона сохраните прежний вариант и дату переключения. Старые документы должны воспроизводиться старой конфигурацией, новые — новой. Нельзя просто заменить координаты в единственном сценарии и затем обнаружить, что ранее сохранённые PDF больше не извлекаются. Версионирование конфигурации относится к форме документа, а не к публичному номеру программы: оно фиксирует собственные правила организации.

Эталонные результаты лучше сравнивать структурно. Побайтовое сравнение CSV может реагировать на порядок кавычек или окончания строк, хотя данные одинаковы. Разберите результат парсером, нормализуйте только допустимые различия и сравните таблицы, ключи и контрольные суммы. При этом исходный файл сохраняйте, чтобы можно было расследовать любое расхождение.

Что Tabula Java не делает вместо пользователя

Движок не понимает предметный смысл колонок. Он не знает, что Итого должно совпасть с суммой строк, дата обязана попадать в отчётный период, а код товара должен иметь ведущие нули. Эти правила добавляются в проверяющий слой. Чем важнее данные, тем меньше следует полагаться на визуально аккуратный CSV без семантических тестов.

Он также не восстанавливает отсутствующие символы и не исправляет ошибки OCR. Если цифра распознана как буква или часть слова закрыта печатью, геометрический разбор лишь поместит ошибочное значение в ячейку. Полезно хранить ссылку на страницу и координаты спорной ячейки, чтобы оператор быстро увидел оригинал. Автоматическая замена похожих символов допустима только при строгом формате поля и с журналом исправлений.

Наконец, извлечение не превращает сложную многоуровневую таблицу в готовую реляционную схему. Объединённые заголовки, секции, сноски и итоги требуют модели данных. Tabula Java решает трудную геометрическую часть — получает строки и ячейки из PDF; последующая нормализация должна быть прозрачной, проверяемой и привязанной к конкретной форме.

Командные сценарии для разных операционных систем

На Windows удобно хранить параметры в BAT-файле, но значения с символом процента требуют экранирования: в пакетном файле один знак % используется для переменных, поэтому процентную область иногда приходится записывать как %%12,6,92,94. Сначала выполните команду непосредственно в терминале, затем перенесите её в сценарий и сравните результаты. Для путей используйте двойные кавычки, а код возврата Java проверяйте после каждого запуска, чтобы следующий документ не обрабатывался после критической ошибки.

@echo off
java -Dfile.encoding=UTF8 -jar tabula.jar "incoming\report.pdf" -p all -a %%12,6,92,94 -t -f CSV -o "result\report.csv"
if errorlevel 1 exit /b 1

В PowerShell параметры лучше передавать как отдельные элементы массива, особенно когда путь или пароль содержит пробелы. Перенаправление стандартного вывода и выбор кодировки зависят от версии оболочки, поэтому надёжнее пользоваться -o. Журнал можно формировать отдельным перенаправлением STDERR. После выполнения проверяйте существование выходного файла, его размер и структуру, а не только код завершения: команда может закончиться без исключения, но вернуть таблицу, не соответствующую ожидаемой схеме.

На macOS и Linux оболочка интерпретирует звёздочки, доллар и обратную косую черту. Заключайте пути в одинарные кавычки, если внутри нет одинарного апострофа, либо корректно экранируйте специальные символы. Для регулярного задания используйте абсолютные пути к Java, JAR, входному и выходному каталогам: планировщик запускается с другим рабочим каталогом и сокращённым PATH. В начале сценария полезно вывести дату, имя хоста, версию Java и хэш JAR, а в конце — число обработанных файлов и список отклонений.

Стандартный вывод, STDERR и коды завершения

Tabula Java разделяет табличные данные и диагностические сообщения: при отсутствии -o результат поступает в STDOUT, а служебный текст — в STDERR. Это позволяет передавать CSV следующей команде конвейера, но только если сценарий не объединяет оба потока. Конструкция, направляющая STDERR в STDOUT, может вставить предупреждение прямо между строками таблицы. Для машинной обработки сохраняйте потоки раздельно: данные — в целевой файл, диагностику — в журнал с датой и именем документа.

Ключ --silent убирает сообщения STDERR, но не должен использоваться как способ скрыть ошибки. В тестовой среде оставьте диагностику включённой и классифицируйте известные сообщения. В рабочем задании тихий режим допустим, если код завершения, наличие файла, число таблиц и структурные проверки контролируются отдельно. Пустой журнал не доказывает корректность, как и непустой журнал не всегда означает отказ: важен тип сообщения и состояние результата.

После сбоя сохраняйте не только последнюю строку исключения, но и начало стека, команду и документ. Ошибка оболочки, Java и парсера PDF выглядят по-разному. Оболочка может не найти файл, виртуальная машина — не загрузить класс, а PDFBox — отвергнуть структуру документа. Разделение уровней ускоряет исправление: путь лечится кавычками, среда — настройкой Java, повреждённый PDF — восстановлением или повторным экспортом.

Разделители, локаль и числовые значения

Извлечение сохраняет видимый текст, а не назначает числовые типы. Значение 1 234,50, код 00127 и дата 03.04.25 выходят строками. Нельзя передавать их табличному редактору с автоматическим распознаванием без контроля: код потеряет ведущие нули, дата может поменять порядок дня и месяца, а длинный идентификатор — перейти в экспоненциальную запись. При импорте задайте столбцам текстовый тип либо выполняйте преобразование программно после проверки шаблона.

Десятичная запятая внутри CSV не мешает корректному парсеру, потому что поле экранируется кавычками, но выбор локали в электронном редакторе влияет на преобразование. Безопасная схема хранит два значения: исходную строку и нормализованное число. Нормализатор удаляет только подтверждённые разделители тысяч, заменяет известный десятичный символ и отвергает строку с лишними знаками. Тогда 1.234,50 и 1,234.50 не смешиваются по догадке.

Знак минус может быть обычным дефисом, типографским минусом или длинным тире, а отрицательная сумма иногда заключена в скобки. До вычислений нормализуйте эти варианты по правилам конкретного отчёта и сохраняйте предупреждение о замене. Аналогично обрабатываются проценты, валютные символы и сноски после числа. Удаление всех нецифровых символов опасно: оно превращает отрицательное значение в положительное и может склеить два числа.

Сохранение происхождения каждой строки

При объединении многостраничного результата добавьте технические поля: имя исходного PDF, номер страницы, индекс области и порядковый номер строки. Они не обязаны попадать в конечную бизнес-таблицу, но нужны для аудита и исправлений. Если пользователь сообщает о неверной сумме, по этим полям можно открыть точную страницу и рамку, а не искать значение во всём наборе. Для JSON происхождение удобно хранить рядом с массивом ячеек; для CSV — в дополнительных первых или последних столбцах.

Номер страницы следует брать из фактически обработанного диапазона, а не вычислять по позиции строки в общем файле. Одна страница может дать несколько таблиц или ни одной. Если запускается несколько областей, присвойте им устойчивые имена вроде items, totals и notes, а не только номер. Это предотвращает смешивание двух структур, которые случайно имеют одинаковое число столбцов.

При последующей очистке сохраняйте связь между исходной и нормализованной строкой. Полезны поля с идентификатором записи, списком применённых преобразований и статусом проверки. Тогда автоматическое объединение переноса, удаление повторного заголовка или преобразование числа можно воспроизвести. Ручная правка без журнала разрушает эту связь и делает невозможным доказательство того, откуда взялось значение.

Регрессионный набор для Tabula Java

Регрессионный набор должен включать не только идеальные документы. Добавьте страницу без линий, страницу с полной сеткой, многострочную ячейку, пустой столбец, объединённый заголовок, альбомный лист, защищённый тестовый PDF и крупный документ. Для каждого примера храните команду, ожидаемое число таблиц, строк и столбцов, а также несколько контрольных значений. Набор выполняется после изменения Java, JAR, параметров OCR или сценария очистки.

Сравнивать можно на трёх уровнях. Первый — технический: команда завершилась, JSON разбирается, все файлы созданы. Второй — структурный: совпадает число таблиц, полей и обязательных заголовков. Третий — содержательный: контрольные суммы и значения ключевых ячеек равны эталону. Побайтовое совпадение полезно, но не обязательно, если допустимы изменения экранирования или порядка служебных полей.

Когда тест падает, отчёт должен показать минимальное различие: файл, страницу, таблицу, строку, столбец, ожидаемое и фактическое значение. Огромный diff всего CSV затрудняет поиск причины. Если изменение признано правильным, эталон обновляют осознанно с пояснением. Автоматическая перезапись эталонов после каждого запуска превращает тест в формальность и скрывает регрессии.

Предварительная нормализация PDF

Перед извлечением иногда полезно создать техническую копию PDF: применить поворот страниц, удалить пустые поля, объединить разрозненные листы или выполнить OCR. Каждая операция может изменить координаты, поэтому шаблон области настраивают уже на нормализованной копии и не применяют к оригиналу. В журнале фиксируют последовательность преобразований и хэш обоих файлов. Это позволяет понять, относится ли ошибка к подготовке или к извлечению таблицы.

Печать в новый PDF может упростить необычную структуру, но одновременно превратить текст в кривые, изменить шрифты или потерять доступность. После преобразования повторите проверку выделения и поиска текста. Не используйте печать как изображение, если затем планируется геометрический разбор символов: результат потребует OCR и внесёт дополнительную вероятность ошибок. Нормализация должна сохранять текстовый слой и векторные линии, если на них рассчитывает Lattice.

Обрезка страницы помогает исключить постоянные колонтитулы, но часто достаточно параметра --area, который не меняет исходник. Физическую обрезку выбирают, когда тот же подготовленный PDF будет использоваться несколькими инструментами или когда внутренние рамки страницы некорректны. Перед массовым преобразованием сравните размеры, повороты, количество страниц и возможность открыть результат независимым просмотрщиком.

Когда разделять задачу на несколько команд

Одна команда удобна, но не является целью сама по себе. Разделите обработку, если первая страница имеет другую шапку, последние страницы содержат итоги, часть листов повёрнута, на странице есть таблицы разных типов или геометрия меняется после определённой даты. Несколько коротких команд с ясными областями легче тестировать, чем одна универсальная команда с большим количеством исключений.

Результаты отдельных команд объединяют по схеме, а не простым склеиванием текста. Сначала разбирают каждый файл, добавляют происхождение, проверяют число полей и только затем соединяют строки. Заголовок удаляют по точному совпадению, а итоговые строки помещают в отдельную таблицу, если их структура отличается. Такой подход сохраняет данные, которые универсальный CSV мог бы исказить ради одинакового количества колонок.

Разделение также упрощает повторный запуск. Если ошибка произошла на страницах 201–250, не нужно заново обрабатывать первые двести. Имена файлов должны отражать диапазон и шаблон, а финальный манифест — перечислять все фрагменты и их хэши. После объединения проверьте непрерывность страниц и отсутствие дублей, особенно если диапазоны создавались вручную.

Интерпретация пустого или подозрительно малого результата

Пустой файл может означать отсутствие таблицы, неправильную страницу, область вне видимой части, неподходящий режим, скан без текста, неверный пароль или ошибку чтения. Диагностика идёт от простого к сложному: открыть страницу, убрать --area, проверить текстовый слой, запустить Stream и Lattice, посмотреть STDERR. Не увеличивайте область вслепую на всех страницах: это может скрыть проблему, добавив посторонний текст вместо нужной таблицы.

Подозрительно маленький результат опаснее полного отказа, потому что выглядит успешным. Сравните число строк с ожидаемым минимумом и найдите последнюю запись в исходнике. Если экспорт остановился посередине страницы, исследуйте строку с необычным шрифтом, объединением или длинным значением. Если отсутствует целый столбец, проверьте правую границу области и ширину страницы после поворота.

Для документов, где таблица законно бывает пустой, добавьте отдельный признак пустого состояния: например, текст операций нет в ожидаемой области. Тогда ноль строк можно отличить от ошибки. Пустой результат без такого подтверждения отправляют на проверку. Это правило предотвращает молчаливую потерю данных в дни, когда поставщик изменил макет или прислал скан.

Итоговый контроль перед использованием данных

Перед передачей результата в бухгалтерскую, аналитическую или систему долговременного хранения убедитесь, что сохранены исходный PDF, команда, параметры области, выбранный режим, хэш JAR и журнал проверок. Затем проверьте количество документов, страниц, таблиц, строк и отклонений. Любой файл без результата, с необычным числом колонок или проваленной контрольной суммой должен оставаться в карантине, а не попадать в общий набор.

Для ручной задачи достаточно сверить несколько репрезентативных строк и итог. Для регулярной загрузки нужны автоматические тесты, эталонные документы и понятный процесс обновления шаблона. Когда эти элементы настроены, Tabula Java даёт не просто разовый CSV, а воспроизводимый способ извлечь одинаковую структуру из серии PDF, обнаружить изменение макета и доказать, какими параметрами был получен каждый результат.