pygraphics

Cross-platform 2D drawing for MicroPython, CircuitPython and CPython.

Draw shapes, text and images into a framebuffer. Every drawing call returns the Area it changed, so you can send just that part to a screen.

The compiled module and the pure-Python package have the same names, except four that write or read Python source and exist only in the pure-Python package; each says so. implementation() tells you which one you have.

Example:

import pygraphics

fb = pygraphics.FrameBuffer(bytearray(16 * 16 * 2), 16, 16, pygraphics.RGB565)
fb.fill(0)
area = fb.fill_rect(1, 1, 6, 6, 0xFFFF)
pygraphics.text8(fb, "Hi", 0, 0, 0xFFFF)
pygraphics.MONO_VLSB

1 bit per pixel; each byte is 8 pixels down a column, low bit at the top.

pygraphics.MONO_HLSB

1 bit per pixel; bytes run across a row, high bit on the left.

pygraphics.MONO_HMSB

1 bit per pixel; bytes run across a row, low bit on the left.

pygraphics.GS2_HMSB

four-level greyscale.

Type:

2 bits per pixel

pygraphics.GS4_HMSB

sixteen-level greyscale.

Type:

4 bits per pixel

pygraphics.GS8

256-level greyscale.

Type:

8 bits per pixel

pygraphics.RGB565

16 bits per pixel, the format of most small colour screens.

pygraphics.RGB888

24 bits per pixel, stored red, green, blue. pygraphics’ own format, not framebuf’s.

class pygraphics.Area(x, y=None, w=None, h=None)[source]

Bases: object

Rectangular geometry helper used for dirty-rectangle updates, hit testing, and clipping.

Area values are commonly returned by drawing helpers such as fill_rect and circle and can be used to refresh only the pixels that changed. They are also useful for widget hit testing, button bounds, and trimming a draw operation to a sub-region of the screen.

The constructor accepts either separate (x, y, w, h) values or a single tuple containing those four values.

x

The x-coordinate of the top-left corner of the area.

Type:

int | float

y

The y-coordinate of the top-left corner of the area.

Type:

int | float

w

The width of the area.

Type:

int | float

h

The height of the area.

Type:

int | float

contains(x, y=None)[source]

Checks if the specified point is contained within the area.

Parameters:
  • x (int | tuple) – The x-coordinate of the point to check or a tuple containing the x and y coordinates of the point.

  • y (int) – The y-coordinate of the point to check.

Returns:

(bool) – True if the point is contained within the area, False otherwise.

contains_area(other)[source]

Checks if the specified area is contained within the area.

Parameters:

other (Area) – The other area to check.

Returns:

(bool) – True if the other area is contained within the area, False otherwise.

intersects(other)[source]

Checks if the current Area object intersects with another Area object.

Parameters:

other (Area) – The other Area object to check for overlap.

Returns:

(bool) – True if the two Area objects intersect, False otherwise.

touches_or_intersects(other)[source]

Checks if the current Area object touches or intersects with another Area object.

Parameters:

other (Area) – The other Area object to check for overlap or touch.

Returns:

(bool) – True if the two Area objects touch or intersect, False otherwise.

shift(dx=0, dy=0)[source]

Returns a new Area shifted by the specified amount in the x and y directions.

Parameters:
  • dx (int | float) – The amount to shift the area in the x direction.

  • dy (int | float) – The amount to shift the area in the y direction.

Returns:

(Area) – A new Area object shift by the specified amount in the x and y directions.

clip(other)[source]

Clips the current Area object to the specified Area object.

Parameters:

other (Area) – The other Area object to clip to.

Returns:

(Area) – A new Area object representing the clipped area.

offset(d1, d2=None, d3=None, d4=None)[source]

Returns a new Area offset by the specified amount(s).

If only one argument is provided, it is used as the offset in all 4 directions. If two arguments are provided, the first is used as the offset in the x direction and the second as the offset in the y direction. If three arguments are provided, they are used as the offsets in the left, top/bottom, and right directions, respectively. If four arguments are provided, they are used as the offsets in the left, top, right, and bottom directions, respectively.

Parameters:
  • d1 (int | float) – The offset in the x direction or the offset in all 4 directions.

  • d2 (int | float) – The offset in the y direction or the offset in the top/bottom direction.

  • d3 (int | float) – The offset in the right direction.

  • d4 (int | float) – The offset in the bottom direction.

Returns:

(Area) – A new Area object offset by the specified amount(s).

inset(d1, d2=None, d3=None, d4=None)[source]

Returns a new Area inset by the specified amount(s).

If only one argument is provided, it is used as the inset in all 4 directions. If two arguments are provided, the first is used as the inset in the x direction and the second as the inset in the y direction. If three arguments are provided, they are used as the insets in the left, top/bottom, and right directions, respectively. If four arguments are provided, they are used as the insets in the left, top, right, and bottom directions, respectively.

Parameters:
  • d1 (int | float) – The inset in the x direction or the inset in all 4 directions.

  • d2 (int | float) – The inset in the y direction or the inset in the top/bottom direction.

  • d3 (int | float) – The inset in the right direction.

  • d4 (int | float) – The inset in the bottom direction.

Returns:

(Area) – A new Area object inset by the specified amount(s).

class pygraphics.FrameBuffer(buffer, width, height, format, *args, **kwargs)[source]

Bases: object

Framebuffer surface for drawing either to the display itself or to an off-screen buffer.

This class preserves the standard framebuf API while adding helpers for shapes, text, and image I/O. Each draw operation returns an Area describing the pixels that changed, which is ideal for dirty-rectangle updates and for compositing a pre-rendered scene before pushing it to the display.

Typical usage is to create a bytearray large enough for the target size, draw a frame with fill, fill_rect, circle, or text8, then copy that buffer to a display driver or use the returned Area to refresh only the changed region.

Parameters:
  • buffer (bytearray) – Framebuffer buffer.

  • width (int) – Width in pixels.

  • height (int) – Height in pixels.

  • format (int) – Framebuffer format constant such as RGB565 or RGB888.

property color_depth

Bits per pixel for the current format (1, 2, 4, 8, 16, or 24).

property width

Framebuffer width in pixels.

property height

Framebuffer height in pixels.

property buffer

Underlying pixel buffer passed to the constructor.

property format

Pixel format constant (RGB565, RGB888, MONO_HLSB, …).

fill_rect(x, y, w, h, c)[source]

Fill a rectangle with a solid color.

This is the usual primitive for clearing a region, drawing panels, or staging a background before more detailed shapes or text are drawn.

Parameters:
  • x (int) – X coordinate of the top-left corner.

  • y (int) – Y coordinate of the top-left corner.

  • w (int) – Width in pixels.

  • h (int) – Height in pixels.

  • c (int) – Color to write.

Returns:

Area – Bounding box of the filled rectangle.

pixel(x, y, c=None)[source]

Read or draw a single pixel.

With c it draws the pixel; without, it reads the pixel’s color.

Parameters:
  • x (int) – x coordinate

  • y (int) – y coordinate

  • c (int) – color to draw (default: None, to read the pixel)

Returns:

(Area | int) – The bounding box of the pixel when drawing, or the pixel’s color when reading.

fill(c)[source]

Fill the buffer with the given color.

Parameters:

c (int) – color

Returns:

(Area) – Bounding box of the filled buffer

ellipse(x, y, rx, ry, c, f=False, m=15)[source]

Draw an ellipse at the given location, radii and color.

Parameters:
  • x (int) – Center x coordinate

  • y (int) – Center y coordinate

  • rx (int) – X radius

  • ry (int) – Y radius

  • c (int) – color

  • f (bool) – Fill the ellipse (default: False)

  • m (int) – Bitmask to determine which quadrants to draw (default: 0b1111)

Returns:

(Area) – Bounding box of the ellipse

hline(x, y, w, c)[source]

Draw a horizontal line at the given location, width and color.

Parameters:
  • x (int) – x coordinate

  • y (int) – y coordinate

  • w (int) – Width in pixels

  • c (int) – color

Returns:

(Area) – Bounding box of the horizontal line

line(x1, y1, x2, y2, c)[source]

Draw a line between the given start and end points and color.

Parameters:
  • x1 (int) – Start x coordinate

  • y1 (int) – Start y coordinate

  • x2 (int) – End x coordinate

  • y2 (int) – End y coordinate

  • c (int) – color

Returns:

(Area) – Bounding box of the line

poly(x, y, coords, c, f=False)[source]

Draw a polygon at the given location, coordinates and color.

Parameters:
  • x (int) – x coordinate

  • y (int) – y coordinate

  • coords (array) – Array of x, y coordinate tuples

  • c (int) – color

  • f (bool) – Fill the polygon (default: False)

Raises:

MemoryError – In the compiled module, a filled polygon of more than 256 vertices needs one int of scratch memory per vertex, and there wasn’t enough. Nothing is drawn. A polygon of any size fills; 256 vertices or fewer allocates nothing.

Returns:

(Area) – Bounding box of the polygon

rect(x, y, w, h, c, f=False)[source]

Draw a rectangle at the given location, size and color.

Parameters:
  • x (int) – Top left corner x coordinate

  • y (int) – Top left corner y coordinate

  • w (int) – Width in pixels

  • h (int) – Height in pixels

  • c (int) – color

  • f (bool) – Fill the rectangle (default: False)

Returns:

(Area) – Bounding box of the rectangle

vline(x, y, h, c)[source]

Draw a vertical line at the given location, height and color.

Parameters:
  • x (int) – x coordinate

  • y (int) – y coordinate

  • h (int) – Height in pixels

  • c (int) – color

Returns:

(Area) – Bounding box of the vertical line

text(s, x, y, c=1, scale=1, inverted=False, font_data=None, height=8)[source]

Draw text at the given location, using the given font and color.

Parameters:
  • s (str) – Text to draw

  • x (int) – x coordinate

  • y (int) – y coordinate

  • c (int) – color

  • scale (int) – Scale factor (default: 1)

  • inverted (bool) – Invert the text (default: False)

  • font_data (str) – Path to the font file (default: None)

  • height (int) – Height of the font (default: 8)

Returns:

(Area) – Bounding box of the text

blit(source, x, y, key=-1, palette=None)[source]

Blit the given buffer at the given location.

Parameters:
  • source (FrameBuffer) – FrameBuffer to blit

  • x (int) – x coordinate

  • y (int) – y coordinate

  • key (int) – Color key (default: -1)

  • palette (FrameBuffer) – Palette (default: None)

Returns:

(Area) – Bounding box of the blitted buffer

arc(x, y, r, a0, a1, c)[source]

Arc drawing function. Will draw a single pixel wide arc with a radius r centered at x, y from a0 to a1.

Parameters:
  • x (int) – X-coordinate of the arc’s center.

  • y (int) – Y-coordinate of the arc’s center.

  • r (int) – Radius of the arc.

  • a0 (float) – Starting angle in degrees.

  • a1 (float) – Ending angle in degrees.

  • c (int) – color.

Returns:

(Area) – The bounding box of the arc.

blit_rect(buf, x, y, w, h)[source]

Blit a rectangular area from a buffer to the canvas. Uses the canvas’s blit_rect method if available, otherwise writes directly to the buffer.

Parameters:
  • buf (memoryview) – Buffer to blit. Must already be byte-swapped if necessary.

  • x (int) – X-coordinate to blit to.

  • y (int) – Y-coordinate to blit to.

  • w (int) – Width of the area to blit.

  • h (int) – Height of the area to blit.

Returns:

(Area) – The bounding box of the blitted area.

blit_transparent(buf, x, y, w, h, key)[source]

Blit a buffer with transparency.

Parameters:
  • buf (memoryview) – Buffer to blit.

  • x (int) – X-coordinate to blit to.

  • y (int) – Y-coordinate to blit to.

  • w (int) – Width of the area to blit.

  • h (int) – Height of the area to blit.

  • key (int) – Key value for transparency.

Returns:

(Area) – The bounding box of the blitted area.

blit_alpha(buf, x, y, w, h, color)[source]

Tint color onto the framebuffer through an 8-bit alpha mask.

buf holds w * h alpha values, one byte each, row by row. Each pixel becomes (color * a + old * (255 - a) + 127) // 255, worked out per channel (5, 6 and 5 bits for RGB565, 8 each for RGB888, one for GS8), so alpha 0 leaves the pixel alone and 255 writes color. color is a pixel value in the framebuffer’s own format, the same number pixel takes. The mask is read where it lives and never copied, so a memoryview over a frozen bytes literal stays in flash. Parts of the mask outside the framebuffer are clipped.

Parameters:
  • buf (bytes) – Alpha mask: bytes, bytearray or memoryview.

  • x (int) – X-coordinate of the mask’s top-left corner.

  • y (int) – Y-coordinate of the mask’s top-left corner.

  • w (int) – Mask width in pixels.

  • h (int) – Mask height in pixels.

  • color (int) – Tint, in the framebuffer’s pixel format.

Returns:

(Area) – The bounding box of the mask.

Raises:

ValueError – If the format is not RGB565, RGB888 or GS8, if w or h is negative, or if buf is shorter than w * h.

circle(x0, y0, r, c, f=False)[source]

Circle drawing function. Will draw a single pixel wide circle centered at x0, y0 and the specified r.

Parameters:
  • x0 (int) – Center x coordinate

  • y0 (int) – Center y coordinate

  • r (int) – Radius

  • c (int) – Color

  • f (bool) – Fill the circle (default: False)

Returns:

(Area) – The bounding box of the circle.

gradient_rect(x, y, w, h, c1, c2=None, vertical=True)[source]

Fill a rectangle with a gradient.

Parameters:
  • x (int) – X-coordinate of the top-left corner of the rectangle.

  • y (int) – Y-coordinate of the top-left corner of the rectangle.

  • w (int) – Width of the rectangle.

  • h (int) – Height of the rectangle.

  • c1 (int) – 565 encoded color for the top or left edge.

  • c2 (int) – 565 encoded color for the bottom or right edge. If None or the same as c1, fill_rect will be called instead.

  • vertical (bool) – If True, the gradient will be vertical. If False, the gradient will be horizontal.

Returns:

(Area) – The bounding box of the filled area.

polygon(points, x, y, color, angle=0, center_x=0, center_y=0)[source]

Draw a polygon on the canvas.

Parameters:
  • points (list) – List of points to draw.

  • x (int) – X-coordinate of the polygon’s position.

  • y (int) – Y-coordinate of the polygon’s position.

  • color (int) – color.

  • angle (float) – Rotation angle in radians (default: 0).

  • center_x (int) – X-coordinate of the rotation center (default: 0).

  • center_y (int) – Y-coordinate of the rotation center (default: 0).

Raises:

ValueError – If the polygon has less than 3 points.

Returns:

(Area) – The bounding box of the polygon.

round_rect(x0, y0, w, h, r, c, f=False)[source]

Rounded rectangle drawing function. Will draw a single pixel wide rounded rectangle starting at x0, y0 and extending w, h pixels with the specified radius.

Parameters:
  • x0 (int) – X-coordinate of the top-left corner of the rectangle.

  • y0 (int) – Y-coordinate of the top-left corner of the rectangle.

  • w (int) – Width of the rectangle.

  • h (int) – Height of the rectangle.

  • r (int) – Radius of the corners.

  • c (int) – color.

  • f (bool) – Fill the rectangle (default: False).

Returns:

(Area) – The bounding box of the rectangle.

triangle(x0, y0, x1, y1, x2, y2, c, f=False)[source]

Triangle drawing function. Draws a single pixel wide triangle with vertices at (x0, y0), (x1, y1), and (x2, y2).

Parameters:
  • x0 (int) – X-coordinate of the first vertex.

  • y0 (int) – Y-coordinate of the first vertex.

  • x1 (int) – X-coordinate of the second vertex.

  • y1 (int) – Y-coordinate of the second vertex.

  • x2 (int) – X-coordinate of the third vertex.

  • y2 (int) – Y-coordinate of the third vertex.

  • c (int) – color.

  • f (bool) – Fill the triangle (default: False).

Returns:

(Area) – The bounding box of the triangle.

text8(s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Place text on the canvas with an 8 pixel high font. Breaks on \n to next line. Does not break on line going off canvas.

Parameters:
  • s (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • c (int) – The color to draw the text in. Default is 1.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

  • font_data (str) – The path to the font file to use. Default is None.

Returns:

Area – The area that was drawn to.

text14(s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Place text on the canvas with a 14 pixel high font. Breaks on \n to next line. Does not break on line going off canvas.

Parameters:
  • s (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • c (int) – The color to draw the text in. Default is 1.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

  • font_data (str) – The path to the font file to use. Default is None.

Returns:

Area – The area that was drawn to.

text16(s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Place text on the canvas with a 16 pixel high font. Breaks on \n to next line. Does not break on line going off canvas.

Parameters:
  • s (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • c (int) – The color to draw the text in. Default is 1.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

  • font_data (str) – The path to the font file to use. Default is None.

Returns:

Area – The area that was drawn to.

scroll(xstep, ystep)[source]

Scroll buffer contents. Returns the full buffer bounds.

save(filename=None)[source]

Save the framebuffer to a file. The file extension must match the format, otherwise the extension will be appended to the filename.

Saves 1-bit formats as PBM, 2-bit formats as PGM with max value 3, 4-bit formats as PGM with max value 15, 8-bit formats as PGM with max value 255, and 16-bit formats as BMP.

Parameters:

filename (str) – Filename to save to

export(filename)[source]

Export this framebuffer as an importable .py bitmap module.

Only the pure-Python package has this.

See pygraphics._files.export_framebuffer. Ships BITMAP as a bytearray for zero-copy from_bitmap on MicroPython.

static from_file(filename)[source]

Load a framebuffer from a file.

Parameters:

filename (str) – Filename to load from

Returns:

FrameBuffer – Image loaded as a framebuffer.

static from_bitmap(buffer, width, height, format)[source]

Build a FrameBuffer from a bitmap buffer (export-module style).

If buffer is already a writable bytearray (or a writable memoryview), it is used without copying. Legacy bytes / memoryview(bytes) modules get one bytearray copy so MicroPython can own a writable pixel buffer.

Only the pure-Python package has this.

static from_module(mod)[source]

Load from a module with WIDTH, HEIGHT, FORMAT, BITMAP.

Only the pure-Python package has this.

pygraphics.arc(canvas, x, y, r, a0, a1, c)[source]

Arc drawing function. Will draw a single pixel wide arc with a radius r centered at x, y from a0 to a1.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x (int) – X-coordinate of the arc’s center.

  • y (int) – Y-coordinate of the arc’s center.

  • r (int) – Radius of the arc.

  • a0 (float) – Starting angle in degrees.

  • a1 (float) – Ending angle in degrees.

  • c (int) – color.

Returns:

(Area) – The bounding box of the arc.

pygraphics.blit(canvas, source, x, y, key=-1, palette=None)[source]

Copy a source buffer or sprite onto a canvas.

This is useful for compositing an off-screen frame into the live display, for scrolling text and sprite animations, and for drawing pre-rendered tiles or bitmaps. The returned area is the region that was written so that it can be treated as a dirty rectangle.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • source (FrameBuffer) – Source framebuffer or canvas-like object.

  • x (int) – X-coordinate to blit to.

  • y (int) – Y-coordinate to blit to.

  • key (int) – Key value for transparency (default: -1).

  • palette (Palette) – Palette object for color translation (default: None).

Returns:

Area – The bounding box of the blitted area.

pygraphics.blit_rect(canvas, buf, x, y, w, h)[source]

Blit a rectangular area from a buffer to the canvas. Uses the canvas’s blit_rect method if available, otherwise writes directly to the buffer.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • buf (memoryview) – Buffer to blit. Must already be byte-swapped if necessary.

  • x (int) – X-coordinate to blit to.

  • y (int) – Y-coordinate to blit to.

  • w (int) – Width of the area to blit.

  • h (int) – Height of the area to blit.

Returns:

(Area) – The bounding box of the blitted area.

pygraphics.blit_transparent(canvas, buf, x, y, w, h, key)[source]

Blit a buffer with transparency.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • buf (memoryview) – Buffer to blit.

  • x (int) – X-coordinate to blit to.

  • y (int) – Y-coordinate to blit to.

  • w (int) – Width of the area to blit.

  • h (int) – Height of the area to blit.

  • key (int) – Key value for transparency.

Returns:

(Area) – The bounding box of the blitted area.

pygraphics.circle(canvas, x0, y0, r, c, f=False)[source]

Draw a circle or filled disk centered at (x0, y0).

This is a common primitive for buttons, status indicators, animated balls, and other UI ornaments. Pass f=True for a filled circle.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – Center x coordinate.

  • y0 (int) – Center y coordinate.

  • r (int) – Radius.

  • c (int) – Color.

  • f (bool) – Fill the circle (default: False).

Returns:

Area – The bounding box of the circle.

pygraphics.ellipse(canvas, x0, y0, r1, r2, c, f=False, m=15, w=None, h=None)[source]

Midpoint ellipse algorithm Draw an ellipse at the given location. Radii r1 and r2 define the geometry; equal values cause a circle to be drawn. The c parameter defines the color.

The optional f parameter can be set to True to fill the ellipse. Otherwise just a one pixel outline is drawn.

The optional m parameter enables drawing to be restricted to certain quadrants of the ellipse. The LS four bits determine which quadrants are to be drawn, with bit 0 specifying Q1, b1 Q2, b2 Q3 and b3 Q4. Quadrants are numbered counterclockwise with Q1 being top right.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – Center x coordinate

  • y0 (int) – Center y coordinate

  • r1 (int) – x radius

  • r2 (int) – y radius

  • c (int) – color

  • f (bool) – Fill the ellipse (default: False)

  • m (int) – Bitmask to determine which quadrants to draw (default: 0b1111)

  • w (int) – Width of the ellipse (default: None)

  • h (int) – Height of the ellipse (default: None)

Returns:

(Area) – The bounding box of the ellipse.

pygraphics.fill(canvas, c)[source]

Fill the entire canvas with a solid color.

This is the typical first step for each frame: clear the previous scene, then draw the next frame on top of it.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • c (int) – Color.

Returns:

Area – The bounding box of the filled area.

pygraphics.fill_rect(canvas, x, y, w, h, c)[source]

Draw a filled rectangle.

Use this for backgrounds, panels, status bars, and other simple UI blocks. It is also the workhorse for clipping and partial redraw operations.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x (int) – X-coordinate of the top-left corner.

  • y (int) – Y-coordinate of the top-left corner.

  • w (int) – Width of the rectangle.

  • h (int) – Height of the rectangle.

  • c (int) – Color.

Returns:

Area – The bounding box of the filled area.

pygraphics.gradient_rect(canvas, x, y, w, h, c1, c2=None, vertical=True)[source]

Fill a rectangle with a vertical or horizontal color ramp.

This is useful for scenery, backgrounds, and other effects where a smooth transition looks better than a flat fill. The gallery applications use it for animated skies and other stylized backdrops.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x (int) – X-coordinate of the top-left corner.

  • y (int) – Y-coordinate of the top-left corner.

  • w (int) – Width of the rectangle.

  • h (int) – Height of the rectangle.

  • c1 (int) – Color for the top or left edge (format-native).

  • c2 (int) – Color for the bottom or right edge. If omitted or equal to c1, the helper falls back to fill_rect.

  • vertical (bool) – If True, draw a vertical gradient; otherwise a horizontal one.

Returns:

Area – The bounding box of the filled area.

pygraphics.hline(canvas, x0, y0, w, c)[source]

Horizontal line drawing function. Will draw a single pixel wide line.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – X-coordinate of the start of the line.

  • y0 (int) – Y-coordinate of the start of the line.

  • w (int) – Width of the line.

  • c (int) – color.

Returns:

(Area) – The bounding box of the line.

pygraphics.line(canvas, x0, y0, x1, y1, c)[source]

Draw a single-pixel line from (x0, y0) to (x1, y1).

Use this for outlines, rulers, charts, and small UI connectors where a solid stroke is more appropriate than a filled shape.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – X-coordinate of the start of the line.

  • y0 (int) – Y-coordinate of the start of the line.

  • x1 (int) – X-coordinate of the end of the line.

  • y1 (int) – Y-coordinate of the end of the line.

  • c (int) – Color.

Returns:

Area – The bounding box of the line.

pygraphics.pixel(canvas, x, y, c)[source]

Draw a single pixel at the specified x, y location. Uses the canvas’s pixel method if available, otherwise writes directly to the buffer.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x (int) – X-coordinate of the pixel.

  • y (int) – Y-coordinate of the pixel.

  • c (int) – color.

Returns:

(Area) – The bounding box of the pixel.

pygraphics.poly(canvas, x, y, coords, c, f=False)[source]

Given a list of coordinates, draw an arbitrary (convex or concave) closed polygon at the given x, y location using the given color.

The coords must be specified as an array of integers, e.g. array(‘h’, [x0, y0, x1, y1, … xn, yn]) or a list or tuple of points, e.g. [(x0, y0), (x1, y1), … (xn, yn)].

The optional f parameter can be set to True to fill the polygon. Otherwise, just a one-pixel outline is drawn.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x (int) – X-coordinate of the polygon’s position.

  • y (int) – Y-coordinate of the polygon’s position.

  • coords (list) – List of coordinates.

  • c (int) – color.

  • f (bool) – Fill the polygon (default: False).

Raises:

MemoryError – In the compiled module, a filled polygon of more than 256 vertices needs one int of scratch memory per vertex, and there wasn’t enough. Nothing is drawn. A polygon of any size fills; 256 vertices or fewer allocates nothing.

Returns:

(Area) – The bounding box of the polygon.

pygraphics.polygon(canvas, points, x, y, color, angle=0, center_x=0, center_y=0)[source]

Draw a polygon on the canvas.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • points (list) – List of points to draw.

  • x (int) – X-coordinate of the polygon’s position.

  • y (int) – Y-coordinate of the polygon’s position.

  • color (int) – color.

  • angle (float) – Rotation angle in radians (default: 0).

  • center_x (int) – X-coordinate of the rotation center (default: 0).

  • center_y (int) – Y-coordinate of the rotation center (default: 0).

Raises:

ValueError – If the polygon has less than 3 points.

Returns:

(Area) – The bounding box of the polygon.

pygraphics.rect(canvas, x0, y0, w, h, c, f=False)[source]

Rectangle drawing function. Will draw a single pixel wide rectangle starting at x0, y0 and extending w, h pixels.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – X-coordinate of the top-left corner of the rectangle.

  • y0 (int) – Y-coordinate of the top-left corner of the rectangle.

  • w (int) – Width of the rectangle.

  • h (int) – Height of the rectangle.

  • c (int) – color.

  • f (bool) – Fill the rectangle (default: False).

Returns:

(Area) – The bounding box of the rectangle.

pygraphics.round_rect(canvas, x0, y0, w, h, r, c, f=False)[source]

Rounded rectangle drawing function. Will draw a single pixel wide rounded rectangle starting at x0, y0 and extending w, h pixels with the specified radius.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – X-coordinate of the top-left corner of the rectangle.

  • y0 (int) – Y-coordinate of the top-left corner of the rectangle.

  • w (int) – Width of the rectangle.

  • h (int) – Height of the rectangle.

  • r (int) – Radius of the corners.

  • c (int) – color.

  • f (bool) – Fill the rectangle (default: False).

Returns:

(Area) – The bounding box of the rectangle.

pygraphics.triangle(canvas, x0, y0, x1, y1, x2, y2, c, f=False)[source]

Triangle drawing function. Draws a single pixel wide triangle with vertices at (x0, y0), (x1, y1), and (x2, y2).

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – X-coordinate of the first vertex.

  • y0 (int) – Y-coordinate of the first vertex.

  • x1 (int) – X-coordinate of the second vertex.

  • y1 (int) – Y-coordinate of the second vertex.

  • x2 (int) – X-coordinate of the third vertex.

  • y2 (int) – Y-coordinate of the third vertex.

  • c (int) – color.

  • f (bool) – Fill the triangle (default: False).

Returns:

(Area) – The bounding box of the triangle.

pygraphics.vline(canvas, x0, y0, h, c)[source]

Horizontal line drawing function. Will draw a single pixel wide line.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • x0 (int) – X-coordinate of the start of the line.

  • y0 (int) – Y-coordinate of the start of the line.

  • h (int) – Height of the line.

  • c (int) – color.

Returns:

(Area) – The bounding box of the line.

pygraphics.text(*args, height=8, **kwargs)[source]

Selector to call the correct text function based on the height of the font. See text8, text14, and text16 for more information.

Parameters:

height (int) – The height of the font to use. Default is 8.

pygraphics.text8(canvas, s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Draw a single line of text with the built-in 8-pixel font.

This helper suits labels, status text, and scrolling captions. The text is written into the given canvas at (x, y) and returns the region that was updated so that it can be used as a dirty rectangle.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • s (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • c (int) – The color to draw the text in. Default is 1.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

  • font_data (str | bytearray) – Path to a font file or memoryview. Default is None.

Returns:

Area – The area that was drawn to.

pygraphics.text14(canvas, s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Place text on the canvas with a 14 pixel high font. Breaks on \n to next line. Does not break on line going off canvas.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • s (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • c (int) – The color to draw the text in. Default is 1.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

  • font_data (str | bytearray) – The path to the font .bin file or memoryview. Default is None.

Returns:

Area – The area that was drawn to.

pygraphics.text16(canvas, s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Place text on the canvas with a 16 pixel high font. Breaks on \n to next line. Does not break on line going off canvas.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • s (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • c (int) – The color to draw the text in. Default is 1.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

  • font_data (str | bytearray) – The path to the font .bin file or memoryview. Default is None.

Returns:

Area – The area that was drawn to.

class pygraphics.Font(font_data=None, height=None, cached=True)[source]

Bases: object

Load a bundled romfont and reuse it for multiple text draws.

Font is useful when the same UI needs to draw several labels, scores, or status strings with the same glyph set. It can load either an embedded font or a custom .bin file from disk or from memory.

Parameters:
  • font_data (str | bytearray) – Path to a font file or memoryview. Default is None.

  • height (int) – The height of the font. Default is None.

  • cached (bool) – If True (default), read the font into memory on init. If False, read it from disk each time it is needed.

font_name

"default", the file’s base name, or "memoryview".

Type:

What the font is called

property width

Return the width of the font in pixels.

property height

Return the height of the font in pixels.

deinit()[source]

Close the font file as cleanup.

draw_char(char, x, y, canvas, color, scale=1, inverted=False)[source]

Draw one character at position (x,y).

Parameters:
  • char (str) – The character to draw.

  • x (int) – The x position to draw the character.

  • y (int) – The y position to draw the character.

  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • color (int) – The color to draw the character in.

  • scale (int) – The scale factor to draw the character at. Default is 1.

  • inverted (bool) – If True, draw the character inverted. Default is False.

Returns:

(Area) – The area that was drawn to.

text(canvas, string, x, y, color, scale=1, inverted=False)[source]

Draw text to the canvas.

Parameters:
  • canvas (FrameBuffer) – The surface to draw on; any object with the same drawing methods works.

  • string (str) – The text to draw.

  • x (int) – The x position to start drawing the text.

  • y (int) – The y position to start drawing the text.

  • color (int) – The color to draw the text in.

  • scale (int) – The scale factor to draw the text at. Default is 1.

  • inverted (bool) – If True, draw the text inverted. Default is False.

Returns:

(Area) – The area that was drawn to.

text_width(text, scale=1)[source]

Return the pixel width of the specified text message. Takes into account the scale factor, but not any newlines.

Parameters:
  • text (str) – The text to measure.

  • scale (int) – The scale factor to measure the text at. Default is 1.

Returns:

int – Width in pixels.

export(filename)[source]

Export the font data in self._cache to a .py file that can be imported. The format is a single bytes object named _FONT. There are 256 lines, one for each character. The last line is FONT = memoryview(_FONT).

Parameters:

filename (str) – The path to save the file to.

class pygraphics.Draw(canvas)[source]

Bases: object

Draw shapes on a canvas (display, FrameBuffer, or compatible object).

Each method delegates to pygraphics._shapes and returns an Area bounding box.

Parameters:

canvas – Object with framebuf-compatible drawing methods.

Example:

draw = Draw(display)
draw.fill(0x0000)
draw.rect(10, 10, 100, 100, 0xFFFF)

with draw.clip(5, 5, 50, 30):
    draw.fill_rect(0, 0, 200, 200, 0xF800)  # clipped to the 50x30 region
canvas

The canvas this object draws on.

clip(x, y=None, w=None, h=None)[source]

Return a context manager that clips drawing to a rectangle.

Accepts clip(x, y, w, h) or clip(Area(...)). Nested clips intersect.

arc(x, y, r, a0, a1, c)[source]

Draw an arc. Returns Area bounds.

blit(source, x, y, key=-1, palette=None)[source]

Blit a source buffer. Returns Area bounds.

blit_rect(buf, x, y, w, h)[source]

Blit a raw rectangle buffer. Returns Area bounds.

blit_transparent(buf, x, y, w, h, key=None)[source]

Blit with transparency. Returns Area bounds.

circle(x, y, r, c, f=False)[source]

Draw a circle. Returns Area bounds.

ellipse(x, y, r1, r2, c, f=False, m=15, w=None, h=None)[source]

Draw an ellipse. Returns Area bounds.

fill(c)[source]

Fill the canvas. Returns Area bounds.

fill_rect(x, y, w, h, c)[source]

Fill a rectangle. Returns Area bounds.

gradient_rect(x, y, w, h, c1, c2=None, vertical=True)[source]

Fill a rectangle with a gradient. Returns Area bounds.

hline(x, y, w, c)[source]

Draw a horizontal line. Returns Area bounds.

line(x1, y1, x2, y2, c)[source]

Draw a line. Returns Area bounds.

pixel(x, y, c)[source]

Draw a pixel. Returns Area bounds.

poly(x, y, coords, c, f=False)[source]

Draw a polygon from flat coordinates. Returns Area bounds.

polygon(points, x, y, c, angle=0, center_x=0, center_y=0)[source]

Draw a polygon from point list. Returns Area bounds.

rect(x, y, w, h, c, f=False)[source]

Draw a rectangle. Returns Area bounds.

round_rect(x, y, w, h, r, c, f=False)[source]

Draw a rounded rectangle. Returns Area bounds.

triangle(x1, y1, x2, y2, x3, y3, c, f=False)[source]

Draw a triangle. Returns Area bounds.

vline(x, y, h, c)[source]

Draw a vertical line. Returns Area bounds.

text(*args, **kwargs)[source]

Draw text using height from kwargs. Returns Area bounds.

text8(*args, **kwargs)[source]

Draw 8px-high text. Returns Area bounds.

text14(*args, **kwargs)[source]

Draw 14px-high text. Returns Area bounds.

text16(*args, **kwargs)[source]

Draw 16px-high text. Returns Area bounds.

class pygraphics.ClippedCanvas(canvas, clip)[source]

Bases: object

Proxy that restricts drawing on canvas to clip.

Drawing methods that intersect the clip region are forwarded to the underlying canvas; pixels outside the clip are ignored. Unknown attributes fall through to canvas via __getattr__.

property width

Underlying canvas width in pixels.

property height

Underlying canvas height in pixels.

pixel(x, y, c=None)[source]

Get or set a pixel if (x, y) is inside the clip.

Parameters:
  • x – X coordinate.

  • y – Y coordinate.

  • c – Color to set. If None, read the existing pixel color.

Returns:

On set – Area of the pixel, or None if outside the clip. On get: pixel color, or None if outside the clip.

fill(c)[source]

Fill the entire clip rectangle with color c.

Parameters:

c – Fill color.

Returns:

Area of the filled clip, or None if empty.

fill_rect(x, y, w, h, c)[source]

Fill the intersection of the given rectangle with the clip.

Parameters:
  • x – Left edge.

  • y – Top edge.

  • w – Width.

  • h – Height.

  • c – Fill color.

Returns:

Clipped Area that was filled, or None if no overlap.

hline(x, y, w, c)[source]

Draw a horizontal line clipped to this region.

Parameters:
  • x – Start x.

  • y – Y coordinate.

  • w – Width in pixels.

  • c – Color.

Returns:

Clipped Area, or None if no overlap.

vline(x, y, h, c)[source]

Draw a vertical line clipped to this region.

Parameters:
  • x – X coordinate.

  • y – Start y.

  • h – Height in pixels.

  • c – Color.

Returns:

Clipped Area, or None if no overlap.

blit_rect(buf, x, y, w, h)[source]

Blit a packed buffer, cropping to the clip region.

Parameters:
  • buf – Source bytes for a w x h rectangle (canvas bpp).

  • x – Destination x.

  • y – Destination y.

  • w – Source width.

  • h – Source height.

Returns:

Clipped destination Area, or None if no overlap.

blit_transparent(buf, x, y, w, h, key)[source]

Blit a packed buffer with transparency, cropped to the clip.

Parameters:
  • buf – Source bytes for a w x h rectangle (canvas bpp).

  • x – Destination x.

  • y – Destination y.

  • w – Source width.

  • h – Source height.

  • key – Transparent color key.

Returns:

Clipped destination Area, or None if no overlap.

text(s, x, y, c=1, scale=1, inverted=False, font_data=None, height=8)[source]

Draw romfont text clipped to this region.

Glyphs are rendered via fill_rect on self, so pixels outside the clip are discarded (unlike falling through to the underlying canvas text, which draws unclipped).

Parameters:
  • s – Text to draw.

  • x – Left edge.

  • y – Top edge.

  • c – Foreground color.

  • scale – Glyph scale factor.

  • inverted – Mirror glyphs when True.

  • font_data – Optional romfont bytes / path.

  • height – Romfont height (8, 14, or 16).

Returns:

Unclipped text Area (same contract as FrameBuffer.text).

text8(s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Draw 8px-high romfont text clipped to this region.

text14(s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Draw 14px-high romfont text clipped to this region.

text16(s, x, y, c=1, scale=1, inverted=False, font_data=None)[source]

Draw 16px-high romfont text clipped to this region.

class pygraphics.ClipContext(draw, area)[source]

Bases: object

Context manager that pushes a clip rectangle onto a Draw stack.

Entering returns the effective (intersected) clip Area. Nested with draw.clip(...) blocks intersect.

class pygraphics.BMP565(filename=None, source=None, streamed=False, mirrored=False, width=None, height=None)[source]

Bases: object

Read a 16-bit RGB565 BMP as a sliceable, optionally streamed asset.

Provide either filename (path to a BMP file) or source (an in-memory RGB565 buffer with width and height).

width

Image width in pixels.

height

Image height in pixels.

bpp
Type:

Bits per pixel

BPP
Type:

Bytes per pixel

property buffer

Writable memoryview of the full RGB565 pixel buffer, or None if streamed.

save(filename=None)[source]

Write this image as an RGB565 BMP file.

If filename already exists, a numeric suffix is appended (image.bmp → image_1.bmp, etc.).

Parameters:

filename – Output path. Defaults to the source filename or image.bmp.

Returns:

The path actually written.

deinit()[source]

Close the open file handle when constructed with streamed=True.

pygraphics.load_image(filename)[source]

Load a FrameBuffer from a PBM, PGM, or RGB565 BMP file.

pygraphics.save_image(fb, filename=None)[source]

Save a FrameBuffer to PBM, PGM, BMP, or PNG based on format or filename.

MONO_HLSB → PBM, GS2/GS4/GS8 → PGM, RGB565 → BMP (or PNG if filename ends in .png), RGB888 → PNG. Other formats raise ValueError.

pygraphics.pbm_to_framebuffer(filename)[source]

Convert a PBM file to a MONO_HLSB FrameBuffer.

Allocates one pixel buffer and reads pixels with readinto (peak ~1x).

Parameters:

filename (str) – Filename of the PBM file

Returns:

FrameBuffer – Loaded monochrome framebuffer.

pygraphics.pgm_to_framebuffer(filename)[source]

Convert a PGM file to a GS2_HMSB, GS4_HMSB or GS8 FrameBuffer.

Allocates one pixel buffer and reads pixels with readinto (peak ~1x).

Parameters:

filename (str) – Filename of the PGM file

Returns:

FrameBuffer – Loaded greyscale framebuffer (format from max value).

pygraphics.bmp_to_framebuffer(filename)[source]

Convert an RGB565 BMP file to a FrameBuffer.

Parameters:

filename (str) – Path to the BMP file.

Returns:

FrameBuffer – Loaded RGB565 framebuffer.

pygraphics.export_framebuffer(fb, filename)[source]

Export a FrameBuffer as an importable .py bitmap module.

Only the pure-Python package has this.

Format:

WIDTH = …
HEIGHT = …
FORMAT = …
BITMAP = bytearray(
b'…'        b'…'
)

BITMAP is a writable bytearray so MicroPython can wrap it in a FrameBuffer without copying. Prefer FrameBuffer.from_bitmap to load. Differs from Font.export, which keeps a read-only memoryview for glyph indexing.

pygraphics.implementation()[source]

Say which package this is: "native_cmod" for the compiled module, "pygraphics_python" for the pure-Python one.