SnapOtter/apps/docs/ru/api/image-engine.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash

description	i18n_source_hash	i18n_provenance	i18n_output_hash
Справочник по операциям движка изображений. Все операции обработки изображений на базе Sharp и их параметры.	42febdf85fa8	human	b6b18f196fbd

Движок изображений

Пакет @snapotter/image-engine обрабатывает все не-AI операции с изображениями. Он оборачивает Sharp и работает полностью внутри процесса без внешних зависимостей.

Операции

resize

Масштабирование изображения до конкретных размеров или в процентах.

Параметр	Тип	Описание
width	number	Целевая ширина в пикселях
height	number	Целевая высота в пикселях
fit	string	cover, contain, fill, inside или outside
withoutEnlargement	boolean	Если true, не увеличивает меньшие изображения
percentage	number	Масштабировать в процентах вместо абсолютных размеров

Можно задать width, height или оба. Если задать только один, другой вычисляется для сохранения соотношения сторон.

crop

Вырезание прямоугольной области из изображения.

Параметр	Тип	Описание
left	number	Смещение X от левого края
top	number	Смещение Y от верхнего края
width	number	Ширина области обрезки
height	number	Высота области обрезки
unit	string	px (по умолчанию) или percent

rotate

Поворот изображения на заданный угол.

Параметр	Тип	Описание
angle	number	Угол поворота в градусах (0-360)
background	string	Цвет заливки открывшейся области (по умолчанию: #000000). Применяется только к углам, не кратным 90 градусам.

flip

Отражение изображения по горизонтали, вертикали или обоим осям. Хотя бы одно значение должно быть true.

Параметр	Тип	Описание
horizontal	boolean	Отразить слева направо
vertical	boolean	Отразить сверху вниз

convert

Изменение формата изображения.

Параметр	Тип	Описание
format	string	Целевой формат: jpg, png, webp, avif, tiff, gif, jxl, heic, heif, bmp, ico, jp2, qoi
quality	number	Качество сжатия (1-100, применяется к форматам с потерями)

Первые семь форматов (от jpg до jxl) кодируются Sharp внутри процесса. Остальные форматы используют внешние кодеры на уровне API: heic/heif через heif-enc, bmp/ico через ImageMagick, jp2 через opj_compress и qoi через встроенный TypeScript-кодек.

compress

Уменьшение размера файла с сохранением того же формата.

Параметр	Тип	Описание
quality	number	Целевое качество (1-100)
targetSizeBytes	number	Опциональный целевой размер файла в байтах
format	string	Опциональное переопределение формата

strip-metadata

Удаление метаданных EXIF, IPTC, XMP и ICC из изображения. Без параметров (или с stripAll: true) удаляет всё. Передайте отдельные флаги для выборочного удаления.

Параметр	Тип	Описание
stripAll	boolean	Удалить все метаданные (по умолчанию, если флаги не заданы)
stripExif	boolean	Удалить данные EXIF (включая GPS, если stripGps не задан отдельно)
stripGps	boolean	Удалить данные о GPS-местоположении
stripIcc	boolean	Удалить цветовой профиль ICC
stripXmp	boolean	Удалить метаданные XMP

Настройки цвета

Эти операции изменяют цветовые свойства изображения. Каждая принимает одно числовое значение.

Операция	Параметр	Диапазон	Описание
brightness	value	-100 до 100	Настройка яркости
contrast	value	-100 до 100	Настройка контрастности
saturation	value	-100 до 100	Настройка насыщенности цвета

Цветовые фильтры

Применяют фиксированное цветовое преобразование. Не принимают параметров.

Операция	Описание
grayscale	Преобразовать в оттенки серого
sepia	Применить тон сепии
invert	Инвертировать все цвета

Цветовые каналы

Настройка отдельных цветовых каналов RGB. Значения являются множителями, где 100 = без изменений.

Параметр	Тип	Описание
red	number	Множитель красного канала (0 до 200, 100 = без изменений)
green	number	Множитель зелёного канала (0 до 200, 100 = без изменений)
blue	number	Множитель синего канала (0 до 200, 100 = без изменений)

sharpen

Простое повышение резкости, управляемое одним значением.

Параметр	Тип	Описание
value	number	Интенсивность резкости (0 до 100). Сопоставляется с гауссовой сигмой 0.5-10.

sharpen-advanced

Продвинутое повышение резкости с тремя выбираемыми методами и опциональным предварительным проходом шумоподавления.

Параметр	Тип	Описание
method	string	adaptive, unsharp-mask или high-pass
sigma	number	Радиус гауссова размытия, 0.5-10 (адаптивный)
m1	number	Резкость плоских областей, 0-10 (адаптивный)
m2	number	Резкость текстурированных областей, 0-20 (адаптивный)
x1	number	Порог плоское/зубчатое, 0-10 (адаптивный)
y2	number	Максимальное осветление (ограничение ореола), 0-50 (адаптивный)
y3	number	Максимальное затемнение (ограничение ореола), 0-50 (адаптивный)
amount	number	Процент интенсивности, 0-500 (нерезкая маска)
radius	number	Радиус размытия, 0.1-5.0 (нерезкая маска)
threshold	number	Минимальная яркость края, 0-255 (нерезкая маска)
strength	number	Сила смешивания, 0-100 (высокочастотный)
kernelSize	number	3 или 5 для ядра 3x3 / 5x5 (высокочастотный)
denoise	string	Предварительный проход шумоподавления: off, light, medium или strong

Параметры специфичны для метода. Указывайте только те, что относятся к выбранному методу.

color-blindness

Симуляция дефицита цветового зрения с помощью матрицы цветовой рекомбинации 3x3.

Параметр	Тип	Описание
type	string	Одно из: protanopia, deuteranopia, tritanopia, protanomaly, deuteranomaly, tritanomaly, achromatopsia, blueConeMonochromacy

edit-metadata

Запись или удаление отдельных полей метаданных EXIF/IPTC без удаления всего блока.

Параметр	Тип	Описание
artist	string	Тег EXIF Artist
copyright	string	Тег EXIF Copyright
imageDescription	string	Тег EXIF ImageDescription
software	string	Тег EXIF Software
dateTime	string	Тег EXIF DateTime
dateTimeOriginal	string	Тег EXIF DateTimeOriginal
clearGps	boolean	Удалить все теги GPS
fieldsToRemove	string[]	Список имён полей EXIF для удаления

Все параметры опциональны. Поля, перечисленные в fieldsToRemove, удаляются из существующего блока EXIF. Поля, заданные через именованные параметры, записываются (или перезаписываются). Двоичные/небезопасные ключи, такие как MakerNote, молча игнорируются.

Определение формата

Движок определяет входные форматы автоматически по заголовкам файлов, а не только по расширениям. Это значит, что файл .jpg, который на самом деле является PNG, будет обработан корректно. Определение использует многослойный подход: сначала магические байты, затем расширение файла как запасной вариант.

SnapOtter поддерживает 55+ входных форматов и 13 выходных форматов, включая 23 формата RAW камер от 20+ брендов, профессиональные форматы (PSD, EPS, OpenEXR, HDR), современные кодеки (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) и научные/игровые форматы (FITS, DDS). Декодирование выполняется нативно через Sharp там, где это возможно, с автоматическим откатом на ImageMagick, LibRaw и специализированные CLI-декодеры.

См. страницу Поддерживаемые форматы для полного списка.

Извлечение метаданных

Инструмент info возвращает метаданные изображения. См. Информация об изображении для полного справочника полей.

{
  "filename": "photo.jpg",
  "fileSize": 2450000,
  "width": 4032,
  "height": 3024,
  "format": "jpeg",
  "channels": 3,
  "hasAlpha": false,
  "colorSpace": "srgb",
  "density": 72,
  "isProgressive": false,
  "hasExif": true,
  "hasIcc": true,
  "hasXmp": false,
  "bitDepth": "8",
  "pages": 1,
  "histogram": [
    { "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
    { "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
    { "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
  ]
}