Fetching contributors…
Cannot retrieve contributors at this time
240 lines (160 sloc) 6.13 KB


.. py:module:: microbit

The Image class is used to create images that can be displayed easily on the device's LED matrix. Given an image object it's possible to display it via the display API:


There are four ways in which you can construct an image:

  • Image() - Create a blank 5x5 image
  • Image(string) - Create an image by parsing the string, a single character returns that glyph
  • Image(width, height) - Create a blank image of given size
  • Image(width, height, buffer) - Create an image from the given buffer


.. py:class::
    Image(width=None, height=None, buffer=None)

    If ``string`` is used, it has to consist of digits 0-9 arranged into
    lines, describing the image, for example::

        image = Image("90009:"

    will create a 5×5 image of an X. The end of a line is indicated by a colon.
    It's also possible to use a newline (\n) to indicate the end of a line
    like this::

        image = Image("90009\n"

    The other form creates an empty image with ``width`` columns and
    ``height`` rows. Optionally ``buffer`` can be an array of
    ``width``×``height`` integers in range 0-9 to initialize the image::

        Image(2, 2, b'\x08\x08\x08\x08')


        Image(2, 2, bytearray([9,9,9,9]))

    Will create a 2 x 2 pixel image at full brightness.

    .. note::

        Keyword arguments cannot be passed to ``buffer``.

    .. py:method:: width()

        Return the number of columns in the image.

    .. py:method:: height()

        Return the numbers of rows in the image.

    .. py:method:: set_pixel(x, y, value)

        Set the brightness of the pixel at column ``x`` and row ``y`` to the
        ``value``, which has to be between 0 (dark) and 9 (bright).

        This method will raise an exception when called on any of the built-in
        read-only images, like ``Image.HEART``.

    .. py:method:: get_pixel(x, y)

        Return the brightness of pixel at column ``x`` and row ``y`` as an
        integer between 0 and 9.

    .. py:method:: shift_left(n)

        Return a new image created by shifting the picture left by ``n``

    .. py:method:: shift_right(n)

        Same as ``image.shift_left(-n)``.

    .. py:method:: shift_up(n)

        Return a new image created by shifting the picture up by ``n`` rows.

    .. py:method:: shift_down(n)

        Same as ``image.shift_up(-n)``.

    .. py:method:: crop(x, y, w, h)

        Return a new image by cropping the picture to a width of ``w`` and a
        height of ``h``, starting with the pixel at column ``x`` and row ``y``.

    .. py:method:: copy()

        Return an exact copy of the image.

    .. py:method:: invert()

        Return a new image by inverting the brightness of the pixels in the
        source image.

    .. py:method:: fill(value)

        Set the brightness of all the pixels in the image to the
        ``value``, which has to be between 0 (dark) and 9 (bright).

        This method will raise an exception when called on any of the built-in
        read-only images, like ``Image.HEART``.

    .. py:method:: blit(src, x, y, w, h, xdest=0, ydest=0)

        Copy the rectangle defined by ``x``, ``y``, ``w``, ``h`` from the image ``src`` into
        this image at ``xdest``, ``ydest``.
        Areas in the source rectangle, but outside the source image are treated as having a value of 0.

        ``shift_left()``, ``shift_right()``, ``shift_up()``, ``shift_down()`` and ``crop()``
        can are all implemented by using ``blit()``.
        For example, img.crop(x, y, w, h) can be implemented as::

            def crop(self, x, y, w, h):
                res = Image(w, h)
                res.blit(self, x, y, w, h)
                return res


The Image class also has the following built-in instances of itself included as its attributes (the attribute names indicate what the image represents):

  • Image.HEART
  • Image.HAPPY
  • Image.SMILE
  • Image.SAD
  • Image.CONFUSED
  • Image.ANGRY
  • Image.ASLEEP
  • Image.SILLY
  • Image.FABULOUS
  • Image.MEH
  • Image.YES
  • Image.NO
  • Image.CLOCK12, Image.CLOCK11, Image.CLOCK10, Image.CLOCK9, Image.CLOCK8, Image.CLOCK7, Image.CLOCK6, Image.CLOCK5, Image.CLOCK4, Image.CLOCK3, Image.CLOCK2, Image.CLOCK1
  • Image.ARROW_N, Image.ARROW_NE, Image.ARROW_E, Image.ARROW_SE, Image.ARROW_S, Image.ARROW_SW, Image.ARROW_W, Image.ARROW_NW
  • Image.TRIANGLE
  • Image.DIAMOND
  • Image.SQUARE
  • Image.RABBIT
  • Image.COW
  • Image.XMAS
  • Image.PACMAN
  • Image.TARGET
  • Image.TSHIRT
  • Image.DUCK
  • Image.HOUSE
  • Image.TORTOISE
  • Image.GHOST
  • Image.SWORD
  • Image.GIRAFFE
  • Image.SKULL
  • Image.UMBRELLA
  • Image.SNAKE

Finally, related collections of images have been grouped together:

* ``Image.ALL_CLOCKS``
* ``Image.ALL_ARROWS``



Get a compact string representation of the image.


Get a readable string representation of the image.

image1 + image2

Create a new image by adding the brightness values from the two images for each pixel.

image * n

Create a new image by multiplying the brightness of each pixel by n.