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

description, i18n_source_hash, i18n_provenance, i18n_output_hash

description	i18n_source_hash	i18n_provenance	i18n_output_hash
Referensi operasi mesin gambar. Semua operasi pemrosesan gambar berbasis Sharp dan parameternya.	42febdf85fa8	human	6e4ab098a101

Mesin gambar

Paket @snapotter/image-engine menangani semua operasi gambar non-AI. Ini membungkus Sharp dan berjalan sepenuhnya in-process tanpa dependensi eksternal.

Operasi

resize

Skalakan gambar ke dimensi tertentu atau berdasarkan persentase.

Parameter	Tipe	Deskripsi
width	number	Lebar target dalam piksel
height	number	Tinggi target dalam piksel
fit	string	cover, contain, fill, inside, atau outside
withoutEnlargement	boolean	Jika true, tidak akan memperbesar gambar yang lebih kecil
percentage	number	Skalakan berdasarkan persentase alih-alih dimensi absolut

Anda dapat mengatur width, height, atau keduanya. Jika hanya mengatur salah satu, yang lain dihitung untuk mempertahankan rasio aspek.

crop

Potong area persegi panjang dari gambar.

Parameter	Tipe	Deskripsi
left	number	Offset X dari tepi kiri
top	number	Offset Y dari tepi atas
width	number	Lebar area crop
height	number	Tinggi area crop
unit	string	px (default) atau percent

rotate

Putar gambar dengan sudut tertentu.

Parameter	Tipe	Deskripsi
angle	number	Sudut rotasi dalam derajat (0-360)
background	string	Warna isian untuk area yang terekspos (default: #000000). Hanya berlaku untuk sudut non-90-derajat.

flip

Cerminkan gambar secara horizontal, vertikal, atau keduanya. Setidaknya satu harus true.

Parameter	Tipe	Deskripsi
horizontal	boolean	Cerminkan kiri ke kanan
vertical	boolean	Cerminkan atas ke bawah

convert

Ubah format gambar.

Parameter	Tipe	Deskripsi
format	string	Format target: jpg, png, webp, avif, tiff, gif, jxl, heic, heif, bmp, ico, jp2, qoi
quality	number	Kualitas kompresi (1-100, berlaku untuk format lossy)

Tujuh format pertama (jpg hingga jxl) dikodekan oleh Sharp in-process. Format sisanya menggunakan encoder eksternal di lapisan API: heic/heif via heif-enc, bmp/ico via ImageMagick, jp2 via opj_compress, dan qoi via codec TypeScript inline.

compress

Kurangi ukuran berkas sambil mempertahankan format yang sama.

Parameter	Tipe	Deskripsi
quality	number	Kualitas target (1-100)
targetSizeBytes	number	Ukuran berkas target opsional dalam byte
format	string	Override format opsional

strip-metadata

Hapus metadata EXIF, IPTC, XMP, dan ICC dari gambar. Tanpa parameter (atau stripAll: true), menghapus semuanya. Berikan flag individual untuk penghapusan selektif.

Parameter	Tipe	Deskripsi
stripAll	boolean	Hapus semua metadata (default ketika tidak ada flag yang diatur)
stripExif	boolean	Hapus data EXIF (termasuk GPS jika stripGps tidak diatur secara terpisah)
stripGps	boolean	Hapus data lokasi GPS
stripIcc	boolean	Hapus profil warna ICC
stripXmp	boolean	Hapus metadata XMP

Penyesuaian warna

Operasi ini mengubah properti warna gambar. Masing-masing menerima satu nilai numerik.

Operasi	Parameter	Rentang	Deskripsi
brightness	value	-100 hingga 100	Sesuaikan kecerahan
contrast	value	-100 hingga 100	Sesuaikan kontras
saturation	value	-100 hingga 100	Sesuaikan saturasi warna

Filter warna

Ini menerapkan transformasi warna tetap. Tidak menerima parameter.

Operasi	Deskripsi
grayscale	Konversi ke grayscale
sepia	Terapkan nada sepia
invert	Balik semua warna

Kanal warna

Sesuaikan kanal warna RGB individual. Nilai adalah pengali di mana 100 = tanpa perubahan.

Parameter	Tipe	Deskripsi
red	number	Pengali kanal merah (0 hingga 200, 100 = tidak berubah)
green	number	Pengali kanal hijau (0 hingga 200, 100 = tidak berubah)
blue	number	Pengali kanal biru (0 hingga 200, 100 = tidak berubah)

sharpen

Penajaman sederhana yang dikendalikan oleh satu nilai.

Parameter	Tipe	Deskripsi
value	number	Intensitas penajaman (0 hingga 100). Dipetakan ke sigma Gaussian 0.5-10.

sharpen-advanced

Penajaman lanjutan dengan tiga metode yang dapat dipilih dan pra-tahap pengurangan noise opsional.

Parameter	Tipe	Deskripsi
method	string	adaptive, unsharp-mask, atau high-pass
sigma	number	Radius Gaussian blur, 0.5-10 (adaptif)
m1	number	Penajaman area datar, 0-10 (adaptif)
m2	number	Penajaman area bertekstur, 0-20 (adaptif)
x1	number	Ambang batas datar/bergerigi, 0-10 (adaptif)
y2	number	Pencerahan maks (halo clamp), 0-50 (adaptif)
y3	number	Penggelapan maks (halo clamp), 0-50 (adaptif)
amount	number	Persentase intensitas, 0-500 (unsharp-mask)
radius	number	Radius blur, 0.1-5.0 (unsharp-mask)
threshold	number	Kecerahan tepi minimum, 0-255 (unsharp-mask)
strength	number	Kekuatan blend, 0-100 (high-pass)
kernelSize	number	3 atau 5 untuk kernel 3x3 / 5x5 (high-pass)
denoise	string	Pra-tahap pengurangan noise: off, light, medium, atau strong

Parameter bersifat spesifik per metode. Sediakan hanya yang relevan dengan metode yang dipilih.

color-blindness

Simulasikan defisiensi penglihatan warna menggunakan matriks rekombinasi warna 3x3.

Parameter	Tipe	Deskripsi
type	string	Salah satu dari: protanopia, deuteranopia, tritanopia, protanomaly, deuteranomaly, tritanomaly, achromatopsia, blueConeMonochromacy

edit-metadata

Tulis atau hapus field metadata EXIF/IPTC individual tanpa menghapus seluruh blok.

Parameter	Tipe	Deskripsi
artist	string	Tag EXIF Artist
copyright	string	Tag EXIF Copyright
imageDescription	string	Tag EXIF ImageDescription
software	string	Tag EXIF Software
dateTime	string	Tag EXIF DateTime
dateTimeOriginal	string	Tag EXIF DateTimeOriginal
clearGps	boolean	Hapus semua tag GPS
fieldsToRemove	string[]	Daftar nama field EXIF untuk dihapus

Semua parameter opsional. Field yang tercantum dalam fieldsToRemove dihapus dari blok EXIF yang ada. Field yang diatur melalui parameter bernama ditulis (atau ditimpa). Kunci biner/tidak aman seperti MakerNote diabaikan secara diam-diam.

Deteksi format

Mesin mendeteksi format input secara otomatis dari header berkas, bukan hanya ekstensi berkas. Ini berarti berkas .jpg yang sebenarnya adalah PNG akan ditangani dengan benar. Deteksi menggunakan pendekatan multi-lapis: magic bytes terlebih dahulu, lalu ekstensi berkas sebagai fallback.

SnapOtter mendukung 55+ format input dan 13 format keluaran, termasuk 23 format RAW kamera dari 20+ merek, format profesional (PSD, EPS, OpenEXR, HDR), codec modern (JPEG XL, AVIF, HEIC, QOI, JPEG 2000), dan format ilmiah/gaming (FITS, DDS). Decoding ditangani oleh Sharp secara native bila memungkinkan, dengan fallback otomatis ke ImageMagick, LibRaw, dan decoder CLI khusus.

Lihat halaman Format yang Didukung untuk daftar lengkap.

Ekstraksi metadata

Alat info mengembalikan metadata gambar. Lihat Info Gambar untuk referensi field lengkap.

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