Manual of Lua-ImageSize

Lua-ImageSize - Lua 5.1 module for getting the size of bitmap image files

Description

This module can tell you the size in pixels of bitmap images in various formats, as well as what file format they are in. It's a small module which only knows how to extract the size information from image files, not a full graphics library. It is written in pure Lua, so doesn't require any compilation, and it doesn't depend on any other Lua modules.

Loading the module

The ImageSize module doesn't install itself into any global tables, so you can decide what name you want to use to access it. You will probably want to load it like this:

local ImageSize = require "imagesize"

You can use a variable called something other than ImageSize if you'd like, or you could assign the table returned by require to a global variable. In this documentation we'll assume you're using a variable called ImageSize.

Finding the size of an image

To get the size and type of an image stored in a file on disk:

local width, height, format = ImageSize.imgsize(filename)

The width and height will be integer numbers, and the format will be a string containing a MIME type (often an unofficial one like image/x-xpixmap).

If the file can't be read, is in an unrecognized format, or is corrupted, then the width and height will be nil, and the format will be replaced by an error message. If you want to detect errors, use this idiom:

local width, height, format = ImageSize.imgsize(filename)
assert(width, "error getting size of image: " .. format)

Instead of a filename you can also pass an open file handle in to the imgsize function. It must support seeking. It's current position will be restored before the function returns.

You can also get the size of an image file stored in a string, using the alternative function imgsize_string, like this:

local file = assert(io.open(filename, "rb"))
local data = file:read("*a")
file:close()

local width, height, format = ImageSize.imgsize_string(data)

Functions

The table returned from require "imagesize" will contain the following functions:

imgsize(file, [options])

Reads data from file (either a string containing a filename, or a Lua file handle), and if possible returns three values, the width, height, and MIME type of the image. If there is any kind of error then the three values returned will be nil, nil, and a string describing the error.

If options is present it must be a table of values to tune how certain file formats are treated. The options available are documented in the section ‘File formats’ below. If an option has an invalid value then an error will be raised (this being the only kind of error which will be returned as an exception rather than with return values).

The file argument can also be a file handle created by the lua-memoryfile(3) module.

imgsize_string(str, [options])

This behaves identically to imgsize, except that the binary data in the string str is examined instead of the content of a file.

File formats

The following file formats are supported, and return the specified MIME type:

BMP

Windows bitmap images, image/x-ms-bmp

GIF

GIF87a and GIF89a images or animations, image/gif

Accepts the option gif_behavior (note the non-British spelling), which can take any of the following strings as its value:

screen: Returns the size of the whole image, which should be large enough to accommodate all the frames of the animation.
first: Returns the size of the first frame, which may be smaller than the display size of the whole animation.
largest: Returns the size of the largest frame in the animation.

The default value is screen.

JPEG

JFIF JPEG images, image/jpeg

MNG

MNG animations, video/x-mng

PCD

Kodak Photo CD images, image/x-kodak-photocd

Note that the code for this hasn't been tested since it was ported from Perl, because I can't find any PCD images anywhere to test against.

The option pcd_scale can be used to select the scale at which the image should be decompressed. It seems that PCD images don't have a single intrinsic size, or perhaps have several, so there's no one right answer to this. The acceptable values for this option are:

base/16
base/4
base
base4
base16
base64

The default value is base.

PNG

PNG images, image/png

PNM

Any of the ‘portable anymap’ formats: PPM (image/x-portable-pixmap), PGM (image/x-portable-graymap), or PBM (image/x-portable-bitmap). Also supported are the thumbnail files generated by XV (image/x-xv-thumbnail, a MIME type I invented for this purpose).

PSD

Photoshop images, image/x-photoshop

Flash

Macromedia Flash animations (SWF files), application/x-shockwave-flash

Note that currently compressed SWF files are not supported (one which begins with the letters CWS rather than FWS).

TIFF

TIFF/TIF images, image/tiff

XBM

X Bitmap images, image/x-xbitmap

XCF

XCF images, usually used for saving a work-in-progress in The Gimp, application/x-xcf

Note that currently these are only recognized when not compressed.

XPM

X Pixmap images, image/x-xpixmap

Copyright

Copying and distribution are permitted under the terms of the Artistic License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php) or the GNU LGPL (http://www.opensource.org/licenses/lgpl-license.php).

The original Perl module was written by Randy J. Ray <“rjray” at domain “blackperl.com”>, based on image-sizing code by Alex Knowles <“alex” at domain “ed.ac.uk”> and Andrew Tong <“werdna” at domain “ugcs.caltech.edu”>, used with their joint permission.

Many bug fixes and patches were provided by other people. See the documentation for the Image::Size Perl module for details.