Basic usage#
Create Canvas#
You can provide the width and height of the Canvas
in pixels in the constructor.
from ipycanvas import Canvas
canvas = Canvas(width=200, height=200)
canvas
You can also create a multi-layer canvas. This is useful when you have a background that does not need to update much while other objects moves a lot on the screen.
from ipycanvas import MultiCanvas
# Create a multi-layer canvas with 4 layers
multi_canvas = MultiCanvas(4, width=200, height=200)
multi_canvas[0] # Access first layer (background)
multi_canvas[3] # Access last layer (foreground)
multi_canvas
Note
Because the Canvas
is an interactive widget (see https://ipywidgets.readthedocs.io/en/stable/) you can:
display it multiple times in the Notebook
observe some of its attributes and call functions when they change
link some of its attributes to other widget attributes
Resize Canvas#
The Canvas
and MultiCanvas
have two sizes: the size of the color buffer in pixels, and the actual size
displayed on the screen.
Color buffer size#
The color buffer size can dynamically be updated through the width
and height
properties (value in pixels), note that this will clear the canvas.
canvas.width = 300
canvas.height = 600
Screen size#
The size on the screen can be updated through the layout
property, which comes from ipywidgets (see https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Styling.html#The-layout-attribute). The layout
property is an object which contains CSS properties for the canvas.
The default value for the width
and height
of the layout is “auto”, this means the canvas will take the same screen size as the actual color buffer size: a Canvas
of
size 800x600
will take 800x600
pixels on the screen.
canvas.layout.width = "auto"
canvas.layout.height = "auto"
In order to get a “responsive” Canvas
which takes as much space as available while still respecting the aspect ratio, you will need to set the width
property to 100%
, the height
will automatically get computed:
canvas.layout.width = "100%"
canvas.layout.height = "auto"
One can also set the screen size value in pixels:
canvas.layout.width = "200px"
canvas.layout.height = "500px"
Clear Canvas#
The Canvas
and MultiCanvas
classes have a clear
method which allows to clear the entire canvas.
from ipycanvas import Canvas
canvas = Canvas(width=200, height=200)
# Perform some drawings...
canvas.clear()
Optimizing drawings#
By default, the Python Canvas
object sends all the drawings commands like fill_rect
and arc
one by one through the widgets communication layer. This communication is limited
to 1000 commands/s and it can be extremely slow to send commands one after the other.
You can increase this limit via internal Jupyter parameters,
however this is not recommended as it can lead to instability. Instead we provide a hold_canvas
context manager which allows you to hold all the commands and send them in a single batch at the end. For
optimal performance you should try to use hold_canvas
as much as possible.
from ipycanvas import Canvas, hold_canvas
canvas = Canvas(width=200, height=200)
with hold_canvas():
# Perform drawings...
pass