Image API

This library implements its own image format for OpenComputers with a simple loseless compression algorithm. It allows you to load and save pictures in .pic format, as well as to perform simple operations like string serialization/deserialization/scaling/transforming.

How does it work inside?

Every image is stored in RAM as a one-dimensional table, where the first two elements are its width and height, and the next are pixel data. This approach is necessary for RAM saving. For a better understanding, I give you an table example:

{
	160, -- Image width
	50, -- Image height
	
	-- Begin of pixel data
	0xFF0000, -- Red background color
	0x0000FF, -- Blue symbol color,
	0x00, -- Alpha channel,
	"Q", -- Symbol,
	
	... -- Same for every pixel from left to right / top to bottom
}

Loading/saving

image.load(string path): table or boolean result, nil or string reason

Try to load an image from file system by given path. If loading was successful, the image table will be returned, it can be used for drawing on interface - for example, via GUI.image() method. If loading fails, false and reason will be returned. Reason describes why this happened - for example, the file system is read-only or there is not enough RAM to load image

This method applies 24bit to 8bit color compression and color grouping methods for better HDD usage

local result, reason = image.load("test.pic")
if result then
  -- Do your stuff like GUI.image(1, 1, result)
else
 -- Image is broken or not enough RAM
end

image.save(string path, table picture, [, int encodingMethod = 6)]): boolean success, nil or string reason

Tries to save a given picture to a given path, using a specified encoding method. If no encoding method is given, it will be set to 6 automatically. Returns true if image was saved successfully, false and an reason if not (maybe filesystem is readonly or there's not enough disk space to save it)

local success, reason = image.load("test.pic")
if success then
  -- Image was saved
else
 -- Image wasn't saved (fs is read-only, not enough RAM or HDD free space)
end

String searialization

image.toString(table image): string result

Serializes image to string. It can be used for saving image on disk in text (not binary) format. Searialization is nearly slow, you should avoid this method if you don't really know what you're doing

This method applies basic 24bit to 8bit color compression, but doesn't apply color grouping compression to result, and it will be stored as linear sequence

image.toString(myImage)

> A03200BEAA0051...

image.fromString(string image): table result

Deserializes string as picture table.

image.from("A03200BEAA0051...")

> {
	160,
	50,
	00,
	0xDEDEDE,
	0xBBBBBB,
	0xFF,
	0x00,
	"Q",
	...
}

image.create(width, height, background, foreground, alpha, symbol, random) Create a new image of dimensions width and height. If random is true, foreground and background will be set to random colors for every pixel on the image. If random is false and if no background or foreground color is given, black color (0x000000) is automatically selected. If no alpha value is given, no alpha (0x000000) is automatically selected. If random argument is set to true, a random unicode character is selected (from character codes 65 to 90, or 'A' to 'Z') for every pixel of the image. If random is not true and ff no symbol is given, space character (' ') is automatically selected. Otherwise if random is not true and symbol is given that character will be used for the entire image. Returns created image

image.getIndex(x, y, width) Returns the internal table position of a given pixel, given the xy coordinates of the target pixel and the width of the image you want pixel indexes from.