Resize, convert & effects

The raster helpers on painter.image now share the same image-source boundary used by canvas/image rendering. Supported sources are Buffer bytes, http(s): URLs, data:image/...;base64,... values, and filesystem paths. Image metadata is preflighted before decode against the configured source-byte, decoded-dimension, decoded-pixel, frame/page, and SVG-complexity limits. Remote inputs continue through the shared network policy rather than a helper-specific HTTP client.

This means resize, conversion, effects, color filtering, color analysis, masking, crop, and the other raster helpers no longer maintain separate ad-hoc filesystem/HTTP/canvas loaders.

#resize(resizeOptions)

ResizeOptions:

EXIF orientation is applied before fitting, so portrait/landscape sizing uses the effective displayed dimensions rather than unrotated metadata.

1import { ApexPainter } from 'apexify.js';2import fs from 'node:fs';3 4const painter = new ApexPainter();5 6const contained = await painter.image.resize({7  imagePath: './uploads/poster.png',8  size: { width: 1280, height: 720 },9  maintainAspectRatio: true,10  outputFormat: 'jpeg',11  quality: 88,12});13 14const exact = await painter.image.resize({15  imagePath: fs.readFileSync('./raw.webp'),16  size: { width: 512, height: 512 },17  maintainAspectRatio: false,18  outputFormat: 'png',19});20 21const fromUrl = await painter.image.resize({22  imagePath: 'https://cdn.example.com/assets/banner.jpg',23  size: { width: 1200, height: 630 },24  maintainAspectRatio: true,25});26 27const dataUrl = `data:image/png;base64,${fs.readFileSync('./icon.png').toString('base64')}`;28const fromDataUrl = await painter.image.resize({29  imagePath: dataUrl,30  size: { width: 64, height: 64 },31});

Invalid, fractional, zero, over-limit, or otherwise unsafe target dimensions reject before the expensive resize work begins.

#imgConverter(source, newExtension)

source is string | Buffer and uses the same metadata/decode preflight as resize.

Accepted extension names are jpeg, jpg, png, webp, tiff, gif, avif, heif, raw, jp2, and jxl. jpg is normalized to jpeg. Actual codec availability can still depend on the Sharp/libvips build used by the platform.

1const webpBuf = await painter.image.imgConverter('./exports/frame.png', 'webp');2const jpegFromBytes = await painter.image.imgConverter(fs.readFileSync('./frame.png'), 'jpg');3const pngFromRemote = await painter.image.imgConverter('https://cdn.example.com/x.jpg', 'png');

#effects(source, filters)

effects resolves and caches the decoded source through the shared image pipeline, then applies the requested filter stack.

Legacy effect names remain supported for compatibility:

• flip, rotate, brightness, contrast, invert, greyscale, sepia, blur, posterize, pixelate

The typed raster-filter pipeline is also supported:

• grayscale, gaussianBlur, motionBlur, radialBlur, sharpen, noise, grain, edgeDetection, emboss, saturation, hueShift

Noise/grain operations are deterministic for reproducible renders, and the legacy blur path delegates to the shared native filter implementation instead of running a quadratic JavaScript blur loop.

1const painter = new ApexPainter();2 3const toned = await painter.image.effects('./raw.jpg', [4  { type: 'blur', radius: 1.2 },5  { type: 'brightness', value: 0.12 },6  { type: 'contrast', value: 8 },7]);8 9const detailed = await painter.image.effects('./hero.png', [10  { type: 'sharpen', intensity: 0.35 },11  { type: 'grain', intensity: 0.05 },12]);

Explicit zero values are preserved; for example, zero intensity is a no-op instead of being replaced with a default intensity.

#colorsFilter(source, filterColor, opacity?)

Tint / wash using a CSS color string or GradientConfig. opacity is 0–1, and explicit 0 remains fully transparent.

1const tinted = await painter.image.colorsFilter('./bw.png', '#6366f1', 0.35);2 3const vignetteTint = await painter.image.colorsFilter('./scene.jpg', {4  type: 'radial',5  startX: 400,6  startY: 300,7  endX: 400,8  endY: 300,9  startRadius: 0,10  endRadius: 420,11  colors: [12    { stop: 0, color: 'rgba(0,0,0,0)' },13    { stop: 1, color: 'rgba(15,23,42,0.65)' },14  ],15});

Gradient stops must be finite, monotonic, and in 0–1. Linear/radial gradients support repeat: 'repeat' | 'reflect' | 'no-repeat'; reflect mirrors each adjacent period rather than merely repeating it.

#colorAnalysis(source)

Returns a bounded dominant-color list in the historical { color, frequency }[] shape.

For large images the implementation metadata-preflights first, downsamples to at most 160×160, quantizes nearby RGB values, and returns at most 16 dominant colors. Transparent pixels are not emitted as colors; frequency keeps the compatibility denominator based on all sampled pixels.

1const paletteHints = await painter.image.colorAnalysis('./brand-asset.png');2console.log(paletteHints.slice(0, 8));

#colorsRemover(source, colorToRemove)

Removes one exact RGB color. Each channel is 0–255.

1const keyFilled = await painter.image.colorsRemover('./sprite.png', {2  red: 255,3  green: 0,4  blue: 255,5});

#removeBackground(imageURL, apiKey)

Calls the remove.bg service through Apexify.js's bounded remote transport. The API key and remote service quotas remain external concerns.

1const cutout = await painter.image.removeBackground(2  'https://cdn.example.com/uploads/portrait.jpg',3  process.env.REMOVAL_API_KEY!4);

#validHex(hexColor)

Validates #RRGGBB and throws for invalid input.

1painter.image.validHex('#0ea5e9');