The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Image-ThousandWords-0.10
++
/ Image::ThousandWords

NAME

Image::ThousandWords - convert an image to colored HTML text

SYNOPSIS

        use Image::ThousandWords;
        my $html = Image::ThousandWords::html(
                image_path      => 'image.jpg',
                text            => 'TurnMeIntoAnImage',
        };
        print "<html><body bgcolor='white'>$html</body></html>\n\n";
        exit;

Or:

        use Image::ThousandWords;
        my $o = Image::ThousandWords->new(
                text    => $text,
                image_path => 'shakespeare.jpg',
                whitespace      => ' ',
                line_ends       => '<font color=red>&bull;</font>',
                font_size  => 20,
                auto_size => 1,
                size    => 400,
                font_face       => "'Courier New'",
        );
        $html = $o->html;
        print "Content-type:text/html\n\n", $o->wrap_html(background=>'black');

See the file test.pl for examples of use>.

DESCRIPTION

This module is designed to take as input the path to an image file, and a string of text, and return an HTML colored text, resembling the image made out of the string, repeated as necessary.

Henning Møller-Nielsen wrote the original, Lee Goddard modified it slightly.

Henning said,

        The inspiration I got from http://www4.telge.kth.se/~d99_kme/
        look at http://rto.dk/images/camel.html or http://rto.dk/images/llama.html for the first versions
        (and I look like this: http://rto.dk/images/henning.htm)

Lee adds:

        Modified by Lee Goddard (lgoddard-at-cpan.org) 2003, and again 15 February 2004
        - I did send Henning the mod, but he didn't publish it; I lost it, rewrote it
        and didn't want to re-write it again. Module now has more parameters, and more
        control over the HTML, using a combination of CSS and image resizing (the latter
        being one of Henning's original requests).

See the file test.pl for examples of use>.

DEPENDENCIES

        Carp
        GD
        Image::Thumbnail
        HTML::Entities
        Image::Size

CONSTRUCTOR html

Returns a HTML formatted string, colored to resemble IMAGE. The string consists of the letters and characters from STRING.

Accepts parameters as a hash, list or hash-reference:

image_path

Path to the file to convert. Must be openable by your version of GD. If you don't supply this, you must supply thumb as a GD image.

thumb

If you do not supply image_path (above), you must supply this as a loaded GD image.

size

The length in pixels of the largest size of the image when re-sized prior to conversion to text. Default is 100.

auto_size

If set, experimentally tries to re-size the output to be the same size, in pixels, as the input. If supplied, don't bother with font_size or line_height (below), but maybe use size (above).

So, if you supply size as well as auto_size, you are requesting the output to the be size in pixels, the number of characters in each row being determind by font_size

If you supply size without auto_size, then size specifies the number of characters per row.

text

Text to use in conversion of the file. Default is aPictureIsWorthAThousandWords, so you'd better supply your own. Note that whitesapce will be stripped.

whitespace

If you don't supply this at all, all whitespace will be removed. If you do supply this, all whitespace will be substituted for whatever this whitespace value is. Intention is that you'll supply a single space to maintain whitespace - or some character to maintain spacing and colouring. See also line_ends below.

line_ends

Replace line terminators [\n\r\f] with this string: may be multiple characters. By default this paramter is set to whatever whitespace is set to - setting this parameter over-rides the effets of the former parameter on line terminators.

font_face

String to use in the HTML, which will be quoted in "double-quotes". Defaults to 'Arial Black','Lucida Console','Courier New', Courier'.

font_size

Number of pixels for the size of the font used: default is 8.

line_height

Number of pixels for the height of a line of text. Default value is two pixels less than the font_size.

scanline_skip

You shuldn't need this, but... The number of scan-lines or rows to skip jump in each read of the image. The default is to read every line, which is a scanline_skip of 1 - not a very clear name, sorry. Check the relation of this to the line_height parameter, above.

See the file test.pl for examples of use>.

METHOD wrap_html

Convenience method to return the result field wrapped in HTML to make a complete page. Accepts values valid for CSS in the parameter background, and text in the title (which is otherwise inherited from the calling object) or the image_path.

Sets the title field and returns an HTML page.

BACKWARDS COMPARABILITY

The original ThousandWords module's giveme method is still acceptable.

EXAMPLES FROM HENNING:

Made with the v. 0.01 (just a script, inspired by http://www4.telge.kth.se/~d99_kme/)

        http://rto.dk/images/camel.html
        http://rto.dk/images/llama.html
        http://rto.dk/images/henning.html (me)

Made with the v. 0.03

        http://rto.dk/images/neptune.html
        http://rto.dk/images/mars.html
        http://rto.dk/images/pluto_charon.html
        http://rto.dk/images/earth.html
        http://rto.dk/images/saturn.html
        http://rto.dk/images/jupiter.html (here the reason for v. 0.04 is apparent)
        http://rto.dk/images/ira1.html
        http://rto.dk/images/ira2.html (my colleagues)

KNOWN BUGS

None, from a perl perspective. From an image perspective things look different :-)

AUTHOR ETC.

Henning Michael Møller-Nielsen, hmn -at- datagraf.dk

Slightly modified by Lee Goddard, lgoddard -at- cpan.org

VERSION HISTORY

A bit of an overkill, but hey - this is Fun!

0.01 Not really a module, just a script 0.02 'ThousandWords.pm' came to life 0.03 Fixed an error so the first text in a black image wouldn't be white 0.04 Fixed an error so the first text in a black image wouldn't be larger than the rest and so spaces no longer would be used 0.05 Ah - added POD 0.06 Lee added: re-sizing of image; new access method; proper HTML entities 0.07 Sod it - full OO interface, more re-sizing, line-feeds/whitespace 0.08 Fixed MANIFEST for test.pl

Future:

        ANSI colored text?

        Work on the 'size' field

SEE ALSO

ThousandWords, Image::Thumbnail, GD.

See the file test.pl for examples of use>.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 45:

Non-ASCII character seen before =encoding in 'Møller-Nielsen'. Assuming CP1252