Image¶

Overview¶

Image represents a bitmap picture that you can display on the micro:bit.

Images can be of any size, and each pixel on the image has an individual brightness value in the range 0 - 255.

Once created, this class also provides functions to:

undertake graphical operations on that image, including setting pixels, clearing the image, pasting one image onto another at a given position,
shift the content of an image,
compare and copy images.

It is designed to work with uBit.display to allow the creation of animations and visual effects.

Note

This is a managed type. This means that it will automatically use and release memory as needed. There is no need for you to explicitly free or release memory when you're done - the memory will be freed as soon as the last piece of code stops using the data.

Using Images¶

Creating Images¶

Images are easy to create: just create them like a variable, but provide the details requested in one of the constructor functions shown below. This may sound complex, but is quite simple when you get used to it. For example, to create a blank, 2x2 image:

Image image(2,2);

You can also create one from a text string that represents the pixel values that you want. This is a really easy way to create icons and emojis in your code.

The string constructor for an Image takes the form of a series of comma separate values. Each value is the brightness of a pixel, starting at the top left of your image and working to the right. Whenever you put a newline character \n in your string, this moves onto a new line of pixels.

So to create a 3x3 image that is a picture of a cross, you might write:

Image cross("0,255,0\n255,255,255\n0,255,0\n");

Manipulating Images¶

Once you have created an image, you can use any of the functions listed in the API below to change that image. For example, you can use setPixelValue to change an individual pixel.

Note

Co-ordinates are indexed from zero, with the origin (0,0) being at the top left of the image.

You can print characters onto an image:

1 2	`Image image(5,5); image.print('J');`

You can also paste the content of one image onto another - either at the origin, or somewhere else:

1 2	`Image image(5,5); image.paste(cross);`

1 2	`Image image(5,5); image.paste(cross, 1, 1);`

You can display your image on the LEDs using uBit.display:

1
2
3

Image image(5,5);
image.paste(cross);
uBit.display.print(image);

Note

Manipulation functions like paste operate in place. They do not return a copy; rather your existing image will be modified.

Comparing and assigning Images¶

Image is a managed type, so you can pass images as parameters to functions, store then and assign them to other variables without having to worry about memory leaks.

The type will count the number of times it is used, and will delete itself as soon as your image is not used anymore.

You can assign images just like any other variable. So this is perfectly permitted, and memory safe:

Example

Image cross("0,255,0\n255,255,255\n0,255,0\n");
Image img;

img = cross;
uBit.display.print(img);

As is this:

Example

void doSomething(Image i)
{
    uBit.display.print(img);
}

int main()
{
    Image cross("0,255,0\n255,255,255\n0,255,0\n");

    doSomething(cross);
}

You can also compare images:

Example

Image cross("0,255,0\n255,255,255\n0,255,0\n");
Image img;

img = cross;

if (img == cross)
    uBit.display.scroll("SAME!");

Storing Images in flash memory¶

By default, any Image you create will be stored in RAM (128KB) so that you have the ability to change it. However, it is not uncommon to have read-only images. In this case, we can store the image in FLASH memory (the same place as your program), of which the micro:bit has 512KB.

Should you want to create an store a constant image in flash, you can do so using the following constructor, it is a little more complicated, but can save you memory:

The array of bytes should always start with 0xff, 0xff - which tell the runtime that this image is stored in FLASH memory.
The next number should be the width in pixels, followed by a zero.
The next number should be the height in pixels, followed by a zero.
The following bytes are then individual pixel brightness values, starting at the top left, then working left to right, top to bottom until the bottom right corner is reached.

const uint8_t heart[] __attribute__ ((aligned (4))) = 
{ 
    0xff, 0xff, 
    10, 0, 
    5, 0, 
    0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0
};

Image i((ImageData*)heart);
uBit.display.animate(i,5);

These images will be read-only.

If you create an image this way, none of the functions to change the content will work on that image (e.g. setPixelValue, paste, etc).

API¶

getBitmap¶

uint8_t *

getBitmap
()

Description

Return a 2D array representing the bitmap image.

operator=¶

Image

operator=
(
const Image &
i)

Description

Copy assign operation.

Called when one Image is assigned the value of another using the '=' operator.

Decrement our reference count and free up the buffer as necessary.

Then, update our buffer to refer to that of the supplied Image , and increase its reference count.

Parameters

const Image &
i

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 Image i1(); 
 i1 = i; // i1 now references i

operator==¶

bool

operator==
(
const Image &
i)

Description

Equality operation.

Called when one Image is tested to be equal to another using the '==' operator.

Parameters

const Image &
i - The Image to test ourselves against.

Returns

true if this Image is identical to the one supplied, false otherwise.

Example

 DeviceDisplay display; 
 Image i(); 
 Image i1(); 

 if(i == i1) //will be true 
 display.scroll("true");

clear¶

void

clear
()

Description

Resets all pixels in this image to 0.

Example

 Image i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image 
 i.clear();

setPixelValue¶

int

setPixelValue
(
int16_t
x,
int16_t
y,
uint8_t
value)

Description

Sets the pixel at the given co-ordinates to a given value.

Parameters

int16_t
x - The co-ordinate of the pixel to change.

int16_t
y - The co-ordinate of the pixel to change.

uint8_t
value - The new value of the pixel (the brightness level 0-255)

Returns

DEVICE_OK, or DEVICE_INVALID_PARAMETER.

Example

 Image i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image 
 i.setPixelValue(0,0,255);

Note

all coordinates originate from the top left of an image.

getPixelValue¶

int

getPixelValue
(
int16_t
x,
int16_t
y)

Description

Retrieves the value of a given pixel.

Parameters

int16_t
x - The x co-ordinate of the pixel to read. Must be within the dimensions of the image.

int16_t
y - The y co-ordinate of the pixel to read. Must be within the dimensions of the image.

Returns

The value assigned to the given pixel location (the brightness level 0-255), or DEVICE_INVALID_PARAMETER.

Example

 Image i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image 
 i.getPixelValue(0,0); //should be 0;

printImage¶

int

printImage
(
int16_t
x,
int16_t
y,
const uint8_t *
bitmap)

Description

Replaces the content of this image with that of a given 2D array representing the image.

Parameters

int16_t
x - the width of the image. Must be within the dimensions of the image.

int16_t
y - the width of the image. Must be within the dimensions of the image.

const uint8_t *
bitmap - a 2D array representing the image.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(); 
 i.printImage(0,0,heart);

Note

all coordinates originate from the top left of an image.

paste¶

int

paste
(
const Image &
image)

Description

Pastes a given bitmap at the given co-ordinates.

Any pixels in the relevant area of this image are replaced.

Parameters

const Image &
image - The Image to paste.

Returns

The number of pixels written.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); // a big heart 
 i.paste(i, -5, 0); // a small heart

int

paste
(
const Image &
image,
int16_t
x)

Description

Pastes a given bitmap at the given co-ordinates.

Any pixels in the relevant area of this image are replaced.

Parameters

const Image &
image - The Image to paste.

int16_t
x - The leftmost X co-ordinate in this image where the given image should be pasted. Defaults to 0.

Returns

The number of pixels written.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); // a big heart 
 i.paste(i, -5, 0); // a small heart

int

paste
(
const Image &
image,
int16_t
x,
int16_t
y)

Description

Pastes a given bitmap at the given co-ordinates.

Any pixels in the relevant area of this image are replaced.

Parameters

const Image &
image - The Image to paste.

int16_t
x - The leftmost X co-ordinate in this image where the given image should be pasted. Defaults to 0.

int16_t
y - The uppermost Y co-ordinate in this image where the given image should be pasted. Defaults to 0.

Returns

The number of pixels written.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); // a big heart 
 i.paste(i, -5, 0); // a small heart

int

paste
(
const Image &
image,
int16_t
x,
int16_t
y,
uint8_t
alpha)

Description

Pastes a given bitmap at the given co-ordinates.

Any pixels in the relevant area of this image are replaced.

Parameters

const Image &
image - The Image to paste.

int16_t
x - The leftmost X co-ordinate in this image where the given image should be pasted. Defaults to 0.

int16_t
y - The uppermost Y co-ordinate in this image where the given image should be pasted. Defaults to 0.

uint8_t
alpha - set to 1 if transparency clear pixels in given image should be treated as transparent. Set to 0 otherwise. Defaults to 0.

Returns

The number of pixels written.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); // a big heart 
 i.paste(i, -5, 0); // a small heart

print¶

int

print
(
char
c)

Description

Prints a character to the display at the given location

Parameters

char
c - The character to display.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 Image i(5,5); 
 i.print('a');

int

print
(
char
c,
int16_t
x)

Description

Prints a character to the display at the given location

Parameters

char
c - The character to display.

int16_t
x - The x co-ordinate of on the image to place the top left of the character. Defaults to 0.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 Image i(5,5); 
 i.print('a');

int

print
(
char
c,
int16_t
x,
int16_t
y)

Description

Prints a character to the display at the given location

Parameters

char
c - The character to display.

int16_t
x - The x co-ordinate of on the image to place the top left of the character. Defaults to 0.

int16_t
y - The y co-ordinate of on the image to place the top left of the character. Defaults to 0.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 Image i(5,5); 
 i.print('a');

shiftLeft¶

int

shiftLeft
(
int16_t
n)

Description

Shifts the pixels in this Image a given number of pixels to the left.

Parameters

int16_t
n - The number of pixels to shift.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); // a big heart 
 i.shiftLeft(5); // a small heart

shiftRight¶

int

shiftRight
(
int16_t
n)

Description

Shifts the pixels in this Image a given number of pixels to the right.

Parameters

int16_t
n - The number of pixels to shift.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); // a big heart 
 i.shiftLeft(5); // a small heart 
 i.shiftRight(5); // a big heart

shiftUp¶

int

shiftUp
(
int16_t
n)

Description

Shifts the pixels in this Image a given number of pixels to upward.

Parameters

int16_t
n - The number of pixels to shift.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 i.shiftUp(1);

shiftDown¶

int

shiftDown
(
int16_t
n)

Description

Shifts the pixels in this Image a given number of pixels to downward.

Parameters

int16_t
n - The number of pixels to shift.

Returns

DEVICE_OK on success, or DEVICE_INVALID_PARAMETER.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 i.shiftDown(1);

getWidth¶

int

getWidth
()

Description

Gets the width of this image.

Returns

The width of this image.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 i.getWidth(); // equals 10...

getHeight¶

int

getHeight
()

Description

Gets the height of this image.

Returns

The height of this image.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 i.getHeight(); // equals 5...

getSize¶

int

getSize
()

Description

Gets number of bytes in the bitmap, ie., width * height.

Returns

The size of the bitmap.

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 i.getSize(); // equals 50...

toString¶

ManagedString

toString
()

Description

Converts the bitmap to a csv ManagedString .

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 uBit.serial.printString(i.toString()); // "0,1,0,1,0,0,0,0,0,0\n..."

crop¶

Image

crop
(
int
startx,
int
starty,
int
finx,
int
finy)

Description

Crops the image to the given dimensions.

Parameters

int
startx - the location to start the crop in the x-axis

int
starty - the location to start the crop in the y-axis

int
finx

int
finy

Example

 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i(10,5,heart); 
 i.crop(0,0,2,2).toString() // "0,1\n1,1\n"

isReadOnly¶

bool

isReadOnly
()

Description

Check if image is read-only (i.e., residing in flash).

clone¶

Image

clone
()

Description

Create a copy of the image bitmap. Used particularly, when isReadOnly() is true.

Returns

an instance of Image which can be modified independently of the current instance

Component Constructor¶

Advanced users only

Do not use this unless you really know what you're doing. It's usually best to use uBit.

Image(
ImageData *
ptr)

Description

Constructor. Create an image from a specially prepared constant array, with no copying. Will call ptr->incr().

Parameters

ImageData *
ptr - The literal - first two bytes should be 0xff, then width, 0, height, 0, and the bitmap. Width and height are 16 bit. The literal has to be 4-byte aligned.

Example

 static const uint8_t heart[] __attribute__ ((aligned (4))) = { 0xff, 0xff, 10, 0, 5, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart 
 Image i((ImageData*)(void*)heart);

Image¶

Overview¶

Using Images¶

Creating Images¶

Manipulating Images¶

Comparing and assigning Images¶

Storing Images in flash memory¶

API¶

getBitmap¶

uint8_t * getBitmap()

Description

operator=¶

Image operator=( const Image & i)

Description

Parameters

Example

operator==¶

bool operator==( const Image & i)

Description

Parameters

Returns

Example

clear¶

void clear()

Description

Example

setPixelValue¶

int setPixelValue( int16_t x, int16_t y, uint8_t value)

Description

Parameters

Returns

Example

getPixelValue¶

int getPixelValue( int16_t x, int16_t y)

Description

Parameters

Returns

Example

printImage¶

int printImage( int16_t x, int16_t y, const uint8_t * bitmap)

Description

Parameters

Returns

Example

paste¶

int paste( const Image & image)

Description

Parameters

Returns

Example

int paste( const Image & image, int16_t x)

Description

Parameters

Returns

Example

int paste( const Image & image, int16_t x, int16_t y)

Description

Parameters

Returns

Example

int paste( const Image & image, int16_t x, int16_t y, uint8_t alpha)

Description

Parameters

Returns

Example

print¶

int print( char c)

Description

Parameters

Returns

Example

int print( char c, int16_t x)

Description

Parameters

Returns

Example

int print( char c, int16_t x, int16_t y)

Description

Parameters

Returns

uint8_t *

getBitmap
()

Image

operator=
(
const Image &
i)

bool

operator==
(
const Image &
i)

void

clear
()

int

setPixelValue
(
int16_t
x,
int16_t
y,
uint8_t
value)

int

getPixelValue
(
int16_t
x,
int16_t
y)

int

printImage
(
int16_t
x,
int16_t
y,
const uint8_t *
bitmap)

int

paste
(
const Image &
image)

int

paste
(
const Image &
image,
int16_t
x)

int

paste
(
const Image &
image,
int16_t
x,
int16_t
y)

int

paste
(
const Image &
image,
int16_t
x,
int16_t
y,
uint8_t
alpha)

int

print
(
char
c)

int

print
(
char
c,
int16_t
x)

int

print
(
char
c,
int16_t
x,
int16_t
y)

int

shiftLeft
(
int16_t
n)

int

shiftRight
(
int16_t
n)

int

shiftUp
(
int16_t
n)

int

shiftDown
(
int16_t
n)

int

getWidth
()

int

getHeight
()

int

getSize
()

ManagedString

toString
()

Image

crop
(
int
startx,
int
starty,
int
finx,
int
finy)

bool

isReadOnly
()

Image

clone
()

Image(
ImageData *
ptr)