My clear recommendation for a Raspberry Pi image viewer for a digital picture frame is Pi3D and the associated PictureFrame2020 script written by Paddy Gaunt. If you stumbled upon this page by accident and not sure what Pi3D is, get up to speed with this article.
Pi3D uses the full power of the graphics processor of the Raspberry Pi to create smooth blending effects which make the viewing experience unobtrusive and pleasant.
Tested with: Raspberry Pi OS Buster, Raspberry Pi 2, 3 and 4, Pi3D 2.41, PictureFrame2020 Script December 2020, 1080p and 4K displays.
The config file
The Pi3D script PictureFrame2020.py is highly configurable to your needs. The information for the various parameters is contained in the PictureFrame2020config.py file which is used when there are no command-line arguments given.
It is easy to be confused by the many possible options. This is why I have put together a complete overview of all parameters.
Some of these parameters can be altered with MQTT messages remotely. I have mentioned where this is possible and what channel and payload to send.
The order is based on the occurance within the PictureFrame2020config.py script.
Create blurred edges
Name of parameter
"-a", "--blur_amount", default=12, type=float
What this parameter does
This sets the blur amount to the effect described in the next parameter. A value of 1 will make it only slightly blurred, 12 will make it unrecognizable but often yields nice colors. Do not enter a high level than 12.
Recommended setting
10
Name of parameter
"-b", "--blur_edges", default=False, type=str_to_bool
What this parameter does
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.
Recommended setting
If you have photos in completely different aspect ratios on your frame, then this setting can be very nice.
Examples:



Check image directories for new images
Name of parameter
"-c", "--check_dir_tm", default=60.0, type=float
What this parameter does
Pi3D will check every minute if you have made changes to the Pictures directory. If yes, it will create a freshly shuffled playlist, including the new images. This is to avoid that you have to wait until a currently shuffled playlist has ended until any new images are included.
Recommended setting
Leave default value of 60.0.
Verbose
Name of parameter
"-d", "--verbose", default=False, type=str_to_bool
What this parameter does
If set to “True”, Pi3D will show try and exception messages that come up during the execution of the PictureFrame2020 script.
Recommended setting
Unless you are trying to debug any issues, leave it on “False”.
Background color at edge
Name of parameter
"-e", "--edge_alpha", default=0.5, type=float
What this parameter does
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.
“0.0” is a bar (define the color in “Background Color”), and everything in between will reduce the opacity of this mirrored edge.
Recommended setting
You should 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”.
Example:



Frames per second
Name of parameter
"-f", "--fps", default=20.0, type=float
What this parameter does
This changes the granularity of the blending. However, I couldn’t see any difference between 20 fps and 30 fps.
Recommended setting
I would leave it at 20 as visually, you won’t see a difference anyway and older Raspberry Pi models may struggle with the CPU load.
Background color
Name of parameter
"-g", "--background", default=(0.2, 0.2, 0.3, 1.0), type=str_to_tuple
What this parameter does
An alternative to mirroring the gaps at the edges is to give the background another color that you can define in the RGBA color format. The first three numbers define the RGB color, the last one the opacity (Alpha).
Recommended setting
This is really a matter of individual taste. I would probably pick black (0, 0, 0, 1.0).
For an overview of decimal red, green, blue, and opacity color codes, have a look here.
Examples:



No images selected photo
("-i", "--no_files_img", default="PictureFrame2020img.jpg"
What this parameter does
When you set a smart filter like a date_from/date_to a combination that yields no photos that match your criteria, Pi3D will display a placeholder image “No images selected”.

You can replace the default image with a customized version of yours. Just create a jpg file in the dimensions of 960 x 593 px, upload it to the pi3d_demos folder and enter the file name here.
Recommended setting
As you like it!
Transition effect
Name of parameter
"-j", "--blend_type", default="blend", choices=["blend", "burn", "bump"]
What this parameter does
This defines the transition effect. You have the choice between blend, burn, and bump. Have a go and see which transition you like best.
Recommended setting
Set it to “blend”. This will give you wonderful crossfading transitions.
Keyboard connected
Name of parameter
"-k", "--keyboard", default=False, type=str_to_bool
What this parameter does
This is a sort of workaround when you are running your Pi with a keyboard, which in the case of a digital picture frame should rarely be the case. Set it to “True” for debugging purposes.
Recommended setting
False
Using MQTT to remote control parameters
Name of parameter
"-m", "--use_mqtt", default=False
parse.add_argument( "--mqtt_server", default="mqtt.eclipse.org"
parse.add_argument( "--mqtt_port", default=1883, type=int
parse.add_argument( "--mqtt_login", default=""
parse.add_argument( "--mqtt_password", default=""
What this parameter does
This is one of my favorite features of Pi3D: The ability to remote control certain parameters with MQTT messages. To use it you will either have an MQTT broker installed or use a cloud-based one like Eclipse of CloudMQTT. If that is the case, set it to “True” and enter your MQTT broker IP. Most of the time, you don’t need a login nor password.
Recommended setting
Just enter the IP address of your MQTT broker and set “default=True” if you use this function. I recommend the installation of the Mosquitto MQTT broker on your digital picture frame instead of using a cloud-based service. The installation is one line only.
Play recent images first after a reshuffle
Name of parameter
"-n", "--recent_n", default=10, type=int
What this parameter does
Whenever you add or delete images to your pictures folder, or start Pi3D, the playlist will be reshuffled.
“recent_n” will play the newest ones first (based on the Exif date). Set this number to “default=10” if you want to show the ten newest images, or “0” if you want to turn this functionality off.
Recommended setting
When you upload new images, it is quite nice to immediately see them show up on the frame. Setting this value to “10” is not a bad idea.
Font File
Name of parameter
"-o", "--font_file", default="/home/pi/pi3d_demos/fonts/NotoSans-Regular.ttf")
What this parameter does
This is the font that is used to display the file names if you have activated this option. If you are using a language other than English which has a number of special characters like umlaute, accents, etc. and you are seeing weird characters displayed on the screen, changing the font file may be the solution.
Recommended setting
Leave the default.
Main picture directory
Name of parameter
"-p", "--pic_dir", default="/home/pi/pi3d_demos/textures")
What this parameter does
This is the main directory where your photos are located.
Recommended setting
/home/pi/Pictures
Shader
Name of parameter
"-q", "--shader", default="/home/pi/pi3d_demos/shaders/blend_new"
What this parameter does
This defines which Pi3D shader file to use for the transitions.
Recommended setting
Leave the default.
Times through before reshuffling
Name of parameter
"-r", "--reshuffle_num", default=5, type=int
What this parameter does
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’re going 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.
Recommended setting
I always set it to “1”.
Show file name, date and location
Name of parameters
"-s", "--show_text_tm", default=26.0, type=float, help="time to show text over the image")
"--show_text_fm", default="%d %B %Y", help="format to show date over the image")
"--show_text_sz", default=50, type=int, help="text character size")
"--show_text", default="date, location", help="show text, include combination of words: name, date, location")
"--text_width", default=90, type=int, help="number of character before breaking into new line")
What these parameter do
This section allows you to show either the file name, the (Exif) date, or the location or any combination thereof. You find name and date explained here, and location here.
The first parameter is the time how long the text overlay is shown. Keep it at max a few seconds shorter than your image display time. The second line is the date format. You can change the character size in line 3 and the width of the display (breakpoint) in line 5. Item 4 sets the default display combination. If you leave it empty, nothing will be shown.
Recommended setting
Up to you! For some inspiration click on the above article links.
Fit image into the screen
Name of parameter
"-t", "--fit", default=True, type=str_to_bool
What this parameter does
“True” means that the entire image fits onto the screen, and there will be gaps left (letter- or pillar boxing) 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 picture.
Recommended setting
False. I don’t like these pillar-boxes but I crop my images to the exact dimensions of the screen anyway, so I don ‘t use this feature.
Ken Burns
Name of parameter
"-u", "--kenburns", default=False, type=str_to_bool
What this parameter does
Ken Burns is is a type of panning and zooming effect to create the impression of moving images. Pi3D has a very smooth Ken Burns capability and it’s nice to look at if you like the effect.
Recommended setting
False
Time between images
Name of parameter
"-v", "--time_delay", default=10.0, type=float
What this parameter does
This defines how long an image is being displayed in seconds.
Recommended setting
200. I found this value to be ideal. It’s not too fast and it’s not too long. So just right.
You can change this setting with an MQTT message to “frame/time_delay” and the value as payload.
Transition time
Name of parameter
"-w", "--fade_time", default=4.0, type=float
What this parameter does
This defines the length of transition from one photo to the other in seconds. Having this at 10 seconds creates a sort of suspense each time you watch an image change and will make you guess what comes next for a few seconds. It must be larger than 0.0
Recommended setting
10. If you are using a 4K screen, a value of 3 seconds seems to be like a value of 10 with a smaller screen.
You can change this setting with an MQTT message to “frame/fade_time” and the value as payload.
Shuffle playlist
Name of parameter
"-x", "--shuffle", default=False, type=str_to_bool
What this parameter does
This is the same as music playlist. I guess you don’t want to see your photos in a static order, so “True” randomizes the playback sequence.
Recommended setting
True
You can change this setting with an MQTT message to “frame/shuffle” and the value “True” or “False” as payload.
Subdirectory
Name of parameter
"-y", "--subdirectory", default=""
What this parameter does
This is the subdirectory of “/home/pi/Pictures” which you have specified above. You can use different subdirectories and change them via MQTT. That way, you can have a folder with art images and one with vacation photos and quickly change when you have dinner guests!
Recommended setting
Either leave empty or specify your most frequently used subdirectory, e.g. “nature”.
You can change this setting with an MQTT message to “frame/subdirectory” and the subdirectory as payload like “nature”. If you send an empty payload like “”, you will be back taken back to “pi/pictures”. More here.
Blur zoom
Name of parameter
"-z", "--blur_zoom", default=1.0, type=float
What this parameter does
It expands the background to just fill the space around the image.
Recommended setting
Just leave this value at “1.0”, it will expand the background to just fill the space around the image just right. A larger value than 1 will zoom the blur effect.
Auto resize
Name of parameter
"--auto_resize", default=True, type=str_to_bool
What this parameter does
If you are using a 4K monitor with the Raspberry Pi 4 this is an important command as it will make sure that images are rendered at full 3840 x 2160 px resolution. You should also ensure that your images are the correct size for the 4K display.
Recommended setting
Set this to “False” if you want to use 4K resolution on Raspberry Pi 4. Set this to “True” for all other cases.
Geolocation
Name of parameter
"--load_geoloc", default=True, type=str_to_bool, help="load geolocation code")
"--geo_key", default="picture_frame_123456", help="set the google key - change to something unique to you")
"--geo_path", default="gpsdata.txt", help="set the local file to store data from google - ignored if --load_geoloc is not true")
What these parameter do
These lines activate the reverse geocoding module. Images that contain GPS metadata will be translated into places, streets, cities, and countries. You can display this information permanently or on-demand with an MQTT message.
Recommended settings
To turn on geolocation set “default=True” and enter a unique name in “default=”picture_frame_123456”. You can read all about this very powerful module here.
Locale
Name of parameter
"--locale", default="en_US.utf8", help="set the locale")
What this parameter does
This setting is useful when you show the date and want the month to have names in your local language instead of the default English version.
Recommended setting
Your local language. You can find all the country codes in “sudo raspi-config” under “Localisation”. Make sure that this country code is also installed in the same config menu.
Delay Exif
Name of parameter
"--delay_exif", default=True, type=str_to_bool, help="set this to false if there are problems with date filtering - it will take a long time for initial loading if there are many images.")
What this parameter does
If you have a few thousand images in your library, it may take a few minutes for Pi3D to scan all file metadata and prepare the playlist.
Recommended setting
If you have your digital picture frame continuously running, this is not an issue as the delay only occurs at start-up. But especially for tests, you may want to set it to “False”. I have it set to “True”.
Screen Offset
Name of parameters
"--display_x", default=0, type=int, help="offset from left of screen (can be negative)")
"--display_y", default=0, type=int, help="offset from top of screen (can be negative)")
What these parameter do
For certain aspect ratios, you can fine tune the exact display position with these value. For an example, look here.
Recommended settings
No need to alter these value unless you have a very special installation.
Display Width and Height
Name of parameters
"--display_w", default=None, type=int, help="width of display surface (None will use max returned by hardware)")
"--display_h", default=None, type=int, help="height of display surface")
What these parameter do
For certain types of displays or frame arrangement, you can use them for custom adjustments.
Recommended settings
Mere mortals probably don’t want to touch those values.
Conclusion
I hope this list is useful to navigate the PictureFrame2020config.py file and to get exactly the effect you want from Pi3D.
If you have any questions, let me know!
Related Articles
- How I added smooth crossfading image transitions to my Raspberry Pi digital picture frame
- How to trigger a Home Assistant script through Alexa and make your Raspberry Pi picture frame do (just about) anything
- How to show the place where your photo was taken with the Raspberry Pi digital picture frame geolocation feature
- Ask Siri about when a photo on your Raspberry Pi digital picture frame was taken