All the options and settings of the Pi3D image viewer explained in one simple cheat sheet

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.

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!