A tool that writes radiation levels (and optionally geocoordinates) to image files and extracts the infos from external sources.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Marcus Scholz 67db75ece8 Fixed broken link to github help page. 1 year ago
images Added contributing guide, exchanged geigerlog main window screenshot with light colorscheme. 1 year ago
.gitignore Prepared pipenv virtual environment and added documentation. 1 year ago
CHANGELOG.md Fixed release data in changelog. 1 year ago
CONTRIBUTING.md Fixed broken link to github help page. 1 year ago
LICENSE Added MIT license. Do whatever you want with this thing. 2 years ago
Pipfile Prepared pipenv virtual environment and added documentation. 1 year ago
Readme.md Unified mentions for Exif/ITPC/XMP tags. Finalized 0.3.2 release. 1 year ago
functions.py Unified mentions for Exif/ITPC/XMP tags. Finalized 0.3.2 release. 1 year ago
rad_tag.py Unified mentions for Exif/ITPC/XMP tags. Finalized 0.3.2 release. 1 year ago

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 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 A Python 3 binding for (lib)exiv2.
  • pytz World timezone definitions, modern and historical.
  • 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 and it's development package. Exiv2 is a Cross-platform C++ library and a command line utility to manage image metadata.
  • boost and it's development package. Boost provides free peer-reviewed portable C++ source libraries.
  • boost.python3 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.

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

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.