py5-posix-renderer 0.1.0

2D & 3D Posix Renderers for py5

py5 Posix Renderer

The Posix Renderer library is used to render py5 Sketches in the terminal.

For example, you can create something like this:

or perhaps something like this:

This library makes heavy use of ANSI escape codes to integrate a py5 Sketch into the terminal.

The main idea is to create a hidden rasterized image and then convert that image into something that can appear in the terminal. Sketches can be converted into plain ASCII characters, colored ASCII characters, colored cells, and more! You can customize this conversion process however you like.

The animated Posix Sketch supports many of py5's keyboard, mouse, and window events.

Requirements

This library creates animations that appear in a Posix terminal window. Therefore, this works on Linux and MacOS only. It cannot work in a Windows DOS window because a DOS window is not a Posix terminal. It probably works in the Windows Linux subsystem but I haven't specifically tested that.

You must have a working py5 installation. You can learn how to install py5 on the documentation website. Installing py5 requires you have Java installed on your machine.

Once you have py5 installed, you can install the Posix Renderer library with pip:

pip install py5-posix-renderer

You will find some examples to get you started in the examples/ directory.

Caveats

This library is highly experimental and subject to change. There are certainly many bugs that will impact user experience.

py5 issue #772 impacts this library's performance on MacOS machines. This will be resolved after the next py5 release.

When you use this library's 3D renderer (POSIX3D), you will see a small window with the py5 logo appear on the screen. It is not possible for this library to offer 3D graphics without opening that window.

Currently this library has no documentation or docstrings. You can learn how to use it from reading the example code or from looking at the source code. If you'd like to help create more example code or write tutorials, I'd be grateful.

Why does this exist?

This renderer was built over the past two years as a passion project, driven by curiosity and the willingness to do something without a clear purpose beyond the desire to explore a corner of the technology world I am not familiar with. The more I learned about Python and Posix terminals, the more opportunities I saw to expand py5’s functionality in ways I didn’t think were possible. I’d like to share that expanded horizon with the Python community.

The Python library py5 is often used for educational purposes to teach people how to code in the context of creative coding. Providing an avenue for creative coding in the terminal can make the terminal a more inviting place to people who might otherwise be intimidated by its complexity.

There is a deeper purpose here related to my interest in creating what I call experimental renderers for computational art. Processing is an amazing library with a long history. One of its overlooked strengths is its ability to support users who wish to inherit from the PGraphics class and create their own renderers. I intend to explore this idea further. This library is also an investigation into some of the design decisions for how to go about creating these experimental renderers. Any thoughts or feedback is welcome.

Acknowledgements

Many, many thanks to @jsbueno for the very helpful discussions about terminal programming. We met at Python Brasil 2025 in Sao Paulo, Brazil and he introduced me to his project terminedia. It wouldn't have occurred to me that receiving mouse events in the terminal was even possible had he not shown me how. Some of the code in device_events.py is adapted from terminedia. Obrigado!

Accessibility

What kind of support does this library provide folks who use screen readers?

I don't know, someone will have to tell me. I do know that this library moves the cursor around the terminal, and I suspect this would conflict with how a screen reader moves its focus around a terminal window. But perhaps screen readers can do things that I don't know about? This is likely. In any case, I'd love it if someone who is more knowledgeable about this subject will investigate and tell me what they find. If there's a way for me to improve this library and make it useful for screen reader users, I'd be happy to hear about it.

Funding

Please sponsor py5!

This project is not an official part of the Processing Foundation and is not receiving any funding from them. Any funds you contribute will be used first for website expenses and next to support @hx2A's time to further develop py5 as a solid creative coding framework used by educators, artists, and hobbyists all around the world.

Thank you much for the support from py5's generous sponsors!

• @adanaher (Alec Danaher)
• @ericof (Érico Andrei)
• @nickmcintyre (Nick McIntyre)

Get In Touch

Have a comment or question? We'd love to hear from you! The best ways to reach out are:

• github discussions and issues
• Mastodon fosstodon.org/@py5coding
• processing foundation discourse