Metadata-Version: 2.4
Name: py5-posix-renderer
Version: 0.1.1
Summary: 2D & 3D Posix Renderers for py5
Project-URL: Bug Tracker, https://github.com/hx2A/py5-posix-renderer/issues
Project-URL: Documentation, https://posix-renderer.py5coding.org/
Project-URL: Homepage, https://posix-renderer.py5coding.org/
Project-URL: Source Code, https://github.com/hx2A/py5-posix-renderer
Author-email: Jim Schmitz <jim@ixora.io>
License-Expression: LGPL-2.1-only
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Java
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Requires-Dist: numpy>=2.2
Requires-Dist: py5>=0.10.10a7
Description-Content-Type: text/markdown

# py5 Posix Renderer

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

For example, you can create something like this:

![ascii style image of happy software developer](https://raw.githubusercontent.com/py5coding/py5-posix-renderer/main/examples/output/webcam1.png?token=GHSAT0AAAAAADVEZVRN3WHMBA65KNNFKZIU2QTSO5Q)

or perhaps something like this:

![rotating cube with green background](https://raw.githubusercontent.com/py5coding/py5-posix-renderer/main/examples/output/rotating-box.png?token=GHSAT0AAAAAADVEZVRMYLIHV6POBV6OTVAC2QTSPFQ)

This library makes heavy use of [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
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](https://py5coding.org/content/user_functions.html).

## 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](https://py5coding.org/) installation. You can
learn how to [install py5](https://py5coding.org/content/install.html) 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:

```bash
pip install py5-posix-renderer
```

You will find some examples to get you started in the [examples/](https://github.com/py5coding/py5-posix-renderer/tree/main/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](https://github.com/py5coding/py5generator/issues/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](https://github.com/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](https://github.com/jsbueno/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](https://github.com/py5coding/py5-posix-renderer/blob/main/src/py5_renderers/posix/device_events.py)
is adapted from [terminedia](https://github.com/jsbueno/terminedia/blob/main/terminedia/input.py).
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!](https://github.com/sponsors/py5coding)

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](https://github.com/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](https://github.com/adanaher) (Alec Danaher)
* [@ericof](https://github.com/ericof) (Érico Andrei)
* [@nickmcintyre](https://github.com/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](https://github.com/py5coding/py5generator/discussions) and [issues](https://github.com/py5coding/py5generator/issues)
* Mastodon <a rel="me" href="https://fosstodon.org/@py5coding">fosstodon.org/@py5coding</a>
* [processing foundation discourse](https://discourse.processing.org/c/28)

[processing]: https://github.com/processing/processing4
[jpype]: https://github.com/jpype-project/jpype
[py5_repo]: https://github.com/py5coding/py5
[py5generator_repo]: https://github.com/py5coding/py5generator
