Blend, mask, crop & gradient

These painter.image helpers share the same bounded image-source/decode pipeline used by canvas rendering. Local files, bytes, data URLs, and remote images are resolved through one policy; metadata limits and SVG restrictions are applied before expensive raster work.

1import { ApexPainter } from 'apexify.js';2 3const painter = new ApexPainter();

#blend(layers, baseImageBuffer, defaultBlendMode?)

Stacks ImageBlendLayer entries over a baseImageBuffer. Layer order is deterministic: array index 0 is composited first, later entries are painted above it. Optional layer opacity preserves explicit 0.

1import fs from 'node:fs';2 3const base = fs.readFileSync('./base-photo.jpg');4const blended = await painter.image.blend([5  {6    image: './overlay-flare.png',7    blendMode: 'screen',8    position: { x: 0, y: 0 },9    opacity: 0.75,10  },11  {12    image: './grain.png',13    blendMode: 'overlay',14    opacity: 0.25,15  },16], base, 'source-over');

#cropImage(options)

cropImage uses the shared source validator/cache and then applies either an axis-aligned inner crop or an outer punch-out path.

##Coordinate rules

• At least 3 coordinate rows are required.
• Every from.x, from.y, to.x, and to.y must be finite and non-negative.
• 0 is valid for both axes.
• Coordinates that exceed the decoded source width/height reject instead of relying on backend clipping.
• A degenerate inner crop with zero width or height rejects.

##crop: 'inner'

Every from/to point contributes to the minimum/maximum X/Y values. Those extrema form the rectangular output region. Optional numeric radius rounds the crop rectangle; radius: 'circular' clips it to the largest centered circle that fits.

##crop: 'outer'

The source dimensions are preserved. The coordinate path is filled using destination-out, producing a transparent hole while leaving pixels outside the path untouched. tension influences the Bézier control points.

1const innerCrop = await painter.image.cropImage({2  imageSource: './poster.jpg',3  crop: 'inner',4  radius: 16,5  coordinates: [6    { from: { x: 0, y: 0 }, to: { x: 520, y: 0 } },7    { from: { x: 520, y: 0 }, to: { x: 520, y: 380 } },8    { from: { x: 520, y: 380 }, to: { x: 0, y: 380 } },9    { from: { x: 0, y: 380 }, to: { x: 0, y: 0 } },10  ],11});12 13const outerCrop = await painter.image.cropImage({14  imageSource: './texture.png',15  crop: 'outer',16  coordinates: [17    { from: { x: 0, y: 0 }, to: { x: 400, y: 0 }, tension: 0 },18    { from: { x: 400, y: 0 }, to: { x: 200, y: 300 }, tension: 0.15 },19    { from: { x: 200, y: 300 }, to: { x: 0, y: 0 }, tension: 0 },20  ],21});

#masking(source, maskSource, options?)

Both the source and mask pass through the shared image-source policy and decoded-image cache. The output uses the source dimensions; the mask is fitted to those dimensions before mask values are applied.

MaskOptions:

1const alphaMasked = await painter.image.masking('./photo.jpg', './soft-mask.png', {2  type: 'alpha',3});4 5const thresholdMask = await painter.image.masking('./photo.jpg', './heightmap.png', {6  type: 'grayscale',7  threshold: 128,8});9 10const keyed = await painter.image.masking('./photo.jpg', './greenscreen-solid.png', {11  type: 'color',12  colorKey: '#00ff00',13  invert: false,14});

Invalid mask modes/options use Apexify.js structured input/decode errors rather than generic helper-specific exceptions.

#gradientBlend(source, options)

BlendOptions supports linear, radial, and conic gradients plus the documented blend modes. Gradient stop validation is shared with the rest of the rendering pipeline, so stops must be finite, monotonic, and within 0–1.

1const graded = await painter.image.gradientBlend('./hero.jpg', {2  type: 'linear',3  angle: 120,4  colors: [5    { stop: 0, color: 'rgba(59,130,246,0)' },6    { stop: 1, color: 'rgba(59,130,246,0.45)' },7  ],8  blendMode: 'multiply',9});10 11const vignette = await painter.image.gradientBlend('./still.jpg', {12  type: 'radial',13  colors: [14    { stop: 0.35, color: 'rgba(2,6,23,0)' },15    { stop: 1, color: 'rgba(2,6,23,0.55)' },16  ],17  blendMode: 'overlay',18});

#Composition mindset

Use these helpers when you need a transformed raster before or between larger canvas/scene composition steps. Because the source resolver, decoder limits, cache, and structured validation are shared, the same safety/resource behavior applies whether the image is used directly or later placed into a scene.