=head1 NAME

Image::PNG::FileConvert - put a file into a PNG image

=head1 SYNOPSIS

    
    use File::Compare;
    use Image::PNG::FileConvert qw/file2png png2file/;
    # Convert a data file into a PNG image
    file2png ('myfile.txt', 'myfile.png');
    # Extract a data file from a PNG image
    png2file ('myfile.png', name => 'newfile.txt');
    if (compare ('myfile.txt', 'newfile.txt') == 0) {
        print "Round trip OK\n";
    }


produces output

    Round trip OK


(This example is included as L<F<synopsis.pl>|https://fastapi.metacpan.org/source/BKB/Image-PNG-FileConvert-0.10/examples/synopsis.pl> in the distribution.)

=head1 VERSION

This documents version 0.10 of Image::PNG::FileConvert
corresponding to git commit L<b5e49fd8e14684145965c2f5b41d0c9e9492e91a|https://github.com/benkasminbullock/Image-PNG-FileConvert/commit/b5e49fd8e14684145965c2f5b41d0c9e9492e91a> released on Sat Oct 14 16:31:45 2017 +0900.

=head1 DESCRIPTION

This module can convert any arbitrary data file, either binary or
text, into a PNG image. PNG (Portable Network Graphics) is a lossless
image format. (See L<Image::PNG::Libpng/SEE ALSO> for details about
the PNG format.)  Lossless means that there is no loss of data;
whatever data is put into the original image can always be recovered
exactly. This module takes advantage of that to use PNG image format
to store arbitrary data under the guise of a PNG image.

This module is very simplistic, and should be considered an example of
the use of L<Image::PNG::Libpng>. If you need to do more complex
things than this module provides, please consider reading the source
code of this module as a starting point for making your own functions.

=head1 FUNCTIONS

=head2 file2png

    file2png ('myfile.txt', 'myfile.png');

Convert C<myfile.txt> into a PNG graphic. The function uses the data
from myfile.txt to write a greyscale (black and white) image. The
bytes of the file correspond to the pixels of the image.

When this PNG is unwrapped using L</png2file>, it will be called
C<myfile.txt> again. If you want to specify a different name,

    file2png ('myfile.txt', 'myfile.png',
              { name => 'not-the-same-name.txt' });

and the file will be unwrapped into C<not-the-same-name.txt>.

If you want your PNG to have a different width than the default, there
is another option, C<row_length>, specified in the same way:

    file2png ('myfile.txt', 'myfile.png', { row_length => 0x100 });

The number you specify for C<row_length> will be the width of the
image in pixels. If this is not specified, the row length is given by
C<default_row_length> in the module, which is 2048
as of version 0.10 of this module.

=head2 png2file

    png2file ('myfile.png');

Convert C<myfile.png> into a data file. C<myfile.png> must be a PNG
created using L</file2png>. The file is stored in whatever the name of
the file given to L</file2png> was.

This only converts PNG files output by L</file2png>, not general PNG
files. L</file2png> uses the text segment of the PNG image to store
the name and number of bytes of the original data, and without that
the data cannot be recovered.

An option "name" overrides the file name used in the input:

    file2png ('file.png', name => 'another-name.txt');

=head1 SEE ALSO

For more information about the PNG format itself, see
L<Image::PNG::Libpng/SEE ALSO>.

Other CPAN modules with a similar function to Image::PNG::FileConvert include

=over

=item Acme::Steganography::Image::Png

L<Acme::Steganography::Image::Png> hides data in a PNG image.

=item Image::PNG::Write::BW

L<Image::PNG::Write::BW> creates minimal black and white PNG files
from user data.

=back

=head1 DEPENDENCIES

=over

=item Image::PNG::Libpng

L<Image::PNG::Libpng> is used for all the PNG reading and writing
functions.

=item Carp

L<Carp> is used to report errors.

=back

=head1 SCRIPTS

The distribution also includes two utility scripts, file2png and
png2file, which convert a file to a PNG image and back again.


=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head1 COPYRIGHT & LICENCE

This package and associated files are copyright (C) 
2011-2017
Ben Bullock.

You can use, copy, modify and redistribute this package and associated
files under the Perl Artistic Licence or the GNU General Public
Licence.



