bimg

An API that draws and manipulates .bimg images.

new(path, binary)Instantiate a new Image object.
new(path, binary)Source

Instantiate a new Image object.

Parameters

  1. path string Path to the image.
  2. binary boolean Whether or not the image was written in binary mode.

Returns

  1. Image the new image object.

Types

Image

The image object. Contains functions for drawing, and extracting metadata. Created by {@new}.

Image.draw(x, y, Options)Source

Draw the image. If this is an animated image in between each frame it will call sleep. This will not reset cursor position!

Parameters

  1. x number X coordinate to draw the image at.
  2. y number Y coordinate to draw the image at.
  3. Options { window? = table, transparency? = boolean }

    that control how the image is drawn.

    • window: A window object to draw to. This is so that transparency can be supported. If this is not passed, we will see if term.current().getLine exists. If it does not, then transparency will not be supported, and will be replaced by black. If a window object is provided then this will draw to that, and call window.setVisible as appropriate to make the image draw better. Otherwise it will just direct call term. It will still call window functions even if transparency is false.
    • transparency: Even if transparency is supported, if this is false then it will be replaced by black. Setting this to true can not force transparency to work.
    • term: The terminal to draw to, defaults to regular terminal.
Image:getMetadata()Source

Retrieve the metadata of the image. This returns a table of all of the metadata in the bimg format. :::info This will also return custom keys, that are not part of the spec. ::: @treturn table Metadata of the image.

Image:setMetadata(metadata)Source

Set the metadata of the image. This takes a table (Usually one returned by image:draw, but can be custom made), and writes in the keys (Basically a shallow clone) to the image. This will then save the image to a file. :::info Custom metadata keys can be added, and it will not complain, but note that other programs might not see these keys, or do anything with them. ::: :::caution This will only write string keys, and will ignore function, table, number, etc. keys. ::: @tparam table metadata Metdata information.

Parameters

  1. metadata
Image.clearMetadata()Source

This clears the metadata, useful to completely overwrite metadata. It also returns a copy of the removed metadata.

Returns

  1. table Old metadata of the image.
Image.setPixel(...)Source

Set a pixel at a specific point.

Parameters

  1. x number X coordinate of the pixel.
  2. y number Y coordinate of the pixel.
  3. char string Character to place.
  4. fg string | number Foreground colour. Accepts either a blit colour or colours colour.
  5. bg string | number Background colour. Accepts either a blit colour or colours colour.
  6. frame number Frame to set, defaults to 1.

Or

  1. x number X coordinate of the pixel.
  2. y number Y coordinate of the pixel.
  3. Table { string, string | number, string | number, number } describing a character. This follows the same parameters as before.
Image.setLine(...)Source

Set a line of characters.

Parameters

  1. y number Y coordinate of the line.
  2. char string Characters to set.
  3. fg string Foreground blit colour.
  4. bg string Background blit colour.
  5. frame number Frame to set, defaults to 1.

Or

  1. y number Y coordinate of the pixel.
  2. Table { string, string, string, number } describing a blit line. This follows the same parameters as before.
Image.getPixel(x, y [, frame])Source

Get a pixel.

Parameters

  1. x number X coordinate of the pixel.
  2. y number Y coordinate of the pixel.
  3. frame? number Frame to get, defaults to 1.

Returns

  1. string Character of the pixel.
  2. string Foreground colour of the pixel.
  3. string Background colour of the pixel.

Or

  1. nil Pixel does not exist in the image.
Image.getLine(y [, frame])Source

Get a line.

Parameters

  1. y number Y coordinate of the line.
  2. frame? number Frame to get, defaults to 1.

Returns

  1. string Characters of the line.
  2. string Foreground colours of the line.
  3. string Background colours of the line.

Or

  1. nil Line does not exist in the image.
Image.resize(method)Source

Resize the image.

Parameters

  1. method string

    Method used to resize the image. Valid methods are:

    • "black": Fills in empty space with just black characters.
    • "repeat": Repeats the last row/column data for the empty space.
    • "transparent": Fills the empty space with completely invisible characters.
Image:reload()Source

Refresh the image from the file. This simply reads the file again.

Image.save([path])Source

Save the image to the file.

Parameters

  1. path? string A new path to save to. Defaults to the original path of the image.