Class: SceneAPI

Create, load, save, and manipulate scenes.

Scenes are the root element of every design hierarchy. Their children, stacks of pages, individual pages or other blocks, define the content of the design. Scenes can be created from scratch, loaded from a file or URL, or created from an image or video. After manipulation, they can be saved to a string or an archive. This allows further processing in another editor instance, automated processing in scripts or sharing with other users.

Scene Creation#

Create new scenes from scratch or from media files.

create()#

Create a new design scene, along with its own camera.

const scene = engine.scene.create(layout);

Parameters#

Parameter	Type	Default value	Description
`sceneLayout`	`SceneLayout`	`'Free'`	The layout of the scene.
`options?`	`CreateSceneOptions`	`undefined`	Optional parameters for the scene. Properties: - `page` - Page options. Properties: - `size` - The size of the page. - `color` - Optional background color of the page.

Returns#

number

The scene’s handle.

Signature#

create(sceneLayout?: SceneLayout, options?: CreateSceneOptions): number

createVideo()#

Create a new scene in video mode, along with its own camera.

const scene = engine.scene.createVideo();

Parameters#

Parameter	Type	Description
`options?`	`CreateSceneOptions`	Optional parameters for the scene. Properties: - `page` - Page options. Properties: - `size` - The size of the page. - `color` - Optional background color of the page.

Returns#

number

The scene’s handle.

Signature#

createVideo(options?: CreateSceneOptions): number

createFromImage()#

Loads the given image and creates a scene with a single page showing the image.

Fetching the image may take an arbitrary amount of time, so the scene isn’t immediately available.

const scene = await engine.scene.createFromImage('https://img.ly/static/ubq_samples/sample_4.jpg');

Parameters#

Parameter	Type	Default value	Description
`url`	`string`	`undefined`	The image URL.
`dpi`	`number`	`300`	The scene’s DPI.
`pixelScaleFactor`	`number`	`1`	The display’s pixel scale factor.
`sceneLayout`	`SceneLayout`	`'Free'`	-
`spacing`	`number`	`0`	-
`spacingInScreenSpace`	`boolean`	`false`	-

Returns#

Promise<number>

A promise that resolves with the scene ID on success or rejected with an error otherwise.

Signature#

createFromImage(url: string, dpi?: number, pixelScaleFactor?: number, sceneLayout?: SceneLayout, spacing?: number, spacingInScreenSpace?: boolean): Promise<number>

createFromVideo()#

Loads the given video and creates a scene with a single page showing the video.

Fetching the video may take an arbitrary amount of time, so the scene isn’t immediately available.

const scene = await engine.scene.createFromVideo('https://img.ly/static/ubq_video_samples/bbb.mp4');

Parameters#

Parameter	Type	Description
`url`	`string`	The video URL.

Returns#

Promise<number>

A promise that resolves with the scene ID on success or rejected with an error otherwise.

Signature#

createFromVideo(url: string): Promise<number>

Scene Loading#

Load scenes from various sources including strings, URLs, and archives.

loadFromString()#

Load the contents of a scene file.

The string must be the binary contents of a scene file and is directly imported as blocks. Any existing scene is replaced by the new one. This is useful for loading scenes that were saved with saveToString or scenes that were created in another editor instance.

const sceneContent = await creativeEngine.scene.saveToString();
creativeEngine.scene.loadFromString(sceneContent);

Parameters#

Parameter	Type	Description
`sceneContent`	`string`	The scene file contents, a base64 string.

Returns#

Promise<number>

A handle to the loaded scene.

Signature#

loadFromString(sceneContent: string): Promise<number>

loadFromURL()#

Load a scene from the URL to the scene file.

The scene file will be fetched asynchronously by the engine and loaded into the engine once it is available. Any existing scene is replaced by the new one.

const sceneURL = 'https://example.com/my-scene.json';
creativeEngine.scene.loadFromURL(sceneURL);

Parameters#

Parameter	Type	Description
`url`	`string`	The URL of the scene file.

Returns#

Promise<number>

scene A promise that resolves once the scene was loaded or rejects with an error otherwise.

Signature#

loadFromURL(url: string): Promise<number>

loadFromArchiveURL()#

Load a previously archived scene from the URL to the scene file.

The scene file will be fetched asynchronously by the engine. This requires continuous render calls on this engines instance.

Parameters#

Parameter	Type	Description
`url`	`string`	The URL of the scene file.

Returns#

Promise<number>

scene A promise that resolves once the scene was loaded or rejects with an error otherwise.

Signature#

loadFromArchiveURL(url: string): Promise<number>

Scene Saving#

Save and export scenes to different formats.

saveToString()#

Serializes the current scene into a string. Selection is discarded.

Parameters#

Parameter	Type
`allowedResourceSchemes`	`string`[]

Returns#

Promise<string>

A promise that resolves with a string on success or an error on failure.

Signature#

saveToString(allowedResourceSchemes?: string[]): Promise<string>

saveToArchive()#

Saves the current scene and all of its referenced assets into an archive.

The archive contains all assets, that were accessible when this function was called. Blocks in the archived scene reference assets relative from to the location of the scene file. These references are resolved when loading such a scene via loadSceneFromURL.

Returns#

Promise<Blob>

A promise that resolves with a Blob on success or an error on failure.

Signature#

saveToArchive(): Promise<Blob>

Page Management#

Manage pages within scenes and find elements.

getPages()#

Get the sorted list of pages in the scene.

const pages = engine.scene.getPages();

Returns#

number[]

The sorted list of pages in the scene.

Signature#

getPages(): number[]

getCurrentPage()#

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.

const currentPage = engine.scene.getCurrentPage();

Returns#

null | number

The current page in the scene or null.

Signature#

getCurrentPage(): null | number

findNearestToViewPortCenterByType()#

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

// Use longhand block type ID to find nearest pages.
let nearestPageByType = engine.scene.findNearestToViewPortCenterByType('//ly.img.ubq/page')[0];
// Or use shorthand block type ID.
nearestPageByType = engine.scene.findNearestToViewPortCenterByType('page')[0];

Parameters#

Parameter	Type	Description
`type`	`DesignBlockType`	The type to search for.

Returns#

number[]

A list of block ids sorted by distance to viewport center.

Signature#

findNearestToViewPortCenterByType(type: DesignBlockType): number[]

findNearestToViewPortCenterByKind()#

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

let nearestImageByKind = engine.scene.findNearestToViewPortCenterByKind('image')[0];

Parameters#

Parameter	Type	Description
`kind`	`string`	The kind to search for.

Returns#

number[]

A list of block ids sorted by distance to viewport center.

Signature#

findNearestToViewPortCenterByKind(kind: string): number[]

Event Subscriptions#

Subscribe to scene-related events and changes.

onZoomLevelChanged()#

Subscribe to changes to the zoom level.

const unsubscribeZoomLevelChanged = engine.scene.onZoomLevelChanged(() => {
  const zoomLevel = engine.scene.getZoomLevel();
  console.log('Zoom level is now: ', zoomLevel);
});

Parameters#

Parameter	Type	Description
`callback`	() => `void`	This function is called at the end of the engine update, if the zoom level has changed.

Returns#

A method to unsubscribe.

(): void;

Returns#

void

Signature#

onZoomLevelChanged(callback: () => void): () => void

onActiveChanged()#

Subscribe to changes to the active scene rendered by the engine.

const unsubscribe = engine.scene.onActiveChanged(() => {
  const newActiveScene = engine.scene.get();
});

Parameters#

Parameter	Type	Description
`callback`	() => `void`	This function is called at the end of the engine update, if the active scene has changed.

Returns#

A method to unsubscribe.

(): void;

Returns#

void

Signature#

onActiveChanged(callback: () => void): () => void

Scene Properties#

Get and set scene properties like design units and mode.

get()#

Return the currently active scene.

const scene = engine.scene.get();

Returns#

null | number

The scene or null, if none was created yet.

Signature#

get(): null | number

getMode()#

Get the current scene mode.

const mode = scene.getMode();

Returns#

SceneMode

The current mode of the scene.

Signature#

getMode(): SceneMode

setDesignUnit()#

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

engine.scene.setDesignUnit('Pixel');

Parameters#

Parameter	Type	Description
`designUnit`	`DesignUnit`	The new design unit of the scene

Returns#

void

Signature#

setDesignUnit(designUnit: DesignUnit): void

getDesignUnit()#

Returns the design unit of the current scene.

engine.scene.getDesignUnit();

Returns#

DesignUnit

The current design unit.

Signature#

getDesignUnit(): DesignUnit

Template Operations#

Apply templates to existing scenes.

applyTemplateFromString()#

Applies the contents of the given template scene to the currently loaded scene.

This loads the template scene while keeping the design unit and page dimensions of the current scene. The content of the pages is automatically adjusted to fit the new dimensions.

engine.scene.applyTemplateFromString("UBQ1ewoiZm9ybWF0Ij...");

Parameters#

Parameter	Type	Description
`content`	`string`	The template scene file contents, a base64 string.

Returns#

Promise<void>

A Promise that resolves once the template was applied or rejects if there was an error.

Signature#

applyTemplateFromString(content: string): Promise<void>

applyTemplateFromURL()#

Applies the contents of the given template scene to the currently loaded scene.

This loads the template scene while keeping the design unit and page dimensions of the current scene. The content of the pages is automatically adjusted to fit the new dimensions.

engine.scene.applyTemplateFromURL('https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene');

Parameters#

Parameter	Type	Description
`url`	`string`	The url to the template scene file.

Returns#

Promise<void>

A Promise that resolves once the template was applied or rejects if there was an error.

Signature#

applyTemplateFromURL(url: string): Promise<void>

Camera & Zoom#

Control camera position, zoom levels, and auto-fit behavior.

setZoomLevel()#

Set the zoom level of the scene, e.g., for headless versions.

This only shows an effect if the zoom level is not handled/overwritten by the UI. Setting a zoom level of 2.0f results in one dot in the design to be two pixels on the screen.

// Zoom to 100%
engine.scene.setZoomLevel(1.0);

// Zoom to 50%
engine.scene.setZoomLevel(0.5 * engine.scene.getZoomLevel());

Parameters#

Parameter	Type	Default value	Description
`zoomLevel`	`number`	`1.0`	The new zoom level.

Returns#

void

Signature#

setZoomLevel(zoomLevel?: number): void

getZoomLevel()#

Get the zoom level of the scene or for a camera in the scene in unit dpx/dot. A zoom level of 2.0 results in one pixel in the design to be two pixels on the screen.

const zoomLevel = engine.scene.getZoomLevel();

Returns#

number

The zoom level of the block’s camera.

Signature#

getZoomLevel(): number

zoomToBlock()#

Sets the zoom and focus to show a block, optionally with animation. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block that should be focused on.
`options?`	`ZoomOptions`	Configuration for padding and animation.

Returns#

Promise<void>

A promise that resolves once the zoom was set or rejects with an error otherwise.

Call Signature#

zoomToBlock(
   id,
   paddingLeft?,
   paddingTop?,
   paddingRight?,
paddingBottom?): Promise<void>;

Sets the zoom and focus to show a block.

This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block.

// Bring entire scene in view with padding of 20px in all directions
engine.scene.zoomToBlock(scene, 20.0, 20.0, 20.0, 20.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block that should be focused on.
`paddingLeft?`	`number`	Optional padding in screen pixels to the left of the block.
`paddingTop?`	`number`	Optional padding in screen pixels to the top of the block.
`paddingRight?`	`number`	Optional padding in screen pixels to the right of the block.
`paddingBottom?`	`number`	Optional padding in screen pixels to the bottom of the block.

Returns#

Promise<void>

A promise that resolves once the zoom was set or rejects with an error otherwise.

Deprecated#

Use zoomToBlock with options object instead

Signatures#

zoomToBlock(id: number, options?: ZoomOptions): Promise<void>

zoomToBlock(id: number, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): Promise<void>

enableZoomAutoFit()#

Continually adjusts the zoom level to fit the width or height of a block’s axis-aligned bounding box.

This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. No more than one block per scene can have zoom auto-fit enabled. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

// Follow page with padding of 20px horizontally before and after the block
engine.scene.enableZoomAutoFit(page, 'Horizontal', 20, 20)

Parameters#

Parameter	Type	Description
`id`	`number`	The block for which the zoom is adjusted.
`axis`	`"Horizontal"`	`"Vertical"`
`paddingBefore?`	`number`	Optional padding in screen pixels before the block.
`paddingAfter?`	`number`	Optional padding in screen pixels after the block.

Returns#

void

Call Signature#

enableZoomAutoFit(
   id,
   axis,
   paddingLeft?,
   paddingTop?,
   paddingRight?,
   paddingBottom?): void;

Continually adjusts the zoom level to fit the width or height of a block’s axis-aligned bounding box.

This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

// Follow page with padding of 20px in both directions
engine.scene.enableZoomAutoFit(page, 'Both', 20.0, 20.0, 20.0, 20.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block for which the zoom is adjusted.
`axis`	`"Both"`	The block axis for which the zoom is adjusted.
`paddingLeft?`	`number`	Optional padding in screen pixels to the left of the block.
`paddingTop?`	`number`	Optional padding in screen pixels to the top of the block.
`paddingRight?`	`number`	Optional padding in screen pixels to the right of the block.
`paddingBottom?`	`number`	Optional padding in screen pixels to the bottom of the block.

Returns#

void

Signatures#

enableZoomAutoFit(id: number, axis: "Horizontal" | "Vertical", paddingBefore?: number, paddingAfter?: number): void

enableZoomAutoFit(id: number, axis: "Both", paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void

disableZoomAutoFit()#

Disables any previously set zoom auto-fit.

engine.scene.disableZoomAutoFit(scene);

Parameters#

Parameter	Type	Description
`blockOrScene`	`number`	The scene or a block in the scene for which to disable zoom auto-fit.

Returns#

void

Signature#

disableZoomAutoFit(blockOrScene: number): void

isZoomAutoFitEnabled()#

Queries whether zoom auto-fit is enabled for the given block.

engine.scene.isZoomAutoFitEnabled(scene);

Parameters#

Parameter	Type	Description
`blockOrScene`	`number`	The scene or a block in the scene for which to query the zoom auto-fit.

Returns#

boolean

True if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false otherwise.

Signature#

isZoomAutoFitEnabled(blockOrScene: number): boolean

Experimental Features#

Experimental features that may change or be removed in future versions.

unstable_enableCameraPositionClamping()#

Continually ensures the camera position to be within the width and height of the blocks axis-aligned bounding box.

// Keep the scene with padding of 10px within the camera
engine.scene.unstable_enableCameraPositionClamping([scene], 10.0, 10.0, 10.0, 10.0, 0.0, 0.0, 0.0, 0.0);

Without padding, this results in a tight clamp on the block. With padding, the padded part of the blocks is ensured to be visible.

Parameters#

Parameter	Type	Default value	Description
`ids`	`number`[]	`undefined`	The blocks to which the camera position is adjusted to, usually, the scene or a page.
`paddingLeft`	`number`	`0`	Optional padding in screen pixels to the left of the block.
`paddingTop`	`number`	`0`	Optional padding in screen pixels to the top of the block.
`paddingRight`	`number`	`0`	Optional padding in screen pixels to the right of the block.
`paddingBottom`	`number`	`0`	Optional padding in screen pixels to the bottom of the block.
`scaledPaddingLeft`	`number`	`0`	Optional padding in screen pixels to the left of the block that scales with the zoom level until five times the initial value.
`scaledPaddingTop`	`number`	`0`	Optional padding in screen pixels to the top of the block that scales with the zoom level until five times the initial value.
`scaledPaddingRight`	`number`	`0`	Optional padding in screen pixels to the right of the block that scales with the zoom level until five times the initial value.
`scaledPaddingBottom`	`number`	`0`	Optional padding in screen pixels to the bottom of the block that scales with the zoom level until five times the initial value. This API is experimental and may change or be removed in future versions.

Returns#

void

unstable_disableCameraPositionClamping()#

Disables any previously set position clamping for the current scene.

engine.scene.unstable_disableCameraPositionClamping();

Parameters#

Parameter	Type	Description
`blockOrScene`	`null`	`number`

Returns#

void

unstable_isCameraPositionClampingEnabled()#

Queries whether position clamping is enabled.

engine.scene.unstable_isCameraPositionClampingEnabled();

Parameters#

Parameter	Type	Description
`blockOrScene`	`null`	`number`

Returns#

boolean

True if the given block has position clamping set or the scene contains a block for which position clamping is set, false otherwise. This API is experimental and may change or be removed in future versions.

unstable_enableCameraZoomClamping()#

Continually ensures the zoom level of the camera in the active scene to be in the given range.

// Allow zooming from 12.5% to 800% relative to the size of a page
engine.scene.unstable_enableCameraZoomClamping([page], 0.125, 8.0, 0.0, 0.0, 0.0, 0.0);

Parameters#

Parameter	Type	Default value	Description
`ids`	`number`[]	`undefined`	The blocks to which the camera zoom limits are adjusted to, usually, the scene or a page.
`minZoomLimit`	`number`	`-1.0`	The minimum zoom level limit when zooming out, unlimited when negative.
`maxZoomLimit`	`number`	`-1.0`	The maximum zoom level limit when zooming in, unlimited when negative.
`paddingLeft`	`number`	`0`	Optional padding in screen pixels to the left of the block. Only applied when the block is not a camera.
`paddingTop`	`number`	`0`	Optional padding in screen pixels to the top of the block. Only applied when the block is not a camera.
`paddingRight`	`number`	`0`	Optional padding in screen pixels to the right of the block. Only applied when the block is not a camera.
`paddingBottom`	`number`	`0`	Optional padding in screen pixels to the bottom of the block. Only applied when the block is not a camera. This API is experimental and may change or be removed in future versions.

Returns#

void

unstable_disableCameraZoomClamping()#

Disables any previously set zoom clamping for the current scene.

engine.scene.unstable_disableCameraZoomClamping();

Parameters#

Parameter	Type	Description
`blockOrScene`	`null`	`number`

Returns#

void

unstable_isCameraZoomClampingEnabled()#

Queries whether zoom clamping is enabled.

engine.scene.unstable_isCameraZoomClampingEnabled();

Parameters#

Parameter	Type	Description
`blockOrScene`	`null`	`number`

Returns#

boolean

True if the given block has zoom clamping set or the scene contains a block for which zoom clamping is set, false otherwise. This API is experimental and may change or be removed in future versions.

Other#

setPlaying()#

Starts or stops playback of the current scene. Only works in Video mode, not in Design mode.

Parameters#

Parameter	Type	Description
`play`	`boolean`	True to start playback, false to stop

Returns#

void

Throws#

Error if no page is available for playback

Signature#

setPlaying(play: boolean): void