The @image module contains functions and classes for manipulating images.

Functions

:exif(path) #

Get EXIF metadata from an image file, typically a JPEG.

Parameters

Return

Notes

A lot of these values assume the use of a professional camera with a detachable lens (DSLR), and don't really apply to modern cell phone cameras (although cell phone cameras are getting fancier and some have multiple lenses now).

:plot(data,cols,type) #

Generate a plot from tabular data.

Parameters

Return

Notes

This uses the same underlying code as my plot tool, so see that page for output examples.

@surface Methods

A surface is an image, represented internally as an array of pixels, which can be manipulated. Each pixel is 32 bits: 8 bits for each of the color components (red, green, blue), and 8 bits for alpha (transparency). This allows the color of each pixel to be represented as a 32-bit integer.

The order of the pixels is left-to-right, top-to-bottom (just like text). The order of the components can be changed with :set_color_format().

Most methods return the surface itself so that they they can be chained to save typing.

Most methods can take color as either number or string. When passed as a string, the color is converted to a number using :color().

:new() #
:new(path)
:new(width,height)

Create a new surface.

Parameters

Return

Notes

If no parameters are specified, an empty 0 by 0 surface is created.

If path is specified, the surface is loaded from a file.

If width and height are specified, a blank (all black) width by height surface is created.

:load(path) #

Load data from file into surface.

Parameters

Return

Notes

If the file fails to load, :data() and :data_ptr() will be null.

:save(path) #

Save surface to file.

Parameters

Return

:clear() #

Clear all data and make the surface 0x0 and empty (no data).

Return

Notes

After calling this, :data() and :data_ptr() will be null.

:allocate(width,height) #

Allocate data for this surface.

Parameters

Return

Notes

After calling, this surface will be a width by height and blank (all black).

:width() #

Get the width in pixels.

Return

:height() #

Get the height in pixels.

Return

:size() #

Get the size in pixels, which is equivalent to :width() multiplied by :height().

Return

:data() #

Get a copy of the surface data as bytes.

Return

Notes

The length of the string will be :size() multiplied by 4 (since there are 4 bytes per pixel).

Remember that strings in Axiom are just arbitrary bytes (no explicit encoding) and can also hold binary data.

:data_ptr() #

Get a pointer to the surface data, for use with native code (@native)

Return

Notes

The length of the data in bytes is :size() multiplied by 4 (since there are 4 bytes per pixel).

Remember that pointers in Axiom are opaque (incompatible with pointer arithmetic), and are just for interfacing with native code.

:get(x,y) #

Get the color of a pixel.

Parameters

Return

Notes

The method :rgba() can be used to get individual components from the color.

Remember that 0,0 is at the top left.

If the coordinates are out of bounds, the behavior is to return the pixel that would be mirrored from the out-of-bounds edge. This is for compatibility with image algorithms that use kernels.

:set(x,y,color) #

Set the color of a pixel

Parameters

Return

:rgba(color) #

Get components of a color.

Parameters

Return

Notes

All components are unsigned bytes, so they will be in the range [0,255].

:hsl(color) #

Get the components of a color in HSL (Hue, Saturation, Lightness) color space.

Parameters

Return

Notes

Hue will be in the range [0,360):

Saturation will be in the range [0,1], where 0 = grayscale and 1 = pure color.

Lightness will be in the range [0,1], where 0 = black, 1 = white.

:luma(color) #

Convert a color to grayscale.

Parameters

Return

:color(str) #

Create a color from string.

Parameters

Return

Notes

Colors can be specified in one of the following formats:

For the tuples, RGB must be [0,255], alpha must be [0,1], hue must be [0,360), saturation [0,1], and lightness [0,1]. If alpha is not specified, it is assumed to be 0xff (255).

If str is actually a number, no processing is done.

:get_color_format() #

Get the pixel color format.

Return

:set_color_format(format,convert) #

Set the pixel color format

Parameters

Return

:copy(s) #

Set this surface to a copy of another surface.

Parameters

Return

:swap(s) #

Swap data with another surface.

Parameters

Return

:crop(x,y,w,h,s) #

Set this surface to the cropped area of another surface.

Parameters

Return

:fill(color) #

Fill the surface with a single color.

Parameters

Return

:interpolate(s,p) #

Interpolate this surface with another surface.

Parameters

Return

Notes

Each pixel in both surfaces are blended using the following formula: a*p + b*(1-p), where a is every pixel in this surface and b is every pixel in the other surface.

If p is greater than 1, then a is "extrapolated" from b.

:blend(s,p,q) #

Blend this surface with another surface.

Parameters

Return

Notes

Each pixel in both surfaces are blended using the following formula: a*p + b*q, where a is this surface and b is the other surface.

:blur(radius) #

Blur the image.

Parameters

Return

:desaturate() #

Desaturate the image (convert to grayscale).

Return

:lazy_sharpen(amount) #

Sharpen the image by extrapolating from the average color.

Parameters

Return

Notes

Faster than :sharpen().

:sharpen(amount,blur_radius) #

Sharpen the image by extrapolating from a blurred image.

Parameters

Return

Notes

Slower than :lazy_sharpen() but should give a nicer result.

:saturate(amount) #

Saturate the image by extrapolating from a desaturated image.

Parameters

Return

:negate() #

Negate the image (invert the colors).

Return

:brighten(amount) #

Brighten the image by extrapolating from black.

Parameters

Return

:lazy_resize(scale) #
:lazy_resize(w,h)

Resize this image using nearest-neighbor for in-between pixels.

Parameters

Return

:resize(scale) #
:resize(w,h)

Resize this image with upsampling/downsampling for in-between pixels.

Parameters

Return

Notes

Slower than :lazy_resize() but gives a better result.

:threshold(luma) #

Perform a threshold operation on the image, which changes all pixels white if > threshold, and black if <= threshold.

Parameters

Return

:average() #

Get the average color of the image.

Return

:text(x,y,str,color,face,size,transparent) #

Draw text on this surface.

Parameters

Return

Notes

The text is bound by surface width, and will wrap.

If face is specified, the current directory and the operating system font directories will be searched. Only TrueType (.ttf) files are supported. Tahoma is the default because it is already present on most operating systems.

:text_width(str,face,size) #

Get the width of the text given the font face and size.

Parameters

Return

Notes

Doesn't actually draw anything on the surface; just used for layout calculations.

:line_height(face,size) #

Get the line height given the font face and size.

Parameters

Return

Notes

Doesn't actually draw anything on the surface; just used for layout calculations.

:blit(s,x,y,use_alpha) #

Blit (copy image from) another surface onto this surface.

Parameters

Return

:rect(x,y,w,h,color,filled) #

Draw a rectangle.

Parameters

Return

:line(x1,y1,x2,y2,color) #

Draw a line.

Parameters

Return

:circle(x,y,radius,color,filled) #

Draw a circle.

Parameters

Return

:rotate_left() #

Rotate the image left (counter-clockwise).

Return

:rotate_right() #

Rotate the image right (clockwise).

Return

:flip(x_axis,y_axis) #

Flip the image across the x-axis, y-axis, or both.

Parameters

Return

:pivot() #

Flip the image across the diagonal that runs from the top-left to the bottom-right.

Return

:cinema() #

Enhance the image in a cinema-like manner; increase sharpness and contrast while reducing saturation.

Return

:find_exact(s) #

Find another surface within this surface.

Parameters

Return

Notes

All pixels must match exactly.

:find_fuzzy(s) #

Find another surface within this surface using fuzzy matching.

Parameters

Return

Notes

Only a subset of a pixels in s have to match.

:ascii(x,y,str,color,scale) #

Draw text on this surface using the ASCII 5x7 font which is typically seen on a Code Page 437 console. (The font face is pixelated and fixed width).

Parameters

Return

Notes

Each glyph is actually 5 by 8 pixels (the 8th pixel is the descender). This function leaves a 1 pixel margin around the top and left of the glyph, so the total size is actually 6 by 9 pixels per letter. (Assuming scale is 1).

The text is bound by surface width, and will wrap.

:ascii_table(scale) #

Draw all ASCII 5x7 glyphs on this surface.

Parameters

Return

Notes

This is so you can view the entire font (since unlike TrueType fonts which typically have a viewer built into the operating system, there is no other way to view the embedded 5x7 font).

The replaces whatever was in the surface with an entirely new image.

:dither(bits) #

Reduce the bit depth of each color component, and compensate for the loss in color accuracy by dithering.

Parameters

Return

Notes

This truncates each color components of each pixel so that instead of being 8 bits, the most significant [8 - bits] bits are zeroed.

This is used within :hide() for preprocessing.

:hide(s,bits) #

Hide an image within the most significant bits of this surface, also known as steganography

Parameters

Return

Notes

The image within s is dithered and has its bit depth reduced to bits. It is then hidden in the most significant bits bits of the image within this surface, which makes it hard to detect.

:unhide(bits) #

Reveal the image hidden within the most significant bits of this surface.

Parameters

Return

Notes

Replaces this surface with the hidden image, if any. This is the opposite of :hide().