Pi3D PictureFrame was the image viewer this blog was built around for years, and on a Raspberry Pi 2, 3 or Zero 2 W it still is: its crossfading and blending effects use the full graphic power of the Raspberry Pi and were unmatched at the time.

On a Raspberry Pi 4 or 5 I now use picframe3 instead. Everything on this page is about Pi3D, so read it with that in mind.

In this FAQ, I have compiled, in no particular order, questions we received, commands you may frequently use, and several tidbits you may want to discover and try for yourself.

If you have a question, please let me know.

What is the Pi3D PictureFrame developers’ site?

The Pi3D documentation is: https://pi3d.github.io/html/ReadMe.html#acknowledgements
The Pi3D Github page is: https://github.com/pi3d/pi3d_demos
The PictureFrame Github page is: https://github.com/helgeerbe/picframe
The Python Package Index page is: https://pypi.org/project/picframe/

Does Pi3D PictureFrame run on all Raspberry Pi models?

Pi3D will run on the Raspberry Pi 2, 3, 4 and 5, and on the Raspberry Pi Zero 2 W. The small boards may have memory limitations if you run other things in the background. If you do, read this.

Should I use Pi3D PictureFrame or picframe3?

It depends on the board. picframe3 renders with OpenGL ES 3, which only the Pi 4, 400, 5 and 500 provide — the Pi 2, Pi 3 and Zero 2 W stop at ES 2.0 and are not supported, so on those Pi3D PictureFrame remains the route and I keep its guide up to date.

On a Pi 4 or 5, picframe3 is what I would install: Raspberry Pi OS Lite, one command, no desktop session underneath it, a web interface for the settings, and video.

Does Pi3D PictureFrame support the Raspberry Pi’s capability to connect to 4K screens?

Absolutely. My 2021 shortlist of 32-inch 4K monitors explains what to look for in a panel, though the models it names have all been discontinued since.

Is there a way to change the Pi3D PictureFrame parameters while the program is running?

Pi3D PictureFrame has an in-build remote control functionality based on MQTT messages.
These are the parameters you can change or commands you can send in Pi3D (picframe3's command set is a different and larger one, announced to Home Assistant automatically):
– Filter images on date_to and date_from
– Delay between images
– Duration of the transition
– Set shuffle mode on/off
– Pause playback
– Jump to the previous photo
– Set photos subdirectory
– Delete the currently shown image
– Quit Pi3D
– Show date, location, or filename

Why does Pi3D PictureFrame always show the same images after reboot?

Pi3D has a parameter setting where you specify to show a number of recent images first following a reboot or a reselect (i.e. reshuffle after a filter command has been entered). Set this value to zero in configuration.yaml in the model section to not show any new images first:
recent_n: 0 # default=7 (days), when shuffling file change date more recent than this number of days play before the rest

How does Pi3D PictureFrame know when I add new images?

Pi3D has a database notify feature whereby it knows when there are changes in the pictures folder. If a change is detected, the playlist is reshuffled. This process is called “reselect” in Pi3D speak.

I want to start Pi3D PictureFrame at boot using crontab but it doesn’t work!

I recommend using systemd for launching scripts and have updated the section on auto starting Pi3D using systemd. This applies to the Pi3D route only — picframe3 installs and manages its own systemd service, so there is nothing to write by hand.

My file names are missing some special characters in my language!

Open configuration.yaml and add your special characters or alphabet to the line called CODEPOINTS. If you have characters like ” ‘ ” that have a special meaning in Python, then you have to prefix it with an “\”, so like “\'”.

This is a Pi3D limitation: it draws text from a fixed set of characters it has been told about in advance. picframe3 has no such list — it draws captions with Pillow, so whatever is in the font simply appears.

What is the difference between Pi3D and PictureFrame?

Pi3D is a Python module that aims to greatly simplify writing 3D in Python whilst giving access to the power of the Raspberry Pi GPU. It enables both 3D and 2D rendering and aims to provide a host of exciting commands to load in textured/animated models, create fractal landscapes, shaders, and much more.
PictureFrame is a Raspberry Pi image viewer that builds on the power of Pi3D. When I refer to “Pi3D”, “PictureFrame”, or “Pi3D PictureFrame” I mean the same thing.

I will add more items to this FAQ as they come up.