LeseSolm Files

LeseSolm 0.0.6
==============

Four AWK/BASH scripts for usage with the GPS Logger "Solmeta Geotagger Pro". This device is a direct geotagger with magnetic compass for certain Nikon SLR cameras. In addition, it logs the GPS track in its internal memory in plain NMEA format.

"LeseSolm" downloads the track log from the Geotagger and writes the NMEA data into a file. Also, you can see the memory usage and erase the logger memory.

"GeotagSolm" reads the NMEA file and geotags the images that have been taken while the Geotagger was on the camera hot shoe. This should work with all hardware versions of the Geotagger. The universal meta data tool "ExifTool" by Phil Harvey is used for writing the GPS data into the image files or XMP sidecar files, respectively.

The LeseSolm package including all scripts comes without any warranty.
USE AT YOUR OWN RISK.

Project homepage: http://sourceforge.net/projects/lesesolm/

SYNOPSIS:
LeseSolm [COMPORT]
GeotagSolm NMEA TIME IMAGEFILES
BackupEXIF IMAGEFILES
CreateXMP IMAGEFILES


1. INSTALL
==========

All the script files "LeseSolm", "GeotagSolm", "BackupEXIF" and "CreateXMP" can be placed in any directory. Open a terminal there. Make the scripts executable by

chmod +x LeseSolm GeotagSolm BackupEXIF CreateXMP

on the command line. If that directory is in the PATH environment variable, you can start the scripts everywhere just by "LeseSolm", "GeotagSolm", etc. Otherwise you have to write the full path. E.g. if "LeseSolm" is in the current directory it can be started by "./LeseSolm". In the following we assume that the directory with the scripts is in PATH.


2. LeseSolm
===========

"LeseSolm" downloads the GPS track log from the Geotagger.


2.1 USAGE
=========

Connect the Geotagger to an USB port, open a terminal and change to the directory where the track log shall be saved. Turn the logger on and start LeseSolm by

LeseSolm COMPORT

Replace COMPORT by the serial interface to the logger. If COMPORT is omitted it defaults to "/dev/ttyUSB0". If there are other USB-COM devices you may have to replace 0 by a higher number. You need read and write permissions to the serial interface file. In Opensuse 11.3 it is sufficient to be member of the group "dialout".

LeseSolm will show you a menu:

>LeseSolm 0.0.5: Auslesewerkzeug für den Solmeta Geotagger Pro
>Leseprozeß mit PID 9438 gestartet, öffne Schnittstelle /dev/ttyUSB0, 4800
>Befehl: Version (v), Download (d), Löschen (erase), Ende (q), Abbrechen (abort)

Type "v" (plus ENTER) for showing the version (#Ver) and the used memory (#mem) of the Geotagger.

>Version anzeigen, 4800
>#Ver: Solmeta PRO V1.0-4 (Dec 03 2009)
>#mem:48KB

If nothing is shown try it again. Sometimes the Geotagger is ignoring commands.

The command "d" downloads the track log from the Geotagger and saves the data into the file "Solmeta_YYYY-MM-DD-HHMMSS.nmea", where YYYY-... denotes the date and UTC time of the first track point. Wait until the download is complete.

>Auslesen
>#connect
>Sende #down, 115200
>#download00c2
>Lese Zeile   907,   48/  48 KiB, 100%.
>#downcomplete
>907 Zeilen gelesen in  0:10 min, 4.8 KiB/s.
>14 GPGGA Sätze gefunden.
>NMEA Daten nach Solmeta_2011-02-15-190933.nmea geschrieben.
>Umschalten auf 4800

In this example 907 lines have been saved into the file "Solmeta_2011-02-15-190933.nmea". Among them are 14 $GPGGA sentences which correspond to the track points where photos were taken by the camera. You obtain this information only when the Geotagger was operational and mounted on the hot shoe of the camera.

Now check the NMEA file for completeness. If everything is OK, you can erase the Geotagger memory by typing "erase". Wait approximately one minute until the process is finished.

>Logger leeren, 4800
>#StartErase
>Löschen läuft, bitte warten.
>#erasecomplete
>Logger geleert nach 41 s.

"v" will show you that the Geotagger is empty now.

>Version anzeigen, 4800
>#Ver: Solmeta PRO V1.0-4 (Dec 03 2009)
>#mem:0KB

Type "q" to quit. Turn the logger off.


2.2 REMARKS
===========

* You can abort the download and erase processes with "abort". This may confuse the Geotagger and you may have to turn it off. Use this option only when the Geotagger hangs.

* The LeseSolm script is experimental, it works fine for my configuration:
Old hardware version (10.0) of the "Solmeta Geotagger Pro", Opensuse 11.3, gawk-3.1.6-31.1.i586, coreutils-7.1-11.1.1.i586

* For me LeseSolm works better than the Windoze tool, which often hangs. The USB-COM driver is already part of the Linux kernel. No need to install drivers. The NMEA files created by LeseSolm are given reasonable file names.

* The download command "d" does not overwrite existing Solmeta_YYYY...SS.nmea files, instead the log is written into the file Solmeta_YYYY-...SS-xxxx.nmea, where xxxx is a number starting from 0001.


3. GeotagSolm
=============

"GeotagSolm" enhances image files (or XMP sidecar files) with GPS data from the Geotagger.

This is an early release. Be careful! Geotagging is a delicate process because your image files will be modified. To be precise, it is the image meta data which will be amended by GPS data. It is strongly recommended that you keep your original files in a safe place. For the beginning, work only on copies in a separate directory. Instead of geotagging your image files you can write the GPS data also into XMP sidecar files and leave the images untouched. In addition, backups of the original EXIF data in the image files can be made. See Sec. 4 below for details.

GeotagSolm needs "ExifTool", which is available for Linux and many other operating systems. If you cannot find it in the repositories of your distribution, you can get it from the ExifTool homepage www.sno.phy.queensu.ca/~phil/exiftool/


3.1 USAGE
=========

Start the geotagging script by

GeotagSolm NMEA TIME IMAGEFILES

Mandatory arguments:

* NMEA denotes the track log file from the Geotagger.

* TIME is the time shift between the camera time (EXIF:DateTimeOriginal) and GPS (UTC) time, precisely: (Camera time) = (TIME + GPSTime) with a 10 second tolerance. The format for TIME is (+/-)H:M:S. If the hour (H), the minute (M) or the second (S) are omitted they are set to zero. Examples:  +1 = +1:0:0,  -1:13:3,  ::4 = 0:0:4,  -0:3 = -0:3:0.
For track logs from the old Geotagger version (10.0), it is sufficient to specify TIME within the 10 sec tolerance. However, logs from newer versions (10.1, 10.2) require TIME to be set precisely within one second. Also, the log interval of the Geotagger should be set to 1 second for precise geotagging.

* IMAGEFILES specifies the files and directories you want to geotag. Wildcards (*) will be expanded by the shell. Be careful, * means all files and the files in directories. It is better to use something like *.JPG or *.xmp.

------------
Example:
GeotagSolm Solmeta_2011-01-22-074402.nmea +1::7 DSC_4766.JPG DSC_4773.JPG Folder

This means that the camera time is assumed to be (GPSTime + 3607 sec). The files DSC_4766.JPG and DSC_4773.JPG will be geotagged as well as *all* suitable files in the directory "Folder".

Example:
GeotagSolm Solmeta_2011-01-22-074402.nmea +1::7 *.xmp

Same action as above, but the GPS data is written into XMP sidecar files (*.xmp). If you do not have these files, you can create them from your JPG images with "CreateXMP *.JPG". See Sec. 4 for details.
------------

The time tolerance for matching image time and GPS time is 10 sec by default. This value can be changed, see below.

After "GeotagSolm" has related the image files (or XMP files) with the GPS data, and before the image files are updated, it will present a menu:

>Befehl: (geo)  Geodaten mit ExifTool in Bilder schreiben
>        (list) Liste mit den zum Geotaggen vorgesehenen Bildern anzeigen
>        (arg)  ExifTool Argumente-Datei anzeigen
>        (quit) Abbruch, temporäre Dateien bleiben erhalten

Type "list" to show which files are going to be geotagged. Check this list for errors. You can exit the list view with "q", which gets you back to the GeotagSolm menu.

"arg" shows the arguments to be passed over to "ExifTool". Again you get back with "q".

"quit" will quit without writing anything. Use this command if you have found errors in the lists.

After you have checked that everything is fine, type "geo" to let "ExifTool" write the geo data into the files. Now check if the geotagged files and the meta data therein can be properly accessed by your image applications. Consult the ExifTool homepage for compatibility issues.


3.2 REMARKS
===========

* GeotagSolm works quite comfortably with track logs from the old Geotagger version because it has the "universal geotagging" feature. This allows relating GPS positions to images very precisely without knowing the exact time difference. More recent Geotagger versions (10.1, 10.2) do not have this capability, but they can log in 1 sec intervals. Consequently, if you know the exact difference between GPS time and image time, precise geotagging is possible, too.

* If the correlation of GPS time and image time fails, improve the value of the TIME argument. The relation (DateTimeOriginal) = (TIME + GPSTime) must be true within the tolerance of 10 sec. See below how to change the tolerance.
It is a good idea to have the minutes and seconds of the camera clock synchronised with the GPS time before taking pictures. Then TIME is just the time zone designator, e.g. +1 in Central Europe (or +2 during summer time).

* The NMEA sentences in the track log must be time-ordered, oldest first. GeotagSolm will work faster if the image files are time-ordered, too.

* The following EXIF tags will be (over)written:

GPS Version ID                  : 2.2.0.0
GPS Latitude Ref                : North
GPS Latitude                    : xx deg xx' 16.82"
GPS Longitude Ref               : East
GPS Longitude                   : xx deg xx' 5.00"
GPS Altitude Ref                : Above Sea Level
GPS Altitude                    : 350 m
GPS Time Stamp                  : 13:19:22
GPS Satellites                  : 11
GPS Status                      : Measurement Active
GPS Dilution Of Precision       : 0.8
GPS Speed Ref                   : km/h
GPS Speed                       : 0.1852
GPS Track Ref                   : True North
GPS Track                       : 72.39
GPS Img Direction Ref           : Magnetic North
GPS Img Direction               : 125.4
GPS Map Datum                   : WGS-84
GPS Processing Method           : GPS,D
GPS Date Stamp                  : 2010:12:08
GPS Differential                : Differential Corrected
User Comment                    : Blabla ; H: 125.4, P: 3.6, R: -1.3

The original UserComment "Blabla" will be appended by the image direction (compass heading H), the pitch (P) and the roll (R) angles given in degrees. The tag "GPS Dilution Of Precision" is always HDOP because PDOP is not logged. Moreover, I have enhanced the tag "GPS Processing Method", it reads "GPS,x", where x denotes the FAA mode indicator from the end of the GPRMC sentence. x can be A (autonomous), D (differential), E (estimated), M (manual), N (not valid), S (simulated). A means normal, D differential corrected, and E indicates that the indoor function of the Geotagger was active.

* It can happen that an NMEA sentence in the track log is broken, which yields error/warning messages or simply wrong meta data entries. In this case you can try to repair the broken sentence by hand. Links to the specification are given below. Then run GeotagSolm again using the repaired NMEA file.

* Some parameters of GeotagSolm can be adjusted easily by editing the script file with a text editor. Search for "Einstellungen" near the beginning of the file. There you can modify several parameters:

  # Zeit Toleranz in Sekunden
  ZeitTol=10;
  
"ZeitTol" specifies the tolerance in seconds for matching GPS time with image time.
  
  # interaktiv: 0: keine Interaktion, 1: Frage nach vorm Geotaggen
  interaktiv=1;
  
Set "interaktiv" to 0 to turn off the menu. Then GeotagSolm will not ask for confirmation before modifying the image files.
  
  # Pfad zu "exiftool"
  ExiftoolPfad="exiftool";
  
If the "exiftool" executable is not in PATH, you can specify its exact location in "ExiftoolPfad".
  
  # Exiftool-Optionen fürs Geotaggen:
  ExiftoolGeotagOpt=""

In "ExiftoolGeotagOpt" you can set additional ExifTool parameters. They must be formatted for the usage in an argument file. Consult the ExifTool documentation for details.

  # -overwrite_original_in_place: Originalbilder überschreiben.
  #ExiftoolGeotagOpt="-overwrite_original_in_place\n"

By uncommenting the last line ExifTool does not make backup copies of your image files. Instead, the original files will be overwritten.


4. HELPER SCRIPTS
=================

Two helper shell scripts have been added. They are useful shortcuts for ExifTool. The scripts can be adjusted easily to your needs.


4.1 BackupEXIF
==============

"BackupEXIF IMAGEFILES" makes backups of the EXIF meta date in IMAGEFILES. The backup files have the file extension ".orig.exif" and they are placed into the directory "origexif". For instance, the following command creates the EXIF files "foto.orig.exif" and "*.orig.exif":

BackupEXIF foto.jpg *.JPG

If necessary, the EXIF data from "foto.orig.exif" can be written back to "foto.jpg" by

exiftool -P -tagsfromfile origexif/foto.orig.exif -b -exif foto.jpg

If only GPS data tags and the UserComment shall be restored you can use

exiftool -P -tagsfromfile origexif/foto.orig.exif -gps:all -UserComment foto.jpg

Consult the ExifTool homepage for all possibilities.

Making backups of the EXIF meta data is a good idea in general before you modify your image files with whatever program or operating system function. There are certainly lots of applications which do not handle meta data with care. Even better is saving your images to a safe place immediately after they have been downloaded from your camera or memory card. However, this requires more disk space than the ".orig.exif" files.


4.2 CreateXMP
=============

"CreateXMP IMAGEFILES" creates simple XMP sidecar files for storing the GPS data therein instead of writing it into the image files. For example,

CreateXMP *.JPG

produces the files "*.xmp" corresponding to the "*.JPG" files. After that, use

GeotagSolm NMEA TIME *.xmp

to store the GPS data in the XMP sidecar files. Here, the original JPG files are left untouched.

Of course, this procedure to be useful, your image applications should be capable of using XMP sidecar files. If your images come already with XMP sidecar files, you do not need to create them with "CreateXMP", just run "GeotagSolm" on them.


5. USEFUL RESOURCES AND LINKS
=============================

* LeseSolm homepage at SourceForge:
http://sourceforge.net/projects/lesesolm/

* Solmeta Geotagger Pro:
www.solmeta.com

* ExifTool:
www.sno.phy.queensu.ca/~phil/exiftool/

* GAWK:
www.gnu.org/software/gawk/

* NMEA:
http://gpsd.berlios.de/NMEA.html
http://www.gpsinformation.org/dale/nmea.htm

* Compass sentence $PTNTHPR:
http://www.magneticsensors.com/datasheets/hmr3000_manual.pdf

* Thanks to Sebastian Hofer (www.gps-camera.eu) for useful correspondence and information about the Geotagger.