Solid Framework SDK позволяет встроить в собственное приложение реконструкцию PDF в Word, Excel, PowerPoint, HTML и текст, извлечение таблиц и изображений, OCR сканов, проверку PDF/A, рендеринг страниц и низкоуровневый доступ к структуре документа через Core Model.

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

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

Как устроен рабочий процесс

Вместо универсального окна с кнопкой Конвертировать разработчик получает набор API, примеров и справочных классов. В .NET-проект обычно добавляют ссылку на SolidFramework.dll, а нативный проект подключает SolidFramework.h и SolidFramework.cpp и загружает библиотечные файлы нужной разрядности. После инициализации программа создаёт объект конвертера, добавляет один или несколько исходных файлов, назначает выходной путь и вызывает метод преобразования. Такой порядок удобен для фоновых служб, пакетных обработчиков, серверных очередей и корпоративных систем, где пользователь вообще не должен видеть внутренний PDF-конвертер.

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

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

Подключение библиотеки к проекту

Вариант для .NET

Сборка для .NET рассчитана на языки, совместимые с CLS, поэтому типовые примеры одинаково переносимы между C#, Visual Basic .NET и другими языками этой среды. Для нового проекта проще брать вариант AnyCPU: он сам выбирает 32- или 64-разрядные нативные компоненты в зависимости от процесса. Это снижает риск получить BadImageFormatException, когда приложение собирается как 32-разрядное, а подключённая сборка содержит только 64-разрядную часть. Если используется специализированная x86- или x64-сборка, разрядность проекта должна совпадать с ней во всех конфигурациях, включая Debug, Release и сервисный хост.

SolidFramework.dll лучше хранить рядом с исходным кодом решения или в управляемом внутреннем пакете, а не ссылаться на случайную копию из каталога загрузок. Тогда сборочный сервер и рабочие станции используют один и тот же бинарный файл. В свойствах ссылки следует проверить Copy Local, а в публикуемый каталог включить лицензионный XML и дополнительные данные OCR, если они требуются сценарию. При обновлении библиотеки полезно очистить bin и obj, потому что старые нативные компоненты могут сохраниться в промежуточных каталогах.

Нативный вариант C++

В C++ поставка разворачивается как набор файлов для Windows, macOS и Linux. Проект включает интерфейсные файлы SolidFramework.h и SolidFramework.cpp, после чего вызывает инициализацию с путём к распакованным библиотекам. В отличие от .NET-обёртки, здесь разработчик сам контролирует расположение зависимостей и выбирает папку Win32, Win64, Linux или OSX. В рабочую сборку не нужно копировать каталоги других платформ: достаточно файлов для фактической цели, заголовков и тех ресурсов, которые использует OCR или шрифтовая база.

Нативная интеграция полезна там, где .NET Framework отсутствует или где основное приложение уже написано на C++. На Windows сборка должна соответствовать выбранной архитектуре, а на macOS поддерживается запуск на Apple Silicon без обязательного слоя Rosetta. На Linux особое внимание требуется шрифтам и путям к данным: серверная система обычно содержит гораздо меньше гарнитур, чем рабочая станция Windows, поэтому без подготовленной базы метрик результат Word может заметно отличаться.

Лицензия, Machine ID и инициализация

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

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

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

Реконструкция PDF в Word

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

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

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

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

Извлечение таблиц и данных в Excel

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

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

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

Для табличного извлечения доступен и путь не через XLSX. PdfToDataConverter может подготовить данные в CSV, минимальный Excel или инструкции для MySQL и Microsoft SQL Server. Такой режим подходит для загрузки в базу, но не заменяет проверку схемы: распознанный заголовок, объединённая ячейка или примечание над таблицей способны изменить структуру. Надёжный импорт сначала сохраняет промежуточный файл, валидирует количество столбцов и только затем выполняет загрузку.

Преобразование в PowerPoint

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

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

Формат N-up, где на одной PDF-странице размещено несколько слайдов, нельзя трактовать как обычную презентацию без дополнительной логики. Сначала нужно определить прямоугольники отдельных миниатюр, затем обрезать или реконструировать каждую область как самостоятельный слайд. Автоматический экспорт страницы целиком создаст один слайд с несколькими маленькими кадрами. Для потоковой обработки такой тип входа лучше выявлять по повторяющейся сетке и направлять в отдельный профиль.

HTML, текст, изображения и рендеринг страниц

PdfToHtmlConverter создаёт переразмеченный HTML, где текст приспосабливается к ширине окна и сохраняет стили, таблицы и гиперссылки. Это удобно для чтения на узком экране и публикации содержимого в системе знаний. Но переразметка сознательно меняет исходную геометрию, поэтому страница не будет пиксельно совпадать с PDF. Когда требуется визуально близкий HTML, официальный пример строит его из Core Model и координат, позволяя самостоятельно определить CSS-позиционирование и правила для каждого объекта.

Извлечение текста восстанавливает порядок чтения, а не просто сортирует символы по координате. Это важно для многоколоночных статей, боковых примечаний и таблиц. Результат можно сохранить как обычный текст либо обходить внутри Core Model. При индексации стоит хранить номер страницы и границы блока вместе со строкой: тогда поисковая система сможет подсветить найденный фрагмент в исходном PDF, а не только показать документ целиком.

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

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

Core Model и координаты объектов

Core Model — внутреннее представление восстановленного документа. Вместо работы только с готовым DOCX разработчик получает абзацы, разделы, строки, текстовые запуски, таблицы, изображения и связи между ними. Это открывает сценарии, которые нельзя решить обычным конвертером: сравнение документов на уровне смысловых блоков, извлечение конкретных разделов, перевод с сохранением структуры, создание собственного RTF или HTML, классификация и построение поискового индекса.

Для сопоставления с исходной страницей при создании модели включают ExposeTargetDocumentPagination. Затем LayoutDocument позволяет найти объект разметки по идентификатору элемента Core Model. У абзаца появляется соответствующий LayoutParagraph с геометрией. Координаты можно использовать для подсветки, построения карты чтения, проверки попадания текста в заданную область или извлечения данных из форм, где смысл определяется положением относительно подписи.

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

Поворот страницы также имеет два уровня. В PDF страница может быть физически нарисована боком и дополнительно снабжена флагом Rotate. Анализатор нормализует ориентацию текста, но координаты всё равно нужно интерпретировать в правильной системе. При тестировании полезно иметь набор файлов с 0, 90, 180 и 270 градусами, включая документы, где разные страницы ориентированы по-разному.

OCR для сканов и нестандартного кодирования

Если страница содержит только изображение, Solid OCR распознаёт текст, определяет строки, блоки, координаты, цвет и характеристики шрифта, после чего эти данные используются при создании Word, searchable PDF или собственного результата. Основной движок ориентирован на деловые документы с латиницей и кириллицей. Для китайского, японского, корейского, греческого, иврита и других поддерживаемых сценариев подключаются данные Tesseract.

Файлы traineddata не всегда входят в стандартный набор из-за размера. Их размещают в папке tessdata, доступной процессу, и задают путь до инициализации. Для распознавания нелатинского языка нужен соответствующий файл, а английский набор полезен для цифр и латинских символов, встречающихся почти в любом документе. Если приложение разворачивается в контейнере, tessdata нужно включить в образ и проверить права чтения под фактической учётной записью.

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

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

Предварительная обработка изображений

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

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

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

PDF/A: создание, проверка и исправление

Библиотека проверяет соответствие PDF/A и формирует подробный отчёт либо простой результат pass/fail. Для архивного процесса подробный режим предпочтительнее: он показывает отсутствующие профили, проблемные шрифты, прозрачность, метаданные и другие причины несоответствия. Простой результат удобен как быстрый фильтр, но не объясняет, что исправлять и можно ли сделать это автоматически.

Конвертер способен создать PDF/A из обычного или отсканированного PDF, а с OCR — добавить поисковый слой. Важно различать проблему исходника и итог. Статус PdfAError может означать, что входной файл не соответствовал стандарту, но библиотека всё же исправила нарушения и создала выходной документ. Поэтому обработчик должен проверить Paths в ConversionResults. Если путь есть, файл следует дополнительно валидировать и только затем считать задание проваленным или успешным.

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

Изменение существующих PDF

API умеет открывать структуру PDF, менять свойства документа и настройки начального просмотра. Можно назначить Title, Author, Subject и Keywords, выбрать раскладку страниц, начальный масштаб, отображение миниатюр, скрытие панели инструментов или меню и подгонку окна. Эти параметры влияют на поведение совместимого просмотрщика, но не заменяют изменение самого содержимого страницы.

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

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

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

Параллельная обработка и JobProcessor

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

JobProcessor в .NET запускает независимые процессы JobHandler, помещает запросы в очередь и назначает их свободным рабочим. По умолчанию число обработчиков связано с количеством ядер, но WorkerCount можно уменьшить, чтобы оставить ресурсы операционной системе и другим службам. Каждый процесс выполняет одну конверсию, поэтому сбой или зависание затрагивает конкретное задание, а не всю очередь. Рабочие процессы периодически перезапускаются для предотвращения накопления ресурсов.

Для ASP.NET рекомендуемая схема выносит JobProcessor в Windows Service и связывает веб-приложение с ним через сервисный интерфейс. Веб-узел загружает файл, отправляет задачу, опрашивает состояние и получает результат. Это отделяет тяжёлую реконструкцию от пула IIS, исключает конфликт AppDomain и упрощает права на локальные каталоги. Внешний API должен ограничивать размер файла, число страниц и максимальное время обработки, иначе один сложный скан способен занять рабочий процесс надолго.

В нативной C++ версии встроенного JobProcessor нет. Для неё поставщик описывает отдельную реализацию на Python, работающую на Windows и Linux. Альтернативно можно построить собственный диспетчер процессов: создавать ограниченное число воркеров, передавать им задания через очередь, контролировать тайм-аут и перезапускать после ошибки. Ключевое правило остаётся тем же — одна активная конверсия на один процесс.

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

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

Количество воркеров нельзя автоматически приравнивать к числу логических процессоров без измерений. OCR и реконструкция одновременно потребляют CPU, память и дисковый ввод-вывод. На сервере с восемью ядрами восемь тяжёлых конверсий могут вызвать своп и работать медленнее четырёх. Практический тест измеряет среднее время, 95-й процентиль, пиковую память и длину очереди при нескольких значениях WorkerCount.

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

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

Шрифты и одинаковый результат на разных системах

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

На Linux набор шрифтов обычно меньше, чем на рабочем компьютере Windows. В результате один и тот же PDF может получить Arial-подобную гарнитуру на одной машине и DejaVu Sans на другой. Для воспроизводимости используется база шрифтов fonts.pdf. Она содержит метрики выбранных TrueType и OpenType гарнитур и задаётся через SetFontsDataBaseFile. После этого реконструкция опирается на одну и ту же коллекцию независимо от локально установленных шрифтов.

Базу создают утилитой FontsToPdf.exe на Windows. По умолчанию она собирает доступные системные шрифты; если рядом создать папку fonts, можно ограничить набор конкретными файлами. Гарнитуры с запрещённым встраиванием не попадут в базу. Полученный fonts.pdf следует версионировать вместе с приложением и обновлять контролируемо, поскольку изменение базы способно поменять разметку результатов даже без обновления кода.

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

Диагностика и журнал обработки

Подробный журнал включается назначением пути через SolidFramework.Plumbing.Logging. В нём отражаются этапы чтения PDF, OCR, построения модели и экспорта. Файл лучше создавать заново для каждого задания или добавлять уникальный идентификатор в имя. При использовании JobHandler дополнительные журналы получают собственные суффиксы; общий файл для нескольких процессов может вызвать конфликт доступа.

Логирование включают после инициализации и импорта лицензии. Каталог должен существовать, а учётная запись службы — иметь право записи. Если журнал пуст, сначала проверяют именно эти условия, затем абсолютный путь и свободное место. Внешнему пользователю не следует возвращать весь лог: он может содержать пути и внутренние сведения. Достаточно кода ошибки и идентификатора, по которому администратор найдёт файл.

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

Типовые ошибки и их устранение

BadImageFormatException

Эта ошибка обычно означает несовпадение разрядности процесса и сборки. В Visual Studio проект AnyCPU может фактически запускаться как 32-разрядный из-за флажка Prefer 32-bit, тогда как подключена x64-версия SolidFramework.dll. Предпочтительное решение — взять AnyCPU-сборку. Второй вариант — снять Prefer 32-bit или явно выбрать x64 во всех конфигурациях. После изменения следует удалить старые файлы из bin и obj и проверить, какая сборка реально загружается.

Не найден api-ms-win-crt-runtime-l1-1-0.dll

Сообщение связано с библиотеками времени выполнения Microsoft Visual C++, необходимыми сборке. На старых Windows нужные компоненты могут отсутствовать. Устанавливают поддерживаемый пакет Visual C++ Redistributable соответствующей архитектуры, перезагружают службу и повторяют запуск. Копировать отдельную DLL с неизвестного сайта в системный каталог нельзя: это не гарантирует совместимость и создаёт риск безопасности.

Неверная лицензия или файл не найден

Проверяют абсолютный путь, права учётной записи, соответствие Machine ID и то, что импорт выполнен до создания конвертера. В службе путь относительно текущего каталога часто указывает не туда, куда ожидает разработчик. Надёжнее вычислять его от каталога приложения или передавать через конфигурацию. Содержимое XML не следует изменять вручную.

Конверсия завершилась, но файл не найден

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

Текст превратился в бессмысленные символы

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

Безопасность серверной интеграции

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

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

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

Для многоарендной системы каждому клиенту назначают отдельный каталог и идентификатор задания. JobHandler не должен брать произвольный путь из запроса. В ответ возвращается только файл, принадлежащий текущему пользователю. После сбоя нужно удалить частичный результат, иначе следующий запрос может получить повреждённый или чужой документ.

Практические сценарии внедрения

Поисковый архив сканов

Система принимает TIFF или image-only PDF, выравнивает страницы, удаляет шум, выполняет OCR и создаёт searchable PDF/A. Параллельно текст и координаты отправляются в индекс. Пользователь ищет фразу, получает документ и страницу, а интерфейс подсвечивает соответствующий прямоугольник. Контроль включает PDF/A-валидацию, выборочную проверку OCR и сравнение рендера до и после.

Импорт таблиц в корпоративную базу

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

Восстановление договоров для сравнения

PDF преобразуется в Word или Core Model. Из модели извлекаются абзацы в порядке чтения, заголовки и таблицы. Сравнение выполняется по структуре и тексту, а найденные отличия связываются с координатами исходных страниц. Для сканов предварительно применяется OCR; для нестандартного кодирования — восстановление глифов. Это позволяет сравнивать PDF с DOCX и два PDF, не полагаясь на визуальный слой.

Конвертация презентаций из опубликованных PDF

Каждая страница становится слайдом PPTX, после чего автоматическая проверка ищет потерянные шрифты, изображения поверх текста и неверный порядок объектов. Файлы N-up распознаются заранее и разбиваются по областям. Слайды со сканированным содержимым помечаются как требующие ручной доработки, поскольку OCR не всегда восстанавливает исходные диаграммы как редактируемые элементы.

Веб-сервис документов

Веб-приложение загружает PDF и ставит задачу в очередь. Отдельная служба JobProcessor распределяет операции по рабочим процессам, ограничивает параллелизм и возвращает DOCX, XLSX, PPTX, HTML или изображения. Пользовательский запрос не выполняет тяжёлую работу внутри IIS. Для каждого задания задаются тайм-аут, лимит страниц и уникальный журнал.

Как тестировать качество конвертации

Набор тестов должен отражать реальные риски: обычный текст, две и три колонки, таблицы с линиями и без них, длинные числа, списки, колонтитулы, ссылки, прозрачные изображения, Type 3 и нестандартные шрифты, поворот, скан, смешанные языки, защищённый PDF и повреждённая структура. Один хороший файл не показывает, что произойдёт на производственном потоке.

Для DOCX проверяют количество страниц, наличие ожидаемых заголовков, число таблиц, текст ключевых абзацев и открытие в Word без восстановления. Для XLSX сравнивают число листов, строк и столбцов, критические значения и типы ячеек. Для PPTX контролируют число слайдов и присутствие текста. Для HTML проверяют кодировку, локальные ресурсы и порядок чтения. Для PDF/A используют независимый валидатор и визуальное сравнение.

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

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

Настройка профиля конвертации в Word

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

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

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

Изображения с автоматической привязкой обычно дают лучший баланс, но диаграммы, расположенные между двумя абзацами, стоит проверять на перемещение. Anchor to Paragraph сохраняет связь с текстом, Anchor to Page — фиксированную координату, Remove Images — чистый текстовый результат. При извлечении только юридического текста удаление изображений уменьшает размер и ускоряет работу, но может потерять печати, подписи и содержательные схемы. Такие элементы нужно заранее классифицировать как обязательные или декоративные.

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

Контроль извлечения таблиц и чисел

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

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

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

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

Если PDF содержит теги, они могут улучшить выделение таблицы, но неверные теги способны ухудшить результат. Для диагностики выполняют анализ с тегами и после RemoveStructTreeRoot. Разница показывает, опирался ли конвертер на структурное дерево. Удалять теги в оригинале нельзя без необходимости: создают копию, выполняют эксперимент и сохраняют оба результата вместе с журналом.

Работа с Core Model на практике

Обход Core Model обычно начинается с Topic и коллекций разделов. Внутри находятся абзацы, таблицы, изображения и текстовые runs. Разработчик может построить собственное дерево, присвоить каждому элементу тип, текст, порядковый номер и идентификатор. Идентификатор затем связывается с LayoutDocument, чтобы получить прямоугольник на исходной странице. Эта связь полезна для интерфейса проверки: оператор видит извлечённый абзац и одновременно подсвеченную область PDF.

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

Таблица в Core Model должна сохраняться как структурный объект, а не превращаться в последовательность абзацев. Для каждой ячейки хранят строку, столбец, объединение и текст. Если downstream-система принимает JSON, структура таблицы передаётся явно: массив строк и ячеек, а не HTML-фрагмент. Это упрощает валидацию и не связывает бизнес-логику с конкретным способом визуализации.

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

При создании собственного HTML из модели разработчик сам решает, что важнее: точное расположение или адаптивное чтение. Для визуального режима используют координаты и абсолютное позиционирование. Для адаптивного — порядок элементов и семантические теги. Смешанный режим может оставить таблицы и изображения фиксированными, а текстовые разделы сделать потоковыми. Официальный пример PDF to HTML показывает, почему готовый reflowed converter и ручная сборка из Core Model решают разные задачи.

Классификация страниц перед OCR

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

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

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

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

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

Надёжный конвейер PDF/A

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

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

Статус PdfAError требует специальной ветки. Он сигнализирует о проблеме исходного файла, но коллекция результатов может содержать корректно созданный путь. Обработчик проверяет наличие файла, запускает независимую валидацию и только затем определяет итог. Простое условие status != Success приводит к потере успешно исправленных документов; простое условие file exists — к принятию невалидного результата.

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

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

Рендеринг, миниатюры и сравнение изображений

PdfToImageConverter используют для миниатюр, предпросмотра и контрольных рендеров. DPI выбирают по задаче: небольшая миниатюра не нуждается в печатном разрешении, а OCR мелкого текста требует более крупного изображения. Формат тоже влияет: PNG сохраняет линии и текст без артефактов, JPEG уменьшает фотографии, но размывает мелкие символы. Для чёрно-белых архивов можно использовать компактные варианты, если просмотрщик их поддерживает.

Нумерация выходных файлов должна быть предсказуемой и сортируемой: page-0001.png, page-0002.png и далее. Нельзя полагаться на лексикографический порядок page-1, page-10, page-2. Результаты операции могут содержать несколько путей, поэтому список берут из API, а не строят по догадке. Перед публикацией проверяют, что число изображений совпало с числом страниц.

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

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

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

Протокол задания для очереди конвертации

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

Состояния полезно разделить на queued, running, succeeded, failed, timed_out и cancelled. Отдельно хранят прогресс, если библиотека или оболочка его предоставляет, время старта, номер воркера и путь к журналу. Повтор задания создаёт новую попытку с собственным идентификатором, а не перезаписывает старую запись. Тогда можно увидеть, что первый запуск завершился по памяти, а второй — после уменьшения WorkerCount.

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

Отмена не всегда может мгновенно остановить внутренний этап. Диспетчер помечает запрос, прекращает выдачу новых действий и при необходимости завершает конкретный JobHandler после безопасного тайм-аута. Завершать весь пул из-за одного задания нельзя. После принудительной остановки временный каталог очищается, а воркер запускается заново.

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

Развёртывание на Windows, Linux и macOS

На Windows .NET-вариант удобен для служб и приложений, уже использующих .NET Framework. Публикация включает правильную сборку, лицензию, данные OCR, шрифтовую базу и Visual C++ Runtime. Установщик должен проверять наличие зависимостей, но не скачивать неизвестные DLL. Служба запускается под отдельной учётной записью с правами только на каталоги входов, результатов, временных файлов и журналов.

Нативный Windows-проект выбирает Win32 или Win64 и включает SolidFramework.cpp и SolidFramework.h. Смешивание каталогов разных архитектур приводит к ошибке загрузки. В диагностике фиксируют полный путь фактически загруженной библиотеки. Для производительности крупных сканов предпочтителен Win64, поскольку 32-разрядный процесс ограничен памятью.

На Linux основная проблема обычно не запуск, а воспроизводимость шрифтов и путей. Каталоги чувствительны к регистру, системных гарнитур мало, а служба может работать из другого текущего каталога. Все пути задают явно, fonts.pdf и tessdata монтируют как версионированные ресурсы, а временный каталог размещают на томе с достаточным объёмом. После сборки проверяют нативные зависимости стандартными инструментами системы.

На macOS нативная библиотека может работать на Apple Silicon без Rosetta. Тем не менее приложение и все подключаемые компоненты должны иметь совместимую архитектуру. Универсальная оболочка не исправит x86-only зависимость внутри собственного плагина. Перед подписью и нотаризацией проверяют, что библиотечные файлы включены в пакет и доступны по ожидаемому относительному пути.

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

Форматы входа и выхода в едином конвейере

Основным входом для реконструкции остаётся PDF, включая электронные и сканированные страницы. Для архивного сценария также обрабатываются TIFF-изображения, которые можно превратить в searchable PDF или PDF/A через ImagePrintProvider и OCR. Выход выбирается по назначению: DOCX для редактирования текста, XLSX или данные для таблиц, PPTX для слайдов, HTML для публикации, plain text для индекса, bitmap для предпросмотра и PDF/A для хранения.

Не следует считать форматы взаимозаменяемыми. DOCX пытается восстановить семантику абзацев и таблиц; HTML может быть потоковым или визуальным; текст теряет изображения и часть структуры; XLSX оптимизирован для табличных областей; PPTX сохраняет композицию слайдов. Если пользователь просит конвертировать PDF, интерфейс должен уточнить цель или предложить профили с понятными последствиями.

При извлечении данных в CSV, SQL или минимальный Excel важен контроль кодировки и разделителей. Текстовые поля могут содержать запятые, переводы строк и кавычки. Надёжный экспорт использует стандартное экранирование и явно задаёт UTF-8. SQL-вывод нельзя выполнять без проверки и параметризации: он является результатом распознавания, а не доверенным запросом.

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

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

Приёмка результата пользователем и оператором

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

Оператору контроля нужен просмотр исходника и результата рядом. Для Word и PowerPoint достаточно рендеров ключевых страниц; для Excel — таблицы с подсветкой подозрительных ячеек; для OCR — изображение и текст по координатам. Кнопка подтверждения должна сохранять, какой профиль и сборка использовались, чтобы принятый результат можно было воспроизвести.

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

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

Отчёт приёмки может содержать идентификатор входа, контрольные суммы, параметры, длительность, статус, список выходов и замечания. Он не должен включать лицензионный XML, пароли и внутренние секреты. Для регулируемого архива отчёт подписывают или помещают в неизменяемое хранилище вместе с исходником и PDF/A.

Сравнение Solid Framework SDK с аналогами

Программа	Лучше подходит для	Главное ограничение
Solid Framework SDK	Реконструкция PDF в Word, Excel и PowerPoint, извлечение структуры и OCR деловых документов	Параллельность строится через отдельные процессы
Apryse SDK	Широкий жизненный цикл документов: просмотр, редактирование, конвертация, подпись и серверная автоматизация	Для узкой задачи реконструкции набор возможностей может быть избыточным
Foxit PDF SDK	Встраиваемые просмотрщики, аннотации, формы, редактирование и кроссплатформенная работа с PDF	Функции распределены по платформам и лицензируемым компонентам
iText Core с pdfOffice	Программное создание, изменение, подпись PDF и преобразование Office в PDF	Обратная реконструкция PDF в Office не является основной функцией pdfOffice
PDFix SDK	Автоматизация доступности PDF, анализ логической структуры и извлечение данных	Меньше ориентирован на восстановление Word, Excel и PowerPoint
LEADTOOLS Document SDK	OCR, сканирование, изображения, форматы документов и крупные корпоративные конвейеры	Большая модульная система требует тщательного подбора компонентов

Solid Framework SDK стоит выбирать, когда центральная задача — получить редактируемый Office-документ из PDF или использовать восстановленную структуру и координаты в собственном анализаторе. Apryse и Foxit логичнее для универсального просмотрщика и полного набора PDF-инструментов. iText подходит для генерации, подписания и серверной обработки PDF, но его pdfOffice направлен прежде всего из Office в PDF. PDFix сильнее в доступности и логической разметке, а LEADTOOLS — в комплексных OCR- и imaging-конвейерах.

Ограничения, которые нужно учитывать заранее

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

Одна конверсия на процесс влияет на расчёт серверной мощности. Для высокой нагрузки нужны несколько JobHandler или собственный пул процессов. Внутри одного веб-процесса параллельные вызовы небезопасны. JobProcessor доступен в .NET, а для нативной интеграции диспетчер процессов строится отдельно. Это не косметическая деталь, а основа устойчивой архитектуры.

Полный набор функций зависит от лицензии. Базовые инструменты включают текст и изображения, рендеринг, простую PDF/A-проверку и изменение PDF; реконструкция в Office, подробная PDF/A-валидация и Core Model относятся к профессиональным возможностям, а OCR и очистка сканов требуют соответствующей опции. Перед разработкой прототипа нужно проверить, какие классы разрешены выбранной лицензией, иначе демонстрация с водяным знаком или тестовой лицензией не отражает производственные условия.

Лицензия, шрифтовая база, tessdata и нативные зависимости являются частью развёртывания. Нельзя считать, что достаточно скопировать одну DLL из проекта разработчика. Для повторяемого результата все сопутствующие файлы версионируют, включают в сборочный пакет и проверяют при старте приложения. В контейнере или службе пути должны быть абсолютными и доступными фактической учётной записи.

Пошаговый план внедрения

• Выберите один реальный PDF и один целевой формат, затем запустите официальный пример без изменения параметров.
• Подключите AnyCPU для .NET или нужную нативную архитектуру и добейтесь стабильной инициализации с тестовой лицензией.
• Добавьте проверку статуса, коллекции результатов, существования выходного файла и подробный журнал на каждое задание.
• Создайте профиль параметров для Word, Excel, PowerPoint, HTML, OCR или PDF/A вместо одного универсального набора.
• Соберите эталонный корпус с таблицами, сканами, поворотами, защитой, нестандартным кодированием и разными шрифтами.
• Для серверной нагрузки вынесите конвертацию в JobProcessor или отдельный пул процессов и измерьте память при реальных файлах.
• Зафиксируйте версии библиотеки, лицензии, fonts.pdf и tessdata в поставке, затем автоматизируйте проверку наличия при запуске.
• Перед выпуском сравните структуру и рендеры результатов, проверьте тайм-ауты, очистку временных файлов и обработку ошибок.

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

Итоговый подход к работе

Solid Framework SDK наиболее полезен там, где приложению нужно не просто показать PDF, а понять его: восстановить абзацы и таблицы, получить редактируемые документы, связать текст с координатами, распознать сканы или подготовить архивный PDF/A. Для единичного файла достаточно класса конвертера и проверки результата; для сервера требуется очередь процессов, лимиты ресурсов, журнал и набор эталонных документов.

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