NAME

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

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 synopsis.pl in the distribution.)

VERSION

This documents version 0.10 of Image::PNG::FileConvert corresponding to git commit b5e49fd8e14684145965c2f5b41d0c9e9492e91a released on Sat Oct 14 16:31:45 2017 +0900.

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 "SEE ALSO" in Image::PNG::Libpng 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 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.

FUNCTIONS

file2png

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

Convert 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 "png2file", it will be called 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 not-the-same-name.txt.

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

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

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

png2file

    png2file ('myfile.png');

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

This only converts PNG files output by "file2png", not general PNG files. "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');

SEE ALSO

For more information about the PNG format itself, see "SEE ALSO" in Image::PNG::Libpng.

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

Acme::Steganography::Image::Png

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

Image::PNG::Write::BW

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

DEPENDENCIES

Image::PNG::Libpng

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

Carp

Carp is used to report errors.

SCRIPTS

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

AUTHOR

Ben Bullock, <bkb@cpan.org>

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.