Skip to content

Scenes

Commonly, a scene contains several pages which in turn contain any other blocks such as images and texts. A block (or design block) is the main building unit in CE.SDK. Blocks are organized in a hierarchy through parent-child relationships. A scene is a specialized block that acts as the root of this hierarchy.

At any time, the engine holds only a single scene. Loading or creating a scene will replace the current one.

Interacting With The Scene

Creating or Using an Existing Scene

When using the Engine’s API in the context of the CE.SDK editor, there’s already an existing scene. You can obtain a handle to this scene by calling the SceneAPI’s scene.get(): number method. However, when using the Engine on its own you first have to create a scene, e.g. using scene.create(): number. See the Creating Scenes guide for more details and options.

  let scene = engine.scene.get();
  /* In engine only mode we have to create our own scene and page. */
  if (!scene) {
    scene = engine.scene.create();

Next, we need a page to place our blocks on. The scene automatically arranges its pages either in a vertical (the default) or horizontal layout. Again in the context of the editor, there’s already an existing page. To fetch that page call the BlockAPI’s block.findByType(type: ObjectType): number[] method and use the first element of the returned array.

When only using the engine, you have to create a page yourself and append it to the scene. To do that create the page using block.create(type: DesignBlockType): number and append it to the scene with block.appendChild(parent: number, child: number).

    const page = engine.block.create('page');
    engine.block.appendChild(scene, page);
  }
  /* Find all pages in our scene. */
  const pages = engine.block.findByType('page');
  /* Use the first page we found. */
  const page = pages[0];

At this point, you should have a handle to an existing scene as well as a handle to its page. Now it gets interesting when we start to add different types of blocks to the scene’s page.

Modifying the Scene

As an example, we create a graphic block using the BlockAPI’s create() method which we already used for creating our page. Then we set a rect shape and an image fill to this newly created block to give it a visual representation. To see what other kinds of blocks are available see the Block Types in the API Reference.

/* Create an graphic block with an image fill and add it to the scene's page. */
const block = engine.block.create('graphic');
engine.block.setShape(block, engine.block.createShape('rect'));
const imageFill = engine.block.createFill('image');
engine.block.setFill(block, imageFill);

We set a property of our newly created image fill by giving it a URL to reference an image file from. We also make sure the entire image stays visible by setting the block’s content fill mode to 'Contain'. To learn more about block properties check out the Block Properties API Reference.

engine.block.setString(
  imageFill,
  'fill/image/imageFileURI',
  'https://img.ly/static/ubq_samples/imgly_logo.jpg',
);
/* The content fill mode 'Contain' ensures the entire image is visible. */
engine.block.setEnum(block, 'contentFill/mode', 'Contain');

And finally, for our image to be visible we have to add it to our page using appendChild.

engine.block.appendChild(page, block);

To frame everything nicely and put it into view we direct the scene’s camera to zoom on our page.

/* Zoom the scene's camera on our page. */
engine.scene.zoomToBlock(page);

Full Code

Here’s the full code snippet for exploring a scene’s contents using the scene API:

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


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


CreativeEngine.init(config).then(engine => {
  document.getElementById('cesdk_container').append(engine.element);
  let scene = engine.scene.get();
  /* In engine only mode we have to create our own scene and page. */
  if (!scene) {
    scene = engine.scene.create();
    const page = engine.block.create('page');
    engine.block.appendChild(scene, page);
  }
  /* Find all pages in our scene. */
  const pages = engine.block.findByType('page');
  /* Use the first page we found. */
  const page = pages[0];


  /* Create an graphic block with an image fill and add it to the scene's page. */
  const block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('rect'));
  const imageFill = engine.block.createFill('image');
  engine.block.setFill(block, imageFill);


  engine.block.setString(
    imageFill,
    'fill/image/imageFileURI',
    'https://img.ly/static/ubq_samples/imgly_logo.jpg',
  );
  /* The content fill mode 'Contain' ensures the entire image is visible. */
  engine.block.setEnum(block, 'contentFill/mode', 'Contain');


  engine.block.appendChild(page, block);


  /* Zoom the scene's camera on our page. */
  engine.scene.zoomToBlock(page);
});

Exploring Scene Contents Using The Scene API

Functions

getPages(): DesignBlockId[]

Get the sorted list of pages in the scene.

  • Returns The sorted list of pages in the scene.
setDesignUnit(designUnit: DesignUnit): void

Converts all values of the current scene into the given design unit.

  • designUnit: The new design unit of the scene
getDesignUnit(): DesignUnit

Returns the design unit of the current scene.

  • Returns The current design unit.
type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';

The unit type in which the page values (size, distances, etc.) are defined.

getCurrentPage(): DesignBlockId | null

Get the current page, i.e., the page of the first selected element if this page is at least 25% visible or, otherwise, the page nearest to the viewport center.

  • Returns The current page in the scene or null.
findNearestToViewPortCenterByType(type: DesignBlockType): DesignBlockId[]

Find all blocks with the given type sorted by the distance to viewport center.

  • type: The type to search for.
  • Returns A list of block ids sorted by distance to viewport center.
findNearestToViewPortCenterByKind(kind: string): DesignBlockId[]

Find all blocks with the given kind sorted by the distance to viewport center.

  • kind: The kind to search for.
  • Returns A list of block ids sorted by distance to viewport center.

Full Code

Here’s the full code for exploring a scene’s contents:

const pages = engine.scene.getPages();
const currentPage = engine.scene.getCurrentPage();
const nearestPageByType =
  engine.scene.findNearestToViewPortCenterByType('//ly.img.ubq/page')[0];
const nearestImageByKind =
  engine.scene.findNearestToViewPortCenterByKind('image')[0];


engine.scene.setDesignUnit('Pixel');


/* Now returns 'Pixel' */
engine.scene.getDesignUnit();

Exploring Scene Contents Using The Block API

Learn how to use the CreativeEditor SDK’s CreativeEngine to explore scenes through the block API.

Functions

findAll(): DesignBlockId[]

Return all blocks currently known to the engine.

  • Returns A list of block ids.
findAllPlaceholders(): DesignBlockId[]

Return all placeholder blocks in the current scene.

  • Returns A list of block ids.
findByType(type: ObjectType): DesignBlockId[]

Finds all blocks with the given type.

  • type: The type to search for.
  • Returns A list of block ids.
findByKind(kind: string): DesignBlockId[]

Finds all blocks with the given kind.

  • kind: The kind to search for.
  • Returns A list of block ids.
findByName(name: string): DesignBlockId[]

Finds all blocks with the given name.

  • name: The name to search for.
  • Returns A list of block ids.

Full Code

Here’s the full code snippet for exploring a scene’s contents using the block API:

const allIds = engine.block.findAll();
const allPlaceholderIds = engine.block.findAllPlaceholders();
const allPages = engine.block.findByType('page');
const allImageFills = engine.block.findByType('fill/image');
const allStarShapes = engine.block.findByType('shape/star');
const allHalfToneEffects = try engine.block.findByType('effect/half_tone')
const allUniformBlurs = try engine.block.findByType('blur/uniform')
const allStickers = engine.block.findByKind('sticker');
const ids = engine.block.findByName('someName');