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

description

description
Image engine operations reference. All Sharp-based image processing operations and their parameters.

Image engine

The @snapotter/image-engine package handles all non-AI image operations. It wraps Sharp and runs entirely in-process with no external dependencies.

Operations

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

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 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

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

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

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

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

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

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

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

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

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

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

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

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 page for the complete list.

Metadata extraction

The info tool returns image metadata. See Image Info for the full field reference.

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