A module for handling camera distorsion and undistorting images/videos by keeping the meta-data, originally developed for fisheye-removal. The project is written in Python, consists of a pacakge and an application for media undistortion.
- Collect calibration images from video: Extract calibration images from video
- Camera calibration: Determine the intrinsic camera parameters from calibration images or calibration video
- Image/video undistorsion: Undistort images and videos given the intrinsic camera parameters but keeping the meta-data
Background Every images and videos which have been taken with real-world camera are distorted, it means that the projection of the camera is not perfectly linear. Simply speaking, the straight line become on the images curved. This effect can be seen mainly on "fisheye" cams.
Modelling distortion There are many ways to model camera distortions. The most wide-spread model is the radial distortion model, which assumes that the distortion depends on the distance from the optical center. This library supports currently only the model used by opencv
The camera model
To handle the distortion one must obtain the camera model. In this project it is represented
by the CameraModel class. Obtaining the parameters for a specific model is called calibration.
It requires images taken with the camera and reference to calculate the optimal parameters.
Generally images from calibration pattern are taken, which contains known shapes and
easily markable corner points.
Calibration images
Currently, calibration images taken about checkerboard calibration pattern are supported.
Many (minimum 20 is recommended) images are required in different poses to calculate
precise camera parameters. These images can be taken individually, or a it can be extracted
from a video sequence using the collect module.
Undistortion Given the camera model the images and videos can be undistorted, as a result the straight lines should appear straight in the undistorted images.
The camera_distortion module is developed for easily undistort images and videos. Currently, it has three main submodules:
Collecting calibration images from a video sequence. Given a video about a calibration pattern, images can be extracted and saved for the calibration.
Calculating intrinsic parameters from calibration images. The parameters of the camera model can be calculated from images taken about known calibration patterns. This module supports only checkerboard calibration pattern, you can find one here: https://github.com/Peter-Kocsis/camera-distortion/tree/main/calibration_images
The calibration images should be clear, not blurred and the calibration pattern needs to be visible.
Knowing the camera distortion model one can find a mapping between the distorted and undistorted point coordinates, which can be used to restore the undistorted image. Generally, in favour of efficiency, the camera models uses invertible, which allows to calculate the mapping in closed from.
To install the python module, you can use the setup script
python setup.py installor the provided requirements file
pip install -r requirements.txt- 1.: Capture video about the calibration pattern in which the pattern is moved around in many different poses, or capture calibration images and continue with step 3
- 2.: Collect the calibration images from the video:
python -m collect.collect --video <PATH_TO_THE_CALIBRATION_VIDEO> --out_folder <PATH_TO_THE_OUTPUT>- 3.: Calculate the camera parameters:
python -m calibrate.calibrate --images <PATH_TO_THE_CALIBRATION_IMAGES>python -m unsitort.undistort <PATH_OR_PATHES_TO_THE_MEDIA_FILES_SEPARATED_BY_SPACE> --out_folder <PATH_TO_THE_OUTPUT> --parameters <PATH_TO_THE_CALIBRATION_FILE_FROM_STEP_3>The GUI application provides easily usable interface for the full undistortion process.
The prebuilt binaries can be found in the latest release.
NOTE: For choosing any path, you can use Drag-and-Drop!
1. Run the program!
2. Choose the calibration video!
3. Start the calibration!
4. Wait for finish!
5. Choose the input media and output path!
6. Start the undistortion!
7. Wait for every input to finish!
8. Success!
TkDnD gives support for drag-and-drop in the GUI. If not provided, the application won't support drag-and-drop. It can be installed for system-wide use as described here or you can install it only for this application as follows:
- Download the TkDnD library and place in the root of the project
- Download the TkDnD Python wrapper and place the module TkinterDnD2 in the root of the project
This steps can be done by calling the install_tkdnd.sh from the root of the project in case of Linux or MacOS systems or install_tkdnd.bat in case of Windows:
bash ./gui/install_tkdnd.shIn order to build the Media undistorsion app, you should run the following command from the root of the repository:
Linux/MacOS:
pyinstaller --name media_undistortion --add-data "./gui/camera_distortion.ui:." --add-data "./gui/icon.png:." --add-data "./tkdnd2.8:./tkdnd2.8" --hidden-import "pygubu.builder.tkstdwidgets" --add-binary "$(python -c 'import site; print(site.getsitepackages()[0])')/cv2/qt:./cv2/qt" --add-binary "$(python -c 'import site; print(site.getsitepackages()[0])')/opencv_python.libs:./opencv_python.libs" --hidden-import "pygubu.builder.ttkstdwidgets" --icon "./gui/icon.ico" --onefile ./gui/camera_distortion_app.pyWindows:
pyinstaller --name media_undistortion --add-data "./gui/camera_distortion.ui;." --add-data "./gui/icon.png;." --add-data "./tkdnd2.8;./tkdnd2.8" --hidden-import "pygubu.builder.tkstdwidgets" --add-binary "<PATH_TO_SITE_PACKAGES>/cv2/qt;./cv2/qt" --add-binary "<PATH_TO_SITE_PACKAGES>/opencv_python.libs;./opencv_python.libs" --hidden-import "pygubu.builder.ttkstdwidgets" --icon "./gui/icon.ico" --onefile ./gui/camera_distortion_app.pyThe package is based on the implementation of The Eminenet Codefish.