NAME
PDF::API2::Resource::XObject::Image::Imager - Import Imager images into PDF
SYNOPSIS
use PDF::API2;
use PDF::API2::Resource::XObject::Image::Imager;
use Imager;
# read the image
my $img = Imager->new;
$img->read( file=>$file ) or die $img->errstr;
my $pdf = PDF::API2->new;
# import the image
my $xo = $pdf->imager( $img );
my $page = $pdf->page;
my $gfx = $page->gfx;
# place the image on a page
$gfx->image( $xo, $x, $y, $scale );DESCRIPTION
This module makes it trivial to import images into your PDF. It leverages all the hard image file handling work done by Imager.
PDF::API2 is a fine module, if a bit baroque. One gap is that its handling of images: PNG import is in pure-Perl and very slow and GD imports ignore alpha channels.
That said, given that TIFFs and PNGs may be included as-is in PDFs, PDF::API2's is probably doing things in a better way.
Optimization
PDF::API2::Resource::XObject::Image::Imager currently only outputs FlatDecode. If the size of your PDF is important, you should pass it through GhostScript's ps2pdf.
$pdf->save( "$file.tmp.pdf" );
system( "ps2pdf $file.tmp.pdf $file" );
unlink "$file.tmp.pdf";METHODS
imager
my $xo = $pdf->imager( $img, %opts );Imports an Imager object into your PDF. Returns an XObject that may be place on pages of your PDF.
Currently no options are defined. If you want to reproduce "image_png" in PDF::API2's -notrans option, you must strip out the alpha channel before calling "imager".
my $noalpha = $img->convert( preset=>'noalpha' );
my $xo = $pdf->imager( $noalpha );Paletted images are converted to RGB before importing.
Greyscale images are left as-is.
16 bit or double images are not currently supported and will throw an error. If you want to import a 16 bit or double image, convert it to rgb8 beforehand.
my $rgb8 = $img->to_rgb8;
my $xo = $pdf->imager( $rgb8 );This method is created in the PDF::API2 package. While this is bad behaviour, it beats typing out PDF::API2::Resource::XObject::Image::Imager.
INTERNAL METHODS
You should not be calling these methods. Call /imager instead.
new
my $xo = PDF::API2::Resource::XObject::Image::Imager->new( $pdf, $img, $name, %opts );Creates a new image xobject from an Imager object.
A $name is assigned if none is given.
Currently no options are defined.
read_imager
$xo->read_imager( $img, %opts );Adds $img to the XObject.
Currently no options are defined.
SEE ALSO
AUTHOR
Philip Gwyn, <gwyn at cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2025 by Philip Gwyn
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.26.3 or, at your option, any later version of Perl 5 you may have available.