PiccoPin — User Manual

PiccoPin writes GPS coordinates into your photos — automatically from a recorded GPX track, or by hand with a click on the map. This manual describes everything the program can do, in the order you will usually need it.

1 — Getting started

The main window has three areas:

• the photo list at the top left,
• the track list at the bottom left, with its own search field,
• the map on the right, with the bar for all actions above it.

You can drag the divider between the photo list and the track list; PiccoPin remembers the split. The status line at the bottom left shows how many photos are loaded, how many of them are located, and how many tracks are loaded. If an error occurs, it appears there in red.

The usual workflow

1. Load photos (chapters 2 and 3).
2. Load one or more GPX tracks (chapter 4).
3. Press Match (chapter 5).
4. Locate photos without a matching track by hand (chapter 7).
5. Export writes the coordinates into the photos (chapter 11).

The action bar

On the left of the bar are the place search and the Category menu, see chapter 8.

2 — Loading photos

Photos opens the file dialog; you can choose several files at once. You can just as well drag images from the Finder into the photo list. JPEG, PNG, TIFF and HEIC are accepted. A photo that is already in the list is not added a second time.

When loading, PiccoPin reads each photo's capture time, camera model and any GPS position it may already contain. The capture time is the basis for matching. A photo without a capture time shows No capture time and can only be located by hand.

What the rows show

Each row shows a status symbol, optionally a thumbnail, the file name and the capture time. If the photo is linked to a track, ↳ track name appears below it. A small library badge in front of the name marks photos from the Photos library.

Selecting

A click selects a photo; the map moves it to the centre if it has a position. Use ⌘-click or ⇧-click to select several. A second click on the same photo shows or hides the information panel.

Removing

⌘⌫ or Remove in the context menu takes the selected photos out of the list. Clear list takes out all of them. In both cases the files are not touched.

If Remember working session across restarts is on (the default), the photo list with its positions is back on the next launch, see Settings › General.

3 — Photos from the Photos library

Library takes photos straight from the Apple Photos library. The first time, macOS asks whether PiccoPin may access your photos. If you have denied access, PiccoPin offers Open System Settings. There you allow it under Privacy & Security › Photos.

In the window Choose photos from the library you select photos by clicking them; another click deselects them. ⇧-click selects a whole range. The bottom of the window shows how many photos are selected. Import adds them to the photo list.

PiccoPin works with working copies; the library stays unchanged until you export. Photos that already have a GPS position are skipped on import. You can turn this off under Settings › Photo library.

4 — Loading GPX tracks

Load GPX opens the file dialog for a GPX file, as recorded by GPS devices, sports watches and tracking apps. The track appears as a blue line on the map, and the map zooms to it. You can load as many tracks as you like; the same file is not loaded twice.

The track list

The track list shows the file name and the recording period of each track. A click selects a track; a second click on the same track shows or hides the information panel. It shows start, end, duration, number of points and the elevation range.

The context menu of a track offers:

• Information — opens the information panel for the track;
• Show track on map — zooms the map to the track;
• Notes — enter a title, description and keywords, see chapter 10;
• Delete track — removes the track from PiccoPin.

Delete track or ⌘⌫ removes the track from the list. The GPX file and your notes are kept. What is deleted are the remembered links between photos and this track; the photos themselves stay in the list and keep their positions.

5 — Matching photos

Match looks for the track point whose time is closest to each photo's capture time and takes over its position and elevation. All loaded tracks are searched together. Each located photo is also linked to the track whose recording period it falls into; the line ↳ track name below the photo shows this.

Positions set by hand are left untouched by matching. A photo that is further in time from the nearest track point than the set tolerance gets no position and the red warning triangle.

The related settings

6 — Clock correction per camera

A wrongly set clock belongs to the camera, not to the individual photo. PiccoPin therefore stores the correction per camera model. If you mix photos from a camera and a smartphone, each photo is matched with the correction of its own device.

If Match finds photos from a camera model PiccoPin does not know yet, the dialog Set clock correction for camera appears first. It shows the detected model, such as “SONY ILCE-7M3” or “Apple iPhone 15 Pro”. With several new models it goes through them one by one (Next); on the last one, Save and match starts the matching.

Entering the correction

If the camera clock is right, leave all fields at 0. Otherwise choose the sign and enter hours, minutes and seconds:

• + if the camera clock was behind — the time is moved forward;
• − if it was ahead — the time is moved back.

Example: the camera showed Jul 2 12:24, but the real time was Jul 3 10:40. Then enter + 22 hours 16 minutes.

Photos without camera model information are matched without correction. You can change or delete recorded models under Settings › Camera.

7 — Setting a position by hand

For photos without a matching track, or to correct a position, you set the position by clicking the map:

1. Select one or more photos in the list.
2. Open the lock at the top left of the map.
3. Click the desired spot on the map.

All selected photos get this position. This way you locate many shots from the same place in one step. A photo that already has a position gets the new one.

The lock is closed at launch, so that no positions are set by accident while you pan and zoom the map. While photos are selected, a hint at the top of the map says what a click will do.

Photos located by hand are also linked to a loaded track if their capture time falls into its recording period.

8 — The map

Map style

At the bottom of the map you choose Standard, Satellite or Hybrid. PiccoPin remembers the choice.

Pins

Each located photo appears as a pin. Clicking a pin also selects the photo in the list. The selected pin carries a coloured ring at its foot and, if turned on, the file name. Under Settings › Display you can show the photos as small thumbnails on the map instead.

Searching for a place

The Search place field on the left of the action bar takes a place name or an address. Return zooms the map there. This is handy for finding a spot when setting positions by hand.

Categories

The Category menu shows matching places in the visible part of the map: attractions, restaurants, cafes, hotels, supermarkets, gas stations, parking, pharmacies or hospitals. Only one category is active at a time. When you move the map, the places are reloaded. No category hides them again.

9 — Preview and information

The preview

A selected photo appears as a floating preview at the top right of the map. When it appears is set under Settings › General:

• Automatic — whenever a single photo is selected;
• On double-click — only after a double-click on the photo; another double-click closes it;
• Off — never.

The information panel

You open the panel on the right of the map with Information, with a second click on a photo or a track, or with Information in the context menu. For a photo it shows:

• under File the path and the name; for photos from the library it shows “Photo Library” instead of the path;
• under General the capture time, the status and the linked track;
• under Position latitude, longitude and elevation.

All values can be selected with the mouse and copied. For a selected track, the panel shows its recording data, see chapter 4.

10 — Notes and search

Entering notes

Notes in a track's context menu opens an input area below the map with Title, Description and Keywords. Confirm each keyword with Return; a click on the small x next to it removes it again. Save (⌘S) stores the entries. You change the height of the area with the handle at its top edge.

Finding tracks again

The Search recordings field above the track list searches the title, description and keywords of every track you have ever loaded — including those not loaded right now. Such hits appear dimmed and carry the hint load; a click loads them. Each hit shows how many photos are linked to the track.

If the GPX file is currently not reachable – deleted, moved or on a disconnected drive – the hit stays in the list with an orange warning triangle and the hint not reachable. Its notes are kept. As soon as the drive is connected again, the track loads as usual.

Loading linked photos again

PiccoPin permanently remembers which photos are linked to which track. If you select a track whose linked photos are not in the list, PiccoPin asks Load linked photos?. Load brings them back with their positions, including photos from the library. If photos are currently not reachable, PiccoPin reports their number in the status line; their links are kept. Only photos deleted from the library lose their link.

If a photo should no longer belong to its track, choose Remove photo from track in the photo list's context menu. The photo and its position are kept.

11 — Writing coordinates (export)

Export writes the positions of all photos that have one into the image files — including photos that already brought their position with them when loaded. All other metadata and the image itself are preserved. Where the data is written is set in the settings, separately for files and for the library:

Confirming

Before writing, PiccoPin shows what will happen: how many photos are written as copies, how many originals are overwritten and how many are written back to the library. If originals are affected, the Export button is red, and a warning points out that this cannot be undone.

Target folder and file names

For copies, PiccoPin needs a target folder. If none is set under Settings › Photos or Photo library, the program asks for one when you export. The copy keeps the name of the original. If the target folder already contains a file of that name, or if the target folder is the original's folder, the copy gets the suffix _geo, for example IMG_1234_geo.jpg, then _geo-1, _geo-2 and so on. An existing file is therefore never overwritten.

After the export, PiccoPin reports how many files were written, how many photos were written back to the library and how many failed.

12 — Settings

Open the settings with the gear in the action bar or with ⌘, . The sections are listed on the left.

Purchase

Shows whether the full version or the trial version is running, and how many days of the trial are left. Here you buy the full version, and Restore Purchase brings back an earlier purchase, for example after reinstalling.

General

• Remember session — restores the photo list, positions and tracks on the next launch. It is on by default. Turning it off deletes the remembered state; your current work stays until you quit.
• Thumbnails — small images in the photo list. With very many photos, turning them off makes the list faster.
• Photo preview — when the floating preview appears, see chapter 9.

Display

• Photo names on the map — the file name at the selected pin.
• Photos on the map — located photos as small thumbnails at their position.

Appearance

Light, dark or following the system, plus one of twelve accent colours for highlights and selection.

Matching

Capture time zone and Maximum tolerance, see chapter 5.

Camera

All recorded camera models with their clock correction. You can change the values here. The trash can removes a model; on the next matching, PiccoPin asks for its correction again.

Photos

Applies to photos from files. Write coordinates chooses between Write to a copy and Write back to the original. Target folder for copies sets where the copies go; without one, PiccoPin asks when you export.

Photo library

• Write coordinates — copy or write back to the library, see chapter 11.
• Target folder for copies — a separate target folder for copies of library photos.
• Skip already located — leave out photos with a GPS position when importing from the library. It is on by default.

Language

PiccoPin speaks German, English, French, Italian, Spanish and Dutch, or follows your Mac's language with System. The change takes effect immediately, without a restart.

Log

Write log records errors and activity in a file. This helps when you contact support about a problem.

• Level — from Errors only to Everything (debug). For troubleshooting, Including info is enough.
• At 2 MB the file starts over; the previous one is kept as a copy.
• Show, Show in Finder and Clear for the file.

About

Version, an overview of the features, the link to the website and Show What's New. After an update, PiccoPin shows what is new once by itself.

13 — Help and keyboard shortcuts

PiccoPin has a built-in help. Open it with Help in the action bar, from the Help menu or with ⌘?. A right-click on Photos, Library, Load GPX, Match or Export offers Help for this function and jumps straight to the matching section.

14 — Frequently asked questions

“Match” is greyed out.

It needs at least one photo and one loaded track.

My photos get the red warning triangle.

Their capture time is further than the set tolerance from every track point. First check the Capture time zone; a wrong time zone shifts all photos by whole hours. Then check the camera's clock correction. If both are right, the photo belongs to none of the loaded tracks.

The positions are a little off the route.

Usually the camera clock is a few minutes wrong. Correct the value under Settings › Camera and match again.

A click on the map does not set a position.

The lock at the top left of the map is closed, or no photo is selected.

I can't find an old track with the search.

The search only looks at title, description and keywords, not the file name. A track without notes cannot be found this way. Load it with Load GPX and give it notes.

“Load GPX” opens the purchase window.

The 14-day trial has expired. With the full version, loading and export are available again, and the remembered tracks appear right away.

Are my originals changed?

Only if you choose so under Settings › Photos or Photo library. By default PiccoPin writes to copies.

Does my data go to the internet?

No. Photos, tracks and notes stay on your Mac. Only for the map images, the place search and the categories does the map contact Apple.