My wife always wanted to have one feature in our digital picture frame: To know where a particular photo was taken.

When you have thousands of photos on your Raspberry Pi digital picture frame, you may not immediately remember every single image taken over many years from your far-away travels.

This is where the GPS data comes in handy. Every modern smartphone will record the geo-coordinates of where a picture has been taken. DSLR photographers can use a GPS module on their camera, which can record this data. And alternatively, you can add the location manually in post-processing software like Adobe Lightroom.

Pi3D PictureFrame 2021 came with built-in reverse geocoding features which leave nothing to be desired. The settings below are the pi3d ones. picframe3 geocodes too, with different setting names and no file to edit; that translation is at the end of this article.

How to extract the GPS data and turn it into places

Recently, Paddy, one of the authors of Pi3D PictureFrame, the undisputed best image viewer for Raspberry Pi-based digital picture frames, updated the software to allow a much simpler way to show the GPS location of a photo.

The GPS data that is stored in a JPG file provides the longitude and latitude data. But this needs to be translated into places or towns and countries; a process called “reverse geocoding”.

You wouldn’t want to see “latitude 48.864716 and longitude 2.349014” on your display but expect it to be translated as “Avenue des Champs-Elysées, Paris, France.”

“We’ll always have 48.864716/2.349014.”

Luckily, many free services provide these reverse geocoding services. And with Geopy, there is a perfect Python client to connect to several popular geocoding web services.

Paddy used Nominatim in his Pi3D image viewer script, a tool to search Open Street Map (OSM) data by name and address and to generate addresses of OSM points.

For example, this service tells us that latitude 48.864716 and longitude 2.349014 is Paris and not Los Angeles.

The advantage of using Nominatim is that you don’t need to create an account with any user name and password hassle. It works right out of the box with any random user name.

Here is how you install it.

Activating the Geo extension of Pi3D PictureFrame

In configuration.yaml in picframe_data/config this is the part where the geo action is:

  load_geoloc: False         # get location information from open street map
  geo_key: "this_needs_to@be_changed"     # you **MUST** change the geo_key to something unique to you
  locale: "en_US.utf8"     # "locale -a" shows the installed locales which could used
  key_list: [
    ["tourism","amenity","isolated_dwelling"],
    ["suburb","village"],
    ["city","county"],
    ["region","state","province"],
    ["country"]]

Change the first line to True to activate PictureFrame’s geo module. The text after the # is only a comment explaining the setting — what you edit is the value in front of it.

  load_geoloc: True

Add a “unique key” in the next line in “default” to replace “this_needs_to@be_changed”. You can use just about any word. Nominatem doesn’t require you to create an account but uses a unique identifier to prevent users from abusing a free service. If lots of people use the same string, then Nominatem might start restricting the queries, so put a word here that is not commonplace.

I would recommend to use your email address because it is unique to you.

  geo_key: "your_email@address.com"

Next, check your locale. The “locale” is the language setting on your Raspberry Pi. In the context of geocoding, it specifies the output language for countries or regions – provided a translation is available. The chosen locale must be installed on your Raspberry Pi. How that works, see the chapter below.

  locale: "en_US.utf8"   # "locale -a" shows the installed locales which could used

Changing the language of the Geo Information

The language of the places (e.g., countries) is based on your Raspberry Pi default language that you have specified in

sudo raspi-config

in the “Localisation” section. So, if you want to change the language, go in there and select additional language sets. I would recommend using the “UTF8” variant of a language to display any special characters in your language properly, e.g., German Umlaute or French accents.

At the end of the selection, you will be asked to select your default locale. This will be the language to show e.g., “Österreich” instead of “Austria” in the address data.

To change the date format, have a look here.

Triggering the display of the geolocation automatically when images change

As described in this article, the display of the file name, the Exif date, or the location is either invoked whenever a new image fades in or is manually triggered by using an MQTT command.

If you want to show either information automatically, look for this line in configuration.yaml:

  show_text: "title caption name date folder location"  # default="title caption name date folder location"

You can show any combination of information, but if you want the geodata then “location” must be included.

Triggering the display of the geolocation on demand

You may not want any information to be overlaid permanently on your photos all the time. However, it’s actually quite intriguing to turn it on permanently for a while. Especially for events, it may be interesting for your guests to see where you have been. (Ok, that is a bit of bragging but you get the idea!)

But to trigger the text overlay display manually, this is how it works:

Pi3D PictureFrame contains extensive remote control capabilities via MQTT, which you can find in the configuration.yaml file in the mqtt section.

  use_mqtt: True

You can find a good introduction here and in the other MQTT articles on this blog.

MQTT may be somewhat confusing initially, but once you understand the basic logic, you will see that it is very straightforward to use and yet very powerful.

To send an MQTT message to PictureFrame, you can use Siri Shortcuts (on iPhone), one of the older phone apps (iPhone, Android, both now unmaintained) or talk to Alexa with Home Assistant.

I have written articles explaining each mode in the links above.

The MQTT messages that you need to know for the display of an information bar are:

- name text on/off: homeassistant/switch/picframe_name_toggle/set, ON,OFF
- date text on/off: homeassistant/switch/picframe_date_toggle/set, ON,OFF
- location text on/off: homeassistant/switch/picframe_location_toggle/set, ON,OFF
- directory text on/off: homeassistant/switch/picframe_directory_toggle/set, ON,OFF
- title text on/off: homeassistant/switch/picframe_title_toggle/set, ON,OFF
- caption text on/off: homeassistant/switch/picframe_caption_toggle/set, ON,OFF
- all text off: homeassistant/switch/picframe_text_off/set, ON # yes that is confusing!
- text refresh: homeassistant/switch/picframe_text_refresh/set, ON

I have covered the date and file name here. For location just send an MQTT with the topic “homeassistant/switch/picframe_location_toggle/set_”_ and the payload “ON”.

You can toggle the display of the various items. To turn off the overlay of the location, just send another “homeassistant/switch/picframe_location_toggle/set” and payload “OFF”.

To turn off the information overlay completely, use “homeassistant/switch/picframe_text_off/set” and payload “ON”.

And “homeassistant/switch/picframe_text_refresh/set” with payload “ON” brings up the display again if you couldn’t read it before it disappeared.

By the way, even if you turn off the text overlay: When you pause, “PAUSED” is briefly displayed.

homeassistant/switch/picframe_paused/set with payload "ON" of "OFF"

When everything works, you will see something like

The Ring has awoken, it’s heard its master’s call.

What is really nice with the Nomination Geo Service that in conjunction with Open Street Map, a lot of additional information will show up. Stuff that volunteers from all over the world have entered, which has a connection with the place where you took your photo. The example above is from a place in New Zealand where a scene from a movie was filmed. The language of the places and the date were set to German in the PictureFrame configuration.yaml file.

Please note: If no location is shown, then no valid Exif GPS data was found. If “no location found” is shown, it means that the Geoservice has no address, e.g. when you are flying or sailing across the ocean.

Please note: If the Exif data is not shown properly, then your Exif information may be corrupted. You can’t see this as the file opens and shows as normal. Out of 1,000 old photos, I had it in over 300 files, most of them older. What I did was to export them from Adobe Lightroom again, and then everything was clean. You can probably do the same with the photo software that you are using. You can verify the state of your Exif data with this simple script.

Please note: reverse geocoding did not work with HEIC files when I wrote this in 2020. I have not re-tested that on a current Pi3D release, so treat it as a question rather than a fact. picframe3 reads HEIC, coordinates included.

Place names on picframe3

On a Raspberry Pi 4 or 5 I now run picframe3, and none of the keys above exist there. The place-name settings are:

geo.enabled     on or off
geo.contact     your email address - required when enabled, because
                OpenStreetMap's usage policy asks for a way to reach you
geo.language    two-letter code for the language place names come back in
geo.detail      how much of an address a caption shows
geo.suppress    place names never to show, e.g. your own country
geo.key_order   which address parts to prefer, when detail is set to Custom

So geo_key becomes geo.contact — same idea, and my advice to use your email address is now what the software requires. locale splits in two: geo.language decides the language of the place names, viewer.locale the language month names are written in.

Two behaviours differ. picframe3 looks a place up the first time a photo is shown, as pi3d did, but it also fills the rest of the library in quietly in the background at the one request per second OpenStreetMap asks for — so turning geocoding on after your library is already indexed works, with no re-index. picframe3 scan resolves everything outstanding in one go.

And geo.detail can be changed at any time without costing a single new request: the replies are cached forever, so re-wording your place names is free.

For the caption itself, location is one of the elements in viewer.show_text, exactly as in pi3d. The on-demand trick is neater: set viewer.text_seconds: 0 and the caption writes nothing by itself, then the Show the caption button in Home Assistant, the i key, or the button in the web interface reveals it for viewer.peek_seconds — 40 seconds by default, because a deliberate look wants longer than a glance.

The MQTT topics listed above are pi3d's. picframe3 announces its own entities to Home Assistant by auto-discovery, so you do not write topics by hand at all.

Conclusion

I find the display of location data most interesting as it invokes even more memories in addition to seeing the photo. Yes, it does require that your photos are tagged, but as most photos today are taken with a smartphone, the location is already included.

Thank you very much, Paddy, for yet another tremendous Pi3D PictureFrame feature!