Image::Magick::Thumbnail::PDF - make thumbnail of a page in a pdf document
use Image::Magick::Thumbnail::PDF 'create_thumbnail'; my $out = create_thumbnail('/home/myself/mypdfile.pdf');
I wanted a quick sub to make a thumbnail of a pdf. The goal of this module is to make a quick thumbnail of a page in a pdf.
They give the viewer an idea of what is inside the document, but is not meant as a replacement for the actual file.
This module is a quick interface to a predetermined use of convert. There are a ton of ways to do this via ImageMagick and convert, etc. I took what seemed to make most sense from various suggestions/ideas, and slapped this together. If you think something can be better, please contact the AUTHOR.
No subroutines are exported by default.
You must import as:
use Image::Magick::Thumbnail::PDF 'create_thumbnail'; my $abs_thumb = create_thumbnail('/abs/path/to.pdf');
Or you can do this also:
Image::Magick::Thumbnail::PDF; my $abs_thumb = Image::Magick::Thumbnail::PDF::create_thumbnail('/abs/path/to.pdf');
The second example is a lot of text but improves legibility in a lot of code.
By default this will make a normalized thumbnail with a 6 pixel light grey border, 125 pixel max height and 125 pixel max width png image, which in the above example returns '/abs/path/to-001.pdf'.
The subroutine create_thumbnail() takes 1 required argument and optionally 4 arguments in any order. The first argument must always be the pdf file you want to make a thumbnail of.
Absolute path to the pdf you want to make a thumbnail for. Required. This is the only required argument. Will not check if the thumbnail exists already or not.
Absolute path you want the thumbnail to be output to (the destination). Optional. By default, it is the same as the first argument but the .pdf is replaced with a .png extension.
A page number. Optional. Default is page 1. There is no page 0. Furthermore, if instead of a number you providing the string 'all_pages', will trigger to make a thumbnail of each page and return an array ref with absolute paths to each thumbnail.
Hash ref. Optional. Hash ref with one or more of the following keys and values:
Boolean. Default is true. This increases contrast and makes thin lines appear thicker.
Number. Default is 6. Places light grey frame border around the image.
Number. Default is 125. This is the maximum pixels tall and wide the thumbnail will be. Regardless of what the frame is set to, your thumbnail will fall within these dimensions. If you pass false, it will default to 125.
Number. This will set JPEG/MIFF/PNG compression level. No default set- if no value is set, this is not performed. If your thumbnails occupy too much space, you may want to use this. This only really worls well with jpg.
If you are making one thumbnail: Returns absolute path of the thumbnail made.
If you are making all pages: Returns array ref with absolute paths of all thumbnails made.
If the subroutine is provided really dumb arguments, it croaks. Otherwise it carps and returns undef on failures.
The following example creates /abs/file-000.png 125x125 thumbnail image of first page.
create_thumbnail('/abs/file.pdf');
To create a thumb for page 5 instead:
create_thumbnail('/abs/file.pdf',5); # creates '/abs/file-005.png'
To create a thumb for page 6 with restriction 200, a frame of 2 px, and no normalize:
create_thumbnail( '/abs/file.pdf', 6, { restriction => 200, frame => 2, normalize => 0, }, ); # creates '/abs/file-006.png'
To save a thumbnail of page 3 named differently, in another palce
create_thumbnail( '/abs/file.pdf', '/abs/another/page3.png', 3, { restriction => 200, frame => 2, normalize => 0 }, ); # creates '/abs/file-006.png'
To make all thumbnails of all pages:
my $all = create_thumbnail('/abs/file.pdf','all_pages'); # $all = [ '/abs/file-001.png', '/abs/file-002.png', '/abs/file-003.png' ];
A default thumbnail is about 3k, If you ask to output a jpg and set quality to 30, you get a low quality 0.9 k image:
my $out = create_thumbnail('/abs/file.pdf','/abs/file.jpg', { quality => 30 });
Ok, you don't like having file-002.png as a thumbnail name.. You want file_page2.png :
my $out = create_thumbnail('/abs/file.pdf',2,'/abs/file_page2.png');
Beware! The following examples fo NOT make a thumbnail of page 2 :
create_thumbnail('/abs/file.pdf','/abs/file_page2.png'); create_thumbnail('/abs/file.pdf',3,'/abs/file_page2.png');
Remember that to make a thumbnail of ANY page other then page 1, you must specify 'all_pages' or pass a number as argument.
These options are provided because a lot of pdfs are hard copy documents scanned in and turned into pdf. This kind of document is by and large (by the thousands of documents I see fly by our network) very popular, and usually white paper space with scant black text. When it sizes down, you see nothing! So, by default, normalize is set to true, and a 6 pixel light grey border is added to the thumbnail. This is a dramatic improvement for thumbnails of such documents.
Normalize is used to accentuate lines. This creates an extra step in the process, the image is sized down about halfway between the target size and the original size, the filter is applied, and then resized down again. So- if you do or do not use normalize (on by default) you will see a large change in time taken.
In the following example, turn normalize to false and the frame border to nothing;
create_thumbnail('/path/to/my.pdf',{ normalize => 0, frame => 0 });
I strongly encourage to try the defaults first.
This can be slow! This can be useful offline, but I don't suggest it real-time. If this is being used in some cgi, consider forking. You try it out.
The following example makes all thumbnails:
my $all = create_thumbnail('/abs/file.pdf','all_pages');
The returned value is an array ref holding ['/abs/file-001.png', '/abs/file-002.png', '/abs/file-003.png'].
GIF spit out all thumbs of all pages into one gif. NOT IMPLEMENTED presently.
The following example makes '/abs/file.gif', which is an animated gif with heach frame being a page in the document.
create_thumbnail('/abs/file.pdf','all_pages','/abs/file.gif');
If you make all thumbnails and specify as output a .gif file, the output image is an animated gif, with each page in its own frame. This may or may not be what you desire.
Note that if you enable debugger
$Image::Magick::Thumbnail::PDF::DEBUG = 1;
You will see that a restriction of 125 changes to 113.. how come? Because we compensate for the frame size. Asking for a thumbnail no wider or taller then 125 px gives you just that.
The arguments can be provided in any order. I read somewhere that good code is liberal in what it receives as input and conservative in its output- kind of what 'people' should be like.
There are three ghostscripts out there, ESP Ghostscript, AFPL Ghostscript, and GNU Ghostscript.
Image::Magick Image::Magick::Thumbnail Smart::Comments File::Which Carp ESP Ghostscript, NOT AFPL Ghostscript, this is tested for.
ImageMagick on the web, convert. Image::Magick::Thumbnail
Leo Charre leocharre at cpan dot org
Copyright (c) 2009 Leo Charre. All rights reserved.
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".
This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the "GNU General Public License" for more details.
To install Image::Magick::Thumbnail::PDF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Image::Magick::Thumbnail::PDF
CPAN shell
perl -MCPAN -e shell install Image::Magick::Thumbnail::PDF
For more information on module installation, please visit the detailed CPAN module installation guide.