Class: SceneAPI | node - Node.js (Native)

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.

Constructors#

Constructor#

SceneAPI

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);
// With a specific design unit and auto-paired font-size unit:
const pxScene = engine.scene.create('Free', { designUnit: 'Pixel' });

Parameters#

Parameter	Type	Description
`sceneLayout?`	`"Free"`	`"VerticalStack"`
`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. - `designUnit` - The design unit of the new scene. Defaults to `Pixel`. - `fontSizeUnit` - The font-size unit. If omitted, paired with `designUnit` (`Pixel` design unit → `Pixel` font unit, others → `Point`).

Returns#

number

The scene’s handle.

Signature#

create(sceneLayout?: "Free" | "VerticalStack" | "HorizontalStack" | "DepthStack", options?: CreateSceneOptions): number

createVideo()#

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

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.

Deprecated#

Scene mode no longer affects engine behavior. Use create() followed by setMode('Video') instead.

const scene = engine.scene.createVideo();

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	Description
`url`	`string`	The image URL.
`dpi?`	`number`	The scene’s DPI.
`pixelScaleFactor?`	`number`	The display’s pixel scale factor.
`sceneLayout?`	`"Free"`	`"VerticalStack"`
`spacing?`	`number`	-
`spacingInScreenSpace?`	`boolean`	-

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?: "Free" | "VerticalStack" | "HorizontalStack" | "DepthStack", 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.

load()#

Load a scene from a scene string or from a URL to a scene or archive file.

The input kind is detected automatically: serialized scene content is loaded directly, while a URL is fetched and loaded as an archive or as a scene file depending on its content. This loads .imgly files as well as the legacy .scene and .zip formats. Any existing scene is replaced by the new one.

await creativeEngine.scene.load('https://example.com/my-scene.imgly');

Parameters#

Parameter	Type	Description
`source`	`string`	`URL`
`overrideEditorConfig?`	`boolean`	Whether to override editor configuration with settings and data from the scene file. Defaults to false.
`waitForResources?`	`boolean`	Whether to wait for all resources to finish loading before resolving. Defaults to false.

Returns#

Promise<number>

A handle to the loaded scene.

Signature#

load(source: string | URL, overrideEditorConfig?: boolean, waitForResources?: boolean): Promise<number>

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.
`overrideEditorConfig?`	`boolean`	Whether to override editor configuration with settings and data from the scene file. Defaults to false.
`waitForResources?`	`boolean`	Whether to wait for all resources to finish loading before resolving. Defaults to false.

Returns#

Promise<number>

A handle to the loaded scene.

Signature#

loadFromString(sceneContent: string, overrideEditorConfig?: boolean, waitForResources?: boolean): 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.

This requires continuous render calls on this engine instance, as loadFromArchiveURL does. The engine advances the fetch while it renders, so without a render loop the returned promise never settles — it neither resolves nor rejects, even for a URL that cannot be reached.

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

Parameters#

Parameter	Type	Description
`url`	`string`	The URL of the scene file.
`overrideEditorConfig?`	`boolean`	Whether to override editor configuration with settings and data from the scene file. Defaults to false.
`waitForResources?`	`boolean`	Whether to wait for all resources to finish loading before resolving. Defaults to false.

Returns#

Promise<number>

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

Signature#

loadFromURL(url: string, overrideEditorConfig?: boolean, waitForResources?: boolean): 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 archive file.
`overrideEditorConfig?`	`boolean`	Whether to override editor configuration with settings and data from the scene file. Defaults to false.
`waitForResources?`	`boolean`	Whether to wait for all resources to finish loading before resolving. Defaults to false.

Returns#

Promise<number>

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

Signature#

loadFromArchiveURL(url: string, overrideEditorConfig?: boolean, waitForResources?: boolean): 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	Description
`allowedResourceSchemes`	`string`[]	The resource schemes to allow in the saved string.
`onDisallowedResourceScheme?`	(`url`, `dataHash`) => `Promise`<`string`>	An optional callback that is called for each resource URL that has a scheme absent from `resourceSchemesAllowed`. The `url` parameter is the resource URL and the `dataHash` parameter is the hash of the resource’s data. The callback should return a new URL for the resource, which will be used in the serialized scene. The callback is expected to return the original URL if no persistence is needed.

Returns#

Promise<string>

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

Deprecated#

Use saveToString(options) instead for better extensibility and to access compression features.

Call Signature#

saveToString(options?): Promise<string>;

Serializes the current scene into a string. Selection is discarded. When persisting the result as a file, use the .imgly extension.

Parameters#

Parameter	Type	Description
`options?`	{ `allowedResourceSchemes?`: `string`[]; `onDisallowedResourceScheme?`: (`url`, `dataHash`) => `Promise`<`string`>; `compression?`: { `format?`: `CompressionFormat`; `level?`: `CompressionLevel`; }; }	Save options containing: - allowedResourceSchemes: The resource schemes to allow in the saved string. Defaults to [‘blob’, ‘bundle’, ‘file’, ‘http’, ‘https’, ‘opfs’]. - onDisallowedResourceScheme: An optional callback that is called for each resource URL that has a scheme absent from `resourceSchemesAllowed`. The `url` parameter is the resource URL and the `dataHash` parameter is the hash of the resource’s data. The callback should return a new URL for the resource, which will be used in the serialized scene. The callback is expected to return the original URL if no persistence is needed. - compression: Optional compression settings containing: - format: Compression format (None or Zstd). Defaults to Zstd. - level: Compression level (Fastest, Default, or Best). Defaults to Default.
`options.allowedResourceSchemes?`	`string`[]	-
`options.onDisallowedResourceScheme?`	(`url`, `dataHash`) => `Promise`<`string`>	-
`options.compression?`	{ `format?`: `CompressionFormat`; `level?`: `CompressionLevel`; }	-
`options.compression.format?`	`CompressionFormat`	-
`options.compression.level?`	`CompressionLevel`	-

Returns#

Promise<string>

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

Signatures#

saveToString(allowedResourceSchemes: string[], onDisallowedResourceScheme?: (url: string, dataHash: string) => Promise<string>): Promise<string>

saveToString(options?: object): 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 load. When persisting the result as a file, use the .imgly extension.

Parameters#

Parameter	Type	Description
`options?`	`SaveToArchiveOptions`	Optional settings: - compression: Compression applied to the scene inside the archive, containing: - format: Compression format (None or Zstd). Defaults to Zstd. - level: Compression level (Fastest, Default, or Best). Defaults to Default. Bundled media is always stored uncompressed, because it already is in compressed formats.

Returns#

Promise<Blob>

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

Signature#

saveToArchive(options?: SaveToArchiveOptions): 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#

number

The current page in the scene or null.

Signature#

getCurrentPage(): 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

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

Color Management#

Configure the document CMYK profile and its conversion settings. These properties are saved with the scene.

setCMYKProfile()#

Loads the ICC profile at a URI and makes it the CMYK profile of the document.

The profile is document state: it is saved with the scene and bundled into an archive. It converts CMYK colors, the CMYK approximations of spot colors, and CMYK images without an embedded profile, while scene/colorConversionMode is 'Managed'. An image with its own profile keeps using that profile.

The assignment is atomic. The previous profile stays in effect while the new one loads, and a failure leaves it unchanged. A later assignment, removeCMYKProfile or a scene load replaces a request that is still loading. Undo and redo do not change the profile.

await engine.scene.setCMYKProfile('https://example.com/profiles/PSOcoated_v3.icc');

Parameters#

Parameter	Type	Description
`uri`	`string`	The URI of a CMYK ICC profile.

Returns#

Promise<void>

A promise that resolves once the profile is in effect. It rejects with COLOR.PROFILE_MISSING when the URI cannot be loaded, COLOR.PROFILE_INVALID or COLOR.PROFILE_UNSUPPORTED_SPACE when the bytes are not a usable profile, COLOR.PROFILE_SPACE_MISMATCH when the profile is not CMYK, and COLOR.PROFILE_ASSIGNMENT_SUPERSEDED when a later change replaced the request.

Signature#

setCMYKProfile(uri: string): Promise<void>

setCMYKProfileFromData()#

Makes the ICC profile in the given bytes the CMYK profile of the document.

Works like setCMYKProfile, but the change is in effect when the call returns. The engine keeps one buffer per distinct profile for its lifetime.

saveToString stores this profile as a buffer:// URI that only this engine can read. Save to an archive to keep the profile bytes with the scene.

const response = await fetch('https://example.com/profiles/PSOcoated_v3.icc');
engine.scene.setCMYKProfileFromData(new Uint8Array(await response.arrayBuffer()));

Parameters#

Parameter	Type	Description
`data`	`Uint8Array`	The bytes of a CMYK ICC profile.

Returns#

void

Throws#

COLOR.PROFILE_INVALID or COLOR.PROFILE_UNSUPPORTED_SPACE when the bytes are not a usable profile, and COLOR.PROFILE_DATA_SPACE_MISMATCH when the profile is not CMYK. The previous profile then stays in effect.

Signature#

setCMYKProfileFromData(data: Uint8Array): void

getCMYKProfileInfo()#

What the document stores about its CMYK profile.

Reports the profile that the document names, whether it is loaded, still loading, or failed to load. The fallback profile is not reported. Await engine.editor.loadCMYKProfile() to learn whether the profile that renders is usable.

Returns#

CMYKProfileInfo

The info for the document’s CMYK profile.

Throws#

Error when the document names no CMYK profile.

Signature#

getCMYKProfileInfo(): CMYKProfileInfo

removeCMYKProfile()#

Removes the CMYK profile from the document.

CMYK conversion then uses the fallbackCMYKProfileUri setting, or the bundled profile when that setting is unset. Color management stays on. A setCMYKProfile request that is still loading is cancelled.

engine.scene.removeCMYKProfile();

Returns#

void

Signature#

removeCMYKProfile(): void

getColorRenderingIntent()#

How a color that the destination cannot reproduce is mapped into it.

const intent = engine.scene.getColorRenderingIntent();

Returns#

ColorRenderingIntent

The rendering intent of the document. RelativeColorimetric unless it was changed.

Signature#

getColorRenderingIntent(): ColorRenderingIntent

setColorRenderingIntent()#

Sets how a color that the destination cannot reproduce is mapped into it.

The intent is document state and applies to every conversion from the document CMYK profile. Undo and redo do not change it.

engine.scene.setColorRenderingIntent(ColorRenderingIntent.Perceptual);

Parameters#

Parameter	Type	Description
`intent`	`ColorRenderingIntent`	The rendering intent.

Returns#

void

Throws#

COLOR.RENDERING_INTENT_INVALID when the value is not one of the four intents.

Signature#

setColorRenderingIntent(intent: ColorRenderingIntent): void

isBlackPointCompensationEnabled()#

Whether conversion maps the black point of the source onto the destination.

const enabled = engine.scene.isBlackPointCompensationEnabled();

Returns#

boolean

True when black point compensation is on, which is the default.

Signature#

isBlackPointCompensationEnabled(): boolean

setBlackPointCompensationEnabled()#

Turns black point compensation of the document on or off.

The setting is document state and applies to every conversion from the document CMYK profile. Undo and redo do not change it.

engine.scene.setBlackPointCompensationEnabled(false);

Parameters#

Parameter	Type	Description
`enabled`	`boolean`	Whether conversion maps the black point.

Returns#

void

Signature#

setBlackPointCompensationEnabled(enabled: boolean): void

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. Disables any previously set camera position clamping in the scene and also takes priority over clamp camera commands.

// 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	Description
`ids`	`number`[]	The blocks to which the camera position is adjusted to, usually, the scene or a page.
`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.
`scaledPaddingLeft?`	`number`	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`	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`	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`	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?`	`number`	Optionally, the scene or a block in the scene for which to query the position clamping. This API is experimental and may change or be removed in future versions.

Returns#

void

unstable_isCameraPositionClampingEnabled()#

Queries whether position clamping is enabled.

engine.scene.unstable_isCameraPositionClampingEnabled();

Parameters#

Parameter	Type	Description
`blockOrScene?`	`number`	Optionally, the scene or a block in the scene for which to query the position clamping.

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	Description
`ids`	`number`[]	The blocks to which the camera zoom limits are adjusted to, usually, the scene or a page.
`minZoomLimit?`	`number`	The minimum zoom level limit when zooming out, unlimited when negative.
`maxZoomLimit?`	`number`	The maximum zoom level limit when zooming in, unlimited when negative.
`paddingLeft?`	`number`	Optional padding in screen pixels to the left of the block. Only applied when the block is not a camera.
`paddingTop?`	`number`	Optional padding in screen pixels to the top of the block. Only applied when the block is not a camera.
`paddingRight?`	`number`	Optional padding in screen pixels to the right of the block. Only applied when the block is not a camera.
`paddingBottom?`	`number`	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?`	`number`	Optionally, the scene or a block for which to query the zoom clamping. This API is experimental and may change or be removed in future versions.

Returns#

void

unstable_isCameraZoomClampingEnabled()#

Queries whether zoom clamping is enabled.

engine.scene.unstable_isCameraZoomClampingEnabled();

Parameters#

Parameter	Type	Description
`blockOrScene?`	`number`	Optionally, the scene or a block for which to query the zoom clamping.

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.

Scene Properties#

Get and set scene properties like design units and mode.

get()#

Return the currently active scene.

const scene = engine.scene.get();

Returns#

number

The scene or null, if none was created yet.

Signature#

get(): number

getMode()#

Get the current scene mode.

Returns#

"Design" | "Video"

The current mode of the scene, or null if no mode has been set.

Deprecated#

Scene mode no longer affects engine behavior. All features work regardless of mode.

const mode = scene.getMode();

setMode()#

Set the mode of the scene.

Parameters#

Parameter	Type	Description
`mode`	`"Design"`	`"Video"`

Returns#

void

Deprecated#

Scene mode no longer affects engine behavior. All features work regardless of mode.

engine.scene.setMode('Video');

setDesignUnit()#

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

engine.scene.setDesignUnit('Pixel');

Parameters#

Parameter	Type	Description
`designUnit`	`"Pixel"`	`"Millimeter"`

Returns#

void

Signature#

setDesignUnit(designUnit: "Pixel" | "Millimeter" | "Inch"): void

getDesignUnit()#

Returns the design unit of the current scene.

engine.scene.getDesignUnit();

Returns#

"Pixel" | "Millimeter" | "Inch"

The current design unit.

Signature#

getDesignUnit(): "Pixel" | "Millimeter" | "Inch"

setFontSizeUnit()#

Sets the unit in which font sizes for setTextFontSize and getTextFontSizes are interpreted. The engine continues to store font sizes in points internally; this only affects how values are interpreted at the API boundary when callers don’t specify a unit in TextFontSizeOptions.

engine.scene.setFontSizeUnit('Pixel');

Parameters#

Parameter	Type	Description
`fontSizeUnit`	`"Pixel"`	`"Point"`

Returns#

void

Signature#

setFontSizeUnit(fontSizeUnit: "Pixel" | "Point"): void

getFontSizeUnit()#

Returns the font-size unit of the current scene.

engine.scene.getFontSizeUnit();

Returns#

"Pixel" | "Point"

The current font-size unit.

Signature#

getFontSizeUnit(): "Pixel" | "Point"

getLayout()#

Get the layout of the current scene.

const layout = engine.scene.getLayout();

Returns#

"Free" | "VerticalStack" | "HorizontalStack" | "DepthStack"

The current layout of the scene.

Signature#

getLayout(): "Free" | "VerticalStack" | "HorizontalStack" | "DepthStack"

setLayout()#

Set the layout of the current scene. This will handle all necessary conversions including creating or destroying stack blocks and reparenting pages as needed.

When transitioning from stack layouts (VerticalStack, HorizontalStack, DepthStack) to Free layout, the global positions of pages are preserved to maintain their visual appearance in the scene.

engine.scene.setLayout('VerticalStack');

Parameters#

Parameter	Type	Description
`layout`	`"Free"`	`"VerticalStack"`

Returns#

void

Signature#

setLayout(layout: "Free" | "VerticalStack" | "HorizontalStack" | "DepthStack"): void

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(await engine.scene.saveToString());

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/v4/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	Description
`zoomLevel?`	`number`	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

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