NAME

PDF::Builder - Facilitates the creation and modification of PDF files

SYNOPSIS

    use PDF::Builder;
    # Create a blank PDF file
    $pdf = PDF::Builder->new();
    # Open an existing PDF file
    $pdf = PDF::Builder->open('some.pdf');
    # Add a blank page
    $page = $pdf->page();
    # Retrieve an existing page
    $page = $pdf->open_page($page_number);
    # Set the page size
    $page->size('Letter');  # or mediabox('Letter')
    # Add a built-in font to the PDF
    $font = $pdf->font('Helvetica-Bold'); # or corefont('Helvetica-Bold')
    # Add an external TrueType (TTF) font to the PDF
    $font = $pdf->font('/path/to/font.ttf');  # or ttfont() in this case
    # Add some text to the page
    $text = $page->text();
    $text->font($font, 20);
    $text->position(200, 700);  # or translate()
    $text->text('Hello World!');
    # Save the PDF
    $pdf->saveas('/path/to/new.pdf');

SOME SPECIAL NOTES

See the file README.md (in downloadable package and on CPAN) for a summary of prerequisites and tools needed to install PDF::Builder, both mandatory and optional.

  (The master copy of this license lives on the GNU website.)
  (A copy is provided in the INFO/LICENSE file for your convenience.)

GENERAL PURPOSE METHODS

$pdf = PDF::Builder->new(%opts)

Creates a new PDF object.

Options

    $pdf = PDF::Builder->new();
    ...
    print $pdf->to_string();
    $pdf = PDF::Builder->new(compress => 'none');
    # equivalent to $pdf->{'forcecompress'} = 'none'; (or older, 0)
    $pdf = PDF::Builder->new();
    ...
    $pdf->saveas('our/new.pdf');
    $pdf = PDF::Builder->new(file => 'our/new.pdf');
    ...
    $pdf->save();

$pdf->default_page_size($size); # Set

@rectangle = $pdf->default_page_size() # Get

Set the default physical size for pages in the PDF. If called without arguments, return the coordinates of the rectangle describing the default physical page size.

This is essentially an alternate method of defining the "mediabox()" call, and added for compatibility with PDF::API2.

See "Page Sizes" in PDF::Builder::Page for possible values.

$pdf->default_page_boundaries(%boundaries); # Set

%boundaries = $pdf->default_page_boundaries(); # Get

Set default prepress page boundaries for pages in the PDF. If called without arguments, returns the coordinates of the rectangles describing each of the supported page boundaries.

See the equivalent "page_boundaries" method in PDF::Builder::Page for details.

INPUT/OUTPUT METHODS

$pdf = PDF::Builder->open($pdf_file, %opts)

Opens an existing PDF file. See "new()" for options.

Example:

    $pdf = PDF::Builder->open('our/old.pdf');
    ...
    $pdf->saveas('our/new.pdf');
    $pdf = PDF::Builder->open('our/to/be/updated.pdf');
    ...
    $pdf->update();
    

$pdf = PDF::Builder->from_string($pdf_string, %opts)

Opens a PDF contained in a string. See "new()" for other options.

    # Read a PDF into a string, for the purpose of demonstration
    open $fh, 'our/old.pdf' or croak $@;
    undef $/;  # Read the whole file at once
    $pdf_string = <$fh>;
    $pdf = PDF::Builder->from_string($pdf_string);
    ...
    $pdf->saveas('our/new.pdf');

$string = $pdf->to_string()

Return the document as a string and remove the object structure from memory.

Caution: Although the object $pdf will still exist, it is no longer usable for any purpose after invoking this method! You will receive error messages about "can't call method new_obj on an undefined value".

Example:

    $pdf = PDF::Builder->new();
    ...
    print $pdf->to_string();
    

Alternate name: "stringify"

"to_string" was formerly known as "stringify", and this older name is still valid as an alternative to "to_string". It is possible that "stringify" will be deprecated and then removed some time in the future, so it may be advisable to use "to_string" in new work.

$pdf->finishobjects(@objects)

Force objects to be written to file if possible.

Example:

    $pdf = PDF::Builder->new(file => 'our/new.pdf');
    ...
    $pdf->finishobjects($page, $gfx, $txt);
    ...
    $pdf->save();
    

Note: this method is now considered obsolete, and may be deprecated. It allows for objects to be written to disk in advance of finally saving and closing the file. Otherwise, it's no different than just calling "save()" when all changes have been made. There's no memory advantage since "ship_out" doesn't remove objects from memory.

$pdf->update()

Saves a previously opened document.

Example:

    $pdf = PDF::Builder->open('our/to/be/updated.pdf');
    ...
    $pdf->update();
    

Note: it is considered better to simply "save()" the file, rather than calling "update()". They end up doing the same thing, anyway. This method may be deprecated in the future.

$pdf->saveas($file)

Save the document to $file and remove the object structure from memory.

Caution: Although the object $pdf will still exist, it is no longer usable for any purpose after invoking this method! You will receive error messages about "can't call method new_obj on an undefined value".

Example:

    $pdf = PDF::Builder->new();
    ...
    $pdf->saveas('our/new.pdf');
    

$pdf->save()

$pdf->save(filename)

Save the document to an already-defined file (or filename) and remove the object structure from memory. Optionally, a new filename may be given.

Caution: Although the object $pdf will still exist, it is no longer usable for any purpose after invoking this method! You will receive error messages about "can't call method new_obj on an undefined value".

Example:

    $pdf = PDF::Builder->new(file => 'file_to_output');
    ...
    $pdf->save();
    

Note: now that "save()" can take a filename as an argument, it effectively is interchangeable with "saveas()". This is strictly for compatibility with recent changes to PDF::API2. Unlike PDF::API2, we are not deprecating the "saveas()" method, because in user interfaces, "save" normally means that the current filename is known and is to be used, while "saveas" normally means that (whether or not there is a current filename) a new filename is to be used.

$pdf->close();

Close an open file (if relevant) and remove the object structure from memory.

PDF::API2 contains circular references, so this call is necessary in long-running processes to keep from running out of memory.

This will be called automatically when you save or stringify a PDF. You should only need to call it explicitly if you are reading PDF files and not writing them.

Alternate names: "release" and "end"

$pdf->end()

Remove the object structure from memory. PDF::Builder contains circular references, so this call is necessary in long-running processes to keep from running out of memory.

This will be called automatically when you save or to_string a PDF. You should only need to call it explicitly if you are reading PDF files and not writing them.

This (and release) are older and now deprecated names formerly used in PDF::API2 and PDF::Builder. You should try to avoid having to explicitly call them.

INTERACTIVE FEATURE METHODS

$otls = $pdf->outline()

Creates (if needed) and returns the document's 'outline' tree, which is also known as its 'bookmarks' or the 'table of contents', depending on the PDF reader being used.

To examine or modify the outline tree, see PDF::Builder::Outlines.

Alternate name: "outlines"

This is the older name; it is kept for compatibility.

$layout = $pdf->page_layout();

$pdf = $pdf->page_layout($layout);

Gets/sets the page layout that should be used when the PDF is opened.

$layout is one of the following:

$mode = $pdf->page_mode(); # Get

$pdf = $pdf->page_mode($mode); # Set

Gets/sets the page mode, which describes how the PDF should be displayed when opened.

$mode is one of the following:

%preferences = $pdf->viewer_preferences(); # Get

$pdf = $pdf->viewer_preferences(%preferences); # Set

Gets/sets PDF viewer preferences, as described in PDF::Builder::ViewerPreferences.

This has been split out from "preferences()" for compatibility with PDF::API2. It also can both set (assign) and get (query) the settings used.

$pdf->preferences(%opts)

Controls viewing preferences for the PDF, including the Page Mode, Page Layout, Viewer, and Initial Page Options. See "Preferences - set user display preferences" in PDF::Builder::Docs for details on all these option groups, and "Page Fit Options" in PDF::Builder::Docs for page positioning.

Note: the various preferences have been split out into their own methods. It is preferred that you use these specific methods.

PAGE METHODS

$page = $pdf->page()

$page = $pdf->page($page_number)

Returns a new page object. By default, the page is added to the end of the document. If you give an existing page number, the new page will be inserted in that position, pushing existing pages back by 1 (e.g., page(5) would insert an empty page 5, with the old page 5 now page 6, etc.

If $page_number is -1, the new page is inserted as the second-to-last page; if $page_number is 0, the new page is inserted as the last page.

Example:

    $pdf = PDF::Builder->new();
    # Add a page.  This becomes page 1.
    $page = $pdf->page();
    # Add a new first page.  $page becomes page 2.
    $another_page = $pdf->page(1);
    

$page = $pdf->open_page($page_number)

Returns the PDF::Builder::Page object of page $page_number. This is similar to "$page = $pdf->page()", except that $page is not a new, empty page; but contains the contents of that existing page.

If $page_number is 0, -1, or unspecified, it will return the last page in the document. If the requested page is out of range, the $page returned will be undefined.

Example:

    $pdf  = PDF::Builder->open('our/99page.pdf');
    $page = $pdf->open_page(1);   # returns the first page
    $page = $pdf->open_page(99);  # returns the last page
    $page = $pdf->open_page(-1);  # returns the last page
    $page = $pdf->open_page(999); # returns undef
    $page = $pdf->open_page(0);   # returns the last page
    $page = $pdf->open_page();    # returns the last page
    

Alternate name: "openpage"

This is the older name; it is kept for compatibility until after June 2023 (deprecated, as previously announced).

$page = $pdf->import_page($source_pdf)

$page = $pdf->import_page($source_pdf, $source_page_number)

$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)

$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_object)

Imports a page from $source_pdf and adds it to the specified position in $pdf.

If the $source_page_number is omitted, 0, or -1; the last page of the source is imported. If the $target_page_number is omitted, 0, or -1; the imported page will be placed as the new last page of the target ($pdf). Otherwise, as with the "page()" method, the page will be inserted before an existing page of that number.

Note: If you pass a page object instead of a page number for $target_page_number, the contents of the page will be merged into the existing page.

Example:

    my $pdf = PDF::Builder->new();
    my $source = PDF::Builder->open('source.pdf');
    # Add page 2 from the old PDF as page 1 of the new PDF
    my $page = $pdf->import_page($source, 2);
    $pdf->saveas('sample.pdf');
    

Note: You can only import a page from an existing PDF file.

$xoform = $pdf->embed_page($source_pdf, $source_page_number)

Returns a Form XObject created by extracting the specified page from $source_pdf.

This is useful if you want to transpose the imported page somewhat differently onto a page (e.g. two-up, four-up, etc.).

If $source_page_number is 0 or -1, it will return the last page in the document.

Example:

    my $pdf = PDF::Builder->new();
    my $source = PDF::Builder->open('source.pdf');
    my $page = $pdf->page();
    # Import Page 2 from the source PDF
    my $object = $pdf->embed_page($source, 2);
    # Add it to the new PDF's first page at 1/2 scale
    my ($x, $y) = (0, 0);
    $page->object($xo, $x, $y, 0.5);
    $pdf->save('sample.pdf');
    

Note: You can only import a page from an existing PDF file.

Alternate name: "importPageIntoForm"

This is the older name; it is kept for compatibility.

$count = $pdf->page_count()

Returns the number of pages in the document.

Alternate name: "pages"

This is the old name; it is kept for compatibility.

$pdf->page_labels($page_number, $opts)

Sets page label numbering format, for the Reader's page-selection slider thumb (not the outline/bookmarks). At this time, there is no method to automatically synchronize a page's label with the outline/bookmarks, or to somewhere on the printed page.

Note that many PDF Readers ignore these settings, and (at most) simply give you the physical page number 1, 2, 3,... instead of the page label specified here.

    # Generate a 30-page PDF
    my $pdf = PDF::Builder->new();
    $pdf->page() for 1..30;
    # Number pages i to v, 1 to 20, and A-1 to A-5, respectively
    $pdf->page_labels(1, 'style' => 'roman');
    $pdf->page_labels(6, 'style' => 'decimal');
    $pdf->page_labels(26, 'style' => 'decimal', 'prefix' => 'A-');
    $pdf->save('sample.pdf');
    

Supported Options:

    # Start with lowercase Roman Numerals at the 1st page, starting with i (1)
    $pdf->page_labels(0, 
        'style' => 'roman',
    );
    # Switch to Arabic (decimal) at the 5th page, starting with 1
    $pdf->page_labels(4, 
        'style' => 'decimal',
    );
    # invalid style at the 25th page, should just continue 
    # with decimal at the current counter
    $pdf->page_labels(24, 
        'style' => 'raman_noodles',  # fail over to decimal
           # note that PDF::API2 will see the 'r' and treat it as 'roman'
        'start' => 21,  # necessary, otherwise would restart at 1
    );
    # No page label at the 31st and 32nd pages. Note that this could be
    # confusing to the person viewing the PDF, but may be appropriate if
    # the page itself has no numbering.
    $pdf->page_labels(30, 
        'style' => 'nocounter',
    );
    # Numbering for Appendix A at the 33rd page, A-1, A-2,...
    $pdf->page_labels(32, 
        'start' => 1,  # unnecessary
        'prefix' => 'A-'
    );
    # Numbering for Appendix B at the 37th page, B-1, B-2,...
    $pdf->page_labels( 36, 
        'prefix' => 'B-'
    );
    # Numbering for the Index at the 41st page, Index I, Index II,...
    $pdf->page_labels(40, 
        'style' => 'Roman',
        'start' => 1,  # unnecessary
        'prefix' => 'Index '  # note trailing space
    );
    # Unnumbered 'Index' at the 45th page, Index, Index,...
    $pdf->page_labels(40, 
        'style' => 'nocounter',
        'prefix' => 'Index '
    );

$pdf->userunit($value)

Sets the global UserUnit, defining the scale factor to multiply any size or coordinate by. For example, "userunit(72)" results in a User Unit of 72 points, or 1 inch.

See "User Units" in PDF::Builder::Docs for more information.

$pdf->mediabox($name)

$pdf->mediabox($name, 'orient' => 'orientation')

$pdf->mediabox($w,$h)

$pdf->mediabox($llx,$lly, $urx,$ury)

($llx,$lly, $urx,$ury) = $pdf->mediabox()

Sets (or gets) the global MediaBox, defining the width and height (or by corner coordinates, or by standard name) of the output page itself, such as the physical paper size.

See "Media Box" in PDF::Builder::Docs for more information. The method always returns the current bounds (after any set operation).

$pdf->cropbox($name)

$pdf->cropbox($name, 'orient' => 'orientation')

$pdf->cropbox($w,$h)

$pdf->cropbox($llx,$lly, $urx,$ury)

($llx,$lly, $urx,$ury) = $pdf->cropbox()

Sets (or gets) the global CropBox. This will define the media size to which the output will later be clipped.

See "Crop Box" in PDF::Builder::Docs for more information. The method always returns the current bounds (after any set operation).

$pdf->bleedbox($name)

$pdf->bleedbox($name, 'orient' => 'orientation')

$pdf->bleedbox($w,$h)

$pdf->bleedbox($llx,$lly, $urx,$ury)

($llx,$lly, $urx,$ury) = $pdf->bleedbox()

Sets (or gets) the global BleedBox. This is typically used for hard copy printing where you want ink to go to the edge of the cut paper.

See "Bleed Box" in PDF::Builder::Docs for more information. The method always returns the current bounds (after any set operation).

$pdf->trimbox($name)

$pdf->trimbox($name, 'orient' => 'orientation')

$pdf->trimbox($w,$h)

$pdf->trimbox($llx,$lly, $urx,$ury)

($llx,$lly, $urx,$ury) = $pdf->trimbox()

Sets (or gets) the global TrimBox. This is supposed to be the actual dimensions of the finished page (after trimming of the paper).

See "Trim Box" in PDF::Builder::Docs for more information. The method always returns the current bounds (after any set operation).

$pdf->artbox($name)

$pdf->artbox($name, 'orient' => 'orientation')

$pdf->artbox($w,$h)

$pdf->artbox($llx,$lly, $urx,$ury)

($llx,$lly, $urx,$ury) = $pdf->artbox()

Sets (or gets) the global ArtBox. This is supposed to define "the extent of the page's meaningful content".

See "Art Box" in PDF::Builder::Docs for more information. The method always returns the current bounds (after any set operation).

FONT METHODS

$font = $pdf->corefont($fontname, %opts)

Returns a new Adobe core font object. For details, see "Core Fonts" in PDF::Builder::Docs. Note that this is an Adobe-standard corefont name, and not a file name.

See also PDF::Builder::Resource::Font::CoreFont.

$font = $pdf->psfont($ps_file, %opts)

Returns a new Adobe Type1 ("PostScript") font object. For details, see "PS Fonts" in PDF::Builder::Docs.

See also PDF::Builder::Resource::Font::Postscript.

$font = $pdf->ttfont($ttf_file, %opts)

Returns a new TrueType (or OpenType) font object. For details, see "TrueType Fonts" in PDF::Builder::Docs.

$font = $pdf->bdfont($bdf_file, @opts)

Returns a new BDF (bitmapped distribution format) font object, based on the specified Adobe BDF file.

See also PDF::Builder::Resource::Font::BdFont

$font = $pdf->cjkfont($cjkname, %opts)

Returns a new CJK font object. These are TrueType-like fonts for East Asian languages (Chinese, Japanese, Korean). For details, see "CJK Fonts" in PDF::Builder::Docs.

NOTE: "cjkfont" is quite old and is not well supported. We recommend that you try using "ttfont" (or another font routine, if not TTF/OTF) with the appropriate CJK font file. Most appear to be .ttf or .otf format. PDFs created using "cjkfont" may not be fully portable, and support for "cjkfont" may be dropped in a future release. We would appreciate hearing from you if you are successfully using "cjkfont", and are unable to use "ttfont" instead.

Among other things, "cjkfont" selections are limited, as they require CMAP files; they may or may not subset correctly; and they can not be used as the base for synthetic fonts.

See also PDF::Builder::Resource::CIDFont::CJKFont

$font = $pdf->font($name, %opts)

A convenience function to add a font to the PDF without having to specify the format. Returns the font object, to be used by PDF::Builder::Content.

The font $name is either the name of one of the standard 14 fonts ("STANDARD FONTS" in PDF::Builder::Resource::Font::CoreFont), such as Helvetica or the path to a font file. There are 15 additional core fonts on a Windows system. Note that the exact name of a core font needs to be given. The file extension (if path given) determines what type of font file it is.

    my $pdf = PDF::Builder->new();
    my $font1 = $pdf->font('Helvetica-Bold');
    my $font2 = $pdf->font('/path/to/ComicSans.ttf');
    my $page = $pdf->page();
    my $content = $page->text();
    $content->position(1 * 72, 9 * 72);
    $content->font($font1, 24);
    $content->text('Hello, World!');
    $content->position(0, -36);
    $content->font($font2, 12);
    $content->text('This is some sample text.');
    $pdf->saveas('sample.pdf');
    

The path can be omitted if the font file is in the current directory or one of the directories returned by "font_path".

TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe Glyph Bitmap Distribution Format (bdf) fonts are supported.

The following options (%opts) are available:

@directories = PDF::Builder->font_path()

Return the list of directories that will be searched (in order) in addition to the current directory when you add a font to a PDF without including the full path to the font file.

@directories = PDF::Builder::add_to_font_path('/my/fonts', '/path/to/fonts', ...)

Adds one or more directories to the list of paths to be searched for font files.

Returns the font search path.

Alternate name: "addFontDirs"

Prior to recent changes to PDF::API2, this method was addFontDirs(). This method is still available, but may be deprecated some time in the future.

@directories = PDF::Builder->set_font_path('/my/fonts', '/path/to/fonts');

Replace the existing font search path. This should only be necessary if you need to remove a directory from the path for some reason, or if you need to reorder the list.

Returns the font search path.

$font = $pdf->synfont($basefont, %opts)

Returns a new synthetic font object. These are modifications to a core (or PS/T1 or TTF/OTF) font, where the font may be replaced by a Type1 or Type3 PostScript font. This does not appear to work with CJK fonts (created with "cjkfont" method). For details, see "Synthetic Fonts" in PDF::Builder::Docs.

See also PDF::Builder::Resource::Font::SynFont

Alternate name: "synthetic_font"

Prior to recent PDF::API2 changes, the routine to create modified fonts was "synfont". PDF::API2 has renamed it to "synthetic_font", which I don't like, but to maintain compatibility, "synthetic_font" is available as an alias.

There are also some minor option differences (incompatibilities) discussed in "SynFont", including the value of 'bold' between the two entry points.

$font = $pdf->unifont(@fontspecs, %opts)

Returns a new uni-font object, based on the specified fonts and options.

BEWARE: This is not a true PDF-object, but a virtual/abstract font definition!

See also PDF::Builder::Resource::UniFont.

Valid options (%opts) are:

IMAGE METHODS

$object = $pdf->image($file, %opts);

A convenience function to attempt to determine the image type, and import a file of that type and return an object that can be placed as part of a page's content:

    my $pdf = PDF::Builder->new();
    my $page = $pdf->page();
    my $image = $pdf->image('/path/to/image.jpg');
    $page->object($image, 100, 100);
    $pdf->save('sample.pdf');
    

$file may be either a file name, a filehandle, or a PDF::Builder::Resource::XObject::Image::GD object.

Caution: Do not confuse this "image" ($pdf->) with the image method found in the graphics (gfx) class ($gfx->), used to actually place a read-in or decoded image on the page!

See "image" in PDF::Builder::Content for details about placing images on a page once they're imported.

The image format is normally detected automatically based on the file's extension (.gif, .png, .tif/.tiff, .jpg/.jpeg, .pnm/.pbm/.pgm/.ppm). If passed a filehandle, image formats GIF, JPEG, PNM, and PNG will be detected based on the file's header. Unfortunately, at this time, other image formats (TIFF and GD) cannot be automatically detected. (TIFF could be, except that "image_tiff()" cannot use a filehandle anyway as input when using the libtiff library, which is highly recommended.)

If the file has an atypical extension or the filehandle is for a different kind of image, you can set the "format" option to one of the supported types: "gif", "jpeg", "png", "pnm", or "tiff".

Note: PNG images that include an alpha (transparency) channel go through a relatively slow process of splitting the image into separate RGB and alpha components as is required by images in PDFs. If you're having performance issues, install Image::PNG::Libpng to speed this process up by an order of magnitude; either module will be used automatically if available. See the "image_png" method for details.

Note: TIFF image processing is very slow if using the pure Perl decoder. We highly recommend using the Graphics::TIFF library to improve performance. See the "image_tiff" method for details.

$jpeg = $pdf->image_jpeg($file, %opts)

Imports and returns a new JPEG image object. $file may be either a filename or a filehandle.

See PDF::Builder::Resource::XObject::Image::JPEG for additional information and "examples/Content.pl" for some examples of placing an image on a page.

$tiff = $pdf->image_tiff($file, %opts)

Imports and returns a new TIFF image object. $file may be either a filename or a filehandle. For details, see "TIFF Images" in PDF::Builder::Docs.

See PDF::Builder::Resource::XObject::Image::TIFF and PDF::Builder::Resource::XObject::Image::TIFF_GT for additional information and "examples/Content.pl" for some examples of placing an image on a page (JPEG, but the principle is the same). There is an optional TIFF library (TIFF_GT) described, that gives more capability than the default one. However, note that $file can only be a filename when using this library.

$rc = $pdf->LA_GT()

Returns 1 if the library name (package) Graphics::TIFF is installed, and 0 otherwise. For this optional library, this call can be used to know if it is safe to use certain functions. For example:

    if ($pdf->LA_GT() {
        # is installed and usable
    } else {
        # not available. you will be running the old, pure PERL code
    }
    

$pnm = $pdf->image_pnm($file, %opts)

Imports and returns a new PNM image object. $file may be either a filename or a filehandle.

See PDF::Builder::Resource::XObject::Image::PNM for additional information and "examples/Content.pl" for some examples of placing an image on a page (JPEG, but the principle is the same).

$png = $pdf->image_png($file, %opts)

Imports and returns a new PNG image object. $file may be either a filename or a filehandle. For details, see "PNG Images" in PDF::Builder::Docs.

See PDF::Builder::Resource::XObject::Image::PNG and PDF::Builder::Resource::XObject::Image::PNG_IPL for additional information and "examples/Content.pl" for some examples of placing an image on a page (JPEG, but the principle is the same).

There is an optional PNG library (PNG_IPL) described, that gives more capability than the default one. However, note that $file can only be a filename when using this library.

$rc = $pdf->LA_IPL()

Returns 1 if the library name (package) Image::PNG::Libpng is installed, and 0 otherwise. For this optional library, this call can be used to know if it is safe to use certain functions. For example:

    if ($pdf->LA_IPL() {
        # is installed and usable
    } else {
        # not available. don't use 16bps or interlaced PNG image files
    }
    

$gif = $pdf->image_gif($file, %opts)

Imports and returns a new GIF image object. $file may be either a filename or a filehandle.

See PDF::Builder::Resource::XObject::Image::GIF for additional information and "examples/Content.pl" for some examples of placing an image on a page (JPEG, but the principle is the same).

$gdf = $pdf->image_gd($gd_object, %opts)

Imports and returns a new image object from Image::GD.

See PDF::Builder::Resource::XObject::Image::GD for additional information and "examples/Content.pl" for some examples of placing an image on a page (JPEG, but the principle is the same).

COLORSPACE METHODS

$colorspace = $pdf->colorspace($type, @arguments)

Colorspaces can be added to a PDF to either specifically control the output color on a particular device (spot colors, device colors) or to save space by limiting the available colors to a defined color palette (web-safe palette, ACT file).

Once added to the PDF, they can be used in place of regular hex codes or named colors:

    my $pdf = PDF::Builder->new();
    my $page = $pdf->page();
    my $content = $page->graphics();
    # Add colorspaces for a spot color and the web-safe color palette
    my $spot = $pdf->colorspace('spot', 'PANTONE Red 032 C', '#EF3340');
    my $web = $pdf->colorspace('web');
    # Fill using the spot color with 100% coverage
    $content->fill_color($spot, 1.0);
    # Stroke using the first color of the web-safe palette
    $content->stroke_color($web, 0);
    # Add a rectangle to the page
    $content->rectangle(100, 100, 200, 200);
    $content->paint();
    $pdf->save('sample.pdf');
    

The following types of colorspaces are supported

$cs = $pdf->colorspace_act($file)

Returns a new colorspace object based on an Adobe Color Table file.

See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a reference to the file format's specification.

$cs = $pdf->colorspace_web()

Returns a new colorspace-object based on the "web-safe" color palette.

$cs = $pdf->colorspace_hue()

Returns a new colorspace-object based on the hue color palette.

See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an explanation.

$cs = $pdf->colorspace_separation($tint, $color)

Returns a new separation colorspace object based on the parameters.

$tint can be any valid ink identifier, including but not limited to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or 'Orange'.

$color must be a valid color specification limited to: '#rrggbb', '!hhssvv', '%ccmmyykk' or a "named color" (rgb).

The colorspace model will automatically be chosen based on the specified color.

$cs = $pdf->colorspace_devicen(\@tintCSx, $samples)

$cs = $pdf->colorspace_devicen(\@tintCSx)

Returns a new DeviceN colorspace object based on the parameters.

Example:

    $cy = $pdf->colorspace_separation('Cyan',    '%f000');
    $ma = $pdf->colorspace_separation('Magenta', '%0f00');
    $ye = $pdf->colorspace_separation('Yellow',  '%00f0');
    $bk = $pdf->colorspace_separation('Black',   '%000f');
    $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
    $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
    

The colorspace model will automatically be chosen based on the first colorspace specified.

BARCODE METHODS

OTHER METHODS

$xo = $pdf->xo_form()

Returns a new form XObject.

$egs = $pdf->egstate()

Returns a new extended graphics state object, as described in PDF::Builder::Resource::ExtGState.

$obj = $pdf->pattern(%opts)

Returns a new pattern object.

$obj = $pdf->shading(%opts)

Returns a new shading object.

$ndest = $pdf->named_destination()

Returns a new or existing named destination object.