Wipe Effects - Node.js

Hide parts of a block with the linear wipe, radial wipe and venetian blinds effects, and animate a wipe to reveal a block over time.

8 mins

estimated time

Download

StackBlitz

GitHub

Wipe effects hide a part of a block. Their completion property sets the hidden part, from 0 (all shown) to 1 (all hidden), and feather sets the length of the soft edge in design units. 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.

import CreativeEngine from '@cesdk/node';
import { writeFileSync, mkdirSync, existsSync } from 'fs';
import { config } from 'dotenv';

// Load environment variables
config();

/**
 * CE.SDK Server Guide: Wipe Effects
 *
 * Wipes three copies of one image in three ways:
 * - A linear wipe
 * - A radial wipe
 * - Venetian blinds
 * Then reveals a fourth copy over two seconds with keyframes.
 */
async function main() {
  // Initialize the headless Creative Engine
  const engine = await CreativeEngine.init({
    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
    // license: process.env.CESDK_LICENSE
  });

  try {
    // Create a scene with a timeline, as the Keyframes guide does
    const scene = engine.scene.create('DepthStack');
    const page = engine.block.create('page');
    engine.block.setWidth(page, 1920);
    engine.block.setHeight(page, 1080);
    engine.block.appendChild(scene, page);

    // Adds a 720 x 405 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: 720, height: 405 }
      });
      engine.block.appendChild(page, block);
      engine.block.setPositionX(block, x);
      engine.block.setPositionY(block, y);
      return block;
    };

    const linearBlock = await addImageBlock(180, 90);
    const radialBlock = await addImageBlock(1020, 90);
    const blindsBlock = await addImageBlock(180, 585);
    const revealBlock = await addImageBlock(1020, 585);

    // Hide the left half of the block with a soft edge of 40 design units
    const linearWipe = engine.block.createEffect('linear_wipe');
    engine.block.setFloat(linearWipe, 'effect/linear_wipe/angle', 90);
    engine.block.setFloat(linearWipe, 'effect/linear_wipe/completion', 0.5);
    engine.block.setFloat(linearWipe, 'effect/linear_wipe/feather', 40);
    engine.block.appendEffect(linearBlock, linearWipe);

    // Sweep clockwise from 12 o'clock and hide 60% of the circle
    const radialWipe = engine.block.createEffect('radial_wipe');
    engine.block.setFloat(radialWipe, 'effect/radial_wipe/completion', 0.6);
    engine.block.setFloat(radialWipe, 'effect/radial_wipe/startAngle', 0);
    engine.block.setFloat(radialWipe, 'effect/radial_wipe/centerX', 0.5);
    engine.block.setFloat(radialWipe, 'effect/radial_wipe/centerY', 0.5);
    engine.block.setEnum(
      radialWipe,
      'effect/radial_wipe/direction',
      'Clockwise'
    );
    engine.block.setFloat(radialWipe, 'effect/radial_wipe/feather', 20);
    engine.block.appendEffect(radialBlock, radialWipe);

    // Diagonal stripes 60 design units wide, each half hidden
    const blinds = engine.block.createEffect('venetian_blinds');
    engine.block.setFloat(blinds, 'effect/venetian_blinds/completion', 0.5);
    engine.block.setFloat(blinds, 'effect/venetian_blinds/direction', 45);
    engine.block.setFloat(blinds, 'effect/venetian_blinds/width', 60);
    engine.block.setFloat(blinds, 'effect/venetian_blinds/feather', 2);
    engine.block.appendEffect(blindsBlock, blinds);

    // Reveal the block from the right during its 2 seconds
    engine.block.setDuration(revealBlock, 2);
    const reveal = engine.block.createEffect('linear_wipe');
    engine.block.setFloat(reveal, 'effect/linear_wipe/angle', 90);
    engine.block.appendEffect(revealBlock, reveal);

    // Keyframe times are relative to the block's duration, from 0 to 1
    engine.block.setKeyframes(reveal, 'effect/linear_wipe/completion', [
      {
        time: 0,
        value: { type: 'Float', value: 1 },
        easing: { type: 'Preset', preset: 'EaseOut' }
      },
      { time: 1, value: { type: 'Float', value: 0 } }
    ]);
    console.log(
      engine.block.getKeyframes(reveal, 'effect/linear_wipe/completion').length
    ); // 2

    const outputDir = './output';
    if (!existsSync(outputDir)) {
      mkdirSync(outputDir, { recursive: true });
    }

    // Export two frames of the reveal: early, and near the end
    for (const time of [0.5, 1.5]) {
      engine.block.setPlaybackTime(page, time);
      const blob = await engine.block.export(page, { mimeType: 'image/png' });
      const buffer = Buffer.from(await blob.arrayBuffer());
      writeFileSync(`${outputDir}/wipe-effects-${time}s.png`, buffer);
      console.log(`Exported result to output/wipe-effects-${time}s.png`);
    }
  } finally {
    // Always dispose of the engine to free resources
    engine.dispose();
  }
}

main().catch(console.error);

This guide covers the three wipe effects and a reveal that animates completion with keyframes, and exporting the result.

The Wipe Effects#

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

Type	What it hides	Properties
`linear_wipe`	The block from one side, along a straight edge	`completion`, `angle`, `feather`
`radial_wipe`	A wedge that sweeps around a center	`completion`, `startAngle`, `centerX`, `centerY`, `direction`, `feather`
`venetian_blinds`	A part of each stripe in a set of repeating stripes	`completion`, `direction`, `width`, `feather`

Creating the Image Blocks#

The example creates a scene with the DepthStack layout and adds a page to it, as the Keyframes guide does. A helper adds an image block at a position. We put four copies of one image on the page: three for the wipe effects and one for the reveal.

// Adds a 720 x 405 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: 720, height: 405 }
  });
  engine.block.appendChild(page, block);
  engine.block.setPositionX(block, x);
  engine.block.setPositionY(block, y);
  return block;
};

const linearBlock = await addImageBlock(180, 90);
const radialBlock = await addImageBlock(1020, 90);
const blindsBlock = await addImageBlock(180, 585);
const revealBlock = await addImageBlock(1020, 585);

Linear Wipe#

angle sets the direction of the wipe in degrees: 90 wipes from the left, 0 wipes from the bottom. A completion of 0.5 hides half of the block. feather is the length of the soft edge in design units, so it scales with the block.

// Hide the left half of the block with a soft edge of 40 design units
const linearWipe = engine.block.createEffect('linear_wipe');
engine.block.setFloat(linearWipe, 'effect/linear_wipe/angle', 90);
engine.block.setFloat(linearWipe, 'effect/linear_wipe/completion', 0.5);
engine.block.setFloat(linearWipe, 'effect/linear_wipe/feather', 40);
engine.block.appendEffect(linearBlock, linearWipe);

Radial Wipe#

radial_wipe hides a wedge of the full circle around a center. startAngle is the angle where the wipe starts, in degrees clockwise from 12 o’clock. centerX and centerY place the center relative to the block size, from 0 to 1. direction is 'Clockwise', 'Counterclockwise' or 'Both'.

// Sweep clockwise from 12 o'clock and hide 60% of the circle
const radialWipe = engine.block.createEffect('radial_wipe');
engine.block.setFloat(radialWipe, 'effect/radial_wipe/completion', 0.6);
engine.block.setFloat(radialWipe, 'effect/radial_wipe/startAngle', 0);
engine.block.setFloat(radialWipe, 'effect/radial_wipe/centerX', 0.5);
engine.block.setFloat(radialWipe, 'effect/radial_wipe/centerY', 0.5);
engine.block.setEnum(
  radialWipe,
  'effect/radial_wipe/direction',
  'Clockwise'
);
engine.block.setFloat(radialWipe, 'effect/radial_wipe/feather', 20);
engine.block.appendEffect(radialBlock, radialWipe);

Venetian Blinds#

venetian_blinds hides the same part of each stripe. direction turns the stripes in degrees, and 0 gives vertical stripes. width is the width of one stripe in design units. The edge ramp is three times feather.

// Diagonal stripes 60 design units wide, each half hidden
const blinds = engine.block.createEffect('venetian_blinds');
engine.block.setFloat(blinds, 'effect/venetian_blinds/completion', 0.5);
engine.block.setFloat(blinds, 'effect/venetian_blinds/direction', 45);
engine.block.setFloat(blinds, 'effect/venetian_blinds/width', 60);
engine.block.setFloat(blinds, 'effect/venetian_blinds/feather', 2);
engine.block.appendEffect(blindsBlock, blinds);

Revealing a Block over Time#

Effect properties accept keyframes. We give the fourth block a duration of 2 seconds and a linear wipe, and animate effect/linear_wipe/completion from 1 (all hidden) to 0 (all shown). Keyframe times are relative to the duration of the block that the effect is attached to, from 0 to 1. getKeyframes() reads the track back.

// Reveal the block from the right during its 2 seconds
engine.block.setDuration(revealBlock, 2);
const reveal = engine.block.createEffect('linear_wipe');
engine.block.setFloat(reveal, 'effect/linear_wipe/angle', 90);
engine.block.appendEffect(revealBlock, reveal);

// Keyframe times are relative to the block's duration, from 0 to 1
engine.block.setKeyframes(reveal, 'effect/linear_wipe/completion', [
  {
    time: 0,
    value: { type: 'Float', value: 1 },
    easing: { type: 'Preset', preset: 'EaseOut' }
  },
  { time: 1, value: { type: 'Float', value: 0 } }
]);
console.log(
  engine.block.getKeyframes(reveal, 'effect/linear_wipe/completion').length
); // 2

The keyframes do not change the static value of the property, so getFloat() still returns the value that you set without keyframes. To see the animated value, render the page at a playback time, as the export below does. For easing, relative tracks and the other keyframe options, see Keyframes.

Exporting the Result#

We export the page twice, at 0.5 and at 1.5 seconds. The two images show the reveal at two points in time. setPlaybackTime() sets the time of the page before each export.

const outputDir = './output';
if (!existsSync(outputDir)) {
  mkdirSync(outputDir, { recursive: true });
}

// Export two frames of the reveal: early, and near the end
for (const time of [0.5, 1.5]) {
  engine.block.setPlaybackTime(page, time);
  const blob = await engine.block.export(page, { mimeType: 'image/png' });
  const buffer = Buffer.from(await blob.arrayBuffer());
  writeFileSync(`${outputDir}/wipe-effects-${time}s.png`, buffer);
  console.log(`Exported result to output/wipe-effects-${time}s.png`);
}

Troubleshooting#

The whole block disappears: completion is 1. Set a lower value, or check the keyframes at the current playback time.
The revealed block stays hidden: the playback time is at the start of the block, where completion is 1. Move it with setPlaybackTime().
The soft edge looks too hard or too soft: feather is in design units, so a block with a larger size needs a larger value for the same look.

API Reference#

Method	Description
`block.createEffect(type)`	Create an effect, for example `'linear_wipe'`, `'radial_wipe'` or `'venetian_blinds'`
`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/linear_wipe/completion`
`block.setEnum(effect, property, value)`	Set an option property, such as `effect/radial_wipe/direction`
`block.setDuration(block, duration)`	Set the duration of a block in seconds
`block.setKeyframes(block, property, keyframes)`	Animate a property of a block, such as the `completion` of an effect
`block.getKeyframes(block, property)`	Read the keyframes of a property
`block.setPlaybackTime(page, time)`	Move the playback position of a page

Next Steps#

Keyframes: animate effect properties over time.
Apply a Filter or Effect: insert, disable and remove effects.
Supported Filters and Effects: look up the properties of every effect type.
Color Effects: remap the colors of a block.
Distortion Effects: move the pixels of a block.