georef_webcam

Python package to georeference webcam images

Maintainer: Sebastian Buchelt
Citation: Buchelt, S. (2020-): georef_webcam V.1.0. Zenodo. https://doi.org/10.5281/zenodo.3898913.
More on correct citation here.
License: CC-BY-NC-SA 4.0

Overview

georef_webcam is a python package for python3. It provides functionalities to georeference oblique camera images in complex terrain without accurate knowlegde about the required input parameters. The package enables the user to georeference images based on estimations about camera position, system parameters & looking direction. To run the projection you need the image you want to project and a high-resolution Digital Elevation Model (DEM) of the area covered by the camera.
Additionally, Ground Control Points (GCPs) can be added to optimize the projection parameters for a better geolocation accuracy.

georef_webcam uses the Matlab scripts of the PRACTISE package to run the projection procedure. Based on the output generated by PRACTISE, georef_webcam produces tif-files in the size of the original image with the coordinate position (Easting & Northing) of each pixel. Furthermore, a mask layer is generated to filter areas above the skyline. Based on those, a projected map of the camera image can be produced.

Requirements

Please look in requirements.txt to see, which python libraries are required for the georef_webcam package. It is also mandatory to download & install the free software Octave, as the core projection procedure is running on Matlab/Octave scripts from PRACTISE package. PRACTISE itself is downloaded automatically as the code has to be adapted for georef_webcam.
So far this tool has been tested in Ubuntu 16.04, 18.04 & Windows 10.

Installation

Download the package to the directory you like.
Install all required python packages to the conda environment you use (see requirements.txt).
Download and install latest Octave version from here.

Getting started

The following description gives a short idea, how the procedure works and how to get a good georeferencing result.

Start georef_webcam:

Before starting the execution of the script, you should have the webcam image & the DEM file ready for processing. Then:

Activate environment
set directory to downloaded package & start script:

$ cd /path/to/dowloaded/and/unzipped/folder/
$ cd /georef_webcam_v1_0/python_scripts
$ python georef_webcam.py in_dir out_dir [-n name_of_run]

The script georef_webcam.py requires two input parameter:

in_dir: directory, where the DEM file, the camera image and the gcp file (optional) are stored. The files can be stored in separate subdirectories.
out_dir: directory, where output of PRACTISE and georef_webcam will be stored in subfolders.
name_of_run (optional): define a name for projection run to recognize output (default: test_run).

Parameter collection:

Two options:

read an already existing dictionary. The script searches for json-files in the input directory. After loading the dictionary, the parameters can also be edited then.
Otherwise, if no previously generated dictionary exists or you want to generate a new set of projection parameters, a new dictionary will be created:

Do you want to create a new set of projection parameters?  y/n

For details about input parameters, their definition and further requirements, see Parameters.md.
The collected parameters are then stored as json-file under in_dir/[name_of_run].json and can be reused in a later run.

Projection:

The parameters are taken from the dictionary and passed to PRACTISE, which is then executing the projection procedure. Afterwards, the DEM points projected into image plane are plotted in an Octave window and the geolocation accuracy of the projection can be checked:

_{Figure 1: DEM points projected into image plane.
Left: wrong projection parameters; Right: Corrected projection parameters.}

Then you can decide between the following options:

Projection has been executed. 
What do you want to do next?
Please select one of the following options:
0: end procedure
1: edit projection input parameters and repeat projection procedure
2: produce georef_webcam output

Which of the options do you want to choose?

0: ends program
1: edits projection parameters, stores them in new json file (optionally) and repeats the projection with the adapted parameters
2: moves on to output generation

Output generation:

The following output is produced and stored in out_dir/georef_result/name_of_run/ (italic files are optional):

the original image
east_raster & north_raster: two tif-files with the size of the image giving the easting & northing coordinate of each pixel
alt_raster: tif-file with altitude of each image pixel
dist_raster: tif-file with distance of each image pixel to camera location
mask: tif-file containing the mask layer (needed to filter areas above skyline)
[image_name]_map.tif: projected map of the camera image

Output examples

_{Figure 2: Final result - Coordinate rasters.}

_{Figure 3: Used webcam image.}

_{Figure 4: Animation showing same-day Sentinel-2 image overlayed with projected webcam image.}

More examples can be found here.

Additional Comments on how to further improve geolocation accuracy can be found here.
(Only of interest, if you are already familiar with how the package works.)

Projecting other data

After successfully georeferencing an image, any other data or image with the same acquisition geometry can be projected to map coordinates. Besides RBG images also tif files with multiple bands can be projected. Furthermore, it is possible to project georeferenced raster data into image plane as well. You can also project shp-files to image plane or project shp objects, that have been drawn in image plane, to map coordinates. All these tools can be executed with the following function project_data2map.py:

$ python project_data2map.py coord_dir file_or_folder out_dir 
         [-ex EXTENSION] [-px PIXEL_SIZE] [-fill FILL_NODATA] 
         [-i TO_IMAGE_VIEW] [-shp PROJECT_SHP]

These input parameters are required:

coord_dir: directory, where the output of georef_webcam (coordinate rasters and mask) is stored.
file_or_folder: select the dataset or image, which should be projected.
If you want to project several files within one folder, insert the directory here.
In this case, the optional variable -ex EXTENSION is required. All datasets in this folder with the specified file extension will be projected.
out_dir: directory, where produced maps should be stored.
pixel_size (optional): define spatial resolution of your product in meter (only required with raster data that is projected to map coordinates).
fill_nodata (optional): voids in the projected dataset can be filled with interpolation here. The range of interpolation is given in pixel (only required with raster data that is projected to map coordinates).
to_image_view (optional): set keyword, if you want to project georeferenced data (GeoTiffs or Shapefiles) into image plane.
project_shp (optional): set keyword, if you want to project one or several shapefiles.

Citation

Please cite georef_webcam as following:

Buchelt, S. (2020-): georef_webcam V.1.0. Zenodo. https://doi.org/10.5281/zenodo.3898913.

As this work is primarily based on the PRACTISE software and its functionalities, please also cite:

Härer, S., Bernhardt, M., and Schulz, K.: PRACTISE: PRACTISE V.2.1. Zenodo, doi:10.5281/zenodo.35646, 2015.

I also want to give special thanks to Gerhard Keuschnig & Florian Radlherr from foto-webcam.eu, who provide a great system for high-resolution webcam images. The image in the example is provided by their website.

The reuse or adaptation of images and animations provided in the documentation files is only allowed upon request.

SebBuchelt / georef_webcam