radiation-tagger/Readme.md

# radiation tagger

rad_tag.py is a simple unix-style cross-platform Python 3 tool which can write certain tags to an image file.

It can scan a couple of images, extract their Exif-tags, and compare the `DateTimeOriginal` with other sources.

It can parse a .his (CSV) file from a [GeigerLog](https://sourceforge.net/projects/Geigerlog/) file export and calculate the radiation in µS/h using the factor in `sifactor`.

It can optionally read a gpx-file, compare the timestamps to 'DateTimeOriginal' and determine closest-matching latitude / longitude / altitude. Timestamps in GPX files are ususally stored in UTC timezone, you can set --timezone to match the local timezone, your camera / geiger counter ran at.

It then creates some Exif/ITPC/XMP Comment/Description tags with the actual measured radiation at the time the photo has been taken and writes the geocoordinates into the appropiate Exif tags.

## Dependencies
Right now it depends on the following non-core Python 3 libraries. These can be installed using the package manager of your distribution.

  * [py3exiv2](https://pypi.org/project/py3exiv2/) A Python 3 binding for (lib)exiv2.
  * [pytz](https://pypi.org/project/pytz/) World timezone definitions, modern and historical.
  * [gpxpy](https://pypi.org/project/gpxpy/) gpx-py is a python GPX parser. GPX (GPS eXchange Format) is an XML based file format for GPS tracks. 

### Setting up a virtual environment using pipenv

If you prefer to use more updated versions of the dependencies or you do not want to use Python dependencies into your system, I prepared a pipenv virtual environment for you.

Using `pipenv install` all dependencies will be installed automatically. With `pipenv shell` you can source the venv.

For py3exivv2 to work / compile the following dependencies must be installed - preferably from your system's package manager:

  * [exiv2](http://www.exiv2.org/) and it's development package. Exiv2 is a Cross-platform C++ library and a command line utility to manage image metadata.
  * [boost](https://www.boost.org/) and it's development package. Boost provides free peer-reviewed portable C++ source libraries.
  * [boost.python3](http://www.boost.org/libs/python/doc/index.html) and it's development package. A C++ library which enables seamless interoperability between C++ and the Python programming language.

#### Debian / Ubuntu
sudo apt install pipenv build-essential python-all-dev libexiv2-dev libboost-python-dev

#### Fedora
sudo dnf install pipenv exiv2-devel boost-devel boost-python3-devel make automake gcc gcc-c++

## Requirements
  * A bunch of images (jpg, cr2, etc.) with its time of creation stored in `DateTimeOriginal`.
  * GeigerCounter log file in csv format as it is being exported by the software GeigerLog. 
  * Optionally a GPX (1.0 / 1.1) track that has been recorded during the same timeperiod.

All sources are matched by their timestamp, so all sources have to be recorded during the same time (and timezone). The Geiger counter has to log a value every second, as the script compares the timestamps exactly.

These exported .his files look like this:

```
# ID  , time in isoformat  ,    CP/M,    CP/S
149654, 2020-02-27 05:12:42,    13.0,     0.0
```

## Usage

```
usage: rad_tag.py [-h] [-si SIFACTOR] [-tz Timezone] [-d] [-g GPX] [-o OUTDIR]
                  CSV Photo [Photo ...]

A unix-tyle tool that extracts GPS and/or radiation data from GPX/CSV files
and writes them into the Exif/ITPC/XMP tags of given photos.

positional arguments:
  CSV                   Geiger counter history file in CSV format.
  Photo                 One or multiple photo image files to process.

optional arguments:
  -h, --help            show this help message and exit
  -si SIFACTOR, --sifactor SIFACTOR
                        Factor to multiply recorded CPM with. (default:
                        0.0065)
  -tz Timezone, --timezone Timezone
                        Manually set timezone of CSV / and Photo timestamp,
                        defaults to UTC if omitted. This is useful, if the
                        GPS-Logger saves the time incl. timezone (default:
                        utc)
  -d, --dry             Dry-run, do not actually write anything. (default:
                        False)
  -g GPX, --gpx GPX     GPS track in GPX format (default: None)
  -o OUTDIR, --outdir OUTDIR
                        Directory to output processed photos. (default: .)

```

### Examples
Use test.hisdb.his and walk.gpx from testdata and modify (overwrite) all .JPG files in place.

```
./rad_tag.py ./testdata/walk.hisdb.his --gpx .d/testdata/walk.gpx -tz Europe/Berlin ./testdest/*.JPG
Modifying photos in place (overwrite)
filename        date / time               Matched Data          
_MG_3824.JPG    2020-03-15 16:17:54+01:00 ☢: 0.05µS/h Lat.: 51.92611112 Long.: 7.69379252 Alt.: 93.0m
_MG_3825.JPG    2020-03-15 16:18:12+01:00 ☢: 0.08µS/h Lat.: 51.92620192 Long.: 7.69360727 Alt.: 91.7m
_MG_3826.JPG    2020-03-15 16:18:12+01:00 ☢: 0.08µS/h Lat.: 51.92620192 Long.: 7.69360727 Alt.: 91.7m
_MG_3827.JPG    2020-03-15 16:18:12+01:00 ☢: 0.08µS/h Lat.: 51.92620192 Long.: 7.69360727 Alt.: 91.7m

```

Use test.hisdb.his in folder 'testdata', read all files from 'testsource' and write them to 'testdest'.

```
./rad_tag.py ./testdata/walk.hisdb.his -o ./testdest --gpx ./testdata/walk.gpx -tz Europe/Berlin ./testsource/*
Modifying photos in /home/mscholz/testdest (copy)
filename        date / time               Matched Data          
DSC_0226.JPG    2020-03-15 15:02:04+01:00 ☢: N/A Lat.: N/A, Long.: N/A Alt.: N/A
DSC_0227.JPG    2020-03-15 15:11:43+01:00 ☢: N/A Lat.: N/A, Long.: N/A Alt.: N/A
_MG_3804.JPG    2020-03-15 15:59:11+01:00 ☢: 0.06µS/h Lat.: 51.92582544 Long.: 7.68739496 Alt.: 95.4m
_MG_3805.CR2    2020-03-15 16:01:49+01:00 ☢: 0.05µS/h Lat.: 51.92314108 Long.: 7.69078156 Alt.: 104.2m
_MG_3805.JPG    2020-03-15 16:01:49+01:00 ☢: 0.05µS/h Lat.: 51.92314108 Long.: 7.69078156 Alt.: 104.2m
_MG_3807.CR2    2020-03-15 16:07:02+01:00 ☢: 0.08µS/h Lat.: 51.9235013 Long.: 7.69250565 Alt.: 101.3m
_MG_3807.JPG    2020-03-15 16:07:02+01:00 ☢: 0.08µS/h Lat.: 51.9235013 Long.: 7.69250565 Alt.: 101.3m

```

## GeigerLog setup

The Software is Open-Source and can be downloaded from [Sourceforge](https://sourceforge.net/projects/Geigerlog/).

### Configure GeigerLog to use the GMC-Geiger counter

The GMC device has to be enabled in the `geigerlog.cfg` which is located in the main program directory. Because GS (GammaScout) is preactivated, it can be disabled, while you want to enable GMC

```
GSActivation = no
GMCActivation = yes
```

The GMC* defaults are quite sane, but you might want to set the correct serial port:

`usbport   = /dev/ttyUSB0`

GeigerLog can also use a bunch of other devices while still outputting a csv-file in compatible format.

### Using GeigerLog to download history

Now the program can be started by double-clicking `geigerlog` or by executing `./geigerlog` on the command prompt.
Once connected to the device (in any power state) by pressing 'Ctrl+C' , you can download the history ('History' -> 'GMC Series' -> 'Get History from Device'). You will be asked to choose a filename for the hisdb-file (SQLITE format).

GeigerLog now presents you a rendering of the radiation over time in its main window:

![alt text][main_window]

[main_window]: images/geigerlog_main_window.png "GeigerLog Main Window with graph"

Once imported, you can export the history into a hisdb.his-file, which is basically the CSV-file `rad_tag.py` can process. Choose 'History' -> Save History Data into .his file (CSV)'.

## GPS setup

Especially if you use a mobile phone for GPS-logging, ensure the app can use GPS when the phone is locked. Let it write position sufficiently often. Threshold is 5 minutes by default, but precision will improve when logging more often. Especially "inactivity detection" might become a problem, when staying at one place for a period of time.

## future possibilities

  * It might get a setup.py if I want to waste my time on it.
  * I might want to get rid of the requirement to use a bloated GUI application to download the history data off the Geigercounter. There must be a neat working command line tool. Maybe I'll write it myself.