To PDF

Convert to PDF Programmatically#

You can use the CE.SDK to load an image, apply basic edits, and export it as a PDF programmatically. The following examples demonstrate how to convert a single image and how to merge multiple images into a single PDF.

Convert a Single Image to PDF#

The example below loads an image, applies transformations, and exports it as a PDF:

// Prepare an image URL
const imageURL = 'https://example.com/image.jpg';

// Create a new scene by loading the image immediately
await instance.createFromImage(image);

// Find the automatically added graphic block with an image fill
const block = engine.block.findByType('graphic')[0];

// Apply crop with a scale ratio of 2.0
engine.block.setCropScaleRatio(block, 2.0);

// Export as PDF Blob
const page = engine.scene.getCurrentPage();
const blob = await engine.block.export(page, { mimeType: 'application/pdf' });
// You can now save it or display it in your application

Combine Multiple Images into a Single PDF#

The example below demonstrates how to merge multiple images into a single PDF document:

// Prepare image URLs
const images = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.png',
  'https://example.com/image3.webp',
];

// Create an empty scene with a 'VerticalStack' layout
const scene = await engine.scene.create('VerticalStack');
const [stack] = engine.block.findByType('stack');

// Load all images as pages
for (const image of images) {
  // Append the new page to the stack
  const page = engine.block.create('page');
  engine.block.appendChild(stack, page);
  // Set the image as the fill of the page
  const imageFill = engine.block.createFill('image');
  engine.block.setString(imageFill, 'fill/image/imageFileURI', image);
  engine.block.setFill(page, imageFill);
}

// Export all images as a single PDF blob
const blob = await engine.block.export(scene, { mimeType: 'application/pdf' });
// You can now save it or display it in your application

PDF Conversion via the User Interface#

The CE.SDK allows you to enable PDF conversion directly from the user interface. You can customize the UI to include a “Convert to PDF” button, allowing users to trigger conversion to PDF after they upload images and perform any edits or adjustments.

Enable PDF Conversion in the UI#

To modify the UI and add a “Convert to PDF” button to the navigation bar:

// Register a custom button component
instance.ui.registerComponent(
  'convert.nav',
  ({ builder: { Button }, engine }) => {
    Button('conver-to-pdf', {
      label: 'Convert To PDF',
      icon: '@imgly/Download',
      color: 'accent',
      onClick: async () => {
        // Export the current scene as a PDF blob
        const scene = engine.scene.get();
        const blob = await engine.block.export(scene, {
          mimeType: 'application/pdf',
        });
        // Trigger download of the PDF blob
        const element = document.createElement('a');
        element.setAttribute('href', window.URL.createObjectURL(blob));
        element.setAttribute('download', 'converted.pdf');
        element.style.display = 'none';
        element.click();
        element.remove();
      },
    });
  },
);

// Add the custom button at the end of the navigation bar
editor.ui.setNavigationBarOrder([
  ...editor.ui.getNavigationBarOrder(),
  'convert.nav',
]);

For more details on customizing the UI, see the User Interface Configuration Guide.

Configuring PDF Output#

The SDK provides various options for customizing PDF exports. You can control resolution, compatibility and underlayer.

Available PDF Output Settings#

• Resolution: Adjust the DPI (dots per inch) to create print-ready PDFs with the desired level of detail.
• Page Size: Define custom dimensions in pixels for the output PDF. If specified, the block will scale to fully cover the target size while maintaining its aspect ratio.
• Compatibility: Enable this setting to improve compatibility with various PDF viewers. When enabled, images and effects are rasterized based on the scene’s DPI instead of being embedded as vector elements.
• Underlayer: Add an underlayer beneath the image content to optimize printing on non-white or specialty media (e.g., fabric, glass). The ink type is defined in ExportOptions using a spot color. You can also apply a positive or negative offset, in design units, to adjust the underlayer’s scale. See the guide Export for Printing to learn more.

PDF Performance Optimization#

The exportPdfWithHighCompatibility flag significantly impacts PDF export performance, especially for high-DPI content:

When true (default - safer but slower):

• Rasterizes images and gradients at the scene’s DPI setting
• Maximum compatibility with all PDF viewers including Safari and macOS Preview
• Slower performance (4-10x slower for high-DPI content)
• Larger file sizes

When false (faster but needs testing):

• Embeds images and gradients directly as native PDF objects
• 6-15x faster export performance for high-DPI content
• Smaller file sizes (typically 30-40% reduction)
• May have rendering issues in Safari/macOS Preview with gradients that use transparency

const scene = engine.scene.get();

// For maximum performance (test with your print workflow first)
engine.block.setFloat(scene, 'scene/dpi', 150); // Reduce from default 300
const blob = await engine.block.export(scene, {
  mimeType: 'application/pdf',
  exportPdfWithHighCompatibility: false, // Much faster
});

Before using exportPdfWithHighCompatibility: false in production:

• Test generated PDFs with your actual print vendor/equipment
• Verify rendering in Safari and macOS Preview if end-users will view PDFs in those applications
• Check that gradients with transparency render correctly
• Confirm your content renders properly in Adobe Acrobat and Chrome (these typically work fine)

Safe to use false when:

• PDFs go directly to professional printing (not viewed in Safari/Preview)
• Content is primarily photos and solid colors (minimal gradients with transparency)
• Performance is critical for batch processing workflows

Keep true when:

• Users view PDFs in Safari or macOS Preview
• Maximum compatibility is required
• Content has complex gradients with transparency
• You cannot test with your print workflow before production

Customizing PDF Output#

You can configure these settings when exporting:

const scene = engine.scene.get();

// Adjust the DPI to 72
engine.block.setFloat(scene, 'scene/dpi', 72);

// Set spot color to be used as underlayer
engine.editor.setSpotColorRGB('RDG_WHITE', 0.8, 0.8, 0.8);

const blob = await engine.block.export(scene, {
  mimeType: 'application/pdf',
  // Set target width and height in pixels
  targetWidth: 800,
  targetHeight: 600,
  // Increase compatibility with different PDF viewers
  exportPdfWithHighCompatibility: true,
  // Add an underlayer beneath the image content
  exportPdfWithUnderlayer: true,
  underlayerSpotColorName: 'RDG_WHITE',
  underlayerOffset: -2.0,
});