Image::Size - Determine the size of images in several common formats

Version: 2.9 (See CHANGE HISTORY below)

NOTE: Version 2.9 fixes a bug in the newly-added BMP support from 2.8. The
      2.8 files will be marked for deletion from CPAN. Use this version,
      instead.

WHAT IS IT

Image::Size is a library based on the image-sizing code in the wwwimagesize
script, a tool that analyzes HTML files and adds HEIGHT and WIDTH tags to
IMG directives. Image::Size has generalized that code to return a raw (X, Y)
pair, and included wrappers to pre-format that output into either HTML or
a set of attribute pairs suitable for the CGI.pm library by Lincoln Stein.
Currently, Image::Size can size images in XPM, XBM, GIF, JPEG, PNG, TIFF
and the PPM family of formats (PPM/PGM/PBM).

I did this because my old WWW server generated a lot of documents on demand
rather than keeping them in static files. These documents not only used
directional icons and buttons, but other graphics to annotate and highlight
sections of the text. Without size attributes, browsers cannot render the
text of a page until the image data is loaded and the size known for layout.
This library enables scripts to size their images at run-time and include
that as part of the generated HTML. Or for any other utility that uses and
manipulates graphics. The idea of the basic interface + wrappers is to not
limit the programmer to a certain data format.


USING Image::Size IN YOUR SCRIPTS

Image::Size has pod documentation that gives a more complete overview, but
in a nutshell:

        use Image::Size;

        ($x, $y) = imgsize("something.gif");

And ($x, $y) is now the width and height of something.gif. 95% of my usage of
this library is in conjunction with Lincoln Stein's CGI.pm:

        use CGI ':all';
        use Image::Size 'attr_imgsize';

        #
        # Emit an IMG tag with size attributes:
        #
        print img({-SRC => '/server/images/arrow.gif',
                   attr_imgsize('/server_root/server/images/arrow.gif')});


BUILDING/INSTALLING

This package is set up to configure and build like a typical Perl extension.
To build:

        perl Makefile.PL
        make && make test

If Image::Size passes all tests, then:

        make install

You may need super-user access to install.


PROBLEMS/BUG REPORTS

Please send any reports of problems or bugs to rjray@tsoft.com.


CREDITS AND LICENSES

This package is copyright © 1996,1998 by Randy Ray (rjray@tsoft.com) and may be
distributed under terms of the Artistic License used to cover Perl itself.
See the file Artistic in the distribution of Perl 5.002 or later for details
of copy and distribution terms.

Perl module interface by Randy J. Ray (rjray@tsoft.com), original
image-sizing code by Alex Knowles (alex@ed.ac.uk) and Andrew Tong
(werdna@ugcs.caltech.edu), used with their joint permission.

Some bug fixes submitted by Bernd Leibing <bernd.leibing@rz.uni-ulm.de>.
PPM/PGM/PBM sizing code contributed by Carsten Dominik
<dominik@strw.LeidenUniv.nl>. Tom Metro <tmetro@vl.com> re-wrote the JPG
and PNG code, and also provided a PNG image for the test suite. Dan Klein
<dvk@lonewolf.com> contributed a re-write of the GIF code. Cloyce Spradling
<cloyce@headgear.org> contributed the TIFF sizing code and test images.
A fix for reading binary data on PC-ish operating systems was contributed by
Silas Dunsmore <silasd@psyber.com>. Aldo Calpini <a.calpini@romagiubileo.it>
sent in code that was easily adapted to support BMP images (Windows bitmaps).
Fix for a recurring problem with GIF87a files contributed by Matthias Schmitt
<matthias.schmitt@mmp.lu>. Fix for problems with PPM formats on some Win32
versions was contributed by Randy Kobes <randy@theory.uwinnipeg.ca>.


CHANGE HISTORY

This is version 2.9:

* Support for BMP format in 2.8 was marred by a byte-ordering problem not
  found in testing since my Linux and Windows machines are both Intel-based.
  Sorry.

* Added a contributed fix for a recurring problem with GIF87a images that
  have descriptors similar to GIF89a.

* Added a contributed fix to the PPM matching (prior to actual selection for
  sizing) that was caused by some Win32 versions of Perl not handling "\n"
  natively.

* While at that last one, I made an attempt to fix any MacOS concerns that
  may be triggered by the same consideration.

* Added better error handling to the imgsize script and added a little more
  to the manual page.

Initial version 1.0:

* Library model for sizing code from wwwimagesize. By this, I also include
  the extension-style infrastructure, MakeMaker usage, test suite, etc.

* Changed format of returned data to generic (X, Y), added wrappers to format
  into "WIDTH=x HEIGHT=y" HTML-style and (-WIDTH => x, -HEIGHT => y) CGI-style.

* Added cacheing of sizes based on passed-in file name. I have one CGI script
  that uses a given icon for a bullet list, with 35+ items in the list...

* UNDOCUMENTED UNTIL BETTER TESTED: Optional second argument to imgsize can
  be either scalar or a code ref; if scalar, is pasted in front of file name
  as a directory component; if it is a code ref, the routine is called with
  the file name as a single argument and is expected to return the full path
  name. Kind of clunky right now, easier to just pass in the full path to
  begin with.

* Added the XPM sizing myself, though I have yet to use it (I do test it in
  the test suite, though).

Changes in 1.1:

* Added a small, simple script called "imgsize" that gives command-line access
  to the library functionality.

* Discovered and fixed bug in sizing JPEGs.

Changes in 1.2:

Two fixes given to me by Bernd Leibing <bernd.leibing@rz.uni-ulm.de>:

* Fixed bug caused by perl quoting and RCS in Size.pm

* imgsize now comes as imgsize.PL and is auto-extracted as part of the make,
  utilizing your system's configuration to create the start-up #! line.

Changes in 2.0:

* No longer uses filenames to determine image format for examination.

* Can operate on already-open IO::File objects.

* Can operate on in-memory data strings (buffers).

* Documentation overhauled.

* imgsize() now returns an ignorable third parameter. This value is a three-
  letter identifier of the image format (using the standard suffixes. Useful
  when sizing unknown data to also type the image.

* Support for the PPM family (PPM, PGM and PBM) of formats.

* JPG code extensively re-written and simplified.

* PNG code re-written.

* Test cases for PNG and PPM added. Test cases also cover the open-file and
  in-memory capabilities.

* Dropped the "optional second argument" thing in the invocation; no one used
  it, and it was confusing and difficult to explain clearly.

* Various typos cleaned up.

Changes in 2.1:

* Added in changes to the error handling that were meant for 2.0.

* Fixed a bug in attr_imgsize caused by the new return format.

Changes in 2.2:

* Added calls to binmode on filehandles, for the sake of OS flavors such as
  OS/2, etc.

* Cleaned up a new -w warning present in late versions of 5.003 (leading in
  to 5.004).

Changes in 2.3:

* Small fix to the regular expression in xpmsize.

* Changed syntax of utilizing AutoLoader to conform to changes in upcoming
  5.004 release.

Changes in 2.4:

* Small bug in jpegsize, not returning the string 'JPG' as the third element
  of the returned list. Figures I have a half-documented feature, and someone
  actually uses it. :-)

Changes in 2.5:

* Added support for TIFF images and two test cases. Many thanks to Cloyce
  Spradling <cloyce@headgear.org> for both the code patches and the test
  images.

Changes in 2.6:

* 2.5 did not actually deliver the tests for the new TIFF code. Oops.

* Found some variations of the formats of XPM and XBM that were not
  compatible with the regex's being used. Tricky, flexible little devils,
  especially XPM.

Changes in 2.7:

* Corrected numerous documentation bugs in which I repeatedly referred to the
  X and Y dimensions in the wrong order. This was pointed out by several
  people, but I also kept forgetting to attend to it.

* The base routine imgsize now returns a null list when called in a void
  or scalar context. Mainly, I like pre-loading the cache under mod_perl in
  Apache (so that spawned children inherit the cache) and didn't like the
  idea of all those calls populating a stack that was then ignored.

Changes in 2.8:

* Added support for BMP-format files. CR/LF translation between UNIX and
  Windows machines should not affect this, but please let me know if there
  are problems.
