SnapOtter/apps/docs/uk/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	9aa73cb2e6da

Рушій зображень

Пакет @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 (unsharp-mask)
radius	number	Радіус розмиття, 0.1-5.0 (unsharp-mask)
threshold	number	Мінімальна яскравість краю, 0-255 (unsharp-mask)
strength	number	Сила змішування, 0-100 (high-pass)
kernelSize	number	3 або 5 для ядра 3x3 / 5x5 (high-pass)
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 повертає метадані зображення. Повний довідник полів дивіться в Image 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 }
  ]
}