Software for Unwrapping Omnidirectional Images

A small application for unwrapping omnidirectional images using polar to Cartesian coordinate conversion. The size and aspect ratio of the produced images can be adjusted and the application performs bilinear or bicubic interpolation in order to improve the quality. The center of the omnidirectional image can be detected automatically using either a very simple and fast algorithm based on image thresholding or a slower but much more robust method based on edge detection and Hough transform. An example of using the second method is shown below.

Videos presenting sequences of unwrapped omnidirectional images taken from the COLD database can be downloaded here, here and here.

Download, installation and usage instructions for both Linux and Windows can be found below. If you have any questions, you experience problems with the software or you have spotted a bug, please contact Andrzej Pronobis.
Download and Installation
The application is known to compile in both Linux and Windows and depends on the OpenCV library. The source code can be downloaded either as a tar.gz file (for Linux users) or zip file (for Windows users):
   • Tar/gzip file (443.46 kB)
   • Zip file (446.30 kB)

Binaries for both operating systems are also available:
   • Linux binary (449.10 kB)
   • Windows binary (584.34 kB)

CMake is used as a build system for the sources. Windows users can install MinGW to get a C++ compiler. To build from the sources, use either the '' or 'build.bat' script.
Description of the command line options and arguments:
Usage: unwrap [-bl|-bc] [-sx <x_ratio>] [-sy <y_ratio>]
               [-tc <black_threshold>|-fc <center_x> <center_y>|
               -ec <min_radius> <max_radius> <center_x> <center_y> <dx> <dy>]
               [-fi <image_file>] [-eb <l> <t> <r> <b>]
               [-ti <image_file>] [-uw <output_file>]
              <inner_radius> <outer_radius> <input_file>

 -bl - use bilinear interpolation (default: OFF)
 -bc - use bicubic interpolation (default: OFF)
 -sx <x_ratio> produce output scaled horizontally by <x_ratio> (def. 1)
 -sy <y_ratio> produce output scaled vertically by <y_ratio> (def. 1)
 -tc <black_threshold> - estimate center of the image using fast (but
                         not always robust) alg. based on thresholding.
 -ec <min_radius> <max_radius> <center_x> <center_y> <dx> <dy> - estimate
         center of the image using slower but more robust algorithm based
         on edge detection and Hough transform. To speed up the search,
         only images centered in (<center_x>+/-<dx>, <center_y>+/-<dy>)
         and of radius <min_radius> to <max_radius> are considered.
 -fi <image_file> - save the filtered image produced during
                    thresholding or edge detection
 -eb <l> <t> <r> <b> - exclude border during center estimation (def. 0)
 -fc <center_x> <center_y> - use fixed center of the omni image
 -uw <output_file> - unwrap the omnidirectional image
 -ti <image_file> - create test image - the input image on which
                    the center and radii are plotted

 <inner_radius> - inner radius of the omnidirectional image
 <outer_radius> - outer radius of the omnidirectional image
 <input_file> - input omnidirectional image file

  • Estimating the center of the image using the thresholding-based method. 5 pixel boundary on top and bottom of the input image is excluded:
    unwrap -tc 30 -eb 0 5 0 5 -fi filtered.jpg 40 230 input.jpg
  • Estimating the center of the image using the edge-based method. Two "debug" images are created:
    unwrap -ec 230 240 330 240 20 20 -fi filtered.jpg -ti test.jpg 40 230 input.jpg
  • Unwrapping using fixed center and no interpolation or scaling:
    unwrap -uw output.jpg -fc 330 240 40 230 input.jpg
  • Unwrapping using automatic center point detection and bicubic interpolation:
    unwrap -uw output.jpg -ec 230 240 330 240 20 20 -bc 40 230 input.jpg
  • As above, but with vertical resolution of the output increased 2x:
    unwrap -uw out.jpg -ec 230 240 330 240 20 20 -bc -sy 2 40 230 in.jpg
Created by: Andrzej Pronobis Last modified: 20-09-2009 00:26