Save

CE.SDK provides two formats for persisting designs. Choose the format based on your storage and portability requirements.

import Foundation
import IMGLYEngine

@MainActor
func saveDesigns(engine: Engine) async throws {
  // Demo scaffolding: load a template so every snippet has a scene to operate on.
  // In your app you would start from a scene already loaded into the editor.
  let baseURL = try engine.guidesBaseURL
  try engine.editor.setSettingString("basePath", value: baseURL.absoluteString)
  let templateURL = baseURL.appendingPathComponent("ly.img.templates/templates/cesdk_business_card_1.scene")
  try await engine.scene.load(from: templateURL)

  let outputDir = FileManager.default.temporaryDirectory

  let sceneString = try await engine.scene.saveToString()

  let archiveBlob = try await engine.scene.saveToArchive()

  let compressed = try await engine.scene.saveToString(
    options: SaveToStringOptions(
      compression: CompressionOptions(format: .zstd, level: .default),
    ),
  )
  _ = compressed

  let sceneURL = outputDir.appendingPathComponent("scene.imgly")
  try sceneString.write(to: sceneURL, atomically: true, encoding: .utf8)

  let archiveURL = outputDir.appendingPathComponent("archive.imgly")
  try archiveBlob.write(to: archiveURL)

  let restoredString = try String(contentsOf: sceneURL, encoding: .utf8)
  try await engine.scene.load(from: restoredString)

  try await engine.scene.load(from: archiveURL)
}

Save Format Comparison#

String format produces a lightweight serialized string where assets remain as URL references. Use this when asset URLs will remain accessible.

Archive format creates a self-contained ZIP with all assets embedded. Use this for portable designs that work offline.

Persist saved files of either format with the .imgly extension. The .scene and .zip extensions also load, and the same engine.scene.load(from:) call opens either kind.

Save to String#

Serialize the current scene to a string suitable for database storage.

let sceneString = try await engine.scene.saveToString()

The string contains the complete scene structure but references assets by their original URLs.

Save to Archive#

Create a self-contained ZIP with the scene and all embedded assets.

let archiveBlob = try await engine.scene.saveToArchive()

saveToArchive() returns a Blob (a Data value) that includes all pages, elements, and asset data in a single portable file.

Compression Options#

CE.SDK supports optional compression for saved scenes to reduce file size. Compression is particularly useful for large scenes or when storage space is limited.

let compressed = try await engine.scene.saveToString(
  options: SaveToStringOptions(
    compression: CompressionOptions(format: .zstd, level: .default),
  ),
)

Compression Formats:

• CompressionFormat.none — No compression (default)
• CompressionFormat.zstd — Zstandard compression (recommended for best performance)

Compression Levels:

• CompressionLevel.fastest — Fastest compression, larger output
• CompressionLevel.default — Balanced speed and size (recommended)
• CompressionLevel.best — Best compression, slower

Compression adds minimal overhead while reducing scene size by approximately 64%. The default level provides the best balance of speed and compression ratio.

Write to Disk#

Use Foundation’s file APIs to persist saved designs to the file system.

Scene strings can be written directly as text:

let sceneURL = outputDir.appendingPathComponent("scene.imgly")
try sceneString.write(to: sceneURL, atomically: true, encoding: .utf8)

Archives are returned as Data, which writes to disk in a single call:

let archiveURL = outputDir.appendingPathComponent("archive.imgly")
try archiveBlob.write(to: archiveURL)

Load Scene from File#

Read a previously saved .scene file from disk and restore it to the engine with engine.scene.load(from:).

let restoredString = try String(contentsOf: sceneURL, encoding: .utf8)
try await engine.scene.load(from: restoredString)

Scene files are lightweight but require the original asset URLs to remain accessible.

Load Archive from File#

Use engine.scene.load(from:) with a local file URL to restore a self-contained archive that includes all embedded assets — the same call that loads scene files, since the engine detects the file kind automatically.

try await engine.scene.load(from: archiveURL)

Archives are portable and work offline since all assets are bundled within the file.

API Reference#

Next Steps#

• Export Overview — Export designs to image, PDF, and video formats
• Load Scene — Load scenes from remote URLs and archives
• Store Custom Metadata — Attach metadata like tags or version info to designs
• Partial Export — Export individual blocks or selections