Skip to main content
An Image represents the actual pixel data in a cel or a standalone image buffer.

​
Constructor

​
Image(width, height [, colorMode])

​
width
number
required
Width in pixels.
​
height
number
required
Height in pixels.
​
colorMode
ColorMode
Color mode (default: RGB).
local image = Image(32, 32)
local grayImage = Image(64, 64, ColorMode.GRAYSCALE)

​
Image(spec)

​
spec
ImageSpec
required
Image specification.
local image = Image(ImageSpec{ width=32, height=32, colorMode=ColorMode.RGB })

​
Image(sprite [, frame])

​
sprite
Sprite
required
Sprite to render.
​
frame
Frame
Frame to render (default: frame 0).
Creates an image by rendering a sprite. 
local image = Image(sprite)
local frameImage = Image(sprite, frame)

​
Image(image, rectangle)

​
image
Image
required
Source image.
​
rectangle
Rectangle
required
Region to copy.
Creates an image from a region of another image. 
local cropped = Image(sourceImage, Rectangle(10, 10, 20, 20))

​
Properties

​
id
number
Unique image identifier.
​
version
number
Image version (increments when modified).
​
width
number
Image width.
​
height
number
Image height.
​
rowStride
number
Bytes per row.
​
bytesPerPixel
number
Bytes per pixel.
​
bytes
string
Raw pixel data as byte string.
​
bounds
Rectangle
Image bounds.
​
colorMode
ColorMode
Color mode.
​
spec
ImageSpec
Image specification.
​
cel
Cel
Associated cel (if any).

​
Methods

​
image:clone()

Creates a copy of the image. 
local copy = image:clone()

​
image:clear([color])

​
color
Color | number
Clear color (default: transparent).
Clears the image to the specified color. 
image:clear()
image:clear(Color{ r=255, g=0, b=0 })
image:clear(0)  -- Transparent for indexed

​
image:clear(rectangle [, color])

​
rectangle
Rectangle
required
Region to clear.
​
color
Color | number
Clear color.
image:clear(Rectangle(10, 10, 20, 20), Color{ r=0, g=0, b=255 })

​
image:getPixel(x, y)

​
x
number
required
X coordinate.
​
y
number
required
Y coordinate.
Returns the color value at the specified position. 
local pixelValue = image:getPixel(10, 10)

​
image:drawPixel(x, y, color)

​
x
number
required
X coordinate.
​
y
number
required
Y coordinate.
​
color
Color | number
required
Color to draw.
Draws a single pixel. 
image:drawPixel(10, 10, Color{ r=255, g=0, b=0 })
image:drawPixel(20, 20, app.pixelColor.rgba(255, 255, 0, 255))

​
image:drawImage(sourceImage, position [, opacity] [, blendMode])

​
sourceImage
Image
required
Image to draw.
​
position
Point
required
Destination position.
​
opacity
number
Opacity (0-255, default: 255).
​
blendMode
BlendMode
Blend mode (default: Normal).
Draws another image onto this image. 
image:drawImage(otherImage, Point(10, 10))
image:drawImage(otherImage, Point(0, 0), 128, BlendMode.MULTIPLY)

​
image:drawSprite(sprite, frame, position)

​
sprite
Sprite
required
Sprite to render.
​
frame
Frame | number
required
Frame to render.
​
position
Point
Destination position.
Renders a sprite frame onto this image. 
image:drawSprite(sprite, 1, Point(0, 0))

​
image:pixels()

Returns an iterator for all pixels. 
for pixel in image:pixels() do
  local pixelValue = pixel()
  pixel(Color{ r=255, g=0, b=0 })  -- Set pixel
end

​
image:isEqual(otherImage)

​
otherImage
Image
required
Image to compare.
Returns true if images have identical pixel data. 
if image:isEqual(otherImage) then
  print("Images are identical")
end

​
image:isEmpty()

Returns true if the image is completely transparent. 
if image:isEmpty() then
  print("Image is empty")
end

​
image:isPlain([color])

​
color
Color | number
Color to check (default: mask color).
Returns true if all pixels are the same color. 
if image:isPlain(Color{ r=255, g=0, b=0 }) then
  print("Image is solid red")
end

​
image:saveAs(filename)

​
filename
string
required
File path.
Saves the image to a file. 
image:saveAs("output.png")

​
image:resize(width, height)

​
width
number
required
New width.
​
height
number
required
New height.
Resizes the image. 
image:resize(64, 64)

​
image:resize(options)

​
options
table
required
Resize options.
image:resize{
  width = 128,
  height = 128,
  method = "bilinear",
  pivot = Point(0, 0)
}

​
image:shrinkBounds([refColor])

​
refColor
Color | number
Reference color for transparency.
Returns the bounds of non-transparent pixels. 
local bounds = image:shrinkBounds()
print("Content bounds:", bounds)

​
image:flip(flipType)

​
flipType
FlipType
required
Flip direction (horizontal or vertical).
Flips the image. 
image:flip(FlipType.HORIZONTAL)
image:flip(FlipType.VERTICAL)

​
Examples

​
Creating and Drawing on Images

local image = Image(32, 32)

-- Fill with gradient
for y=0,31 do
  for x=0,31 do
    image:drawPixel(x, y, Color{ r=x*8, g=y*8, b=128 })
  end
end

image:saveAs("gradient.png")

​
Compositing Images

local bg = Image(64, 64)
bg:clear(Color{ r=255, g=255, b=255 })

local fg = Image(32, 32)
fg:clear(Color{ r=255, g=0, b=0, a=128 })

bg:drawImage(fg, Point(16, 16), 255, BlendMode.NORMAL)
bg:saveAs("composite.png")

​
Working with Pixel Iterators

local image = cel.image

-- Invert colors
for pixel in image:pixels() do
  local c = pixel()
  local color = app.pixelColor.rgba(
    255 - app.pixelColor.rgbaR(c),
    255 - app.pixelColor.rgbaG(c),
    255 - app.pixelColor.rgbaB(c),
    app.pixelColor.rgbaA(c)
  )
  pixel(color)
end