Exporting Blocks

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to export scenes, pages, groups, or individual blocks with the block API.

Exporting allows fine-grained control of the target format and quality settings. CE.SDK currently supports exporting as PNG, JPEG, TGA, BINARY, PDF and MP4.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

Export a Static Design#

Export a design block element, e.g., a scene, a page, a group, or a single block, as a file of the given mime type.

JavaScript


export(handle: DesignBlockId, mimeType?: MimeType, options?: ExportOptions): Promise<Blob>

Exports a design block element as a file of the given mime type. Performs an internal update to resolve the final layout for the blocks.

handle: The design block element to export.
mimeType: The mime type of the output file.
options: The options for exporting the block type
Returns A promise that resolves with the exported image or is rejected with an error.

TypeScript


type ExportOptions = {
    pngCompressionLevel?: number;
    jpegQuality?: number;
    webpQuality?: number;
    targetWidth?: number;
    targetHeight?: number;
    exportPdfWithHighCompatibility?: boolean;
    exportPdfWithUnderlayer?: boolean;
    underlayerSpotColorName?: string;
    underlayerOffset?: number;
}

Export details:

Exporting automatically performs an internal update to resolve the final layout for all blocks.
Only blocks that belong to the scene hierarchy can be exported.
The export will include the block and all child elements in the block hierarchy.
If the exported block itself is rotated it will be exported without rotation.
If a margin is set on the block it will be included.
If an outside stroke is set on the block it will be included except for pages.
Exporting a scene with more than one page may result in transparent areas between the pages, it is recommended to export the individual pages instead.
Exporting as JPEG drops any transparency on the final image and may lead to unexpected results.

Export with a Color Mask#

JavaScript


exportWithColorMask(handle: DesignBlockId, mimeType: MimeType | undefined, maskColorR: number, maskColorG: number, maskColorB: number, options?: ExportOptions): Promise<Blob[]>

Exports a design block element as a file of the given mime type. Performs an internal update to resolve the final layout for the blocks.

handle: The design block element to export.
mimeType: The mime type of the output file.
maskColorR: The red component of the special color mask color.
maskColorG: The green component of the special color mask color.
maskColorB: The blue component of the special color mask color.
options: The options for exporting the block type
Returns A promise that resolves with an array of the exported image and mask or is rejected with an error.

Export a Video#

Export a page as a video file of the given mime type.

JavaScript


exportVideo(handle: DesignBlockId, mimeType: MimeType | undefined, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options: VideoExportOptions): Promise<Blob>

Exports a design block as a video file of the given mime type. Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.

handle: The design block element to export. Currently, only page blocks are supported.
mimeType: The mime type of the output video file.
progressCallback: A callback which reports on the progress of the export. It informs the receiver of the current frame index, which currently gets exported and the total frame count.
options: The options for exporting the video.
Returns A promise that resolves with a video blob or is rejected with an error.

TypeScript


type VideoExportOptions = {
    h264Profile?: number;
    h264Level?: number;
    videoBitrate?: number;
    audioBitrate?: number;
    timeOffset?: number;
    duration?: number;
    framerate?: number;
    targetWidth?: number;
    targetHeight?: number;
    abortSignal?: AbortSignal;
}

Video export details:

Exporting automatically performs an internal update to resolve the final layout for all blocks and waits until all pending assets have been loaded.
Only blocks that belong to the scene hierarchy can be exported.
The given block determines the size, camera position, and rotation in the same manner as the static design export.
The given block does not influence the time offset and duration of the video. This can be controlled using the timeOffset and duration options.
The video resolution is determined by the largest page width and the largest page height. This can be overridden using the targetWidth and targetHeight options.
When using H.264, transparency info is lost and the video will be exported with a black background.

Export Information#

Before exporting, the maximum export size and available memory can be queried.

JavaScript


getMaxExportSize(): number

Get the export size limit in pixels on the current device. An export is only possible when both the width and height of the output are below or equal this limit. However, this is only an upper limit as the export might also not be possible due to other reasons, e.g., memory constraints.

Returns The upper export size limit in pixels or an unlimited size, i.e, the maximum signed 32-bit integer value, if the limit is unknown.

JavaScript


getAvailableMemory(): number

Get the currently available memory in bytes.

Returns The currently available memory in bytes.


const scene = engine.scene.get();
const page = engine.scene.getCurrentPage();

const sceneBlob = await engine.block.export(scene, 'application/pdf');

const pageBlob = await engine.block.export(page, 'image/png');

const [image, mask] = await engine.block.exportWithColorMask(page, 'image/png', 0.5, 0.5, 0.5);

if (groupable) {
  const group = engine.block.group([member1, member2]);
  const groupBlob = await engine.block.export(group, 'image/png');
}

const blockBlob = await engine.block.export(block, 'image/jpeg', {
  /**
   * The JPEG quality to use when encoding to JPEG.
   *
   * Valid values are (0-1], higher means better quality.
   * Ignored for other encodings.
   *
   * @defaultValue 0.9
   */
  jpegQuality: 0.9,
  /**
   * The PNG compression level to use, when exporting to PNG.
   *
   * Valid values are 0 to 9, higher means smaller, but slower.
   * Quality is not affected.
   * Ignored for other encodings.
   * @defaultValue 5.
   */
  pngCompressionLevel: 5,
  /**
   * An optional target width used in conjunction with target height.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   */
  targetWidth: null,
  /**
   * An optional target height used in conjunction with target width.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   */
  targetHeight: null,
});

// Video Export

const progressCallback = (renderedFrames, encodedFrames, totalFrames) => {
  console.log('Rendered', renderedFrames, 'frames and encoded', encodedFrames, 'frames out of', totalFrames);
};
const videoOptions = {
  /**
   * Determines the encoder feature set and in turn the quality, size and speed of the encoding process.
   *
   * @defaultValue 77 (Main)
   */
  h264Profile: 77,
  /**
   * Controls the H.264 encoding level. This relates to parameters used by the encoder such as bit rate,
   * timings and motion vectors. Defined by the spec are levels 1.0 up to 6.2. To arrive at an integer value,
   * the level is multiplied by ten. E.g. to get level 5.2, pass a value of 52.
   *
   * @defaultValue 52
   */
  h264Level: 52,
  /**
   * The video bitrate in bits per second. The maximum bitrate is determined by h264Profile and h264Level.
   * If the value is 0, the bitrate is automatically determined by the engine.
   */
  videoBitrate: 0,
  /**
   * The audio bitrate in bits per second. If the value is 0, the bitrate is automatically determined by the engine (128kbps for stereo AAC stream).
   */
  audioBitrate: 0,
  /**
   * The time offset in seconds of the scene's timeline from which the video will start.
   *
   * @defaultValue 0
   */
  timeOffset: 0,
  /**
   * The duration in seconds of the final video.
   *
   * @defaultValue The duration of the given page.
   */
  duration: 10,
  /**
   * The target framerate of the exported video in Hz.
   *
   * @defaultValue 30
   */
  framerate: 30,
  /**
   * An optional target width used in conjunction with target height.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   */
  targetWidth: 1280,
  /**
   * An optional target height used in conjunction with target width.
   * If used, the block will be rendered large enough, that it fills the target
   * size entirely while maintaining its aspect ratio.
   */
  targetHeight: 720
};
const videoBlob = await engine.block.exportVideo(page, 'video/mp4', progressCallback, videoOptions);

const maxExportSizeInPixels = engine.editor.getMaxExportSize();

const availableMemoryInBytes = engine.editor.getAvailableMemory();