Great new features for your digital picture frame with the updated Pi3D Image Viewer (Nov 2019)


Great new features for your digital picture frame with the updated Pi3D Image Viewer (Nov 2019) 1

Paddy has done it again! My favorite Raspberry Pi slideshow program just got even better thanks to a number of updated functions, most notably:

  • More options to control it via MQTT with Amazon Alexa or Home Assistant like pausing the playback
  • Use of intelligent smartlists based on the Exif data of the images
  • Automatic refresh of the playback list when new photos are added
  • Recently added images can be selected to be shown immediately
  • Improved handling and auto rotation of images
  • Blur effect on the edges to avoid black bars when aspect ratio doesn’t fit

In this article I will show you the new functionalities and how to use them.

If you haven’t installed Pi3D yet, please have a look at my article “How I added cross­fad­ing slide tran­si­tions to my dig­i­tal pic­ture frame using Pi3D” which explains it in detail.

How to check which Pi3D version you currently have

To find out which Pi3D version is currently installed on your digital photo frame, enter in a Terminal window which is connected to your Raspberry Pi:

python3 -c 'import pi3d; print(pi3d.__version__)'

If you have anything less than Version 2.34 you need to update.

How to update Pi3D

The update process consists of two steps:

Step 1 updates the Pi3D framework.

To do this enter

sudo pip3 install pi3d --upgrade

If you see something like this

Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Collecting pi3d
  Downloading https://files.pythonhosted.org/packages/ed/1e/a9ce342e89305c444494dc1be5054bc9646dc10128177f418a5f18c649ac/pi3d-2.33-py2.py3-none-any.whl (265kB)
    100% |████████████████████████████████<| 266kB 1.1MB/s 
Installing collected packages: pi3d
  Found existing installation: pi3d 2.32
    Uninstalling pi3d-2.32:
      Successfully uninstalled pi3d-2.32
Successfully installed pi3d-2.33

the update will have worked.

Step 2 is about updating your customized PictureFrame script.

If you already updated Pi3D somewhere in the past and you already have a folder “pi3d_demos_old” you will need to rename it to something like “pi3d_demos_very_old” or delete it altogether.

Enter

wget https://github.com/pi3d/pi3d_demos/archive/master.zip && unzip master.zip && mv pi3d_demos pi3d_demos_old && mv pi3d_demos-master pi3d_demos && rm master.zip

to get the latest PictureFrame.py version and any other updated associated files.

What the above command will do is to rename vour current pi3d_demos file into pi3d_demos_old and create a new pi3d_demos folder. This way you can always look at any settings in your old PictureFrame.py file.

I will walk you through the updated parameter section where you can enter your settings.

The new pictureframe.py script – The constants

Paddy has streamlined this configuration file and it is now easier than ever to add any user specific information.

We’ll start with the settings of the constants:

#####################################################
# these variables are constants
#####################################################
PIC_DIR = '/home/pi/Pictures/your_images/'
FPS = 20
FIT = True
EDGE_ALPHA = 0.0 # see background colour at edge. 1.0 would show reflection of image
BACKGROUND = (0.2, 0.2, 0.2, 1.0)
RESHUFFLE_NUM = 1 # times through before reshuffling
FONT_FILE = '/home/pi/pi3d_demos/fonts/NotoSans-Regular.ttf'
CODEPOINTS = '1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ., _-/' # limit to 49 ie 7x7 grid_size
USE_MQTT = False
RECENT_N = 50 # shuffle the most recent ones to play before the rest
SHOW_NAMES = False
CHECK_DIR_TM = 60.0 # seconds to wait between checking if directory has changed
#####################################################
BLUR_EDGES = False # use blurred version of image to fill edges - will override FIT = False
BLUR_AMOUNT = 12 # larger values than 12 will increase processing load quite a bit
BLUR_ZOOM = 1.0 # must be >= 1.0 which expands the backgorund to just fill the space around the image

Let’s go through line by line. It’s easier than it first appears.

PIC_DIR = '/home/pi/Pictures/your_images/'

Enter the directory where your images are stored. Pi3D is recursive, so you enter the main directory and all the subdirectories are included.

FPS = 20

This setting is the frame per seconds speed. Whilst you can set it to 60 on a Pi 4 and to 30 on a Pi 2 and 3, I haven’t noticed any increase in the smoothness of the transitions, so I would suggest that you leave it at 20.

FIT = False

“True” means that the entire image fits onto the screen and there will be gaps left (letter- or pillarboxing) if your image does not have the same aspect ratio as the monitor.

“False” means that the image is blown up to fill the screen thereby cropping parts of the image.

EDGE_ALPHA = 0.0 # see background colour at edge. 1.0 would show reflection of image

If the image doesn’t fit the screen then Pi3D can mirror the original image so there is no hard edge.

Setting this value to 1.0, it will appear, at first glance, as if the image exactly fits the frame. The effect can be quite stunning, and you often won’t even notice it, but sometimes it may be a bit odd.

For serious digital picture frame lovers, I would always recommend to properly crop the images to the aspect ratio of the screen. You can even use service like Croppola to handle that task easily.

However, an easy solution is to set FIT to False and using the mirroring that EDGE_ALPHA achieves.

So, setting this value to 1.0 is a full mirroring, “0.0” is a black bar, and everything in between will reduce the opacity of this mirrored edge.

You should definitely try a setting of “1.0” to see what the effect does and if you don’t like it, you can always change it to “0.0”.

BACKGROUND = (0.2, 0.2, 0.2, 1.0)

An alternative to mirroring the gaps at the edges is to give the background another color that you can define in the RGBA format.

The first three numbers define the RGB color, the last one the opacity (Alpha).

I leave the (0.2, 0.2, 0.2, 1.0) default setting unchanged, but as all my images are cropped to the aspect ratio of the screen, it doesn’t make a difference anyway because there is no background to be seen.

In theory, you could have a yellow background with e.g. (1.0, 1.0, 0.0, 1.0) but I haven’t quite figured out yet what use cases this could serve.

RESHUFFLE_NUM = 1
# times through before reshuffling

When Pi3D is launched it looks at all the images in your folders and creates a random playlist.

If you want this list to be reshuffled every time a full image cycle has been completed, set it to “1”. If you want to repeat the same random playlist several times, set it to “x” with “x” being the number of times the same sequence is being shown.

I always set it to “1”.

USE_MQTT = False

If you are using Home Assistant or Node-Red and want to control your digital picture frame from there, or you have some other app that can send MQTT messages, then you can activate Pi3D’s MQTT functionality here.

Put “True” if you are using MQTT, “False” if you do not.

If you enter “True”, don’t forget to add your MQTT server information further below.

RECENT_N = 50 # shuffle the most recent ones to play before the rest

Pi3D will monitor your image folder and notice if you have added new images.

In this case, it will reshuffle the playlist immediately so that these new images are included.

Plus, you can choose to show the most recent images first. This is very nice when you come back from holiday, and everybody is eager to see the new photos.

Setting RECENT_N to 50 will display the 50 most recent images whenever new images are being added.

SHOW_NAMES = False

You can display the filenames of your images by setting this value to “True”. If you don’t, just leave it as “False”.

This new function also means that you do not longer have to change the code as described in the original Pi3D article.

CHECK_DIR_TM = 60.0 # seconds to wait between checking if directory has changed

This specifies how often you want Pi3D to check if new images have been added.

By default, it is set to check every minute, but you can set it to 3600 if you only want to check every hour. It doesn’t have a real impact on your system load, so you can safely leave it at 60 seconds.

BLUR_EDGES = False

This feature will create blurred edges to fill the screen that would otherwise remain black.

You have surely seen this effect when watching videos that have been filmed in portrait mode on smartphones. As the video playback is always in landscape mode, two-thirds of the screen is filled with a blurred version of the video.

With images it is typically only the edges and setting this value to “True” will create a smooth blur.

BLUR_AMOUNT = 12

This specifies the degree of blur. Setting it to “12” looks good, the higher you adjust this value, the more CPU power your Raspberry Pi will have to sacrifice. On the Pi 4 it’s still only 5% but only an earlier model, it will be quite a bit more.

BLUR_ZOOM = 1.0

Just leave this value at “1.0”, it will expand the backgorund to just fill the space around the image just right.

The new pictureframe.py script – The variables

The new PictureFrame.py script allows you to have additional controls via the MQTT protocol and even to set up smart filters for the playback of your images based on the Exif date.

#####################################################
# these variables can be altered using mqtt messaging
#####################################################
time_delay = 10.0 # between slides
fade_time = 3.0
shuffle = True # shuffle on reloading
date_from = None
date_to = None
quit = False
paused = False # NB must be set to True after the first iteration of the show

Even if you are not using MQTT, you at least need to define the time_delay, fade_time and shuffle.

time_delay = 10.0 # between slides

How long an image is shown. I set this to 200 seconds.

fade_time = 3.0

As I want to enjoy the random artistic creations of Pi3D, I set this value to 10 seconds.

shuffle = True # shuffle on reloading

Unless you want to show your images sorted by name, you will want a random playback sequence. In this case, just set it to “True”.

You can change the three values above by sending an MQTT message to your frame, which I have explained in detail for Home Assistant and Node-Red.

In addition you can send values for the following variables:

date_from = None

This is first part of of the smart filter based on the Exif date.

If you are not sure if your images contain valid Exif data, have a look at “Check the Exif data of your images to pre­pare your pho­to frame for smart playlists” and run the Exifcheck script.

The format for this value is “yyyy:mm:dd” (e.g. “2016:12:25” – you need to use colon separators). All images that have been taken from this day on will be shown, later photos, or photos with missing Exif data, will be excluded from the playlist.

“None” means that no filtering is applied.

date_to = None

This is the second part of the smart filter based on the Exif date.

Specify here the date until which images are included in the playlist. Sending a value like “2018:6:21” via MQTT will result in the exclusion of photos with a newer Exif date than June 21, 2018.

quit = False

You can terminate Pi3D by sending a quit command. This is more for testing purposes than for anything else.

paused = False

Sometimes you want to stop at an image to show it to someone or just to enjoy it longer. Just send a “pause” command and Pi3D will suspend the playback.

If you send the same command again, playback will resume.

Setting up the MQTT server/post office

# set up MQTT listening
client = mqtt.Client()
client.username_pw_set("myuserid", "mypassword") # replace with your own id
client.connect("postman.cloudmqtt.com", 16845, 60) # replace with your own server

Around line 195, you will find the settings for your MQTT server. Enter your username, password, server and port address.

I have said if often before but I’ll say it again. If you are using a digital picture frame in a residential setting, there is no better image viewer for the Raspberry Pi than Pi3D. The super-smooth and unobtrusive crossfades are a pleasure to observe and will take your photo viewing experience to a new level.

A big Thank You to Paddy, the co-author, and maintainer behind this software gem!

Wolfgang Männel

Photography has always been a passion of mine. Since 2005, I have looked at countless ideas on how to enjoy beautiful images digitally, making the experience entertaining, amusing, and stimulating. In my other life, I am an entrepreneur, consultant, and bicyclist based near Frankfurt am Main, Germany.

Recent Content