radiation-tagger/Readme.md

153 lines
8.1 KiB
Markdown
Raw Normal View History

2020-03-01 17:45:31 +01:00
# radiation tagger
2020-03-01 17:36:06 +01:00
rad_tag.py is a simple unix-style cross-platform Python 3 tool which can write certain tags to an image file.
2020-03-01 17:36:06 +01:00
2020-03-01 17:45:31 +01:00
It can scan a couple of images, extract their Exif-tags, and compare the `DateTimeOriginal` with other sources.
2020-03-01 17:36:06 +01:00
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`.
2020-03-01 17:36:06 +01:00
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.
2020-03-01 17:36:06 +01:00
## Dependencies
Right now it depends on the following non-core Python 3 libraries. These can be installed using the package manager of your distribution.
2020-03-01 17:36:06 +01:00
* [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++
2020-03-01 17:36:06 +01:00
## Requirements
* A bunch of images (jpg, cr2, etc.) with its time of creation stored in `DateTimeOriginal`.
2020-03-04 13:04:27 +01:00
* 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.
2020-03-01 17:36:06 +01:00
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.
2020-03-01 17:36:06 +01:00
2020-03-04 13:04:27 +01:00
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
```
2020-03-01 17:36:06 +01:00
## Usage
2020-03-04 13:04:27 +01:00
```
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
2020-03-04 12:56:45 +01:00
```
GSActivation = no
2020-03-04 12:56:01 +01:00
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.
2020-03-01 17:36:06 +01:00
## 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.