# Audion Image Tools - руководство пользователя **Содержание** - [Назначение](#назначение) - [Быстрый маршрут](#быстрый-маршрут) - [Как устроен новый GUI](#как-устроен-новый-gui) - [Workbench I/O](#workbench-io) - [Модули](#модули) - [Обслуживание](#обслуживание) - [Основные папки](#основные-папки) - [CLI-примеры](#cli-примеры) - [Перед релизом](#перед-релизом) - [Канонические названия Workbench](#канонические-названия-workbench) ## Назначение Audion Image Tools - портативный GUI/CLI-инструмент для пакетной обработки изображений и PDF. Основные сценарии: конвертация, извлечение картинок из PDF, сборка PDF из картинок, обрезка, изменение размера, DPI без изменения пикселей, цветовые профили, печатные листы, контактные листы и диагностика окружения. Основной запуск: ```bat launcher_gui.cmd ``` CLI сохранен для автоматизации, но ежедневная работа рассчитана на новый GUI. ## Быстрый маршрут 1. Положить файлы в `input\`, добавить их через рабочий блок GUI или выбрать папку в поле `ИСТОЧНИК`. 2. Запустить `launcher_gui.cmd`. 3. Выбрать ROOT-модуль: `Конвертация`, `PDF`, `Обрезка`, `Размер`, `Цвет`, `Фото-лист`, `Листы и метки`, `Контактный лист` или `Диагностика`. 4. В открытом окне выбрать действие сверху. Быстрые действия запускаются сразу, действия с параметрами открывают или показывают свой блок настройки. 5. Проверить `ИСТОЧНИК`, `НАЗНАЧЕНИЕ` и параметры. 6. Нажать янтарную кнопку `ЗАПУСТИТЬ`, если действие не является быстрым. 7. Забрать результат из `output\` или из указанной папки `НАЗНАЧЕНИЕ`. Если `ИСТОЧНИК` пустой, команда использует свой стандартный вход, обычно `input\`. Если `НАЗНАЧЕНИЕ` пустое, команда пишет в свою стандартную подпапку внутри `output\`. ## Как устроен новый GUI Левая навигация содержит только ROOT-модули. `Конвертация` открывается сразу как рабочее окно, без промежуточного экрана. Остальные ROOT-модули открывают окно с сеткой действий сверху и параметрами выбранного действия ниже. Кнопки действий и `ЗАПУСТИТЬ` подсвечены слабым янтарным цветом. Текст в них светло-серый, чтобы кнопка читалась как действие, а не как обычный переход. Кнопки перехода внутри модулей остаются стандартными синими Quasar-кнопками. Параметры сгруппированы по смыслу: - `ИСТОЧНИК` - папка, которую нужно обработать целиком. - `НАЗНАЧЕНИЕ` - папка результата. - `Результат` - способ сборки или итоговый файл. - `Формат` - формат вывода, качество, PDF-режим. - `Параметры` - численные и режимные настройки команды. - `Опции` - дополнительные флаги. Для режимов из двух, трех или четырех вариантов используются сегментированные переключатели. Для множественного выбора используются чекбоксы, для чисел - поля со стрелками. Длинные пояснения перенесены в tooltip-подсказки: ими снабжены заголовки блоков, кнопки, чекбоксы, радио и переключатели. Кнопка `НАЗАД` подсказку не использует. Фон tooltip-подсказок: `RGB(23, 33, 43)`. Подсказки рассчитаны так, чтобы не обрезаться на крайних правых и левых элементах. ## Workbench I/O Две верхние строки задают активный маршрут обработки: - `ИСТОЧНИК` может быть внутренней папкой `input\`, внешней папкой или одним внешним файлом. - `НАЗНАЧЕНИЕ` может быть внутренней папкой `output\` или выбранной внешней папкой. - Кнопка системного выбора папки находится на правом краю каждой строки. - Постоянная кнопка pin показывает состояние маршрута: активный pin выделен, неактивный приглушён. Закрепление сохраняет путь в кэше, но не делает его обязательным маршрутом запуска. - Кнопка удаления слева очищает содержимое текущей папки, не удаляя саму папку. Для внутреннего `input\` подтверждение не требуется; для внешнего `ИСТОЧНИКА` появляется предупреждение. Если `ИСТОЧНИК` — отдельный файл, подтверждается удаление самого файла как потенциально единственного экземпляра. Нижняя строка разделена на смысловые группы: - `ИСТОЧНИК` открывает текущий источник в Проводнике; для отдельного файла открывается содержащая папка с выделением файла. - `ДОБАВИТЬ ФАЙЛ...` выбирает ровно один файл без копирования. Путь `ИСТОЧНИКА` временно становится путём к этому файлу до следующего изменения маршрута. - `НАЗНАЧЕНИЕ` открывает текущую папку результата. - `СБРОСИТЬ` удаляет из кэша все незакреплённые пути и всегда возвращает активные маршруты к внутренним `input\` и `output\`. Сами файлы и закреплённые записи не удаляются. Это безопасный сброс перед запуском проекта на другой системе. - `УДАЛИТЬ` после одного общего подтверждения удаляет содержимое текущих `ИСТОЧНИКА` и `НАЗНАЧЕНИЯ`. - `СПИСОК` показывает файлы текущего источника; отдельный файл отображается одной строкой. Длинный путь обрезается только при реальном переполнении и мягко затухает в узкой зоне у самого правого края. Короткий путь отображается полностью. Изменение пути сопровождается коротким бликом; эти эффекты отключаются системной настройкой уменьшения движения. ## Модули ### Конвертация Окно `Конвертация` открывается сразу. Сверху находится сетка быстрых действий, ниже - параметры обычной конвертации. Быстрые действия: - `JPG 75% качества` - конвертирует вход в JPG 75%. - `PNG` - конвертирует вход в PNG. - `PNG в оттенках серого` - переводит вход в grayscale PNG. - `2160p JPG 90% качества` - подгоняет под UHD `3840x2160` с центральной обрезкой и сохраняет JPG 90%. - `16:9 JPG 90% качества` - обрезает под 16:9 и сохраняет JPG 90%. `Конвертировать` позволяет выбрать один или несколько форматов: `JPG`, `PNG`, `TIFF`, `WebP`, `AVIF`, `HEIF`, `HEIC`. Для JPG и компактных форматов доступно качество `60%`, `75%`, `90%` и точное поле `1..100` с дефолтом `83`. Для `JPG`, `PNG` и `TIFF` можно записать DPI, не меняя пиксели. Если выбрано несколько форматов, результат раскладывается по подпапкам формата. Качество затемняется для `PNG` и `TIFF`, запись DPI затемняется для форматов, где этот сценарий не используется. Пресет `2160p JPG 90% качества` использует Lanczos. Если исходник меньше UHD и происходит реальный апскейл, после Lanczos применяется мягкая `Unsharp Mask` (`radius 0.8`, `percent 80`, `threshold 2`). Если изображение уменьшается до UHD, дополнительная резкость не добавляется. ### PDF PDF-окно содержит три действия: - `Экспорт страниц PDF` - экспортирует страницы через встроенные растры или рендеринг. - `Извлечь из PDF` - достает встроенные растровые объекты из PDF. - `Картинки в PDF` - собирает PDF из изображений. `Экспорт страниц PDF` по умолчанию использует режим `Встроенные растры`. Если нужен полный рендер страницы, выберите `Рендеринг` и задайте DPI. Формат вывода и качество выбираются в блоке `Формат`. `Извлечь из PDF` по умолчанию пишет картинки в исходном формате. Можно дополнительно выбрать целевые форматы, качество, раскладку `В одну папку` или `По папкам имён PDF`, а также включить TIFF рядом с PNG. `Картинки в PDF` по умолчанию собирает `В несколько PDF`, сохраняет DPI исходников (`Не менять DPI`) и использует режим `PNG без потерь`. Если выключить `Не менять DPI`, станет активным поле `Свой DPI`; оно меняет физический размер страниц PDF, но не пиксели исходных изображений. ### Обрезка Действия: - `Обрезать рамку` - удаляет однотонную рамку по угловому цвету. - `Умный кроп белого` - обрезает белый фон до значимых пикселей. - `Разрезать...` - делит изображения на ленты или прямоугольники по сетке. `Защитное поле, мм = 0` режет ровно по найденному контуру. Значение больше нуля оставляет исходный фон вокруг результата по DPI изображения; если DPI нет, используется 300 DPI. `Обрезать рамку` и `Умный кроп белого` по умолчанию пишут PNG, но формат можно сменить на `JPG`, `TIFF`, `WebP`, `AVIF`, `HEIF` или `HEIC`. Можно сразу собрать PDF после обрезки: `Встроенный PNG` для lossless или `Встроенный JPG 75%` для компактного PDF. Разрешение при этом не меняется. `Разрезать...` пишет части как `name_01.png`, `name_02.png` и так далее. Для режима `Ленты` выбирается направление и число частей, для режима `Сетка` - число частей по вертикали и горизонтали. ### Размер Действия: - `Под экран` - 1080p, 1440p или 2160p/UHD. - `Пропорции` - 16:9, A4 или A3. - `Уменьшить` - 25%, 50%, свой процент или подбор максимального процента под целевой размер файла в MB. - `Под рулон` - расчет DPI под физическую сторону в миллиметрах без изменения пикселей. - `DPI` - запись DPI без изменения пикселей. `Под экран` меняет пиксельное разрешение. Режимы: `Обрезка` заполняет кадр и срезает лишнее, `Вписать` сохраняет все изображение без фона, `Поля` сохраняет все изображение и добавляет фон до целевого размера. Для `2160p/UHD` при реальном апскейле применяется мягкая `Unsharp Mask` после Lanczos. `Пропорции` работает так же по режимам подгонки, но целится в выбранную пропорцию: `16:9`, `A4 вертикально`, `A4 горизонтально`, `A3 вертикально`, `A3 горизонтально`. `Уменьшить` использует `Lanczos` по умолчанию и включает `Unsharp Mask`, чтобы вернуть микроконтраст после downscale. Режимы масштаба: `25%`, `50%`, `Свой %` и `Подогнать`. В режиме `Подогнать` задается целевой размер каждого файла в MB с шагом `0,1`; движок подбирает максимальный процент, который укладывается в лимит, и старается держать результат в диапазоне `0,8-1,0` от цели. Алгоритмы уменьшения: - `Lanczos` - лучший визуальный режим для фото и мягких изображений, но на PNG-картах может создавать ореолы и раздувать файл. - `Bicubic` - качественный компромисс для фото/JPG: мягче и умнее простого усреднения, но может добавлять промежуточные цвета вокруг резких линий. - `Box` - сухое усреднение для карт, планов, скриншотов и плоской графики; обычно даёт меньше ореолов и легче PNG, чем `Lanczos`/`Bicubic`. - `Nearest` - не создает новых цветов и часто даёт самый маленький PNG, но диагонали, подписи и тонкие линии могут стать ступенчатыми. Практический ориентир: для фото и JPG начинать с `Lanczos` или `Bicubic`; для карт, планов и схем в PNG - с `Nearest`, если важен минимальный вес, или с `Box`, если нужен более спокойный вид. Расшифровка подсказок: - `Подогнать` не меняет качество JPG само по себе, а подбирает процент масштабирования под целевой вес файла. Для JPG итоговый вес зависит от масштаба, качества и сложности изображения; для PNG - от числа цветов, резких границ и выбранного алгоритма. - `Цель, MB` задаёт лимит на каждый отдельный файл. Если цель `1,0`, движок старается получить результат близко к 1 MB, но не обязан попадать в байт: нормальным считается диапазон примерно `0,8-1,0` от цели. - `Lanczos` красив на фотографиях и мягких сканах, но на картах может создавать полупрозрачные переходы вокруг резких линий. Для PNG это часто увеличивает файл. - `Bicubic` полезен, когда нужен более мягкий вид, чем `Box`/`Nearest`, но без максимальной “дороговизны” `Lanczos`. - `Box` особенно хорош для карт, схем, планов и скриншотов: он усредняет пиксели проще и часто даёт меньше ореолов. - `Nearest` полезен, когда важны исходные цвета и минимальный PNG, но он не сглаживает диагонали и мелкий текст. `Под рулон` и `DPI` не меняют пиксели. Они только записывают DPI так, чтобы физический размер соответствовал задаче печати или плоттера. ### Цвет `Нормализовать профиль` сохраняет исходный профиль или приводит результат к `sRGB`/`CMYK`. В этом же окне выбираются форматы вывода, качество и политика метаданных: `DPI + цвет`, `Сохранить всё`, `Удалить всё`. ### Фото-лист `Фото-лист` собирает печатные листы из подготовленной папки: - `Экономия бумаги` - плотная раскладка строками без зазоров. - `Быстрая резка` - группировка по похожей высоте и файл `cut_plan.txt`. Общие параметры модуля: ширина листа в мм, конечный DPI, рекурсивное чтение подпапок, фон, формат вывода и качество. В базовом режиме исходные пиксели не пересчитываются: ширина и DPI описывают итоговый лист. Если выбранный DPI слишком мал для исходных пикселей при заданной ширине листа, движок автоматически поднимает DPI листа и пишет предупреждение в отчёт/GUI. Основной лист по умолчанию сохраняется как PNG, preview остается JPG. ### Листы и метки Действия: - `Замостить лист` - размножает одно изображение на A5/A4/A3 или рулон заданной ширины. - `Разделить TIFF` - делит многостраничный TIFF на PNG-кадры. - `Водяной знак` - добавляет горизонтальную подпись в углу или диагональную защитную надпись. В `Замостить лист` доступны размеры `Как есть`, `По ширине`, `По высоте`, `Документ 40x30` и `Документ 60x40`. Для пресетов можно выбрать `Без обрезки` или `Обрезать в рамку`. Рамка, поля и зазор задаются в миллиметрах и пересчитываются по выбранному DPI. `Водяной знак` поддерживает два режима. `В углу` ставит обычный горизонтальный текст в выбранный угол с управляемым отступом и кеглем. `Диагональный защитный` центрирует текст по диагонали изображения и автоматически подбирает кегль так, чтобы надпись занимала заданную долю диагонали; значение `60%` подходит для защитной маркировки документов и оставляет воздух для коротких крупных слов вроде `КОПИЯ`. Шрифт простой и читаемый: Arial Bold, если он доступен в системе. Прозрачность регулируется отдельно: `0` - невидимо, `255` - полностью непрозрачно. Дефолт `64` - около 25% непрозрачности; он выбран под печать, где водяной знак обычно выглядит темнее, чем на экране. Расшифровка подсказок водяного знака: - `В углу` - режим для аккуратной технической маркировки: подпись, дата, автор, статус черновика. - `Диагональный защитный` - режим против недобросовестного использования: текст проходит через документ и заметен даже при кадрировании. - `Длина по диагонали, %` управляет не кеглем напрямую, а целевой длиной надписи относительно диагонали изображения. Чем короче текст, тем крупнее получится кегль при том же проценте. - `Кегль в углу` действует только для режима `В углу`. В диагональном режиме размер шрифта рассчитывается автоматически. - `Прозрачность` - это alpha-канал `0..255`: дефолт `64` даёт около 25% непрозрачности; для красного или чёрного диагонального текста обычно лучше начинать с `64-96`, для светлого текста на тёмном фоне - с `96-128`. - `Цвет` в GUI выбирается человеческими пресетами с плашками: `Красный`, `Чёрный`, `Белый`, `Жёлтый`, `Серый`, `Синий`. Для точного оттенка есть `Свой RGB` с каналами `R`, `G`, `B` от `0` до `255`. В CLI можно передать HTML-цвет или RGB вручную, например `#cc0000` или `204,0,0`. ### Контактный лист `Контактный лист` - отдельный ROOT-модуль для осмотровой сетки по папке изображений. Доступны число колонок, режим размера миниатюры `Из списка` или `Свой размер`, формат вывода и качество. По умолчанию результат пишется в PNG. Миниатюра показывает изображение целиком без обрезки. Подпись содержит имя файла, строку размера `px | cm | DPI` и вес файла в KB. Если DPI в файле отсутствует, сантиметры считаются по fallback `300dpi`, и это явно указано в подписи. ### Диагностика Диагностика не использует `ИСТОЧНИК` и `НАЗНАЧЕНИЕ`, потому что это не обработка изображений. Действия: - `Форматы` - показывает поддерживаемые форматы и адаптеры. - `Информация` - показывает пути проекта и runtime-информацию. - `Проверка окружения` - запускает `doctor.py`. ## Обслуживание Блок `Обслуживание` находится отдельно от рабочих команд. В нём доступны глобальные параметры многопоточности. Управление маршрутами и файлами вынесено в верхний Workbench I/O: `СБРОСИТЬ` сбрасывает маршруты и кэш без удаления файлов, а `УДАЛИТЬ` очищает содержимое текущих `ИСТОЧНИКА` и `НАЗНАЧЕНИЯ` после подтверждения. ### Многопоточность и RAM Многопоточность обрабатывает независимые изображения параллельно. Она помогает на пакетах файлов, но большие карты, TIFF/PDF-рендер и PNG-вывод могут занимать в памяти намного больше места, чем файл на диске. Каждый дополнительный worker может открыть ещё одно тяжёлое изображение, поэтому ускорение быстро превращается в своп или падение по памяти. Практический ориентир: - `16 GB RAM` - оставить многопоточность выключенной; при необходимости ставить `1-2` потока. - `32 GB RAM` - обычно `4` потока. - `64 GB RAM` - `8-12` потоков после проверки пика памяти. - `128 GB+ RAM` - можно пробовать `16+`, но только если контролируется расход памяти. Глобальный параметр из `Обслуживание` работает как дефолт для режимов без локального переопределения. Локальный переключатель внутри режима влияет только на текущий запуск и не меняет Workbench/I/O. ## Основные папки - `input\` - стандартные исходники. - `output\` - стандартные результаты. - `logs\` - журналы запусков. - `report\` - отчеты GUI. - `workspace\` - временная рабочая область. - `config\` - настройки, manifest, ICC-профили, темы. - `docs\` - документация. - `system_core\` - код GUI/CLI. - `runtime\`, `wheelhouse\`, `install\download\` - portable-окружение и сборочные артефакты. ## CLI-примеры Подгонка под рулон 900 мм по короткой стороне: ```bat runtime\python.exe system_core\main.py plotter-size --input input --output output\plotter_roll_fit --to png --side short --target-mm 900 ``` DPI без изменения пикселей: ```bat runtime\python.exe system_core\main.py plotter-dpi-only --input input --output output\plotter_dpi_only --to png --dpi 300 ``` Умный кроп белого: ```bat runtime\python.exe system_core\main.py smart-crop-white --input input --output output\smart_crop_white --to png --tolerance 10 --safety-margin-mm 0 ``` Картинки в PDF: ```bat runtime\python.exe system_core\main.py images-to-pdf --input input --output output\images.pdf --bundle folders --mode lossless ``` ## Перед релизом Запустить интерактивную чистку: ```bat cleanup_project.cmd ``` Скрипт спрашивает `Y/N/Q`. Ответ `Y` очищает рабочие результаты, runtime payload, wheelhouse, download-архивы, кэши и временные файлы. После чистки остаются исходные скрипты, папки, документация, лицензии и конфиги. ## Канонические названия Workbench Workbench использует единый публичный словарь Audion Image Tools во всех проектах. Кнопки всегда расположены и называются одинаково: **Источник**, **Добавить файл...**, **Назначение**, **Сбросить**, **Удалить**, **Список**. `Сбросить` возвращает проектные `input/output` и не удаляет файлы; `Удалить` очищает текущие `Источник` и `Назначение` только после подтверждения. В английском интерфейсе точные названия: **Source**, **Add file...**, **Target**, **Reset**, **Delete**, **List**. Варианты `Цель`, `Очистить`, `Destination` и `Clear` для этих элементов Workbench не используются.