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.
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 directionsengine.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 blockengine.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 directionsengine.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 cameraengine.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 pageengine.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.