- 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
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
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.
Please look in
requirements.txt to see, which python libraries are required for the
It is also mandatory to download & install the free software
Octave, as the core projection procedure is running on Matlab/Octave scripts from
PRACTISE itself is downloaded automatically as the code has to be adapted for
So far this tool has been tested in Ubuntu 16.04, 18.04 & Windows 10.
- Download the package to the directory you like.
- Install all required
pythonpackages to the conda environment you use (see requirements.txt).
- Download and install latest
Octaveversion from here.
The following description gives a short idea, how the procedure works and how to get a good georeferencing result.
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
georef_webcamwill be stored in subfolders.
name_of_run(optional): define a name for projection run to recognize output (default: test_run).
- 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.
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
The following output is produced and stored in
out_dir/georef_result/name_of_run/ (italic files are optional):
- the original image
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
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 with the following function
$ python project_data2map.py coord_dir filename_or_extension pixel_size out_dir [-f IMAGE_FOLDER] [-fill FILL_NODATA]
These input parameters are required:
coord_dir: directory, where the output of
georef_webcam(coordinate rasters and mask) is stored.
filename_or_extension: select the dataset or image, which should be projected.
If you want to project several files, just insert a file extension instead (e.g. tif, png, jpg).
In this case, the optional variable
image_folderis required. All datasets in this folder with the specified file extension will be projected.
pixel_size: define spatial resolution of your product.
out_dir: directory, where produced maps should be stored.
fill_nodata(optional): voids in the projected dataset can be filled with interpolation here.
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.