Backend: DrawingBoard

The DrawingBoard backend provides relatively easy facilities for drawing lines, circles, other geometric primitives, text and SVGs. It is not meant for complex drawings or performance. A detailed description of its API is provided below. DrawingBoard is essentially a wrapper around cairo, Pango and rsvg. Besides, bewegung also offers an explicit cairo backend. If no backend is specified, layers will typically fall back to DrawingBoard. A simple example using DrawingBoard looks as follows:

from bewegung import Video, Vector2D, Color

v = Video(width = 480, height = 270, seconds = 1.0)

@v.sequence()
class Foo:

    @v.layer(canvas = v.canvas(backend = 'drawingboard'))
    def bar(self, canvas): # a DrawingBoard object

        canvas.draw_polygon(
            Vector2D(5, 5), Vector2D(v.width - 5, v.height - 5),
            line_width = 3,
            line_color = Color(255, 0, 0, 255),
        )

        return canvas

v.reset()
v.render_frame(v.time(0))
DrawingBoard output

The function call v.canvas(backend = 'drawingboard') accepts additional keyword arguments, which are passed on to the DrawingBoard constructor. By default, the canvas size is set to the width and height of the video.

The DrawingBoard Class

The DrawingBoard class makes use of vectors and colors.

class bewegung.drawingboard.DrawingBoard(width, height, offset=None, subpixels=1, background_color=None)

A wrapper around Cairo, Pango (PangoCairo) and Rsvg, providing a canvas with a simple API for day-to-day drawing tasks.

DrawingBoard objects are mutable. The color mode is 32 bit RGBA (actually cairo’s ARGB32).

Parameters

  • width (int) – Canvas width in pixels

  • height (int) – Canvas width in pixels

  • offset (Optional[Vector2D]) – Center of coordinate system (device offset)

  • subpixels (int) – Number of subpixels per pixel (devise scale)

  • background_color (Optional[Color]) – Canvas background color - transparent white by default

_stroke(line_color=None, line_width=1.0, **kwargs)

Strokes lines. Never called directly.

Parameters

  • line_color (Optional[Color]) – Color of line. Opaque black by default.

  • line_width (float) – Width of line

as_pil()

Exports drawing as a Pillow Image object

Return type

Image

property ctx: cairo.Context

Exposes drawing’s cairo.Context object

Return type

Context

display()

Displays drawing in an IPython console or Jupyter notebook

draw_bezier(a, b, c, d, **kwargs)

Adds a bezier curve to the drawing.

Parameters

  • a (Vector2D) – A 2D vector representing P0

  • b (Vector2D) – A 2D vector representing P1

  • c (Vector2D) – A 2D vector representing P2

  • d (Vector2D) – A 2D vector representing P3

  • kwargs – Arguments for line stroke (see _stroke)

draw_circle(point, r=1.0, **kwargs)

Adds an unfilled circle to the drawing.

Parameters

  • point (Vector2D) – Center of circle

  • r (float) – Radius of circle

  • kwargs – Arguments for line stroke (see _stroke)

draw_filledcircle(point, r=1.0, fill_color=None)

Adds a filled, frame-less circle to the drawing.

Parameters

  • point (Vector2D) – Center of circle

  • r (float) – Radius of circle

  • fill_color (Optional[Color]) – Fill color. Opaque black by default.

draw_filledpolygon(*points, fill_color=None)

Adds a filled, frame-less polygon to the drawing.

Parameters

  • points (Vector2D) – An arbitrary number of 2D vectors

  • fill_color (Optional[Color]) – Fill color. Opaque black by default.

draw_polygon(*points, close=False, **kwargs)

Adds an unfilled polygon to the drawing.

Parameters

  • points (Vector2D) – An arbitrary number of 2D vectors

  • close (bool) – Whether or not the polygon should be closed

  • kwargs – Arguments for line stroke (see _stroke)

draw_svg(fn=None, raw=None, svg=None, point=None, scale=1.0, angle=0.0, anchor='cc')

Adds an SVG to the drawing.

The SVG can be provided with one of the three following options:

  1. a path/filename, from where the SVG can be loaded

  2. a raw sequence of bytes containing the SVG markup

  3. a handle on an rsvg object

Parameters

  • fn (Optional[str]) – Path to SVG file (1)

  • raw (Optional[bytes]) – SVG markup (2)

  • svg (Optional[Handle]) – rsvg handle object (3)

  • point (Optional[Vector2D]) – Location of the SVG within the drawing relative to the SVG’s anchor

  • scale (float) – Allows to resize the SVG by the provided factor

  • angle (float) – Rotates the SVG by a given angle in radians

  • anchor (Union[Vector2D, str]) – Describes the achor point of the SVG. The location an either be provided as a 2D vector or as a two-letter code. First letters can be “t” (top), “c” (center) and “b” (bottom). Second letters can be “l” (left), “c” (center) and “r” (right).

draw_text(text='', point=None, angle=0.0, font=None, font_color=None, alignment='l', anchor='cc')

Adds text to the drawing.

Parameters

  • text (str) – The actual text. Can handle explicit line breaks (\n) but does not offer automatic line breaks.

  • point (Optional[Vector2D]) – Location of the text within the drawing relative to the text’s anchor

  • angle (float) – Rotates the text by a given angle in radians

  • font (Optional[FontDescription]) – A Pango font description object

  • font_color (Optional[Color]) – The font color. Opaque black by default.

  • alignment (str) – Single letter describing the text allignment. Can be “l” (left), “c” (center) and “r” (right).

  • anchor (Union[Vector2D, str]) – Describes the achor point of the text. The location an either be provided as a 2D vector or as a two-letter code. First letters can be “t” (top), “c” (center) and “b” (bottom). Second letters can be “l” (left), “c” (center) and “r” (right).

property height: int

Height of canvas

Return type

int

static make_font(family, size)

Generates a Pango font description for re-use.

Parameters

  • family (str) – Font family (name)

  • size (float) – Font size

Return type

FontDescription

static make_svg(fn=None, raw=None)

Generates an rsvg handle for re-use.

The SVG’s data can be provided with one of the two following options:

  1. a path/filename, from where the SVG can be loaded

  2. a raw sequence of bytes containing the SVG markup

Parameters

  • fn (Optional[str]) – Path to SVG file (1)

  • raw (Optional[bytes]) – SVG markup (2)

Return type

Handle

save(fn)

Saves drawing to a file

Parameters

fn (str) – Path to image file. The image format is derived from the file extension.

property surface: cairo.ImageSurface

Exposes drawing’s cairo.ImageSurface object

Return type

ImageSurface

property width: int

Width of canvas

Return type

int

Note

The DrawingBoard class can be imported from bewegung.drawingboard.