Search Docs
Loading...
Skip to content

To PDF

Convert images and multi-page designs to PDF programmatically. Load one or more image files, build a scene, and export the result without presenting the editor UI.

10 mins
estimated time
GitHub

CE.SDK converts single or multiple images to PDF while letting you crop, rotate, or add content before export. You can also configure resolution, compatibility, target dimensions, and an underlayer for specialty printing.

This guide covers single-image conversion, combining multiple images into one multi-page PDF, and configuring the resulting document.

Convert to PDF Programmatically#

Use engine.block.export() with MimeType.PDF to export a scene or page. The method returns a ByteBuffer; this sample writes a read-only view to an app-managed output directory so the original buffer remains available to other consumers.

suspend fun saveConversionPdf(
    outputDirectory: File,
    fileName: String,
    buffer: ByteBuffer,
): File = withContext(Dispatchers.IO) {
    check(outputDirectory.isDirectory || outputDirectory.mkdirs()) {
        "Could not create the PDF output directory."
    }


    val source = buffer.asReadOnlyBuffer()
    File(outputDirectory, fileName).apply {
        outputStream().channel.use { channel ->
            while (source.hasRemaining()) {
                channel.write(source)
            }
        }
        check(length() > 0L) { "PDF export was empty." }
    }
}

Convert a Single Image to PDF#

Load the first input image into a fresh scene with engine.scene.createFromImage(), then export the current page.

engine.scene.createFromImage(imageUri = imageUris.first())


val singleImagePage = checkNotNull(engine.scene.getCurrentPage())
val singleImageData = engine.block.export(
    block = singleImagePage,
    mimeType = MimeType.PDF,
)
val singleImagePdf = saveConversionPdf(
    outputDirectory = outputDirectory,
    fileName = "single-image.pdf",
    buffer = singleImageData,
)

engine.scene.createFromImage() creates a scene with one page whose fill is the loaded image. Exporting that page produces a single-page PDF. You can query and mutate its fill or add blocks before export when the image needs edits.

Combine Multiple Images into a Single PDF#

Create a scene with a vertical stack layout, append one page per image, and export the scene to produce a multi-page PDF.

val stackedScene = engine.scene.create(sceneLayout = SceneLayout.VERTICAL_STACK)
val stack = engine.block.findByType(DesignBlockType.Stack).first()


imageUris.forEach { imageUri ->
    val page = engine.block.create(DesignBlockType.Page)
    engine.block.appendChild(parent = stack, child = page)


    val imageFill = engine.block.createFill(FillType.Image)
    engine.block.setUri(
        block = imageFill,
        property = "fill/image/imageFileURI",
        value = imageUri,
    )
    engine.block.setFill(block = page, fill = imageFill)
}


val multiPageData = engine.block.export(
    block = stackedScene,
    mimeType = MimeType.PDF,
)
val multiPagePdf = saveConversionPdf(
    outputDirectory = outputDirectory,
    fileName = "multi-page.pdf",
    buffer = multiPageData,
)

Exporting the scene includes every page owned by the stack. Export an individual page instead when you need a separate PDF for each image.

Configure PDF Output Settings#

The PDF fields on ExportOptions control how CE.SDK renders and sizes the document. Set them individually or combine them in one export call.

Adjust DPI for Print Quality#

The scene’s scene/dpi property controls the resolution used for bitmap images and rasterized effects. It does not change the page size.

engine.block.setFloat(block = stackedScene, property = "scene/dpi", value = 150F)

Higher DPI values can produce sharper output at the cost of larger files. The default is 300 DPI, which suits most print workflows.

Enable High Compatibility Mode#

Set exportPdfWithHighCompatibility to rasterize complex elements at the scene’s DPI for more consistent rendering across PDF viewers.

val compatibilityOptions = ExportOptions(exportPdfWithHighCompatibility = true)
val highCompatibilityData = engine.block.export(
    block = stackedScene,
    mimeType = MimeType.PDF,
    options = compatibilityOptions,
)
val highCompatibilityPdf = saveConversionPdf(
    outputDirectory = outputDirectory,
    fileName = "high-compatibility.pdf",
    buffer = highCompatibilityData,
)

The option defaults to true. Disable it when you need vectors preserved and have verified that your target viewers render the document correctly.

Add an Underlayer for Specialty Printing#

Underlayers provide a base ink layer for printing on transparent or non-white materials such as fabric, glass, or acrylic. CE.SDK generates the underlayer from the design contours and places it behind the visible content.

First, register the spot color that represents the underlayer ink. Its name must match the name expected by your print provider; the RGB value provides a preview.

engine.editor.setSpotColor(
    name = "BrandUnderlay",
    color = Color.fromRGBA(r = 0.8F, g = 0.8F, b = 0.8F, a = 1F),
)

Then enable the underlayer during export. A negative underlayerOffset shrinks the shape inward to reduce visible edges from print misalignment.

val underlayerOptions = ExportOptions(
    exportPdfWithHighCompatibility = true,
    exportPdfWithUnderlayer = true,
    underlayerSpotColorName = "BrandUnderlay",
    underlayerOffset = -2F,
)
val underlayerData = engine.block.export(
    block = stackedScene,
    mimeType = MimeType.PDF,
    options = underlayerOptions,
)
val underlayerPdf = saveConversionPdf(
    outputDirectory = outputDirectory,
    fileName = "with-underlayer.pdf",
    buffer = underlayerData,
)

Combine All Options#

You can apply all PDF settings in one ExportOptions value. This example resets the scene to 300 DPI, targets A4 dimensions at 300 DPI (2480 × 3508 px), enables high compatibility, and generates an underlayer.

engine.block.setFloat(block = stackedScene, property = "scene/dpi", value = 300F)
val combinedOptions = ExportOptions(
    targetWidth = 2480F,
    targetHeight = 3508F,
    exportPdfWithHighCompatibility = true,
    exportPdfWithUnderlayer = true,
    underlayerSpotColorName = "BrandUnderlay",
    underlayerOffset = -2F,
)
val configuredData = engine.block.export(
    block = stackedScene,
    mimeType = MimeType.PDF,
    options = combinedOptions,
)
val configuredPdf = saveConversionPdf(
    outputDirectory = outputDirectory,
    fileName = "configured.pdf",
    buffer = configuredData,
)

Set targetWidth and targetHeight together. CE.SDK scales the scene to cover the requested dimensions while preserving its aspect ratio.

Troubleshooting#

Symptom Resolution
PDF file size is too large Reduce the scene DPI or disable exportPdfWithHighCompatibility when your target viewers support the original content.
Gradients or effects differ between viewers Enable exportPdfWithHighCompatibility so CE.SDK rasterizes complex elements at the scene DPI.
Underlayer is missing from the printed result Confirm that underlayerSpotColorName matches the print provider’s configuration and that the PDF was not flattened.

PDF Export Options#

Pass these fields to ExportOptions when calling engine.block.export().

Option Description
exportPdfWithHighCompatibility Rasterize complex elements at the scene DPI. Defaults to true.
exportPdfWithUnderlayer Generate an underlayer from the design contours. Defaults to false.
underlayerSpotColorName Name of the spot color used for the underlayer ink.
underlayerOffset Size adjustment in design units. Negative values shrink the underlayer inward.
targetWidth Target output width in pixels. Set together with targetHeight.
targetHeight Target output height in pixels. Set together with targetWidth.

API Reference#

API Purpose
engine.scene.createFromImage(imageUri=_) Create a scene with one page filled by an image.
engine.scene.create(sceneLayout=SceneLayout.VERTICAL_STACK) Create an empty scene with vertically stacked pages.
engine.scene.getCurrentPage() Return the current page.
engine.scene.getPages() Return all pages in the current scene.
engine.block.findByType(type=DesignBlockType.Stack) Find the stack that owns the scene’s pages.
engine.block.create(blockType=DesignBlockType.Page) Create a page block.
engine.block.appendChild(parent=_, child=_) Append a page to the stack.
engine.block.createFill(fillType=FillType.Image) Create an image fill.
engine.block.setUri(block=_, property="fill/image/imageFileURI", value=_) Set the source URI of an image fill.
engine.block.getUri(block=_, property="fill/image/imageFileURI") Read the source URI of an image fill.
engine.block.setFill(block=_, fill=_) Apply the image fill to a page.
engine.block.getFill(block=_) Return the fill applied to a page.
engine.block.supportsFill(block=_) Check whether a block supports a fill.
engine.block.export(block=_, mimeType=MimeType.PDF, options=_) Export a page or scene as a PDF ByteBuffer.
engine.block.setFloat(block=_, property="scene/dpi", value=_) Set the scene DPI.
engine.block.getFloat(block=_, property="scene/dpi") Return the scene DPI.
engine.editor.setSpotColor(name=_, color=_) Register the spot color used by an underlayer.
engine.editor.getSpotColorRGB(name=_) Return the preview color for a registered spot color.
ExportOptions(targetWidth=_, targetHeight=_, exportPdfWithHighCompatibility=_, exportPdfWithUnderlayer=_, underlayerSpotColorName=_, underlayerOffset=_) Configure compatibility, underlayer, and target dimensions.

Next Steps#