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 picture): string result

Serializes picture 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,
  
  0xDEDEDE,
  0xBBBBBB,
  0xFF,
  0x00,
  "Q",
  ...
}

Image processing

image.getWidth(table picture): int width

Returns pixel width of given picture. You can also access this value via picture[1]

image.getHeight(table picture): int height

Returns pixel heightof given picture. You can also access this value via picture[2]

image.get(table picture, int x, int y): int background, int foreground, int alpha, string symbol

Returns single pixel data by given x/y from picture

image.set(table picture, int x, int y, int background, int foreground, int alpha, string symbol)

Sets single pixel data by given x/y to picture

image.getIndex(int x, int y, int pictureWidth)

Returns internal picture table position by given x/y and it's width. It can be used in performance-dependent programs with pixel sequences editing instead of calling image.set(...) all the time, because it internally uses getIndex(...) at every call

local picture= image.load("test.pic")
local width = image.getWidth(picture) -- For example, loaded picture width = 160 pixels

local from = image.getIndex(2, 1, width) -- from = 7
local to = image.getIndex(10, 2, width) -- to = 679

-- Let's change picture background from 2x1 to 10x2 pixels to green and symbol to "@"
-- Loop step is 4 because every pixel data contains 4 elements (background, foreground, alpha and symbol)
for i = from, to, 4 do
  picture[i] = 0x00FF00
  picture[i + 3] = "@"
end

image.create(int width, int height, [int background = 0x000000, int foreground = 0x000000, int alpha = 0x00, string symbol = " ", boolean random = false]): table picture

Creates new picture instance by given width / height and pixel data. You can pass nil value to every pixel data - it will be automatically changed to default value.

If optional random argument is true, then every pixel data (except of alpha channel) will be random. Why someone needs random feature? Who knows...

image.copy(table picture): table copy

Performs deep copy of all pixel data of given picture and returns it as new picture. Of course, RAM usage will be doubled in this case