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

---
description: "Довідник операцій рушія зображень. Усі операції обробки зображень на основі Sharp та їхні параметри."
i18n_source_hash: 42febdf85fa8
i18n_provenance: human
i18n_output_hash: 9aa73cb2e6da
---

# Рушій зображень {#image-engine}

Пакет `@snapotter/image-engine` обробляє всі операції із зображеннями, що не належать до AI. Він обгортає [Sharp](https://sharp.pixelplumbing.com/) і виконується повністю в межах процесу без зовнішніх залежностей.

## Операції {#operations}

### resize {#resize}

Масштабувати зображення до конкретних розмірів або за відсотком.

| Параметр | Тип | Опис |
|---|---|---|
| `width` | number | Цільова ширина в пікселях |
| `height` | number | Цільова висота в пікселях |
| `fit` | string | `cover`, `contain`, `fill`, `inside` або `outside` |
| `withoutEnlargement` | boolean | Якщо true, не збільшуватиме менші зображення |
| `percentage` | number | Масштабувати за відсотком замість абсолютних розмірів |

Можна задати `width`, `height` або обидва. Якщо задати лише один, інший обчислюється для збереження співвідношення сторін.

### crop {#crop}

Вирізати прямокутну область із зображення.

| Параметр | Тип | Опис |
|---|---|---|
| `left` | number | Зсув X від лівого краю |
| `top` | number | Зсув Y від верхнього краю |
| `width` | number | Ширина області обрізання |
| `height` | number | Висота області обрізання |
| `unit` | string | `px` (за замовчуванням) або `percent` |

### rotate {#rotate}

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

| Параметр | Тип | Опис |
|---|---|---|
| `angle` | number | Кут повороту в градусах (0-360) |
| `background` | string | Колір заливки відкритої області (за замовчуванням: `#000000`). Застосовується лише до кутів, відмінних від 90 градусів. |

### flip {#flip}

Віддзеркалити зображення горизонтально, вертикально або обидва способи. Принаймні один має бути true.

| Параметр | Тип | Опис |
|---|---|---|
| `horizontal` | boolean | Віддзеркалити зліва направо |
| `vertical` | boolean | Віддзеркалити зверху вниз |

### convert {#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 {#compress}

Зменшити розмір файлу, зберігаючи той самий формат.

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

### strip-metadata {#strip-metadata}

Видалити метадані EXIF, IPTC, XMP та ICC із зображення. Без параметрів (або з `stripAll: true`) видаляє все. Передайте окремі прапорці для вибіркового видалення.

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

### Корекції кольору {#color-adjustments}

Ці операції змінюють властивості кольору зображення. Кожна приймає одне числове значення.

| Операція | Параметр | Діапазон | Опис |
|---|---|---|---|
| `brightness` | `value` | -100 до 100 | Налаштувати яскравість |
| `contrast` | `value` | -100 до 100 | Налаштувати контраст |
| `saturation` | `value` | -100 до 100 | Налаштувати насиченість кольору |

### Колірні фільтри {#color-filters}

Ці застосовують фіксоване перетворення кольору. Вони не приймають параметрів.

| Операція | Опис |
|---|---|
| `grayscale` | Перетворити на відтінки сірого |
| `sepia` | Застосувати тон сепії |
| `invert` | Інвертувати всі кольори |

### Колірні канали {#color-channels}

Налаштувати окремі колірні канали RGB. Значення є множниками, де 100 = без змін.

| Параметр | Тип | Опис |
|---|---|---|
| `red` | number | Множник червоного каналу (0 до 200, 100 = без змін) |
| `green` | number | Множник зеленого каналу (0 до 200, 100 = без змін) |
| `blue` | number | Множник синього каналу (0 до 200, 100 = без змін) |

### sharpen {#sharpen}

Просте підвищення різкості, кероване одним значенням.

| Параметр | Тип | Опис |
|---|---|---|
| `value` | number | Інтенсивність підвищення різкості (0 до 100). Зіставляється з сигмою Гауса 0.5-10. |

### sharpen-advanced {#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 {#color-blindness}

Симулювати порушення колірного зору за допомогою матриці рекомбінації кольорів 3x3.

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

### edit-metadata {#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 мовчки ігноруються.

## Визначення формату {#format-detection}

Рушій визначає вхідні формати автоматично за заголовками файлів, а не лише за розширеннями. Це означає, що файл `.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-декодерів.

Повний перелік дивіться на сторінці [Підтримувані формати](/uk/guide/supported-formats).

## Витягання метаданих {#metadata-extraction}

Інструмент `info` повертає метадані зображення. Повний довідник полів дивіться в [Image Info](/uk/tools/image/info).

```json
{
  "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 }
  ]
}
```