Special Notes for OSX Users¶
There are some difficulties using py5 on Mac computers that still need to be worked out.
Mac users must use Jupyter Notebooks with the
%gui osxmagic at the start of each notebook (Issue #4)
The run_sketch() method’s
blockparameter is not available. This limits some py5 features that depend on it, such as py5bot.
When possible, prefer the
P2Drenderer over the default renderer
If using the default renderer, sometimes keyboard events will be captured by the Jupyter Notebook and not the Sketch window
Sketches that use the default renderer will not appear as an icon on the Dock at the bottom of the screen
Ignore the warnings you see when exiting a Sketch (Issue #6)
None of these will stop you from using py5 productively, but they might annoy you a bit.
The py5 library uses the Python library JPype to create the Java-Python bridge between the two languages. There is currently a bug in JPype that prevents Java GUI applications from running correctly on Mac computers. JPype’s core developer does not have a Mac computer to test and fix the problem, and can’t get access to one because of pandemic related issues. This is a problem, but let’s keep things in perspective: the pandemic has taken a toll on all of us, with many people losing their lives or jobs. Software bugs and delays aren’t a real problem. I’d like you to be patient with me while this gets worked out.
If you like Jupyter Notebooks, you’re in luck! Everything will work just fine after executing the following IPython magic at the start of each notebook:
This should be executed before importing py5. If you
forget to use the
%osx gui magic, py5 will print a warning and
activate it for you.
OSX has some requirement that only allows GUI applications to run on the main thread. That magic command configures things so that py5 can work. I don’t understand how or why it works. I know that it works, and I am grateful.
%osx gui magic should be executed before the
statement. Running a script with the
%run magic doesn’t seem to work.
The py5 Jupyter Notebook Kernel will take care of the
%osx gui magic
for you when run on a Mac computer.
If you like coding in an interactive terminal (I hope I’m not the only
one), you will need to use
jupyter console and not
ipython. The two
interactive terminal applications are not identical, with the
magic working in the former but not the latter. The console can be
frustrating to use though. If a Sketch stops because of an error, no
error message will appear until after you hit the return key in the
Mac users won’t be able to use the generic
python interpreter to run
py5, either interactively or to run a python program. If you need to run
a py5 application in a script, your best bet is to put your code in a
%gui osx at the top and execute the notebook, like so:
$ jupyter nbconvert --execute --to notebook --inplace py5_code.ipynb
Of course you can always use a virtual machine or Docker, but those are more complicated to get working. Still, these are valid choices that might meet your needs.
I’m not an expert Mac user so it is very likely there is more to be said about using py5 on Macs. Please experiment based on your own knowledge and ideas. If you discover something useful, let me know and I’ll update the documentation. Feel free to comment on the Github Issue (#4) for this problem.
The run_sketch() method’s
parameter is not available on OSX. This also limits some py5 features
that depend on it:
py5bot cannot use the
P3Drenderers. This includes the %%py5bot magic and the py5bot Jupyter Notebook Kernel.
The %%py5draw magic cannot use the
The %%py5drawdxf magic is not available.
To undertand the cause of this issue, consider the following code:
import time import py5 def setup(): py5.size(200, 200, py5.P2D) def draw(): if py5.frame_count % 50 == 0: py5.println(py5.frame_count) py5.square(py5.random_int(py5.width), py5.random_int(py5.height), 10) py5.run_sketch(block=False) print('start pause') time.sleep(3) print('end pause')
When this code is run on a Linux or Windows computer, the output will be similar to this:
start pause 50 100 end pause 150 200 ...
You can see that the Sketch is running at the same time as
When run on OSX, the output will look like this:
start pause end pause 50 100 150 200 ...
The Sketch is not able to run at the same time as
Additionally, the Sketch window will not appear until after the Notebook
cell with the run_sketch() call finishes
executing. The Sketch cannot start running until that cell’s execution
completes. If the
block parameter had been set to
execution would not complete because the run_sketch() method
blocks until the Sketch exits. But the Sketch would
not get the opportunity to start running because it needs to wait for
cell execution to complete. The Notebook would be stuck in limbo,
endlessly waiting for a Sketch to exit that cannot even start. The user
will need to interrupt the Kernel to break the deadlock.
If in the above code the Sketch had used the default renderer instead,
the printed output would be correct but the Sketch window would still
wait for cell completion before appearing. However, when the Sketch
window did become visible, it would have many squares drawn on it
already. In this case the animation is hidden when it starts running and
doesn’t become visible to the user until after cell completion.
Furthermore, if one were to later run
time.sleep(3) in a different
cell, the animation would appear to freeze until cell execution
completed, then resume with many new squares drawn on it. This has
nothing to do with
time.sleep; the issue has to do with the fact that
the Notebook and the Sketch need to share the main thread, so any cell
that takes a long time to execute will prevent the Sketch from
simultaneously displaying changes to the drawing surface.
Sketches that use the OpenGL renderers
P3D will not pause or
freeze once they open and start running. I recommend you use the OpenGL
renderers and not the default renderer when possible.
When using the default renderer, sometimes keyboard events are captured by the Jupyter Notebook and not the Sketch window. This seems to happen for the first Sketch if the first Sketch also uses the default renderer. This behavior will be confusing because the Sketch will be capturing mouse events but not keyboard events.
While this behavior is occuring, hitting the
ESC key to exit the
Sketch will cause the window to move behind other windows, making you
think the Sketch has stopped running. On OSX, Sketches that use the
default renderer will not appear as an icon on the Dock at the bottom of
the screen. If you try to run a new Sketch and get a message stating
that the current Sketch is already running, try first looking for the
Sketch window underneath the other windows on your screen.
When the Sketch exits you will see the following warning:
NewtNSView::dealloc: softLock still hold @ dealloc!
Ignore that. Windows and Linux users also get odd messages when exiting.