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, BIN, 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;
}

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 scene 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 the scene block is 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 video blob or is rejected with an error.

TypeScript


type VideoExportOptions = {
    h264Profile?: number;
    h264Level?: 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.


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

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

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: number,
  /**
   * 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: 512
});

// 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 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 scene.
   */
  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(scene 'video/mp4', progressCallback, videoOptions);