Circuitry Logo
Circuitry
Open Circuitry

Pyctures: Python 2D and 3D Graphics

Pyctures ("Python pictures") gives Python 2D and 3D graphics in Circuitry. A Python file in the code editor can show a preview beside the code, and the file draws on it: shapes, text, pictures, moving sprites, games, charts and 3D scenes.

Python gets the full set of JavaScript graphics functions: the web's 2D canvas for 2D, and three.js for 3D, with the same names. So any JavaScript canvas or three.js example can be brought across with a few small changes (how).

It works the way an HTML file does. You write code on one side and see the result on the other. Press Run and the preview draws; change the code and press Run again.

def draw():
    ctx.fill_style = "midnightblue"
    ctx.fill_rect(0, 0, width, height)

    ctx.fill_style = "gold"
    ctx.begin_path()
    ctx.arc(width / 2, height / 2, 80, 0, 6.283)
    ctx.fill()

    ctx.fill_style = "white"
    ctx.font = "32px sans-serif"
    ctx.text_align = "center"
    ctx.fill_text("Hello!", width / 2, height / 2 + 140)

That is a whole program. There is nothing to import and nothing to set up: draw() is called every frame, ctx is the 2D drawing surface, and width and height are the size of the preview.

The quickest start: ask for one

Type a short request in Ask, such as 2d python game, 3d game, 3d scene in python or python animation. A ready-made Python file opens beside its preview and starts running:

Ask forYou get
a 2D Python gameStar Catcher: move a rocket, catch stars, dodge rocks, with a score and lives
a 3D gameCube Dodge: roll a ball left and right to dodge oncoming blocks
a 3D scene in Python3D scene: a lit scene with shadows that you can orbit and zoom
a Python animationBouncing balls: balls with trails; tap to add more

It is an ordinary Python file, so you can read it, change it and press Run again.

Make a Python file

  1. From the new-document menu (+), choose Code, then Python.
  2. Give the file a name ending in .py and create it.
  3. A new, empty Python file opens split: the code on the left and an empty preview on the right that says Run to draw here.
  4. Type or paste a program, then press Run in the footer.

The first run in a session loads Python, which can take a few seconds. After that, runs start straight away.

The views

Two buttons in the editor's footer choose what you see, the same pair an HTML file has:

ButtonWhat you see
PreviewThe preview only, filling the editor
SplitThe code and the preview side by side
Both offPlain Python: only the code, and Run prints to the output panel as usual

A new, empty Python file opens split, and so does a file that draws (one that uses ctx, THREE, Sprite and so on). Plain Python opens as code only. Once you pick a view yourself, it is remembered for that file on this device.

You do not have to remember to turn it on. If you press Run with the preview off and the file uses the preview (ctx, THREE, Sprite, await frame() and so on), the editor switches to split and runs it there.

Run and Stop

  • Run runs the file in the preview. While the program is running, the same button is Stop.
  • A program that only draws once finishes by itself. A program with a draw() function, an update(dt) function or a loop keeps running until you press Stop.
  • Every Run starts from a clean preview.
  • Anything your program prints with print() appears under the preview, and so do errors. copies all of it, to paste into a chat or a message; clears it.
  • A file waits for you to press Run. To have it start by itself whenever its tab is on screen, put # pyctures: autorun near the top. It then stops when you switch to another tab and starts again when you come back. The demos work this way. See How a program is shaped.
  • Frame rate shows how many frames per second the program is drawing, as a small number in the top-right corner of the preview. It is off until you turn it on, and the choice applies to every Python file.
  • Debugging turns breakpoints on and off. See Debugging.

On a phone

A phone has room for one pane at a time.

  1. A file that draws opens on the preview. For any other file, tap in the footer to turn the preview on.
  2. A Code / Preview switcher appears. Use it to move between the code and the preview.
  3. Run shows the preview. Tapping an error's line takes you to the code.

Touch works as the mouse does: a finger on the preview is mouse.down, and dragging moves mouse.x and mouse.y.

Where your Python runs

You never choose this; Circuitry picks for each run:

  • On iPhone and iPad, the Python built into Circuitry runs the file, inside the app, when the libraries the file imports are included with it.
  • In the desktop app, Circuit runs the file with the same built-in Python, installed the first time you run Python. If you picked your own Python in Circuit's Python setup, that one is used.
  • Otherwise (on the web, or when a file imports a library the built-in Python doesn't include), a Python that runs inside the page runs it. It works on any device, with nothing to install, and loads libraries the first time a file imports them.

The program and the preview behave the same in each. The one difference is debugging: a run can stop at a breakpoint only on iPhone and iPad, with the built-in Python. Elsewhere the run tells you so and goes straight through.

Using the module

Everything is ready to use without an import. The names come from a module called pyctures, so if your editor or your habits want an import, this works too:

from pyctures import *

def draw():
    ctx.fill_style = "teal"
    ctx.fill_rect(20, 20, 200, 120)

What's in this section

Related