Managing Colors

When specifying a color property, you can use one of three color spaces: RGB, CMYK and spot color.

The following properties can be set with the function setColor and support all three color spaces:

'backgroundColor/color'
'camera/clearColor'
'dropShadow/color'
'fill/color/value'
'stroke/color'

RGB#

RGB is the color space used when rendering a color to a screen. All values of R, G, Bmust be between 0.0 and 1.0

When using RGB, you typically also specify opacity or alpha as a value between 0.0 and 1.0 and is then referred to as RGBA. When a RGB color has an alpha value that is not 1.0, it will be rendered to screen with corresponding transparency.

CMYK#

CMYK is the color space used when color printing. All values of C, M, Y, and K must be between 0.0 and 1.0

When using CMYK, you can also specify a tint value between 0.0 and 1.0. When a CMYK color has a tint value that is not 1.0, it will be rendered to screen as if transparent over a white background.

When rendering to screen, CMYK colors are first converted to RGB using a simple mathematical conversion. Currently, the same conversion happens when exporting a scene to a PDF file.

Spot Color#

Spot colors are typically used for special printers or other devices that understand how to use them. Spot colors are defined primarily by their name as that is the information that the device will use to render.

For the purpose of rendering a spot color to screen, it must be given either an RGB or CMYK color approximation or both. These approximations adhere to the same restrictions respectively described above. You can specify a tint as a value between 0.0 and 1.0 which will be interpreted as opacity when rendering to screen. It is up to the special printer or device how to interpret the tint value. You can also specify an external reference, a string describing the origin of this spot color.

When rendering to screen, the spot color's RGB or CMYK approximation will be used, in that order of preference. When exporting a scene to a PDF file, spot colors will be saved as a Separation Color Space.

Using a spot color is a two step process:

you define a spot color with its name and color approximation(s) in the spot color registry.
you instantiate a spot color with its name, a tint and an external reference.

The spot color registry allows you to:

list the defined spot colors
define a new a spot color with a name and its RGB or CMYK approximation
re-define an existing spot color's RGB or CMYK approximation
retrieve the RGB or CMYK approximation of an already defined spot color
remove a spot color from the list of defined spot colors

Multiple blocks and their properties can refer to the same spot color and each can have a different tint and external reference.

Warning#

If a block's color property refers to an undefined spot color, the default color magenta with an RGB approximation of (1, 0, 1) will be used.

Converting between colors#

A utility function convertColorToColorSpace is provided to create a new color from an existing color and a new color space. RGB and CMYK colors can be converted between each other and is done so using a simple mathematical conversion. Spot colors can be converted to RGB and CMYK simply by using the corresponding approximation. RGB and CMYK colors cannot be converted to spot colors.

Custom Color Libraries#

You can configure CE.SDK with custom color libraries. More information is found here.

Explore a full code sample on Stackblitz or view the code on Github.

Setup the scene#

We first create a new scene with a graphic block that has a color fill.

Create colors#

Here we instantiate a few colors with RGB and CMYK color spaces. We also define two spot colors, one with an RGB approximation and another with a CMYK approximation. Note that a spot colors can have both color space approximations.

Applying colors to a block#

We can use the defined colors to modify certain properties of a fill or properties of a block. Here we apply it to 'fill/color/value', 'stroke/color' and 'dropShadow/color'.

Converting colors#

Using the utility function convertColorToColorSpace we create a new color in the CMYK color space by converting the rgbaBlue color to the CMYK color space. We also create a new color in the RGB color space by converting the spotPinkFlamingo color to the RGB color space.

Listing spot colors#

This function returns the list of currently defined spot colors.

Redefine a spot color#

We can re-define the RGB and CMYK approximations of an already defined spot color. Doing so will change the rendered color of the blocks. We change it for the CMYK approximation of 'Yellow' and make it a bit greenish. The properties that have 'Yellow' as their spot color will change when re-rendered.

Removing the definition of a spot color#

We can undefine a spot color. Doing so will make all the properties still referring to that spot color ('Yellow' in this case) use the default magenta RGB approximation.


import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.25.0/index.js';

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.25.0/assets'
};

CreativeEngine.init(config).then(async (engine) => {
  document.getElementById('cesdk_container').append(engine.element);

  const scene = engine.scene.create();

  const page = engine.block.create('page');
  engine.block.setWidth(page, 800);
  engine.block.setHeight(page, 600);
  engine.block.appendChild(scene, page);

  engine.scene.zoomToBlock(page, 40, 40, 40, 40);

  const block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('rect'));
  engine.block.setFill(block, engine.block.createFill('color'));
  engine.block.setPositionX(block, 350);
  engine.block.setPositionY(block, 400);
  engine.block.setWidth(block, 100);
  engine.block.setHeight(block, 100);

  const fill = engine.block.getFill(block);

  const rgbaBlue = { r: 0.0, g: 0.0, b: 1.0, a: 1.0 };
  const cmykRed = { c: 0.0, m: 1.0, y: 1.0, k: 0.0, tint: 1.0 };
  const cmykPartialRed = { c: 0.0, m: 1.0, y: 1.0, k: 0.0, tint: 0.5 };

  engine.editor.setSpotColorRGB('Pink-Flamingo', 0.988, 0.455, 0.992);
  engine.editor.setSpotColorCMYK('Yellow', 0.0, 0.0, 1.0, 0.0);
  const spotPinkFlamingo = {
    name: 'Pink-Flamingo',
    tint: 1.0,
    externalReference: 'Crayola'
  };
  const spotPartialYellow = {
    name: 'Yellow',
    tint: 0.3,
    externalReference: ''
  };

  engine.block.setColor(fill, `fill/color/value`, rgbaBlue);
  engine.block.setColor(fill, `fill/color/value`, cmykRed);
  engine.block.setColor(block, `stroke/color`, cmykPartialRed);
  engine.block.setColor(fill, `fill/color/value`, spotPinkFlamingo);
  engine.block.setColor(block, `dropShadow/color`, spotPartialYellow);

  const cmykBlueConverted = engine.editor.convertColorToColorSpace(
    rgbaBlue,
    'CMYK'
  );
  const rgbaPinkFlamingoConverted = engine.editor.convertColorToColorSpace(
    spotPinkFlamingo,
    'sRGB'
  );

  engine.editor.findAllSpotColors(); // ['Crayola-Pink-Flamingo', 'Yellow']

  engine.editor.setSpotColorCMYK('Yellow', 0.2, 0.0, 1.0, 0.0);

  engine.editor.removeSpotColor('Yellow');
});