Import a Design

import android.net.Uri
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import ly.img.engine.DesignBlockType
import ly.img.engine.Engine
import ly.img.engine.MimeType
import java.io.File

suspend fun importDesign(
    engine: Engine,
    assetBaseUri: Uri,
): ImportDesignResult {
    val sceneUri = assetBaseUri.buildUpon()
        .appendPath("ly.img.templates")
        .appendPath("templates")
        .appendPath("cesdk_postcard_1.scene")
        .build()
    val imageUri = assetBaseUri.buildUpon()
        .appendPath("ly.img.templates.premium")
        .appendPath("thumbnails")
        .appendPath("e-commerce")
        .appendPath("e-commerce_modern_square_n1.jpg")
        .build()
    val videoUri = assetBaseUri.buildUpon()
        .appendPath("ly.img.video")
        .appendPath("videos")
        .appendPath("pexels-tony-schnagl-5528015.mp4")
        .build()

    val remoteScene = engine.scene.load(sceneUri = sceneUri, waitForResources = true)

    val sceneString = engine.scene.saveToString(scene = remoteScene)
    val stringScene = engine.scene.load(scene = sceneString, waitForResources = true)

    val archiveBytes = engine.scene.saveToArchive(scene = stringScene)
    val archiveFile = withContext(Dispatchers.IO) {
        val file = File.createTempFile("import-design-", ".zip")
        val archiveBuffer = archiveBytes.asReadOnlyBuffer()
        file.outputStream().channel.use { channel ->
            while (archiveBuffer.hasRemaining()) {
                channel.write(archiveBuffer)
            }
        }
        file
    }
    val archiveScene = engine.scene.loadArchive(
        archiveUri = Uri.fromFile(archiveFile),
        waitForResources = true,
    )

    val imageScene = engine.scene.createFromImage(imageUri = imageUri)

    val previewPngData = engine.block.export(
        block = engine.scene.getPages().first(),
        mimeType = MimeType.PNG,
    )

    val videoScene = engine.scene.createFromVideo(videoUri = videoUri)

    engine.scene.load(sceneUri = sceneUri, waitForResources = true)
    val textBlock = engine.block.findByType(DesignBlockType.Text).first()
    engine.block.setOpacity(block = textBlock, value = 0.85F)

    return ImportDesignResult(
        remoteScene = remoteScene,
        stringScene = stringScene,
        archiveScene = archiveScene,
        imageScene = imageScene,
        videoScene = videoScene,
        textOpacity = engine.block.getOpacity(textBlock),
        pageCount = engine.scene.getPages().size,
        previewPngData = previewPngData,
    )
}

import ly.img.engine.DesignBlock
import java.nio.ByteBuffer

data class ImportDesignResult(
    val remoteScene: DesignBlock,
    val stringScene: DesignBlock,
    val archiveScene: DesignBlock,
    val imageScene: DesignBlock,
    val videoScene: DesignBlock,
    val textOpacity: Float,
    val pageCount: Int,
    val previewPngData: ByteBuffer,
)

CE.SDK supports several ways to open a design beyond starting from a blank canvas. Each load or create call replaces the active scene, so the imported design becomes the scene your app edits and exports.

The sample receives your app’s configured asset base URI and appends one saved scene, one image, and one video resource:

val sceneUri = assetBaseUri.buildUpon()
    .appendPath("ly.img.templates")
    .appendPath("templates")
    .appendPath("cesdk_postcard_1.scene")
    .build()
val imageUri = assetBaseUri.buildUpon()
    .appendPath("ly.img.templates.premium")
    .appendPath("thumbnails")
    .appendPath("e-commerce")
    .appendPath("e-commerce_modern_square_n1.jpg")
    .build()
val videoUri = assetBaseUri.buildUpon()
    .appendPath("ly.img.video")
    .appendPath("videos")
    .appendPath("pexels-tony-schnagl-5528015.mp4")
    .build()

Understanding Import Methods#

CE.SDK provides three Android import approaches, each suited to a different source:

• Scene files (.scene) store design structure, layout, and properties while referencing assets such as images and fonts by URI. They are lightweight, but those asset URIs must stay reachable.
• Archives (.zip or .cesdk) bundle the scene file with accessible referenced assets and use relative references. They are larger, but self-contained and portable. For details on creating archives, see Saving Scenes.
• Media-based scenes build an editable design directly from a source image or video.

Import from Other Design Tools#

Photoshop (.psd) and InDesign (.idml) importers run in browser and Node.js environments, not on device in the Android SDK. Convert Photoshop files with the Node.js PSD importer and InDesign files with the Node.js IDML importer, then load the resulting CE.SDK scene or archive on Android with engine.scene.load() or engine.scene.loadArchive().

Load Saved CE.SDK Scenes#

Load a previously saved scene to resume editing. The Android Engine API accepts a Uri, a serialized scene string, or an archive URI.

From a URI#

Use engine.scene.load(sceneUri=_) for a remote HTTPS scene or a local file URI. This fits cloud-based editing where your app receives the scene location from your backend.

val remoteScene = engine.scene.load(sceneUri = sceneUri, waitForResources = true)

The engine fetches the scene and replaces the current scene. Passing waitForResources=true waits for referenced assets before the sample continues to render, edit, or export the design.

From a String#

Use engine.scene.load(scene=_) when your app already has the serialized scene content in memory, such as a value from a database or the result of engine.scene.saveToString(). Pass waitForResources=true when the next step depends on images, fonts, or other referenced resources being ready.

val sceneString = engine.scene.saveToString(scene = remoteScene)
val stringScene = engine.scene.load(scene = sceneString, waitForResources = true)

This approach works well for custom storage systems that return scene data as text.

From an Archive#

Use engine.scene.loadArchive(archiveUri=_) for self-contained scene archives. Archive creation and temporary-file setup are sample scaffolding; the import call loads the archive URI back into the engine.

val archiveScene = engine.scene.loadArchive(
    archiveUri = Uri.fromFile(archiveFile),
    waitForResources = true,
)

Archives are useful when original asset URIs might move, expire, or become unavailable. Passing waitForResources=true keeps the loaded archive resource-ready for immediate editing or export.

Create Scenes from Media#

Build an editable scene directly from a source image or video instead of loading a saved CE.SDK design.

From an Image#

Use engine.scene.createFromImage(imageUri=_) to create a single-page design scene around an image.

val imageScene = engine.scene.createFromImage(imageUri = imageUri)

The scene is ready for editing, so you can add text, shapes, effects, and other design elements on top of the image.

From a Video#

Use engine.scene.createFromVideo(videoUri=_) to create a video scene with the video as the page content.

val videoScene = engine.scene.createFromVideo(videoUri = videoUri)

The scene is set up for timeline-based editing with the source video as the initial content.

Choosing the Right Import Method#

Pick the method that matches your source and portability requirements:

• Resuming saved work? Use engine.scene.load(sceneUri=_) or engine.scene.load(scene=_) for scenes you previously saved.
• Assets might be unavailable? Use engine.scene.loadArchive(archiveUri=_) for a self-contained scene with bundled assets.
• Coming from design tools? Convert PSD or IDML files outside Android first, then load the converted scene or archive.
• Starting from media? Use engine.scene.createFromImage(imageUri=_) or engine.scene.createFromVideo(videoUri=_).

Asset Availability Considerations#

When you load a scene file rather than an archive, the referenced assets must stay reachable at their original URIs. Scene files store those references, so an image saved at a remote HTTPS URL must still be served there when the scene loads.

Archives avoid this by bundling assets inside the ZIP and using relative references. Use archives for portable files, offline handoff, or imported designs whose original assets should not be fetched again.

Working with Loaded Scenes#

After importing, the design becomes the active scene. Query and modify its blocks immediately with the block APIs.

engine.scene.load(sceneUri = sceneUri, waitForResources = true)
val textBlock = engine.block.findByType(DesignBlockType.Text).first()
engine.block.setOpacity(block = textBlock, value = 0.85F)

Troubleshooting#

Scene loads with missing images or fonts

• Confirm every asset URI referenced in the scene is still reachable.
• Use an archive instead of a scene file when assets might move or become unavailable.

Archive fails to load

• Ensure the archive was created with engine.scene.saveToArchive().
• Confirm the archive URI is reachable and the file was not truncated during transfer.

Image or video fails to load

• Confirm the media URI is reachable and returns the expected file.
• Confirm the media is in a supported image or video format.

Converted PSD or IDML content is incomplete

• Check the conversion logs from the browser or Node.js importer that produced the scene or archive.
• Load the converted archive on Android only after conversion succeeds.

API Reference#