mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
00b651c9f8
Shared Claude Code translation pipeline (scripts/i18n, no API key) plus Astro/VitePress/Scalar i18n wiring. Landing and API reference translated into all 20 languages; docs i18n wiring + English source anchors. The translated docs markdown (apps/docs/<locale>/**, 3,620 files) follows in a companion PR because it exceeds GitHub's per-PR CI file limit.
209 lines
8.1 KiB
Markdown
209 lines
8.1 KiB
Markdown
---
|
|
description: Image engine operations reference. All Sharp-based image processing operations and their parameters.
|
|
---
|
|
|
|
# Image engine {#image-engine}
|
|
|
|
The `@snapotter/image-engine` package handles all non-AI image operations. It wraps [Sharp](https://sharp.pixelplumbing.com/) and runs entirely in-process with no external dependencies.
|
|
|
|
## Operations {#operations}
|
|
|
|
### resize {#resize}
|
|
|
|
Scale an image to specific dimensions or by percentage.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `width` | number | Target width in pixels |
|
|
| `height` | number | Target height in pixels |
|
|
| `fit` | string | `cover`, `contain`, `fill`, `inside`, or `outside` |
|
|
| `withoutEnlargement` | boolean | If true, won't upscale smaller images |
|
|
| `percentage` | number | Scale by percentage instead of absolute dimensions |
|
|
|
|
You can set `width`, `height`, or both. If you only set one, the other is calculated to maintain the aspect ratio.
|
|
|
|
### crop {#crop}
|
|
|
|
Cut out a rectangular region from the image.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `left` | number | X offset from the left edge |
|
|
| `top` | number | Y offset from the top edge |
|
|
| `width` | number | Width of the crop area |
|
|
| `height` | number | Height of the crop area |
|
|
| `unit` | string | `px` (default) or `percent` |
|
|
|
|
### rotate {#rotate}
|
|
|
|
Rotate the image by a given angle.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `angle` | number | Rotation angle in degrees (0-360) |
|
|
| `background` | string | Fill color for exposed area (default: `#000000`). Only applies to non-90-degree angles. |
|
|
|
|
### flip {#flip}
|
|
|
|
Mirror the image horizontally, vertically, or both. At least one must be true.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `horizontal` | boolean | Mirror left to right |
|
|
| `vertical` | boolean | Mirror top to bottom |
|
|
|
|
### convert {#convert}
|
|
|
|
Change the image format.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `format` | string | Target format: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
|
|
| `quality` | number | Compression quality (1-100, applies to lossy formats) |
|
|
|
|
The first seven formats (`jpg` through `jxl`) are encoded by Sharp in-process. The remaining formats use external encoders at the API layer: `heic`/`heif` via heif-enc, `bmp`/`ico` via ImageMagick, `jp2` via opj_compress, and `qoi` via an inline TypeScript codec.
|
|
|
|
### compress {#compress}
|
|
|
|
Reduce file size while keeping the same format.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `quality` | number | Target quality (1-100) |
|
|
| `targetSizeBytes` | number | Optional target file size in bytes |
|
|
| `format` | string | Optional format override |
|
|
|
|
### strip-metadata {#strip-metadata}
|
|
|
|
Remove EXIF, IPTC, XMP, and ICC metadata from the image. With no parameters (or `stripAll: true`), strips everything. Pass individual flags for selective stripping.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `stripAll` | boolean | Strip all metadata (default when no flags are set) |
|
|
| `stripExif` | boolean | Strip EXIF data (including GPS if `stripGps` is not separately set) |
|
|
| `stripGps` | boolean | Strip GPS location data |
|
|
| `stripIcc` | boolean | Strip ICC color profile |
|
|
| `stripXmp` | boolean | Strip XMP metadata |
|
|
|
|
### Color adjustments {#color-adjustments}
|
|
|
|
These operations modify the color properties of an image. Each takes a single numeric value.
|
|
|
|
| Operation | Parameter | Range | Description |
|
|
|---|---|---|---|
|
|
| `brightness` | `value` | -100 to 100 | Adjust brightness |
|
|
| `contrast` | `value` | -100 to 100 | Adjust contrast |
|
|
| `saturation` | `value` | -100 to 100 | Adjust color saturation |
|
|
|
|
### Color filters {#color-filters}
|
|
|
|
These apply a fixed color transformation. They take no parameters.
|
|
|
|
| Operation | Description |
|
|
|---|---|
|
|
| `grayscale` | Convert to grayscale |
|
|
| `sepia` | Apply a sepia tone |
|
|
| `invert` | Invert all colors |
|
|
|
|
### Color channels {#color-channels}
|
|
|
|
Adjust individual RGB color channels. Values are multipliers where 100 = no change.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `red` | number | Red channel multiplier (0 to 200, 100 = unchanged) |
|
|
| `green` | number | Green channel multiplier (0 to 200, 100 = unchanged) |
|
|
| `blue` | number | Blue channel multiplier (0 to 200, 100 = unchanged) |
|
|
|
|
### sharpen {#sharpen}
|
|
|
|
Simple sharpening controlled by a single value.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `value` | number | Sharpening intensity (0 to 100). Mapped to a Gaussian sigma of 0.5-10. |
|
|
|
|
### sharpen-advanced {#sharpen-advanced}
|
|
|
|
Advanced sharpening with three selectable methods and an optional noise-reduction pre-pass.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `method` | string | `adaptive`, `unsharp-mask`, or `high-pass` |
|
|
| `sigma` | number | Gaussian blur radius, 0.5-10 (adaptive) |
|
|
| `m1` | number | Flat-area sharpening, 0-10 (adaptive) |
|
|
| `m2` | number | Textured-area sharpening, 0-20 (adaptive) |
|
|
| `x1` | number | Flat/jagged threshold, 0-10 (adaptive) |
|
|
| `y2` | number | Max brightening (halo clamp), 0-50 (adaptive) |
|
|
| `y3` | number | Max darkening (halo clamp), 0-50 (adaptive) |
|
|
| `amount` | number | Intensity percentage, 0-500 (unsharp-mask) |
|
|
| `radius` | number | Blur radius, 0.1-5.0 (unsharp-mask) |
|
|
| `threshold` | number | Minimum edge brightness, 0-255 (unsharp-mask) |
|
|
| `strength` | number | Blend strength, 0-100 (high-pass) |
|
|
| `kernelSize` | number | `3` or `5` for 3x3 / 5x5 kernel (high-pass) |
|
|
| `denoise` | string | Noise reduction pre-pass: `off`, `light`, `medium`, or `strong` |
|
|
|
|
Parameters are method-specific. Only supply the ones relevant to the chosen method.
|
|
|
|
### color-blindness {#color-blindness}
|
|
|
|
Simulate a color vision deficiency using a 3x3 color-recombination matrix.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `type` | string | One of: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
|
|
|
|
### edit-metadata {#edit-metadata}
|
|
|
|
Write or remove individual EXIF/IPTC metadata fields without stripping the entire block.
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `artist` | string | EXIF Artist tag |
|
|
| `copyright` | string | EXIF Copyright tag |
|
|
| `imageDescription` | string | EXIF ImageDescription tag |
|
|
| `software` | string | EXIF Software tag |
|
|
| `dateTime` | string | EXIF DateTime tag |
|
|
| `dateTimeOriginal` | string | EXIF DateTimeOriginal tag |
|
|
| `clearGps` | boolean | Remove all GPS tags |
|
|
| `fieldsToRemove` | string[] | List of EXIF field names to delete |
|
|
|
|
All parameters are optional. Fields listed in `fieldsToRemove` are deleted from the existing EXIF block. Fields set via the named parameters are written (or overwritten). Binary/unsafe keys like MakerNote are silently ignored.
|
|
|
|
## Format detection {#format-detection}
|
|
|
|
The engine detects input formats automatically from file headers, not just file extensions. This means a `.jpg` file that is actually a PNG will be handled correctly. Detection uses a multi-layer approach: magic bytes first, then file extension as fallback.
|
|
|
|
SnapOtter supports **55+ input formats** and **13 output formats**, including 23 camera RAW formats from 20+ brands, professional formats (PSD, EPS, OpenEXR, HDR), modern codecs (JPEG XL, AVIF, HEIC, QOI, JPEG 2000), and scientific/gaming formats (FITS, DDS). Decoding is handled by Sharp natively where possible, with automatic fallback to ImageMagick, LibRaw, and specialized CLI decoders.
|
|
|
|
See the [Supported Formats](/guide/supported-formats) page for the complete list.
|
|
|
|
## Metadata extraction {#metadata-extraction}
|
|
|
|
The `info` tool returns image metadata. See [Image Info](/tools/image/info) for the full field reference.
|
|
|
|
```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 }
|
|
]
|
|
}
|
|
```
|