Cutout

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine block and editor API to create and modify a cutout block. Cutout blocks can be created from an SVG path or by performing boolean operations on existing multiple cutout blocks. One can then change a cutout's offset from its underlying path and its type.

By default, a cutout's color is set by a spot color. Cutouts of type Solid use the spot color "CutContour" and cutouts of type Dashed use the spot color "PerfCutContour". One can change these defaults to other spot colors.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

Functions#

JavaScript


createCutoutFromPath(path: string): DesignBlockId

Create a Cutout block.

path: An SVG string describing a path.
Returns The newly created block or an error.

JavaScript


createCutoutFromBlocks(ids: DesignBlockId[], vectorizeDistanceThreshold?: number, simplifyDistanceThreshold?: number, useExistingShapeInformation?: boolean): DesignBlockId

Creates a cutout whose path will be the contour of the given blocks. The cutout path for each element is derived from one two ways: - Blocks that have already have a vector path (shapes, SVG-based text or stickers). - Blocks that don't have a vector path are vectorized and then, optionally, simplified to eliminate jaggedness (images).

blocks: The blocks whose shape will serve as the basis for the cutout's path.
vectorizeDistanceThreshold: The maximum number of pixels by which the cutout's path can deviate from the original contour.
simplifyDistanceThreshold: The maximum number of pixels by which the simplified cutout path can deviate from the cutout contour. If 0, no simplification step is performed.
useExistingShapeInformation: If true, the existing vector paths of the provided blocks will be used to create the cutout. If false, new shape information for the cutout will be generated.
Returns The newly created block or an error.

JavaScript


createCutoutFromOperation(ids: DesignBlockId[], op: CutoutOperation): DesignBlockId

Perform a boolean operation on the given Cutout blocks. The cutout offset of the new block is 0. The cutout type of the new block is that of the first block. When performing a Difference operation, the first block is the block subtracted from.

blocks: The blocks with which to perform to the operation.
op: The boolean operation to perform.
Returns The newly created block or an error.

JavaScript


setSpotColorForCutoutType(type: CutoutType, color: string): void

Set the spot color assign to a cutout type. All cutout blocks of the given type will be immediately assigned that spot color.

type: The cutout type.
name: The spot color name to assign.

JavaScript


getSpotColorForCutoutType(type: CutoutType): string

Get the name of the spot color assigned to a cutout type.

type: The cutout type.
Returns The color spot name.


// Create a cutout path in the shape of a circle.
var circle = engine.block.createCutoutFromPath(
  'M 0,25 a 25,25 0 1,1 50,0 a 25,25 0 1,1 -50,0 Z'
);

// Create a cutout from the outlines of existing blocks.
var mixed = engine.block.createCutoutFromBlocks([block]);

// Set a cutout's properties
engine.block.setFloat(circle, 'cutout/offset', 3.0);
engine.block.setEnum(circle, 'cutout/offset', 'Dashed');

// Query a cutout's properties
const cutoutOffset = engine.block.getFloat(circle, 'cutout/offset');
const cutoutType = engine.block.getEnum(circle, 'cutout/type');

// Create a spot color named 'Yellow' and use it for all cutouts of type 'Dashed' instead of the default magenta.
engine.editor.setSpotColorRGB('Yellow', 1, 1, 0);
engine.editor.setSpotColorForCutoutType('Dashed', 'Yellow');
const dashedSpotColor = engine.editor.getSpotColorForCutoutType('Dashed'); // 'Yellow'

// Combine multiple cutouts using different operations to create new cutouts.
var square = engine.block.createCutoutFromPath('M 0,0 H 50 V 50 H 0 Z');
var unionCircleSquare = engine.block.createCutoutFromOperation(
  [circle, square],
  'Union'
);
var differenceCircleSquare = engine.block.createCutoutFromOperation(
  [circle, square],
  'Difference'
);
var intersectionCircleSquare = engine.block.createCutoutFromOperation(
  [circle, square],
  'Intersection'
);
var xorCircleSquare = engine.block.createCutoutFromOperation(
  [circle, square],
  'Xor'
);