Lua bindings to ImageMagick's MagicWand or GraphicsMagick's Wand for LuaJIT using FFI.
You'll need both LuaJIT (any version) and MagickWand or GraphicsMagickinstalled.
On Ubuntu, to use ImageMagick, you might run:
$ sudo apt-get install luajit
$ sudo apt-get install libmagickwand-dev
You can install GraphicsMagick in place of, or alongside, ImageMagick:
$ sudo apt-get install libgraphicsmagick1-dev
It's recommended to use LuaRocks to install magick.
$ sudo apt-get install luarocks
$ luarocks install magick
If you just need to resize/crop an image, use the thumb
function. It provides
a shorthand syntax for common operations.
local magick = require("magick")
magick.thumb("input.png", "100x100", "output.png")
The second argument to thumb
is a size string, it can have the following
kinds of values:
"500x300" -- Resize image such that the aspect ratio is kept,
-- the width does not exceed 500 and the height does
-- not exceed 300
"500x300!" -- Resize image to 500 by 300, ignoring aspect ratio
"500x" -- Resize width to 500 keep aspect ratio
"x300" -- Resize height to 300 keep aspect ratio
"50%x20%" -- Resize width to 50% and height to 20% of original
"500x300#" -- Resize image to 500 by 300, but crop either top
-- or bottom to keep aspect ratio
"500x300+10+20" -- Crop image to 500 by 300 at position 10,20
If you need more advanced image operations, you'll need to work with the
Image
object. Read on.
All functions contained in the table returned by require("magick")
.
Loads and resizes image. Write output to out_fname
if provided, otherwise
return image blob. (input_fname
can optionally be an instance of Image
)
Return a new Image
instance, loaded from filename. Returns nil
and error
message if image could not be loaded.
Loads an image from a Lua string containing the binary image data.
Calling load_image
or load_image_from_blob
returns an Image
object.
local magick = require "magick"
local img = assert(magick.load_image("hello.png"))
print("width:", img:get_width(), "height:", img:get_height());
img:resize(200, 200)
img:write("resized.png")
Images are automatically freed from memory by LuaJIT's garbage collector, but
images can take up a lot of space in memory when loaded so it's recommended to
call destroy
on the image object as soon as possible.
ImageMagick and GraphicsMagick implement the same interface. By default the
magick
module will include ImageMagick. You can specify which library you use
by calling require
on the module for the appropriate library. At the moment
it's impossible to include both libraries into the same process due to
collision of function names in the C namespace.
Load ImageMagick directly:
magick = requrie "magick.wand"
local img = magick.load_image("some_image.png")
Load GraphicsMagick directly:
magick = requrie "magick.gmwand"
local img = magick.load_image("some_image.png")
Note: not all methods on Image for ImageMagick are available in GraphicsMagick right now. Pull requests welcome.
Methods mutate the current image when appropriate. Use clone
to get an
independent copy.
Resizes the image, f
is resize function, see Filer Types
Resizes the image using adaptive resize
Crops image to w
,h
where the top left is x
, y
Blurs the image with specified paramaters. See Blur Arguments
Rotates the image by specified number of degrees. The image dimensions will
enlarge to prevent cropping. The triangles on the corners are filled with the
color specified by r
, g
, b
. The color components are specified as
floating point numbers from 0 to 1.
Sharpens the image with specified parameters. See Sharpening Images
Resizes the image to w
,h
. The image will be cropped if necessary to
maintain its aspect ratio.
Returns Lua string containing the binary data of the image. The blob is
formatated the same as the image's current format (eg. PNG, Gif, etc.). Use
image:set_format
to change the format.
Writes the the image to disk
Gets the width of the image
Gets the height of the image
Gets the current format of image as a file extension like "png"
or "bmp"
.
Use image:set_format
to change the format.
Sets the format of the image, takes a file extension like "png"
or "bmp"
Gets the image compression quality.
Sets the image compression quality.
Gets the image gravity type.
Sets the image's gravity type:
gravity
can be one of the values listed in data.moon
Returns all the option names that match the specified pattern associated with a
image (e.g img:get_option("webp", "lossless")
)
Associates one or options with the img (e.g img:set_option("webp", "lossless", "0")
)
Scale the size of an image to the given dimensions.
Coalesces the current image by compositing each frame on the previous frame. This un-optimized animated images to make them suitable for other methods.
Composite another image onto another at the specified offset x
, y
.
compose
can be one of the values listed in data.moon
Strips image of all profiles and comments, useful for removing exif and other data
Get the r,g,b,a color components of a pixel in the image as doubles from 0
to 1
Returns a copy of the image.
Adjust the brightness, saturation, and hue of the image. See Modulate Brightness, Saturation, and Hue
Mutates the image to be a thumbnail. Uses the same size string format described at the top of this README.
Immediately frees the memory associated with the image, it is invalid to use the image after calling this method. It is unecessary to call this method normally as images are tracked by the garbage collector.
Tests use Busted. Install and execute the
following command to run tests. You can check the output in
spec/output_images/
.
$ busted
- Add
get_depth
andset_depth
to GraphicsMagick & ImageMagick
- Add
reset_page
to GraphicsMagick - Add
get_format
andset_format
to GraphicsMagick
- Add modulate (@granpc)
- Add more methods to graphics magick: composite, clone, blur (@granpc)
- Add reset page to imagemagick wand (@thierrylamarre)
- Clone method is uses the clone function provided by image magick, garbage collects new image
- Add
thumb
method on the image class
- Add preliminary GraphicsMagick support
- Fix bug with gravity getter/setter (@ram-nadella)
- Add additional wand method: leafo#32 (@sergeyfedotov)
- add automatic memory management with
ffi.gc
- fix some string memory leaks when getting type and options of image
- add
coalesce
,rotate
methods to image - use
pkg-config
instead ofMagickWand-config
to query library - all include paths provided by config are searched instead of first
Author: Leaf Corcoran (leafo) (@moonscript)
Email: [email protected]
Homepage: http://leafo.net