Skip to main content

Photo indexing

To get your photos into Cardinal Photos, you need to index them with Cardinal Home Server.

Supported file types​

  • jpg/jpeg
  • png
  • gif
  • heif/heic
  • mov*
  • mp4*

* In development

Folder structure​

  1. Photos can be stored at any folder depth.
  2. Google Takeout folders and files must use their original names from Google.
/photos                       🠘 Photos library root
  /[...]                      🠘 Other folders, any depth, optional
    /takeout-abc-001          🠘 Google Takeout folder
    /photo.jpg                🠘 Photos can be anywhere

Using photos from Google Photos​

You can use Google Takeout to export your photos and videos from Google Photos. After downloading your data, just throw it into your photos directory and Cardinal will know how to read the special directory structure and .json files that Google provides.

Photo types​

While the most common type of photo is one taken by a smartphone camera, there are other places a photo can come from. The structure of a photo's metadata depends on its source, and Cardinal supports these types of photos:

  • Pictures taken by a smartphone or regular camera.
  • Screenshots and screen recordings taken by mobile and desktop devices.
  • Random images downloaded from the internet like wallpapers and memes.

Determining the time a photo was taken​

The most important thing to know about a photo is when it was taken, and internally this is known as the takenAt value. Cardinal guarantees a takenAt value for each photo.

Cardinal will look in these locations, in this order, for a date value. The first one found will be used.

  1. photoTakenTime.formatted from the Google Takeout JSON
  2. createdate from the Exif
  3. datetimeoriginal from the Exif
  4. gpsdatestamp + gpstimestamp from the Exif
  5. If it's a Google Photo, and it matches this regex, the date will be extracted from the file name: /([^\s]+)_(\d{8})-(\d{6})/mi.
  6. modifydate from the Exif
  7. creationTime.formatted from the Google Takeout JSON
  8. createdAt from the file system
  9. modifiedAt from the file system
  10. If still nothing has been found, the time of indexing is used.

Expected takenAt value for each photo type​

  • Pictures taken with a camera should have a takenAt value of when the photo was snapped in real life.
  • Screenshots and screen recordings should have a takenAt value of when the screenshot or video was originally captured.
  • Random images should have a takenAt value of when the file was downloaded.

GPS data​

Cardinal supports GPS data in the Exif data and the Google Photos JSON.