imagine

This module provide classes and functions for dynamic image creation and manipulation. Imagine supports different image formats and can be used to generate thumbnails, charts, graphics, and many other kinds of images on the fly.

The following image formats are currently supported by imagine:

JPEG
PNG
GIF
BMP
AVIF
WebP
HEIF
TIFF
WBMP
TGA

Features

The module supports transparency, blending, images and image text transformations and various filters.

⁠Image loading and saving in various formats (JPEG, PNG, GIF, etc.)
⁠Image resizing, cropping, and rotation
Color manipulation (brightness, contrast, saturation, etc.)
Image filtering (blur, sharpen, edge detection, etc.)
Text rendering and drawing
Support for layers, masks, and alpha channels

Examples

The following create a PNG image filled with color red.

import imagine { * }

# create empty image handle
var img = Image.new(100, 100, true)

# allocate color red and use it to fill the image
var bg_color = img.allocate_color(255, 0, 0)
img.fill(0, 0, bg_color)

# export image to png
img.export_png('image.png')

# close the image handle
img.close()

While the above example works very fine, it is a very common thing from experience for people to forget to close file and image handles and this have real implications on the system. For this reason, the coventionally advice way to use Image instances is via .ImageResource.use().

The example below demonstartes the former example with .use pattern.

import imagine { * }

Image.new(100, 100, true).use(@(img) {
  # allocate color red and use it to fill the image
  var bg_color = img.allocate_color(255, 0, 0)
  img.fill(0, 0, bg_color)

  # export image to png
  img.export_png('image.png')
})

Imagine is great at converting images as well as generating images. The example below loads a PNG image and saves a copy as a JPEG file (for sake of continuity, we're using the image we just created but feel free to play around with your own images).

import imagine { * }

Image.from_png('image.png').use(@(img) {
  img.export_jpeg('image.jpg')
})

Image can create transparent images as well as images containig texts. The example below shows creates a simple transparent PNG image with the text A simple text string written in it.

import imagine { * }

Image.new(130, 20, true).use(@(im) {
  im.save_alpha()

  var bg_color = im.allocate_color(0, 0, 0, 127)
  var fore_color = im.allocate_color(233, 14, 91)

  im.fill(0, 0, bg_color)
  im.string(5, 2, 'A simple text string', FONT_REGULAR, fore_color)

  im.export_png('simple.png')
})

Fields

imagine.QUANT_DEFAULT ➝ number: Default (QUANT_LIQ if libimagequant is available, QUANT_JQUANT otherwise).
imagine.QUANT_JQUANT ➝ number: libjpeg's old median cut. Fast, but only uses 16-bit color.
imagine.QUANT_NEUQUANT ➝ number: NeuQuant - approximation using Kohonen neural network.
imagine.QUANT_LIQ ➝ number: A combination of algorithms used in libimagequant aiming for the highest quality at cost of speed.
imagine.ARC_ARC ➝ number: Produces a rounded edge.
imagine.ARC_PIE ➝ number: Same as ARC_ARC.
imagine.ARC_CHORD ➝ number: Connects the starting and ending angles with a straight line.
imagine.ARC_NO_FILL ➝ number: Indicates that the arc or chord should be outlined, not filled.
imagine.ARC_NO_EDGE ➝ number: Used together with ARC_NO_FILL, indicates that the beginning and ending angles should be connected to the center; this is a good way to outline (rather than fill) a 'pie slice'.
imagine.CROP_DEFAULT ➝ number: Same as CROP_TRANSPARENT
imagine.CROP_TRANSPARENT ➝ number: Crop using the transparent color
imagine.CROP_BLACK ➝ number: Crop black borders
imagine.CROP_WHITE ➝ number: Crop white borders
imagine.CROP_SIDES ➝ number: Crop using colors of the 4 corners
imagine.CMP_IMAGE ➝ number: Actual image IS different
imagine.CMP_NUM_COLORS ➝ number: Number of colors in pallette differ
imagine.CMP_COLOR ➝ number: Image colors differ
imagine.CMP_SIZE_X ➝ number: Image width differs
imagine.CMP_SIZE_Y ➝ number: Image heights differ
imagine.CMP_TRANSPARENT ➝ number: Transparent color differs
imagine.CMP_BACKGROUND ➝ number: Background color differs
imagine.CMP_INTERLACE ➝ number: Interlaced setting differs
imagine.CMP_TRUECOLOR ➝ number: Truecolor vs palette differs
imagine.BLUR_SELECTIVE ➝ number: Blurs the image using the Gaussian method.
imagine.BLUR_GAUSSIAN ➝ number: Blurs the image.
imagine.FLIP_BOTH ➝ number: Flip an image vertically and horizontally
imagine.FLIP_HORIZONTAL ➝ number: Flip an image horizontally
imagine.FLIP_VERTICAL ➝ number: Flip an image vertically
imagine.FONT_SMALL ➝ ptr: A small ISO-8859-2 raster font (5x8 pixels).
imagine.FONT_REGULAR ➝ ptr: The regular ISO-8859-2 raster font (6x13 pixels)
imagine.FONT_MEDIUM ➝ ptr: A medium bold ISO-8859-2 raster font (7x13 pixels).
imagine.FONT_LARGE ➝ ptr: A large ISO-8859-2 raster font (8x16 pixels).
imagine.FONT_EXTRALARGE ➝ ptr: An extra-large ISO-8859-2 raster font (9x15 pixels).
imagine.COLOR_STYLED ➝ number: Use the current style, see set_style()
imagine.COLOR_BRUSHED ➝ number: Use the current brush, see set_brush()
imagine.COLOR_STYLED_BRUSHED ➝ number: Use the current style and brush
imagine.COLOR_TILED ➝ number: Use the current tile, see set_tile()
imagine.COLOR_TRANSPARENT ➝ number: Indicate transparency, what is not the same as the transparent color index; used for lines only
imagine.COLOR_ANTI_ALISED ➝ number: Draw anti aliased
imagine.INTERP_DEFAULT ➝ number: Default (Same as INTERP_BELL)
imagine.INTERP_BELL ➝ number: Bell
imagine.INTERP_BESSEL ➝ number: Bessel
imagine.INTERP_BILINEAR_FIXED ➝ number: Fixed point bilinear
imagine.INTERP_BICUBIC ➝ number: Bicubic
imagine.INTERP_BICUBIC_FIXED ➝ number: Fixed point bicubic integer
imagine.INTERP_BLACKMAN ➝ number: Blackman
imagine.INTERP_BOX ➝ number: Box
imagine.INTERP_BSPLINE ➝ number: BSpline
imagine.INTERP_CATMULLROM ➝ number: Catmullrom
imagine.INTERP_GAUSSIAN ➝ number: Gaussian
imagine.INTERP_GENERALIZED_CUBIC ➝ number: Generalized cubic
imagine.INTERP_HERMITE ➝ number: Hermite
imagine.INTERP_HAMMING ➝ number: Hamming
imagine.INTERP_HANNING ➝ number: Hannig
imagine.INTERP_MITCHELL ➝ number: Mitchell
imagine.INTERP_NEAREST_NEIGHBOUR ➝ number: Nearest neighbour interpolation
imagine.INTERP_POWER ➝ number: Power
imagine.INTERP_QUADRATIC ➝ number: Quadratic
imagine.INTERP_SINC ➝ number: Sinc
imagine.INTERP_TRIANGLE ➝ number: Triangle
imagine.INTERP_WEIGHTED4 ➝ number: 4 pixels weighted bilinear interpolation
imagine.INTERP_LINEAR ➝ number: bilinear interpolation
imagine.LANCZOS3 ➝ number: Lanczos 3
imagine.LANCZOS8 ➝ number: Lanczos 8
imagine.BLACKMAN_BESSEL ➝ number: Blackman Bessel
imagine.BLACKMAN_SINC ➝ number: Blackman Sinc
imagine.QUADRATIC_BSPLINE ➝ number: Quadratic BSpline
imagine.CUBIC_SPLINE ➝ number: Cubic Spline
imagine.COSINE ➝ number: Cosine
imagine.WELSH ➝ number: Welsh

Functions

imagine.true_color(r, g, b, a)

Compose a truecolor value from its components.

@params:
- number? r The red channel (0-255) - Default: 0
- number? g The green channel (0-255) - Default: 0
- number? b The blue channel (0-255) - Default: 0
- number? a The alpha channel (0-127, where 127 is fully transparent, and 0 is completely opaque) - Default: 0.

@returns: number

imagine.decompose(color)

Decomposes an Image true color number into it's respective RGBA components.

The function returns a dictionary that contains the following decomposed items:

r - The red channel value
g - The green channel value
b - The blue channel value
a - The alpha channel value
@params:
- number color

@returns: dict

imagine.load(path)

Creates an image from any supported image file.

As long as the file type is supported by Imagine, the file type will automatically be detected.

This function is a shorthand for Image.from_file.

@params:
- string|file src

@returns: ImageResource

Classes

class ImageResource

The ImageResource class represents a loaded image and exposes all the image processing, metadata and manipulation functions.

.use(callback)

Invokes the given callback with the image as a parameter and automatically closes the image once the callback returns. Leaving images in open can quickly lead to resource exhaustion especially when working with multiple images. The use() method is recommended over manually closing images as it ensures that an image is always closed and not forgotten in memory.

@params:
- function(1) callback

.close()

Closes an image and frees all associated resources.

@notes:

an image can no longer be used once it is closed.

.meta()

Returns metadata information about the image.

Metadata contains:

width: The width of the image (in pixels).
height: The height of the image (in pixels).
colors: The number of colors in the image.
res_x: The horizontal resolution in DPI.
res_y: The vertical resolution in DPI.
interpolation: The method of interpolation used on the image.
true_color: True if the image uses true colors, false otherwise.
interlaced: True if the image is interlaced, false otherwise.
@returns: dict

.set_pixel(x, y, color)

Sets the pixel indicated by x and y coordinate in the image to the given color.

@params:
- number x
- number y
- number color

.get_pixel(x, y)

Returns the color at the give pixel indicated by x and y coordinate in the image.

@params:
- number x
- number y

@returns: number

.line(x1, y1, x2, y2, color)

Draws a line between x1,y1 and x2, y2.The line is drawn using the color index specified. Note that color index can be a color returned by allocate_color() or one of set_style(), or set_brush().

@params:
- number x1
- number y1
- number x2
- number y2
- number color

.dashed_line(x1, y1, x2, y2, color)

Draws a dashed line between x1,y1 and x2, y2.The line is drawn using the color specified. Note that color index can be a color returned by allocate_color() or one of set_style(), or set_brush().

@params:
- number x1
- number y1
- number x2
- number y2
- number color

.rectangle(x1, y1, x2, y2, color)

Draws a rectangle with the upper left (x1, y1) then lower right (y1,y2) corners specified, using the color specified.

@params:
- number x1
- number y1
- number x2
- number y2
- number color

.filled_rectangle(x1, y1, x2, y2, color)

Draws a solid rectangle with the upper left (x1, y1) then lower right (y1,y2) corners specified, using the color specified.

@params:
- number x1
- number y1
- number x2
- number y2
- number color

.safe_bound(x, y)

Returns true if the coordinate represented by x and y is within the bounds of the image.

@params:
- number x
- number y

.char(x, y, char, font, color)

Draws a single character.

@params:
- number x The x coordinate of the upper left pixel.
- number y The y coordinate of the upper left pixel.
- char text The character.
- font font The raster font.
- number color The color.

.char_vert(x, y, char, font, color)

Draws a single character vertically.

@params:
- number x The x coordinate of the upper left pixel.
- number y The y coordinate of the upper left pixel.
- char text The character.
- font font The raster font.
- number color The color.

.string(x, y, text, font, color)

Draws a character string.

@params:
- number x The x coordinate of the upper left pixel.
- number y The y coordinate of the upper left pixel.
- string text The character string.
- font font The raster font.
- number color The color.

.string_vert(x, y, text, font, color)

Draws a character string vertically.

@params:
- number x The x coordinate of the upper left pixel.
- number y The y coordinate of the upper left pixel.
- string text The character string.
- font font The raster font.
- number color The color.

.polygon(points, color)

Draws a polygon with the vertices specified by points, in the specified by color. There must be at least three points.

Point must be a list of lists where each list contains two numbers for the x and y coordinates. It is required that there must be at least three points.

@params:
- list[list] points
- number color

.open_polygon(points, color)

Draws an open polygon with the vertices specified by points, in the specified by color. There must be at least three points.

Point must be a list of lists where each list contains two numbers for the x and y coordinates. It is required that there must be at least three points.

@params:
- list[list] points
- number color

.filled_polygon(points, color)

Fills a polygon with the vertices specified by points, in the specified by color. There must be at least three points.

Point must be a list of lists where each list contains two numbers for the x and y coordinates. It is required that there must be at least three points.

@params:
- list[list] points
- number color

.arc(x, y, width, height, start, end, color)

Draws a partial ellipse centered at the given point, with the specified width and height in pixels. The arc begins at the position in degrees specified by start and ends at the position specified by end. The arc is drawn in the color specified by the last argument. A circle can be drawn by beginning from 0 degrees and ending at 360 degrees, with width and height being equal. end must be greater than start. Values greater than 360 are interpreted modulo 360.

@params:
- number x
- number y
- number width
- number height
- number start
- number end
- number color

.filled_arc(x, y, width, height, start, end, color, style)

Fills a partial ellipse centered at the given point, with the specified width and height in pixels using the specified style. The arc begins at the position in degrees specified by start and ends at the position specified by end. The arc is drawn in the color specified by the last argument. A circle can be drawn by beginning from 0 degrees and ending at 360 degrees, with width and height being equal. end must be greater than start. Values greater than 360 are interpreted modulo 360.

Style must be one or more of ARC_ constants or'ed together. E.g. ARC_NO_FILL | ARC_NO_EDGE.

When style is not given, it defaults to ARC_PIE.

@params:
- number x
- number y
- number width
- number height
- number start
- number end
- number color
- number style

.ellipse(x, y, width, height, color)

Draws a full ellipse centered at the given point, with the specified width, height, and color.

@params:
- number x
- number y
- number width
- number height
- number color

.filled_ellipse(x, y, width, height, color)

Fills a full ellipse centered at the given point, with the specified width, height, and color.

@params:
- number x
- number y
- number width
- number height
- number color

.allocate_color(r, g, b, a)

Returns the given color allocated from the image palette. Any of R, G, B, or A can be omitted or set to nil in which case they'll default to zero.

@params:
- number? r
- number? g
- number? b
- number? a

@returns: number

.closest_color(r, g, b, a)

Returns the closes color based on the image to the color specified by r, g, b, and a. A slightly different color with the same transparency beats the exact same color with radically different transparency.

@params:
- number r
- number g
- number b
- number a

@returns: number

.closest_color_hwb(r, g, b)

Same as closes_color() but uses an alternative algorithm and does not account for transparency.

@params:
- number r
- number g
- number b

@returns: number

.exact_color(r, g, b, a)

Returns an exact match only, including alpha when specified.

@params:
- number r
- number g
- number b
- number a

@returns: number

.resolve_color(r, g, b, a)

Resolves color in the image based on exact_color() and closest_color() and return the one that matches the image best.

@params:
- number r
- number g
- number b
- number a

@returns: number

.deallocate_color(color)

Deallocates a color previously allocated from the image.

@params:
- number color

.color_transparent(color)

Specifies a color index (if a palette image) or an RGB color (if a truecolor image) which should be considered 100% transparent. FOR TRUECOLOR IMAGES, THIS IS IGNORED IF AN ALPHA CHANNEL IS BEING SAVED. Use save_apha(false) to turn off the saving of a full alpha channel in a truecolor image. Note that this function is usually compatible with older browsers that do not understand full alpha channels well.

@params:
- number color

.palette_copy(image)

Copies the palatte from a paletted image to this image.

@params:
- ImageResource image

.color_replace(src, dest)

Replaces every occurrence of color src in the image with the color dest.

@params:
- number src
- number dest

@returns: bool

.fill(x, y, color)

Flood fills the image with the given color starting are the coordinates given by x and y.

@params:
- number x
- number y
- number color

.fill_to_border(x, y, border, color)

Flood fills the image with the given color starting are the coordinates given by x and y and using the color specified by border to fill its borders.

@params:
- number x
- number y
- number color

.copy(src, dst_x, dst_y, src_x, src_y, width, height)

Copy a part of image src onto this image starting at the x,y c oordinates src_x, src_y with the source width and height. The portion defined will be copied onto the x,y coordinates, dst_x and dst_y.

@params:
- ImageResource src
- number dst_x
- number dst_y
- number src_x
- number src_y
- number width
- number height

.copy_merge(src, dst_x, dst_y, src_x, src_y, width, height, pct)

Copy and merge a part of image src onto this image starting at the x,y coordinates src_x, src_y with the source width and height. The portion defined will be copied onto the x,y coordinates, dst_x and dst_y.

The two images will be merged according to pct which can range from 0 to 100. When pct = 0, no action is taken, when 100 this function behaves identically to copy() for pallete images, except for ignoring alpha components, while it implements alpha transparency for true colour images.

@params:
- ImageResource src
- number dst_x
- number dst_y
- number src_x
- number src_y
- number width
- number height
- number pct

.copy_merge_gray(src, dst_x, dst_y, src_x, src_y, width, height, pct)

Same as copy_merge() except that when merging it preserves the hue of the source by converting the destination pixels to gray scale before the copy operation.

@params:
- ImageResource src
- number dst_x
- number dst_y
- number src_x
- number src_y
- number width
- number height
- number pct

.copy_resized(src, x, y, src_x, src_y, width, height, src_width, src_height)

Copy a resized area defined by src_x, src_y, src_width, and src_height from the image src to the area defined by x, y, width, height on this image.

If the source and destination coordinates and width and heights differ, appropriate stretching or shrinking of the image fragment will be performed.

The coordinates refer to the upper left corner.

This function can be used to copy regions within the same image (if this image is the same as src) but if the regions overlap the results will be unpredictable.

@params:
- ImageResource src
- number x
- number y
- number src_x
- number src_y
- number width
- number height
- number src_width
- number src_height

.copy_resampled(src, x, y, src_x, src_y, width, height, src_width, src_height)

Copy a resized area defined by src_x, src_y, src_width, and src_height from the image src to the area defined by x, y, width, height on this image. Unlike copy_resized(), it smoothly interpolates pixel values so that, in particular, reducing the size of an image still retains a great deal of clarity.

If the source and destination coordinates and width and heights differ, appropriate stretching or shrinking of the image fragment will be performed.

The coordinates refer to the upper left corner.

This function can be used to copy regions within the same image (if this image is the same as src) but if the regions overlap the results will be unpredictable.

@params:
- ImageResource src
- number x
- number y
- number src_x
- number src_y
- number width
- number height
- number src_width
- number src_height

.copy_rotated(src, x, y, src_x, src_y, src_width, src_height, angle)

Similar to copy_resized() with an added rotation to the copied image. Destination is the center of the rotated copy. Angle is in degrees, same as arc().

Floating point destination center coordinates allow accurate rotation of objects of odd-numbered width or height.

The rotation angle is interpreted as the number of degrees to rotate the image anticlockwise.

@params:
- ImageResource src
- number x
- number y
- number src_x
- number src_y
- number src_width
- number src_height
- number angle

.clone()

Clones this image resource.

@returns: ImageResource

.set_brush(brush)

Sets the brush image to be used by all line drawing functions for this image.

A "brush" is an image used to draw wide, shaped strokes in another image. Just as a paintbrush is not a single point, a brush image need not be a single pixel. Any image resource can be used as a brush, and by setting the transparent color index of the brush image with color_transparent(), a brush of any shape can be created.

All line-drawing functions, such as gdImageLine and polygon(), will use the current brush if the special "color" COLOR_BRUSHED or COLOR_STYLED_BRUSHED is used when calling them.

NOTE:*

You need not take special action when you are finished with a brush, but if you close the brush image (or let the GC close it), you must not use the COLOR_BRUSHED or COLOR_STYLED_BRUSHED colors until you have set a new brush image.

@params:
- ImageResource brush

.set_tile(tile)

Sets the tile image to be used by all region filling functions.

A tile is an image used to fill an area with a repeated pattern. Any image resource can be used as a tile, and by setting the transparent color index of the tile image with color_transparent(), a tile that allows certain parts of the underlying area to shine through can be created. All region-filling functions, such as fill() and filled_polygon(), will use the current tile if the special "color" COLOR_TILED is used when calling them.

You can set any image resource to be the tile. If the tile image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary GIFs to be used as tile images. It also means, however, that you should not set a tile unless you will actually use it; if you set a rapid succession of different tile images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a tile. As for any other image, if you will not be using the tile image for any further purpose, you should call close(). You must not use the color COLOR_TILED if the current tile has been closed; you can of course set a new tile to replace it.

@params:
- ImageResource tile

.set_antialiased(color, dont_blend)

Set the color for subsequent anti-aliased drawing and whether to blend the color or not.

@params:
- number color
- bool dont_blend

.set_thickness(thickness)

Sets the thickness in pixels for following lines drawn when drawing lines, ellipses, rectangles, polygons and so forth.

@params:
- number thickness

.interlace(enable)

Sets whether an image is interlaced. If the enabled parameter is not given, it defaults to true.

@params:
- bool? enable

.alpha_blending(enable)

Toggles between two different blending modes of drawing on truecolor images.

In blending mode, the alpha channel component of the color supplied to all drawing function, such as set_pixel() determines how much of the underlying color should be allowed to shine through. As a result, the module automatically blends the existing color at that point with the drawing color, and stores the result in the image. The resulting pixel is opaque.

In non-blending mode, the drawing color is copied literally with its alpha channel information, replacing the destination pixel. Blending mode is not available when drawing on palette images.

If the enabled parameter is not given, it defaults to true.

@params:
- bool enable

.flip(mode)

Flips the image horizontally, vertically, or in both direction as specified in mode. mode must be one of the FLIP_ constants. When no mode is set, mode defaults to FLIP_BOTH.

@params:
- number? mode

.crop(x, y, width, height)

Returns a new imaged cropped from the rectangular area specified by x, y, width, and height in this image.

@params:
- number x
- number y
- number width
- number height

@returns: ImageResource

.auto_crop(mode)

Crop an image automatically using one of the CROP_ modes. If mode is not give, it defaults to CROP_DEFAULT.

@params:
- number? mode

@returns: ImageResource

.scale(width, height, method)

Scale an image using the given new width and height with the interpolation algorithm. If height is not given, the height will be automatcially calculated from the new width to maitain aspect ratio.

If the interpolation method is not given, it defaults to INTERP_BILINEAR_FIXED.

This method returns a new image rather than modify this image.

@params:
- number width
- number? height
- number? method

@returns: ImageResource

.rotate(angle, bg_color, method)

Creates a new image rotated counter-clockwise by the requested angle using the given interpolation method. Non-square angles will add a border with bgcolor.

@params:
- number angle
- number bg_color
- number? method

@returns: ImageResource

.save_alpha(save)

Sets the save alpha flag

The save alpha flag specifies whether the alpha channel of the pixels should be saved. This is supported only for image formats that support full alpha transparency, e.g. PNG.

@params:
- bool save

.pixelate(block_size, mode)

Applies pixelation effect to the image based on the block size and given effect mode.

@params:
- number block_size
- number mode

.scatter(sub, plus, colors)

Applies scatter effect to an image using the sub and plus to control the strength of the scatter and colors to indicate the colors it should be restricted to.

@params:
- number sub
- number plus
- list colors

.smooth(weight)

Makes an image smooter based on the specified weight. If weight is not given, it defaults to 1.

@params:
- number weight

.mean_removal()

Uses mean removal to achieve a "sketchy" effect.

.emboss()

Embosses the image.

.blur(type)

Applies a blur to the image. If the type is not given, a Guassian blur will be applied.

@params:
- number type

.detect_edge()

Uses edge detection to highlight the edges in the image.

.grayscale()

Converts the image into grayscale by changing the red, green and blue components to their weighted sum using the same coefficients as the REC.601 luma (Y') calculation. The alpha components are retained. For palette images the result may differ due to palette limitations.

.negate()

Reverses all colors of the image to create a negative image.

.color(r, g, b, a)

Same as grayscale() except this allows you to specify the output color.

@params:
- number r
- number g
- number b
- number a

.contrast(contrast)

Changes the contrast of the image based on the level set in contrast.

@params:
- number contrast

.brightness(brightness)

Changes the brightness of the image based on the level set in brightness.

@params:
- number brightness

.set_clip(x1, y1, x2, y2)

Sets the rectangular clipping region beyond which no pixels will be drawn in the image.

@params:
- number x1
- number y1
- number x2
- number y2

.get_clip()

Returns the clipping region in the image. See set_clip().

The function returns a list containing four numbers that indicates the x1, y1, x2, and y2 of the clipping region in the image.

@returns: list

.set_resolution(res_x, res_y)

Sets the resolution of the the image across both axis.

@params:
- number res_x
- number res_y

.true_color_to_palette(dither, colors_wanted)

Convert a true color image to a palette image.

The first parameter dither controls whether the image should be dithered which results in a more speckled image but with better color approximation.

The second argument colors_wanted controls the number of colors that should be kept in the palette.

@params:
- bool dither
- number colors_wanted

@returns: bool - true if successful, otherwise false.

.palette_to_true_color()

Converts a palette based image to true color.

@returns: bool - true if successful, otherwise false.

.match_color(image)

Makes the colors of the palette version of an image more closely match the true color version. This function should be given a true color image as the function will attempt to make the color of the image given if the current image is a paletted image.

@params:
- ImageResource image

@returns: bool - true if successful, otherwise false.

.compare(image)

Check whether two images are idential.

This check includes a size, transparency, interlace, color profile, and a pixel by pixel check.

If the images are completely identical, the method returns a zero (0). Otherwise, it returns a number greater than 0. The number returned can be tested againt the various CMP_ constants to test for any of the conditions.

For example,

var result = image1.compare(image2)

var both_transparent = !(result & CMP_TRANSPARENT)
var same_width = !(result & CMP_SIZE_X)

@params:
- ImageResource image

@returns: number

.export_png(dest, quality)

Saves the image to file with the PNG format.

Quality level: 0-10, where 9 is NO COMPRESSION at all, 9 is FASTEST but produces larger files, 0 provides the best compression (smallest files) but takes a long time to compress, and 10 selects the default compiled into the zlib library.

@params:
- string|file dest
- number quality

.export_jpeg(dest, quality)

Saves the image to file with the JPEG format.

Quality level: 100 is highest quality (there is always a little loss with JPEG). 0 is lowest. 10 is about the lowest useful setting.

@params:
- string|file dest
- number quality

.export_bmp(dest, quality)

Saves the image to file with the BMP format.

Quality level: 100 is highest quality (there is always a little loss with BMP). 0 is lowest. 10 is about the lowest useful setting.

@params:
- string|file dest
- number quality

.export_wbmp(dest, foreground)

Saves the image to file with the WBMP format using the given foreground color.

@params:
- string|file dest
- number foreground

.export_webp(dest, quantization)

Saves the image to file with the WEBP format using the given quantization.

@params:
- string|file dest
- number quantization

.export_tiff(dest)

Saves the image to file with the TIFF format.

@params:
- string|file dest

.export_avif(dest, quality, speed)

Saves the image to file with the JPEG format.

Quality level: 100 is highest quality (there is always a little loss with JPEG). 0 is lowest. 10 is about the lowest useful setting.

@params:
- string|file dest
- number quality
- number speed Default = 1

.get_pointer()

Returns the raw image resource pointer.

@returns: ptr

class Image

The Image class is allows creating and opening of imnages in any of the supported formats which includes JPEG, PNG, GIF, TIFF, BMP, WBMP, TGA, WEBP, AVIF.

static .new(width, height, use_true_colors)

Creates a palette-based image (up to 256 colors) or a truecolor image (millions of colors) when use_true_colors is set to true.

@params:
- number width
- number height
- bool? use_true_colors

@returns: ImageResource

static .from_png(src)

Creates an image from a PNG file. Truecolor PNG stays truecolor; palette PNG stays palette-based.

@params:
- string|file src

@returns: ImageResource

static .from_jpeg(src)

Creates an image from a JPEG file. JPEG is always truecolor.

@params:
- string|file src

@returns: ImageResource

static .from_gif(src)

Creates an image from a GIF file.

@params:
- string|file src

@returns: ImageResource

static .from_bmp(src)

Creates an image from a BMP file.

@params:
- string|file src

@returns: ImageResource

static .from_wbmp(src)

Creates an image from a WBMP file.

@params:
- string|file src

@returns: ImageResource

static .from_tga(src)

Creates an image from a TGA file.

@params:
- string|file src

@returns: ImageResource

static .from_tiff(src)

Creates an image from a TIFF file.

@params:
- string|file src

@returns: ImageResource

static .from_webp(src)

Creates an image from a WEBP file.

@params:
- string|file src

@returns: ImageResource

static .from_avif(src)

Creates an image from a AVIF file.

@params:
- string|file src

@returns: ImageResource

static .from_file(src)

Creates an image from any supported image file. As long as the file type is supported by Imagine, the file type will automatically be detected.

@params:
- string|file src

@returns: ImageResource

imagine

Features

Examples

Fields

Functions

Classes

Search

Navigation