NAME
App::PNGCrush - Perl wrapper around ``pngcrush'' program
SYNOPSIS
use strict;
use warnings;
use App::PNGCrush;
my $crush = App::PNGCrush->new;
# let's use best compression and remove a few chunks
$crush->set_options(
qw( -d OUT_DIR -brute 1 ),
remove => [ qw( gAMA cHRM sRGB iCCP ) ],
);
my $out_ref = $crush->run('picture.png')
or die "Error: " . $crush->error;
print "Size reduction: $out_ref->{size}%\n"
. "IDAT reduction: $out->{idat}%\n";DESCRIPTION
The module is a simple wrapper around ``pngcrush'' program. The program is free open source and you can obtain it from http://pmt.sourceforge.net/pngcrush/ on Debian systems you can find it in the repos: sudo -H apt-get install pngcrush
I needed this module to utilize only little subsection of pngcrush's functionality, if you would like some features added, I am more than open for suggestions.
CONSTRUCTOR
new
my $crush = App::PNGCrush->new;
my $crush = App::PNGCrush->new( max_time => 300 );Creates a new App::PNGCrush object. Arguments are optional and passed as key/value pairs with keys being Proc::Reliable methods and values being the values for those methods, here you can set some options controlling how pngcrush will be run. Generally, you'd worry only about max_time (which defaults to 300 seconds in App::PNGCrush) and set it to a higher value if you are about to process large images with brute force.
METHODS
run
my $results_ref = $crush->run('pic.png')
or die $crush->error;
my $results_ref = $crush->run('pic.png', opts => [ qw(custom stuff) ] );Instructs the object to run pngcrush. The first argument is mandatory and must be a filename which will be passed to pngcrush as input file. Takes one optional argument (so far), which is passed as key/value pair; the key being opts and value being an arrayref of custom options you want to give to pngcrush (those will bypass shell processing). Generally the custom options option is in here "just in case" and you are recommended to set options via individual methods or set_options() method (see below).
Returns either undef or an empty list (depending on the context) if an error occurred and the reason for the error will be available via error() method. On success returns a hashref with the following keys/values:
$VAR1 = {
'total_idat_length' => '1880',
'cpu' => {
'decoding' => '0.010',
'other' => '0.050',
'total' => '0.210',
'encoding' => '0.150'
},
'stderr' => '',
'status' => '0',
'idat' => '0.80',
'stdout' => '| pngcrush 1.6.4 .. blah blah full STDOUT here',
'size' => '1.56'
};size
{ 'size' => '1.56', }The size key will contain percentage of filesize reduction.
idat
{ 'idat' => '0.80', }The idat key will contain the percentage of IDAT size reduction.
total_idat_length
{ 'total_idat_length' => '1880', }The total_idat_length key will contain total length of data found in IDAT chunks.
cpu
'cpu' => {
'decoding' => '0.010',
'other' => '0.050',
'total' => '0.210',
'encoding' => '0.150'
},The cpu key will contain a hashref with with four keys: total, decoding, other and encoding with values being number of seconds it took to process.
stderr
{ 'stderr' => '', }The stderr key will contain any collected data from STDERR while pngcrush was running.
stdout
{ 'stdout' => '| pngcrush 1.6.4 .. blah blah full STDOUT here', }The stdout key will contain any collected data from STDOUT while pngcrush was running.
status
{ 'status' => '0' }The status key will contain the exit code of pngcrush.
error
my $ret_ref = $crush->run('some.png')
or die $crush->error;If run failed it will return either undef or an empty list depending on the context and the reason for failure will be available via error() method. Takes no arguments, returns a human parsable error message explaining why run failed.
results
my $results_ref = $crush->results;Must be called after a successful call to run(). Takes no arguments, returns the exact same hashref last call to run() returned.
set_options
$crush->set_options(
qw( -d OUT_DIR -brute 1 ),
remove => [ qw( gAMA cHRM sRGB iCCP ) ],
);Always returns a true value. Sets the options with which to run pngcrush. As argument takes a list of key/value pairs of either standard pngcrush options or more verbose names this module offers (see below). If you want to repeat certain option pass values as an arrayref, thus if on a command line you'd write pngcrush -rem gAMA -rem cHRM -rem sRGB ... you'd use ->set_options( '-rem' => [ qw( gAMA cHRM sRGB iCPP ) ] ).
Note: if pngcrush option does not take an argument you must give it a value of 1 when setting it via set_options() method. For -v option you can set it to value 2 to repeat twice (aka uber verbose). Same applies to individual option setting methods.
Note 2: call to set_options() will call reset_options() method (see below) before setting any of your options, thus whatever you don't specify will not be passed to pngcrush
reset_options
$crush->reset_options;Always returns a true value, takes no arguments. Instructs the object to reset all pngcrush options.
individual option methods
Module provides methods to set (almost) all pngcrush options individually You'd probably would want to use set_options() method (see above) in most cases. See set_options() method which describes how to repeat options and how to set options which take no arguments in pngcrush. The following is the list of methods (on the left) and corresponding pngcrush options they set (on the right); some options were deemed useless to the module and were not included (this is as of pngcrush version 1.6.4):
already_size -already
bit_depth -bit_depth
background -bkgd
brute_force -brute
color_type -c
color_counting -cc
output_dir -d
double_image_gamma -dou
output_extension -e
filter -f
fix_fatal -fix
output_force -force
gamma -g
itxt -itxt
level -l
method -m
maximum_idat -max
no_output -n
no_color_counting -no_cc
plte_length -plte_len
remove -rem
replace_gamma -replace_gamma
resolution -res
save_unknown -save
srgb -srgb
text -text
transparency -trns
window_size -w
strategy -z
insert_ztxt -zitxt
ztxt -ztxt
verbose -vSee pngcrush manpage (man pngcrush or pngcrush -v) for descriptions of these options.
Out of those listed above the following pngcrush options do not take arguments, thus to set these you'd need to pass 1 as an argument to the option setting method (except for verbose which can take a value of 2 to indicate double verboseness (equivalent to passing -v -v to pngcrush)
brute_force
color_counting
double_image_gamma
fix_fatal
output_force
no_output
no_color_counting
save_unknown
verboseproc
my $proc_reliable_obj = $crush->proc;
$crush->proc( Proc::Reliable->new );Returns a currently used Proc::Reliable object used under the hood, thus you could dynamically set arguments as $crush->proc->max_time(300). When called with an argument it must be a Proc::Reliable object which will replace the currently used one (and you just SOO don't wanna do this, do you?)
AUTHOR
Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)
BUGS
Please report any bugs or feature requests to bug-app-pngcrush at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-PNGCrush. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc App::PNGCrushYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
COPYRIGHT & LICENSE
Copyright 2008 Zoffix Znet, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.