Manual of Lua-ImageSize
Lua-ImageSize - Lua 5.1 module for getting the size of bitmap image files
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
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
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)
The table returned from
require "imagesize" will contain the following
- 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.
optionsis 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).
fileargument 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
stris examined instead of the content of a file.
The following file formats are supported, and return the specified MIME type:
Windows bitmap images,
GIF87a and GIF89a images or animations,
Accepts the option
gif_behavior(note the non-British spelling), which can take any of the following strings as its value:
Returns the size of the whole image, which should be large enough to accommodate all the frames of the animation.
Returns the size of the first frame, which may be smaller than the display size of the whole animation.
Returns the size of the largest frame in the animation.
The default value is
JFIF JPEG images,
Kodak Photo CD images,
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.
pcd_scalecan 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:
The default value is
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).
Macromedia Flash animations (SWF files),
Note that currently compressed SWF files are not supported (one which begins with the letters
X Bitmap images,
XCF images, usually used for saving a work-in-progress in The Gimp,
Note that currently these are only recognized when not compressed.
X Pixmap images,
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).
This Lua module was ported from the Perl Image::Size module by Geoff Richards. The Lua port and documentation is Copyright © 2008 Geoff Richards <geoff at this domain dot co dot uk>.
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.