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                 -v

See 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
    verbose

proc

    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::PNGCrush

You can also look for information at:

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.