Mecanismo de imagem

O pacote @snapotter/image-engine lida com todas as operações de imagem que não são de IA. Ele encapsula o Sharp e roda inteiramente no próprio processo, sem dependências externas.

Operações

resize

Escala uma imagem para dimensões específicas ou por porcentagem.

Parâmetro	Tipo	Descrição
width	number	Largura alvo em pixels
height	number	Altura alvo em pixels
fit	string	cover, contain, fill, inside ou outside
withoutEnlargement	boolean	Se verdadeiro, não fará upscale de imagens menores
percentage	number	Escala por porcentagem em vez de dimensões absolutas

Você pode definir width, height ou ambos. Se definir apenas um, o outro é calculado para manter a proporção.

crop

Recorta uma região retangular da imagem.

Parâmetro	Tipo	Descrição
left	number	Deslocamento X a partir da borda esquerda
top	number	Deslocamento Y a partir da borda superior
width	number	Largura da área de recorte
height	number	Altura da área de recorte
unit	string	px (padrão) ou percent

rotate

Gira a imagem por um ângulo determinado.

Parâmetro	Tipo	Descrição
angle	number	Ângulo de rotação em graus (0-360)
background	string	Cor de preenchimento para a área exposta (padrão: #000000). Aplica-se apenas a ângulos que não sejam de 90 graus.

flip

Espelha a imagem horizontalmente, verticalmente ou ambos. Pelo menos um deve ser verdadeiro.

Parâmetro	Tipo	Descrição
horizontal	boolean	Espelhar da esquerda para a direita
vertical	boolean	Espelhar de cima para baixo

convert

Altera o formato da imagem.

Parâmetro	Tipo	Descrição
format	string	Formato alvo: jpg, png, webp, avif, tiff, gif, jxl, heic, heif, bmp, ico, jp2, qoi
quality	number	Qualidade de compressão (1-100, aplica-se a formatos com perdas)

Os sete primeiros formatos (de jpg a jxl) são codificados pelo Sharp no próprio processo. Os formatos restantes usam codificadores externos na camada da API: heic/heif via heif-enc, bmp/ico via ImageMagick, jp2 via opj_compress e qoi via um codec TypeScript inline.

compress

Reduz o tamanho do arquivo mantendo o mesmo formato.

Parâmetro	Tipo	Descrição
quality	number	Qualidade alvo (1-100)
targetSizeBytes	number	Tamanho de arquivo alvo opcional em bytes
format	string	Substituição de formato opcional

strip-metadata

Remove metadados EXIF, IPTC, XMP e ICC da imagem. Sem parâmetros (ou com stripAll: true), remove tudo. Passe flags individuais para remoção seletiva.

Parâmetro	Tipo	Descrição
stripAll	boolean	Remove todos os metadados (padrão quando nenhuma flag está definida)
stripExif	boolean	Remove os dados EXIF (incluindo GPS se stripGps não estiver definido separadamente)
stripGps	boolean	Remove os dados de localização GPS
stripIcc	boolean	Remove o perfil de cor ICC
stripXmp	boolean	Remove os metadados XMP

Ajustes de cor

Essas operações modificam as propriedades de cor de uma imagem. Cada uma recebe um único valor numérico.

Operação	Parâmetro	Intervalo	Descrição
brightness	value	-100 a 100	Ajustar brilho
contrast	value	-100 a 100	Ajustar contraste
saturation	value	-100 a 100	Ajustar saturação de cor

Filtros de cor

Estes aplicam uma transformação de cor fixa. Não recebem parâmetros.

Operação	Descrição
grayscale	Converter para escala de cinza
sepia	Aplicar um tom sépia
invert	Inverter todas as cores

Canais de cor

Ajusta canais de cor RGB individuais. Os valores são multiplicadores em que 100 = nenhuma alteração.

Parâmetro	Tipo	Descrição
red	number	Multiplicador do canal vermelho (0 a 200, 100 = inalterado)
green	number	Multiplicador do canal verde (0 a 200, 100 = inalterado)
blue	number	Multiplicador do canal azul (0 a 200, 100 = inalterado)

sharpen

Afiação simples controlada por um único valor.

Parâmetro	Tipo	Descrição
value	number	Intensidade da afiação (0 a 100). Mapeada para um sigma gaussiano de 0.5-10.

sharpen-advanced

Afiação avançada com três métodos selecionáveis e um pré-passe opcional de redução de ruído.

Parâmetro	Tipo	Descrição
method	string	adaptive, unsharp-mask ou high-pass
sigma	number	Raio do desfoque gaussiano, 0.5-10 (adaptativo)
m1	number	Afiação de área plana, 0-10 (adaptativo)
m2	number	Afiação de área texturizada, 0-20 (adaptativo)
x1	number	Limiar plano/irregular, 0-10 (adaptativo)
y2	number	Clareamento máximo (limite de halo), 0-50 (adaptativo)
y3	number	Escurecimento máximo (limite de halo), 0-50 (adaptativo)
amount	number	Porcentagem de intensidade, 0-500 (unsharp-mask)
radius	number	Raio de desfoque, 0.1-5.0 (unsharp-mask)
threshold	number	Brilho mínimo de borda, 0-255 (unsharp-mask)
strength	number	Força de mesclagem, 0-100 (high-pass)
kernelSize	number	3 ou 5 para kernel 3x3 / 5x5 (high-pass)
denoise	string	Pré-passe de redução de ruído: off, light, medium ou strong

Os parâmetros são específicos de cada método. Forneça apenas os relevantes para o método escolhido.

color-blindness

Simula uma deficiência de visão de cores usando uma matriz 3x3 de recombinação de cores.

Parâmetro	Tipo	Descrição
type	string	Um de: protanopia, deuteranopia, tritanopia, protanomaly, deuteranomaly, tritanomaly, achromatopsia, blueConeMonochromacy

edit-metadata

Escreve ou remove campos individuais de metadados EXIF/IPTC sem remover o bloco inteiro.

Parâmetro	Tipo	Descrição
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	Remove todas as tags GPS
fieldsToRemove	string[]	Lista de nomes de campos EXIF a excluir

Todos os parâmetros são opcionais. Os campos listados em fieldsToRemove são excluídos do bloco EXIF existente. Os campos definidos pelos parâmetros nomeados são escritos (ou sobrescritos). Chaves binárias/inseguras como MakerNote são silenciosamente ignoradas.

Detecção de formato

O mecanismo detecta os formatos de entrada automaticamente a partir dos cabeçalhos dos arquivos, não apenas das extensões. Isso significa que um arquivo .jpg que na verdade é um PNG será tratado corretamente. A detecção usa uma abordagem em várias camadas: primeiro os magic bytes, depois a extensão do arquivo como fallback.

O SnapOtter suporta mais de 55 formatos de entrada e 13 formatos de saída, incluindo 23 formatos RAW de câmera de mais de 20 marcas, formatos profissionais (PSD, EPS, OpenEXR, HDR), codecs modernos (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) e formatos científicos/de jogos (FITS, DDS). A decodificação é feita nativamente pelo Sharp sempre que possível, com fallback automático para ImageMagick, LibRaw e decodificadores CLI especializados.

Consulte a página Formatos Suportados para a lista completa.

Extração de metadados

A ferramenta info retorna os metadados da imagem. Consulte Informações da Imagem para a referência completa de campos.

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