New py5_tools functionality and more!

Upgraded py5_tools Module

We have upgraded the py5_tools module so you can run code with it from the command line:

$ python -m py5_tools -h
Usage: python -m py5_tools <command> [args...]

Available commands:
  cmd
  translate-imported2module
  translate-module2imported
  translate-processingpy2imported
  utils
  run-sketch
  live-coding
  install-jdk

The last command line tool you is install-jdk, which is a new tool that helps you install the Java Development Kit (JDK) on your system. This will simplify things for beginners who are having setup issues.

$ python -m py5_tools install-jdk -h
usage: __main__.py [-h] [-j JAVA_VERSION] [--jre]

Install Java Development Kit

options:
  -h, --help            show this help message and exit
  -j JAVA_VERSION, --java-version JAVA_VERSION
                        Java Version (must be 17 or greater, defaults to 21)
  --jre                 Install Java Runtime Environment (JRE) instead of Java Development Kit (JDK)

The command line tool is also available through the more direct route with the py5-install-jdk command.

$ py5-install-jdk -j 26
Installing Java Development Kit version 26...
Java Development Kit version 26 installed to /home/jim/.jdk/jdk-26+35

While testing this new feature, Alexandre Villares and I found a bug in py5's code that starts the JVM. The issue was related to non-ASCII characters. It is likely that this has been causing us support problems for some time. We are both very happy that this is now fixed!

Context Manager Fixes and Improvements

I repaired the type hints for all methods with associated context managers such as begin_shape() or push_matrix(). Also, the begin_record() and begin_raw() methods now correctly return Py5Graphics objects when there is one parameter.

Trimesh Object Conversion

I found a bug in the Trimesh object conversion due to the facets functionality added in the previous release. There are also now flip_u and flip_v keyword arguments to adjust for different UV coordinates systems. From the Trimesh integration page:

def setup():
    global strawberry
    py5.size(300, 500, py5.P3D)
    # the `flip_v=True` kwarg is necessary for this texture to appear correctly
    strawberry = py5.convert_shape(strawberry_scene, flip_v=True)
    assert isinstance(strawberry, py5.Py5Shape)

    strawberry.scale(50)
    strawberry.rotate_z(-py5.radians(90))

Other Bug Fixes and Small Improvements

Python supports something called "entry points" that can be used by a Python library to make other Python libraries aware of their presence in an environment. This allows other Python libraries to add their own jars to the classpath before JVM starts up, which can be useful when using py5 with other Java-based libraries.

I also modernized the organization of py5's source code, moving away from the previous "flat" directory structure.

And finally, I improved the Live Coding functionality to work better with uv.

Small release to fix warning message

Bug fixes

• Version 0.10.8a4 would issue a warning if you tried to use py5 without JavaFX jars available on the classpath. This error has been fixed.
• Fixed a type error with random_gaussian()

New Integration features for trimesh and matplotlib

New Features

This release adds to py5's integration with trimesh and matplotlib.

Previously every triangle in a trimesh mesh would have the edge lines drawn, much like how Processing renders 3D meshes. Now, when converting a Trimesh object to a Py5Shape object, the default will be to only draw the facet edges of the mesh. This results in a much cleaner look for 3D models that are intended to be rendered as wireframes. See the Trimesh integration documentation for details.

The new matplotlib feature is a new supported object type for conversion to Py5Shape objects: TextPath. This allows you to leverage matplotlib's text rendering capabilities, including support for equations and LaTeX typography. See the matplotlib integration documentation for more information.

Version Updates

This py5 release includes the core jars from the latest Processing release, 4.4.10.

Bug Fixes and Small Improvements

There were also some bug fixes in this release:

• One of the newer releases of Processing (4.4.10?) changed the default pixel density on high density displays to 2 but would issue a warning to notify you of the change. The warning perhaps is reasonable for PDE users but is super annoying when using py5 in a terminal or a Jupyter notebook. In py5, the warning will no longer appear.
• #711 - The 2X scaling problem for the %%py5draw Jupyter magic on OSX has been fixed
• The println() method now has a flush parameter that works like the flush parameter in Python's built-in print() function. When set to True, the output buffer is flushed immediately. This is useful when your print stream is writing to a file (enable this with the set_print_stream() method).
• Users with Java 24 or 25 installed experience a weird warning message about enabling native access. Processing has the same issue - this is because of JVM changes in Java 24. This version of py5 enables native access so the warning message won't appear anymore. In addition, the JavaFX renderer needed an additional fix to avoid a similar warning message. However, note that right now py5 plus JavaFX seems to have some other strange and fatal problem on my Linux machine when using Java 25. If use JavaFX and Java 25, please let me know either way if it works for you.
• There were also some small improvements to the documentation, particularly the documentation about color

Python 3.10+, Processing 4.4.6, & Bug Fixes

Version Updates

This release includes the following version updates:

• Minimum Python version is now 3.10 (previously 3.9)
• JPype minimum version is now 1.6 (previously 1.5.2)
• numpy minimum version is now 2.2 (previously 1.26)

Also, this py5 release includes the core jars from the latest Processing release, 4.4.6.

New Features

The Py5Image object has a new resize() method that works like the PImage.resize() method in Processing. See the Py5Image.resize() documentation for more information.

There were also some improvements to the build process but this is mostly behind the scenes.

Bug Fixes

• #666 was fixed, so py5 should now work with FX2D on Windows 11 - many thanks to vsquared for identifying the coding error that caused this problem.
• #578 has been resolved. The problem here was that py5 could crash on older macOS machines if a particular sequence of events occurred with the default JAVA2D renderer and the OpenGL renderer. This issue was a major thorn in my side for a long time, and I'm relieved that it is now closed.
• #659 has been fixed. This issue caused problems when converting Shapely objects with only two vertices to Py5Shape objects for use in P3D mode.

Important Bug Fix

Unfortunately the previous py5 release 0.10.5a0 had a stupid bug that would not let you import py5 without a working network connection. I am embarrassed to say that I didn't catch this before the release. I do apologize for that. I found it while on the train coming back from PyCon because the network connection was spotty. It was a disappointing mistake but I am glad it impacted me before anyone else (or at least before anyone else reported it).

The issue, #647, is now fixed. On the train ride back I also put in a fix for #613.

In addition, I upgraded the core.jar file to the now latest stable Processing release, 4.4.4.

Processing 4.4.1 & Processing Libraries Support

Here's an overview of what's in this release:

• jpype dependency updated from ==1.5.0 to >=1.5.2
• py5 now uses core.jar from the latest Processing release 4.4.1. Moving forward, py5 will use the core.jar maintained by the Processing Foundation
• New tools to facilitate downloading and installing Processing Libraries such as PeasyCam and Camera 3D, which work great with py5
• New random_permutations() method

Closed Issues

• #593 Add new py5.random_permutation() method
• #629 fixed py5's build process to work with the new Processing build process

Issue #593 was fixed by first-time contributor mohitbhasin in PR #594.

Thanks, also, for ijkwxyz's PR #637, fixing a Windows path issue they found in py5's live coding functionality.

Processing Issues & PRs

There were some relevant updates to the Processing library that are all included in this py5 release:

• #912 added a new ThinkDifferent method activateSketchWindow() to the Processing library.
• #918, an issue I found with NullPointerExceptions thrown by PApplet.dequeueWindowEvents(). This was fixed in my PR #930 to address the race conditions.

macOS & Windows improvements

The main purpose of this release is to improve py5 on macOS and Windows. Previously macOS in particular would have frequent problems with windows not getting focus or appearing behind other windows. Additionally, the default renderer would not always easily accept keyboard events. This release fixes all of these things.

However, there is one catch for macOS users: if your macOS machine has an Intel CPU and/or is using an old version of macOS (Ventura or earlier), please head over to #578 for more information. We'd like for you to do a quick test so we can gather information and better understand a problem.

Closed Issues

• Issue #5 - On Windows and on OSX with the default renderer, Sketch windows will open behind other windows
• Issue #549 - Provide a way to disable the ESC key behavior of quitting a sketch
• Issue #564 - On MacOS M1 machines, the default renderer opens the Sketch window behind other windows

Live Coding

New Feature: Live Coding

py5 has a new feature: Live Coding. The basic idea is to have a live coding environment where you can write and modify your py5 code and see the results in real time. It is designed to support rapid prototyping of ideas and experimentation. You'll be able to write code in an editor or Jupyter Notebook and see the results in a running Sketch immediately, without having to exit a running Sketch and then start a new one.

You can read more about Live Coding on the documentation website:

https://py5coding.org/content/live_coding.html

Closed Issues:

• Issue #17 - Why can't run_example_code.py do a complete run-through of all of the reference documentation example code?
• Issue #490 - py5 rejects valid static mode code
• Issue #501 - Py5Shape's get_children() method should return [] when there are no children
• Issue #506 - Incorrect variable description for vertex() methods
• Issue #507 - py5_tools should use __all__ to control what is importable
• Issue #528 - Improve error messages for invalid named colors

Small release with a few new features

Enhancements and Changes

• Minimum Python version now 3.9
• Update library dependencies, including allowing numpy 2.0
• New convert_cached_image() and convert_cached_shape() methods

Closed Issues

• Issue #420 - new convert_cached_image() and convert_cached_shape() methods
• Issue #441 - improve error message when sketch file is executed without ever being saved
• Issue #443 - repairing the Py5Image.copy() method
• Issue #446 - unpin numpy, allowing py5 to be installed alongside numpy 2.0
• Issue #447 - repairing and enhancing set_println_stream(). This change was needed to support the future project py5ascii.

Small release with a few new features

This is a small release with two new features and a handful of bug fixes.

Numpy Version

The main reason why this py5 release is happening now and not later is because numpy will soon have a major release that is not completely backwards compatible. Version 2.0 of numpy will be released soon and library maintainers have been advised to pin dependencies to numpy<2.0 and then test with numpy 2.0 when it is available. This is to ensure that py5 and every library py5 depends on is ready for the new version and does not cause users any problems.

Once the new numpy version is released and I verify py5 works well with it, I will do another release of py5 that removes the numpy<2.0 pin.

New Contributors

Recently py5 had two first-time contributors. Many thanks to keko24 (Andrej) for PR #406 - Implemented corresponding changes to convert_image and convert_shape, addressing Issue #405. Also, thanks to JulienBacquart for PR #416 correct constrain documentation, addressing some documentation errors.

New Features

Neither of these new features are that significant and most likely they won't be useful for most users. However, they have been useful for me as I've done the prototyping experiments for a gallery show, opening next Friday in Detroit.

• The new predraw_update() user function is called before each call to draw(). The purpose of this function is to provide a small performance boost by moving non-drawing update code to a function that executes during a time when the Python interpreter would otherwise be idle. If you want to read more about this feature, visit the new Update Function section of the new User Functions page.
• Processing Mode users can now use the jclass_params keyword parameter to pass arguments to the constructors of their Java Classes. Read the Processing Mode documentation to learn more about this use of py5.

Closed Issues

• Issue #405 - convert_image() and convert_shape() methods should support Py5Image, Py5Graphics, and Py5Shape objects
• Issue #394 - save_frame() cannot be called from a mouse or keyboard event function but that works fine in Processing
• Issue #421 - Add display_progress param to py5_tools.offline_frame_processing()