Rapls PDF Image Creator – PDF Thumbnails & Featured Images

A full guide with setup instructions, the fix for the infamous "black thumbnail" problem (CMYK / PDF/X), and real-world usage tips:

• Rapls PDF Image Creator — Setup & Troubleshooting Guide
• Source code on GitHub
• Developer's blog — Rapls Works

You need ImageMagick with the Imagick PHP extension and PDF support. Most shared hosting providers have this available. Contact your hosting provider if you need to enable it.

Go to Settings > Rapls PDF Image Creator > Status tab. The plugin will show whether ImageMagick is available and properly configured. For detailed troubleshooting including common server setup issues, see the setup guide.

Check Settings > Rapls PDF Image Creator > Status. If it reports ImageMagick 6, that is the cause. ImageMagick 6 can render a PDF it judges to be CMYK through Ghostscript's bmpsep8 device, which writes a separation BMP that ImageMagick's own BMP reader cannot decode. Depending on the exact ImageMagick and Ghostscript versions, the read either fails outright or returns an empty raster — which becomes a blank white thumbnail. ImageMagick 7 uses a different device and is unaffected. Not every ImageMagick 6 build is affected: on Xserver's 6.9.13-25 a CMYK page renders correctly. Since 1.3.2 the Status tab renders a test page and reports what this server actually does, rather than warning on the version number. The plugin cannot work around this, because ImageMagick picks the device from the PDF's own content and no Imagick API call overrides it. Ask your hosting provider to upgrade to ImageMagick 7, or to change the ps:cmyk delegate in delegates.xml from bmpsep8 to pamcmyk32. RGB PDFs are not affected, which is why only some of your PDFs fail.

If the PDF uses CMYK colours and no ICC profile is available on your server, the plugin falls back to a simple arithmetic conversion, which exaggerates greens and blues. Check Settings > Rapls PDF Image Creator > Status to see whether ICC colour management is active. Installing a CMYK profile on the server, or pointing the rapls_pdf_image_creator_icc_paths filter at one, restores accurate colours.

Thumbnails are not regenerated automatically, because regenerating every PDF on a large site during an update is not something a plugin should decide to do. Go to Settings > Rapls PDF Image Creator > Bulk Generate and regenerate them. If you would rather keep the previous colours, pin the old behaviour: add_filter( 'rapls_pdf_image_creator_color_conversion', function() { return 'naive'; } );

Yes. Go to Settings > Rapls PDF Image Creator > Bulk Generate tab to scan and generate thumbnails for all existing PDFs.

Those two settings only scale the rendered page down. They never enlarge it. The size the page is rendered at comes from Rendering Resolution instead, which was fixed at 150 DPI before version 1.2.0 — an A4 page at 150 DPI is about 1240x1754 pixels, and no maximum above that could produce anything bigger. Raise Rendering Resolution (Settings > Rapls PDF Image Creator > Image Settings) and the rendered page grows with it; the maximum dimensions then cap the result as before. Bear in mind that memory use during generation grows with the square of the resolution, so raise it in steps if your server is small.

Go to Tools > Site Health. The "PDF thumbnail generation" test says whether this server can render PDFs, and if not, what to ask your hosting provider for. The same report is on the Status tab of the plugin's settings page, and Site Health > Info has a Rapls PDF Image Creator section you can copy into a support request. There are two different server problems, and they need different requests:

• The Imagick PHP extension is not installed. Ask your host to install and enable it. It is the PHP binding for ImageMagick.
• ImageMagick is installed but its security policy forbids reading PDFs. Many hosts ship a policy.xml that denies the PDF coder, a precaution left over from a 2018 Ghostscript vulnerability. Ask your host to give the PDF coder read rights. The plugin shows the path of the file responsible.

JPEG, PNG, and WebP. Configure your preferred format in the Image Settings tab.

By default, yes. To keep generated images as regular attachments, enable "Keep Images on Uninstall" in Display Settings before uninstalling.

Yes. Use the rapls_pdf_image_creator_thumbnail_page filter: add_filter( 'rapls_pdf_image_creator_thumbnail_page', function( $page, $pdf_id ) { return 1; // Use second page (0-indexed) }, 10, 2 ); Without code, you can set the page for the whole site in Settings > Rapls PDF Image Creator > Page Number (0 is the first page).

Go to Settings > Rapls PDF Image Creator > Insert Settings. Choose from Image only, Title link, or Custom HTML with placeholders like {thumbnail}, {pdf_url}, {pdf_title}.

The plugin itself never runs Ghostscript. ImageMagick does, though: it passes PDFs to Ghostscript to read them, so ImageMagick's PDF support only works if Ghostscript is installed on the server. You don't have to check this by hand. The Status tab (Settings > Rapls PDF Image Creator > Status) tells you whether PDFs can be rendered on your server.

Two causes of black thumbnails have been fixed: PDF/X-1:2001 files (1.0.9), and transparent areas (1.1.0), which are now flattened onto the background colour you choose before the image is saved. If you choose a transparent background with JPEG output, white is used instead, because JPEG cannot store transparency. Thumbnails made before an update are not changed automatically, so regenerate an old black thumbnail before assuming the problem is still there.

Yes. Settings > Rapls PDF Image Creator > Rendering Resolution sets the DPI the page is rendered at, from 72 to 600 (150 by default). Raising it gives a larger, sharper thumbnail: Max Width and Max Height only scale the rendered page down, never up. Higher values use more memory while the thumbnail is being made.