Search Docs
Loading...
Skip to content

Color Effects

Remap the colors of a block with the tint, fill, tritone, levels, invert, threshold and shift channels effects.

8 mins
estimated time
Download
StackBlitz
GitHub

Color effects change the color of every pixel and leave each pixel where it is. They use the same effect API as all other effects: you create an effect with createEffect(), set its properties and add it to a block with appendEffect(). Scenes that use these effects do not open in earlier versions of CE.SDK. For the general effect API, see Apply a Filter or Effect.

This guide covers the color effects, a stack of two effects and three single effects, and exporting the result.

The Color Effects#

The Supported Filters and Effects guide lists the properties and default values of every type.

Type What it does
tint Maps the luminance of each pixel onto a gradient between two colors
fill Replaces the color of every pixel with one color and keeps the alpha
tritone Maps dark, middle and light values to three colors
levels Remaps the input range, the output range and the gamma of the channels
invert Inverts the colors, or one channel or channel group
threshold Turns every pixel black or white at a luminance level
shift_channels Replaces each channel with a channel or value of the input pixel

Creating the Image Blocks#

A helper adds an image block at a position. We put four copies of one image on the page. Each section below adds its effects to one of these blocks.

// Adds a 440 x 330 image block to the page at a position
const imageUri = 'https://img.ly/static/ubq_samples/sample_1.jpg';
const addImageBlock = async (x: number, y: number) => {
const block = await engine.block.addImage(imageUri, {
size: { width: 440, height: 330 }
});
engine.block.appendChild(page, block);
engine.block.setPositionX(block, x);
engine.block.setPositionY(block, y);
return block;
};
const stackBlock = await addImageBlock(40, 47);
const tintBlock = await addImageBlock(520, 47);
const thresholdBlock = await addImageBlock(40, 423);
const shiftBlock = await addImageBlock(520, 423);

Stacking Levels and Tritone#

A block applies its effects in the order of its effect list. appendEffect() adds an effect to the end of the list. Here levels runs first and maps the input range from 0.1 to 0.9 onto the full range. Then tritone maps black, mid gray and white to three colors.

// Levels runs first and stretches the input range 0.1 to 0.9
const levels = engine.block.createEffect('levels');
engine.block.setFloat(levels, 'effect/levels/rgbInBlack', 0.1);
engine.block.setFloat(levels, 'effect/levels/rgbInWhite', 0.9);
engine.block.appendEffect(stackBlock, levels);
// Tritone runs second and maps black, mid gray and white to three colors
const tritone = engine.block.createEffect('tritone');
engine.block.setColor(tritone, 'effect/tritone/shadows', {
r: 0.1,
g: 0.1,
b: 0.3,
a: 1
});
engine.block.setColor(tritone, 'effect/tritone/midtones', {
r: 0.8,
g: 0.3,
b: 0.4,
a: 1
});
engine.block.setColor(tritone, 'effect/tritone/highlights', {
r: 1,
g: 0.9,
b: 0.7,
a: 1
});
engine.block.appendEffect(stackBlock, tritone);

Reverse the order and the result changes: tritone then colors the original values, and levels stretches the colored result. To insert an effect at an index, disable it or remove it, see Apply a Filter or Effect.

Tint#

tint maps black to mapBlackTo and white to mapWhiteTo, and every other luminance to a color between them. amount mixes the input (0) with the tinted color (1). The alpha channel of both colors is ignored.

// Map black to a dark blue and white to a warm yellow, at 80% strength
const tint = engine.block.createEffect('tint');
engine.block.setColor(tint, 'effect/tint/mapBlackTo', {
r: 0.05,
g: 0.1,
b: 0.35,
a: 1
});
engine.block.setColor(tint, 'effect/tint/mapWhiteTo', {
r: 1,
g: 0.85,
b: 0.4,
a: 1
});
engine.block.setFloat(tint, 'effect/tint/amount', 0.8);
engine.block.appendEffect(tintBlock, tint);

Threshold#

threshold turns a pixel white when its luminance is at or above level, and black otherwise. level is in the range 0 to 1.

// Pixels with a luminance of 0.45 or more turn white, the others black
const threshold = engine.block.createEffect('threshold');
engine.block.setFloat(threshold, 'effect/threshold/level', 0.45);
engine.block.appendEffect(thresholdBlock, threshold);

Shift Channels#

shift_channels replaces each channel of a pixel with a value taken from the same pixel. takeRedFrom, takeGreenFrom, takeBlueFrom and takeAlphaFrom each accept 'Red', 'Green', 'Blue', 'Alpha', 'Luminance', 'Hue', 'Lightness', 'Saturation', 'FullOn' or 'FullOff'. Here we swap the red and the blue channel.

// Swap the red and the blue channel
const shiftChannels = engine.block.createEffect('shift_channels');
engine.block.setEnum(
shiftChannels,
'effect/shift_channels/takeRedFrom',
'Blue'
);
engine.block.setEnum(
shiftChannels,
'effect/shift_channels/takeBlueFrom',
'Red'
);
engine.block.appendEffect(shiftBlock, shiftChannels);

Exporting the Result#

We export the page as a PNG file and write it to the output folder.

const outputDir = './output';
if (!existsSync(outputDir)) {
mkdirSync(outputDir, { recursive: true });
}
const blob = await engine.block.export(page, { mimeType: 'image/png' });
const buffer = Buffer.from(await blob.arrayBuffer());
writeFileSync(`${outputDir}/color-effects.png`, buffer);
console.log('Exported result to output/color-effects.png');

API Reference#

Method Description
block.createEffect(type) Create an effect, for example 'levels', 'tint' or 'shift_channels'
block.appendEffect(block, effect) Add an effect to the end of the effect list of a block
block.setFloat(effect, property, value) Set a number property, such as effect/threshold/level
block.setColor(effect, property, color) Set a color property, such as effect/tritone/shadows
block.setEnum(effect, property, value) Set an option property, such as effect/shift_channels/takeRedFrom

Next Steps#